Concerns with em.yaml YNL spec

Concerns with em.yaml YNL spec

[Donald Hunter]

Hi,

I just spotted the new em.yaml YNL spec that got merged in
bd26631ccdfd ("PM: EM: Add em.yaml and autogen files") as part of [1]
because it introduced new yamllint reports:

make -C tools/net/ynl/ lint
make: Entering directory '/home/donaldh/net-next/tools/net/ynl'
yamllint ../../../Documentation/netlink/specs
../../../Documentation/netlink/specs/em.yaml
  3:1       warning  missing document start "---"  (document-start)
  107:13    error    wrong indentation: expected 10 but found 12  (indentation)

I guess the patch series was never cced to netdev or the YNL
maintainers so this is my first opportunity to review it.

Other than the lint messages, there are a few concerns with the
content of the spec:

- pds, pd and ps might be meaningful to energy model experts but they
are pretty meaningless to the rest of us. I see they are spelled out
in the energy model header file so it would be better to use
perf-domain, perf-table and perf-state here.

- I think the spec could have been called energy-model.yaml and the
family called "energy-model" instead of "em".

- the get-pds should probably be both do and dump which would give
multi responses without the need for the pds attribute set (unless I'm
missing something).

- there are 2 flags attributes that are bare u64 which should have
flags definitions in the YNL. Have a look at e.g. netdev.yaml to see
examples of flags definitions.

- the cpus attribute is a string which would appear to be a "%*pb"
stringification of a bitmap. That's not very consumable for a UAPI and
should probably use netlink bitmask or an array of cpu numbers or
something.

- there are no doc strings for any of the attributes. It would be
great to do better for new YNL specs, esp. since there is better
information in energy_model.h

Given that netlink is UAPI, I think we need to address these issues
before v6.19 gets released.

Thanks,
Donald Hunter.

[1] https://lore.kernel.org/all/20251020220914.320832-4-changwoo@igalia.com/

Re: Concerns with em.yaml YNL spec

[Andrew Lunn]

On Thu, Dec 11, 2025 at 03:54:53PM +0000, Donald Hunter wrote:
> Hi,
> 
> I just spotted the new em.yaml YNL spec that got merged in
> bd26631ccdfd ("PM: EM: Add em.yaml and autogen files") as part of [1]
> because it introduced new yamllint reports:
> 
> make -C tools/net/ynl/ lint
> make: Entering directory '/home/donaldh/net-next/tools/net/ynl'
> yamllint ../../../Documentation/netlink/specs
> ../../../Documentation/netlink/specs/em.yaml
>   3:1       warning  missing document start "---"  (document-start)
>   107:13    error    wrong indentation: expected 10 but found 12  (indentation)
> 
> I guess the patch series was never cced to netdev or the YNL
> maintainers so this is my first opportunity to review it.
> 
> Other than the lint messages, there are a few concerns with the
> content of the spec:
> 
> - pds, pd and ps might be meaningful to energy model experts but they
> are pretty meaningless to the rest of us. I see they are spelled out
> in the energy model header file so it would be better to use
> perf-domain, perf-table and perf-state here.

We also need to watch out for other meaning of these letters. In the
context of networking and Power over Ethernet, PD means Powered
Device. We generally don't need to enumerate the PD, we are more
interested in the Power Sourcing Equipment, PSE.

And a dumb question. What is an energy model? A PSE needs some level
of energy model, it needs to know how much energy each PD can consume
in order that it is not oversubscribed. Is the energy model generic
enough that it could be used for this? Or should this energy model get
a prefix to limit its scope to a performance domain? The suggested
name of this file would then become something like
performance-domain-energy-model.yml?

	Andrew

Re: Concerns with em.yaml YNL spec

[Changwoo Min]

On 12/12/25 02:01, Andrew Lunn wrote:
> On Thu, Dec 11, 2025 at 03:54:53PM +0000, Donald Hunter wrote:
>> Hi,
>>
>> I just spotted the new em.yaml YNL spec that got merged in
>> bd26631ccdfd ("PM: EM: Add em.yaml and autogen files") as part of [1]
>> because it introduced new yamllint reports:
>>
>> make -C tools/net/ynl/ lint
>> make: Entering directory '/home/donaldh/net-next/tools/net/ynl'
>> yamllint ../../../Documentation/netlink/specs
>> ../../../Documentation/netlink/specs/em.yaml
>>    3:1       warning  missing document start "---"  (document-start)
>>    107:13    error    wrong indentation: expected 10 but found 12  (indentation)
>>
>> I guess the patch series was never cced to netdev or the YNL
>> maintainers so this is my first opportunity to review it.
>>
>> Other than the lint messages, there are a few concerns with the
>> content of the spec:
>>
>> - pds, pd and ps might be meaningful to energy model experts but they
>> are pretty meaningless to the rest of us. I see they are spelled out
>> in the energy model header file so it would be better to use
>> perf-domain, perf-table and perf-state here.
> 
> We also need to watch out for other meaning of these letters. In the
> context of networking and Power over Ethernet, PD means Powered
> Device. We generally don't need to enumerate the PD, we are more
> interested in the Power Sourcing Equipment, PSE.
> 
> And a dumb question. What is an energy model? A PSE needs some level
> of energy model, it needs to know how much energy each PD can consume
> in order that it is not oversubscribed.Is the energy model generic
> enough that it could be used for this? Or should this energy model get
> a prefix to limit its scope to a performance domain? The suggested
> name of this file would then become something like
> performance-domain-energy-model.yml?
> 

Lukasz might be the right person for this question. In my view, the
energy model essentially provides the performance-versus-power-
consumption curve for each performance domain.

Conceptually, the energy model covers the system-wide information; a
performance domain is information about one domain (e.g., big/medium/
little CPU blocks), so it is under the energy model; a performance state
is one dot in the performance-versus-power-consumption curve of a
performance domain.

Since the energy model covers the system-wide information, energy-
model.yaml (as Donald suggested) sounds better to me.

Regards,
Changwoo Min

Re: Concerns with em.yaml YNL spec

[Andrew Lunn]

> > We also need to watch out for other meaning of these letters. In the
> > context of networking and Power over Ethernet, PD means Powered
> > Device. We generally don't need to enumerate the PD, we are more
> > interested in the Power Sourcing Equipment, PSE.
> > 
> > And a dumb question. What is an energy model? A PSE needs some level
> > of energy model, it needs to know how much energy each PD can consume
> > in order that it is not oversubscribed.Is the energy model generic
> > enough that it could be used for this? Or should this energy model get
> > a prefix to limit its scope to a performance domain? The suggested
> > name of this file would then become something like
> > performance-domain-energy-model.yml?
> > 
> 
> Lukasz might be the right person for this question. In my view, the
> energy model essentially provides the performance-versus-power-
> consumption curve for each performance domain.

The problem here is, you are too narrowly focused. My introduction
said:

> > In the context of networking and Power over Ethernet, PD means
> > Powered Device.

You have not given any context. Reading the rest of your email, it
sounds like you are talking about the energy model/performance domain
for a collection of CPU cores?

Now think about Linux as a whole, not the little corner you are
interested in. Are there energy models anywhere else in Linux? What
about the GPU cores? What about Linux regulators controlling power to
peripherals? I pointed out the use case of Power over Ethernet needing
an energy model.

> Conceptually, the energy model covers the system-wide information; a
> performance domain is information about one domain (e.g., big/medium/
> little CPU blocks), so it is under the energy model; a performance state
> is one dot in the performance-versus-power-consumption curve of a
> performance domain.
> 
> Since the energy model covers the system-wide information, energy-
> model.yaml (as Donald suggested) sounds better to me.

By system-wide, do you mean the whole of Linux? I could use it for
GPUs, regulators, PoE? Is it sufficiently generic? I somehow doubt it
is. So i think you need some sort of prefix to indicate the domain it
is applicable to. We can then add GPU energy models, PoE energy
models, etc by the side without getting into naming issues.

Naming is important, and causes a lot of pain when you get it
wrong. Linux has PHYs and generic PHYs. The PHY subsystem has been
around a long time, and generic PHY is much newer. And sometimes a PHY
has a generic PHY associated to it, so it can get really confusing
unless you are very precises with wording.

We need to be careful with any generic term, such as energy model.

	Andrew

Re: Concerns with em.yaml YNL spec

[Changwoo Min]

Hi  Andrew,

On 12/15/25 01:21, Andrew Lunn wrote:
>>> We also need to watch out for other meaning of these letters. In the
>>> context of networking and Power over Ethernet, PD means Powered
>>> Device. We generally don't need to enumerate the PD, we are more
>>> interested in the Power Sourcing Equipment, PSE.
>>>
>>> And a dumb question. What is an energy model? A PSE needs some level
>>> of energy model, it needs to know how much energy each PD can consume
>>> in order that it is not oversubscribed.Is the energy model generic
>>> enough that it could be used for this? Or should this energy model get
>>> a prefix to limit its scope to a performance domain? The suggested
>>> name of this file would then become something like
>>> performance-domain-energy-model.yml?
>>>
>>
>> Lukasz might be the right person for this question. In my view, the
>> energy model essentially provides the performance-versus-power-
>> consumption curve for each performance domain.
> 
> The problem here is, you are too narrowly focused. My introduction
> said:
> 
>>> In the context of networking and Power over Ethernet, PD means
>>> Powered Device.
> 
> You have not given any context. Reading the rest of your email, it
> sounds like you are talking about the energy model/performance domain
> for a collection of CPU cores?
> 
> Now think about Linux as a whole, not the little corner you are
> interested in. Are there energy models anywhere else in Linux? What
> about the GPU cores? What about Linux regulators controlling power to
> peripherals? I pointed out the use case of Power over Ethernet needing
> an energy model.
> 
>> Conceptually, the energy model covers the system-wide information; a
>> performance domain is information about one domain (e.g., big/medium/
>> little CPU blocks), so it is under the energy model; a performance state
>> is one dot in the performance-versus-power-consumption curve of a
>> performance domain.
>>
>> Since the energy model covers the system-wide information, energy-
>> model.yaml (as Donald suggested) sounds better to me.
> 
> By system-wide, do you mean the whole of Linux? I could use it for
> GPUs, regulators, PoE? Is it sufficiently generic? I somehow doubt it
> is. So i think you need some sort of prefix to indicate the domain it
> is applicable to. We can then add GPU energy models, PoE energy
> models, etc by the side without getting into naming issues.
>

This is really the question for the energy model maintainers. In my
understanding, the energy model can cover any device in the system,
including GPUs. But, in my limited experience, I haven’t seen such cases
beyond CPUs.


@Lukasz — What do you think? The focus here is on the scope of the
“energy model” and its proper naming in the NETLINK.


> Naming is important, and causes a lot of pain when you get it
> wrong. Linux has PHYs and generic PHYs. The PHY subsystem has been
> around a long time, and generic PHY is much newer. And sometimes a PHY
> has a generic PHY associated to it, so it can get really confusing
> unless you are very precises with wording.
> 
> We need to be careful with any generic term, such as energy model.
> 

I absolutely agree with you. Thank you for sharing your concerns and
examples.

Regards,
Changwoo Min

> 	Andrew
> 

Re: Concerns with em.yaml YNL spec

[Rafael J. Wysocki]

On Mon, Dec 15, 2025 at 2:57 AM Changwoo Min <changwoo@igalia.com> wrote:
>
> Hi  Andrew,
>
> On 12/15/25 01:21, Andrew Lunn wrote:
> >>> We also need to watch out for other meaning of these letters. In the
> >>> context of networking and Power over Ethernet, PD means Powered
> >>> Device. We generally don't need to enumerate the PD, we are more
> >>> interested in the Power Sourcing Equipment, PSE.
> >>>
> >>> And a dumb question. What is an energy model? A PSE needs some level
> >>> of energy model, it needs to know how much energy each PD can consume
> >>> in order that it is not oversubscribed.Is the energy model generic
> >>> enough that it could be used for this? Or should this energy model get
> >>> a prefix to limit its scope to a performance domain? The suggested
> >>> name of this file would then become something like
> >>> performance-domain-energy-model.yml?
> >>>
> >>
> >> Lukasz might be the right person for this question. In my view, the
> >> energy model essentially provides the performance-versus-power-
> >> consumption curve for each performance domain.
> >
> > The problem here is, you are too narrowly focused. My introduction
> > said:
> >
> >>> In the context of networking and Power over Ethernet, PD means
> >>> Powered Device.
> >
> > You have not given any context. Reading the rest of your email, it
> > sounds like you are talking about the energy model/performance domain
> > for a collection of CPU cores?
> >
> > Now think about Linux as a whole, not the little corner you are
> > interested in. Are there energy models anywhere else in Linux? What
> > about the GPU cores? What about Linux regulators controlling power to
> > peripherals? I pointed out the use case of Power over Ethernet needing
> > an energy model.
> >
> >> Conceptually, the energy model covers the system-wide information; a
> >> performance domain is information about one domain (e.g., big/medium/
> >> little CPU blocks), so it is under the energy model; a performance state
> >> is one dot in the performance-versus-power-consumption curve of a
> >> performance domain.
> >>
> >> Since the energy model covers the system-wide information, energy-
> >> model.yaml (as Donald suggested) sounds better to me.
> >
> > By system-wide, do you mean the whole of Linux? I could use it for
> > GPUs, regulators, PoE? Is it sufficiently generic? I somehow doubt it
> > is. So i think you need some sort of prefix to indicate the domain it
> > is applicable to. We can then add GPU energy models, PoE energy
> > models, etc by the side without getting into naming issues.
> >
>
> This is really the question for the energy model maintainers. In my
> understanding, the energy model can cover any device in the system,
> including GPUs.

That's correct.

> But, in my limited experience, I haven’t seen such cases beyond CPUs.
>
> @Lukasz — What do you think? The focus here is on the scope of the
> “energy model” and its proper naming in the NETLINK.

I think you need to frame your question more specifically.

Re: Concerns with em.yaml YNL spec

[Changwoo Min]

Thanks, Rafael, for the comments.

On 12/15/25 19:30, Rafael J. Wysocki wrote:
> On Mon, Dec 15, 2025 at 2:57 AM Changwoo Min <changwoo@igalia.com> wrote:
>>
>> Hi  Andrew,
>>
>> On 12/15/25 01:21, Andrew Lunn wrote:
>>>>> We also need to watch out for other meaning of these letters. In the
>>>>> context of networking and Power over Ethernet, PD means Powered
>>>>> Device. We generally don't need to enumerate the PD, we are more
>>>>> interested in the Power Sourcing Equipment, PSE.
>>>>>
>>>>> And a dumb question. What is an energy model? A PSE needs some level
>>>>> of energy model, it needs to know how much energy each PD can consume
>>>>> in order that it is not oversubscribed.Is the energy model generic
>>>>> enough that it could be used for this? Or should this energy model get
>>>>> a prefix to limit its scope to a performance domain? The suggested
>>>>> name of this file would then become something like
>>>>> performance-domain-energy-model.yml?
>>>>>
>>>>
>>>> Lukasz might be the right person for this question. In my view, the
>>>> energy model essentially provides the performance-versus-power-
>>>> consumption curve for each performance domain.
>>>
>>> The problem here is, you are too narrowly focused. My introduction
>>> said:
>>>
>>>>> In the context of networking and Power over Ethernet, PD means
>>>>> Powered Device.
>>>
>>> You have not given any context. Reading the rest of your email, it
>>> sounds like you are talking about the energy model/performance domain
>>> for a collection of CPU cores?
>>>
>>> Now think about Linux as a whole, not the little corner you are
>>> interested in. Are there energy models anywhere else in Linux? What
>>> about the GPU cores? What about Linux regulators controlling power to
>>> peripherals? I pointed out the use case of Power over Ethernet needing
>>> an energy model.
>>>
>>>> Conceptually, the energy model covers the system-wide information; a
>>>> performance domain is information about one domain (e.g., big/medium/
>>>> little CPU blocks), so it is under the energy model; a performance state
>>>> is one dot in the performance-versus-power-consumption curve of a
>>>> performance domain.
>>>>
>>>> Since the energy model covers the system-wide information, energy-
>>>> model.yaml (as Donald suggested) sounds better to me.
>>>
>>> By system-wide, do you mean the whole of Linux? I could use it for
>>> GPUs, regulators, PoE? Is it sufficiently generic? I somehow doubt it
>>> is. So i think you need some sort of prefix to indicate the domain it
>>> is applicable to. We can then add GPU energy models, PoE energy
>>> models, etc by the side without getting into naming issues.
>>>
>>
>> This is really the question for the energy model maintainers. In my
>> understanding, the energy model can cover any device in the system,
>> including GPUs.
> 
> That's correct.
> 
>> But, in my limited experience, I haven’t seen such cases beyond CPUs.
>>
>> @Lukasz — What do you think? The focus here is on the scope of the
>> “energy model” and its proper naming in the NETLINK.
> 
> I think you need to frame your question more specifically.
> 

Let me provide the context of what has been discussed. Essentially, the
question is what the proper name of the netlink protocol is and its file
name for the energy model.

Donald raised concerns that “em” is too cryptic, so it should be
“energy-model”. The following is Donald’s comment:


   “- I think the spec could have been called energy-model.yaml and the
    family called "energy-model" instead of "em".”


Andrew’s opinion is that it would be appropriate to limit the scope of
“energy-model” by adding a prefix, for example, “performance-domain-
energy-model”. Andrew’s comment is as follows:

   “And a dumb question. What is an energy model? A PSE needs some level
   of energy model, it needs to know how much energy each PD can consume
   in order that it is not oversubscribed. Is the energy model generic
   enough that it could be used for this? Or should this energy model get
   a prefix to limit its scope to a performance domain? The suggested
   name of this file would then become something like
   performance-domain-energy-model.yml?”

For me, “performance-domain-energy-model” sounds weird because the
performance domain is conceptually under the energy model. If adding a
prefix to limit the scope, it should be something like “system-energy-
model”, and the “system” prefix looks redundant to me.

So, the question is what the proper name is for the energy model
protocol: “em”, “energy-model”, “performance-domain-energy-model”, or
something else?

Regards,
changwoo Min

Re: Concerns with em.yaml YNL spec

[Rafael J. Wysocki]

On Mon, Dec 15, 2025 at 4:01 PM Changwoo Min <changwoo@igalia.com> wrote:
>
> Thanks, Rafael, for the comments.
>
> On 12/15/25 19:30, Rafael J. Wysocki wrote:
> > On Mon, Dec 15, 2025 at 2:57 AM Changwoo Min <changwoo@igalia.com> wrote:
> >>
> >> Hi  Andrew,
> >>
> >> On 12/15/25 01:21, Andrew Lunn wrote:
> >>>>> We also need to watch out for other meaning of these letters. In the
> >>>>> context of networking and Power over Ethernet, PD means Powered
> >>>>> Device. We generally don't need to enumerate the PD, we are more
> >>>>> interested in the Power Sourcing Equipment, PSE.
> >>>>>
> >>>>> And a dumb question. What is an energy model? A PSE needs some level
> >>>>> of energy model, it needs to know how much energy each PD can consume
> >>>>> in order that it is not oversubscribed.Is the energy model generic
> >>>>> enough that it could be used for this? Or should this energy model get
> >>>>> a prefix to limit its scope to a performance domain? The suggested
> >>>>> name of this file would then become something like
> >>>>> performance-domain-energy-model.yml?
> >>>>>
> >>>>
> >>>> Lukasz might be the right person for this question. In my view, the
> >>>> energy model essentially provides the performance-versus-power-
> >>>> consumption curve for each performance domain.
> >>>
> >>> The problem here is, you are too narrowly focused. My introduction
> >>> said:
> >>>
> >>>>> In the context of networking and Power over Ethernet, PD means
> >>>>> Powered Device.
> >>>
> >>> You have not given any context. Reading the rest of your email, it
> >>> sounds like you are talking about the energy model/performance domain
> >>> for a collection of CPU cores?
> >>>
> >>> Now think about Linux as a whole, not the little corner you are
> >>> interested in. Are there energy models anywhere else in Linux? What
> >>> about the GPU cores? What about Linux regulators controlling power to
> >>> peripherals? I pointed out the use case of Power over Ethernet needing
> >>> an energy model.
> >>>
> >>>> Conceptually, the energy model covers the system-wide information; a
> >>>> performance domain is information about one domain (e.g., big/medium/
> >>>> little CPU blocks), so it is under the energy model; a performance state
> >>>> is one dot in the performance-versus-power-consumption curve of a
> >>>> performance domain.
> >>>>
> >>>> Since the energy model covers the system-wide information, energy-
> >>>> model.yaml (as Donald suggested) sounds better to me.
> >>>
> >>> By system-wide, do you mean the whole of Linux? I could use it for
> >>> GPUs, regulators, PoE? Is it sufficiently generic? I somehow doubt it
> >>> is. So i think you need some sort of prefix to indicate the domain it
> >>> is applicable to. We can then add GPU energy models, PoE energy
> >>> models, etc by the side without getting into naming issues.
> >>>
> >>
> >> This is really the question for the energy model maintainers. In my
> >> understanding, the energy model can cover any device in the system,
> >> including GPUs.
> >
> > That's correct.
> >
> >> But, in my limited experience, I haven’t seen such cases beyond CPUs.
> >>
> >> @Lukasz — What do you think? The focus here is on the scope of the
> >> “energy model” and its proper naming in the NETLINK.
> >
> > I think you need to frame your question more specifically.
> >
>
> Let me provide the context of what has been discussed. Essentially, the
> question is what the proper name of the netlink protocol is and its file
> name for the energy model.
>
> Donald raised concerns that “em” is too cryptic, so it should be
> “energy-model”. The following is Donald’s comment:
>
>
>    “- I think the spec could have been called energy-model.yaml and the
>     family called "energy-model" instead of "em".”
>
>
> Andrew’s opinion is that it would be appropriate to limit the scope of
> “energy-model” by adding a prefix, for example, “performance-domain-
> energy-model”. Andrew’s comment is as follows:
>
>    “And a dumb question. What is an energy model? A PSE needs some level
>    of energy model, it needs to know how much energy each PD can consume
>    in order that it is not oversubscribed. Is the energy model generic
>    enough that it could be used for this? Or should this energy model get
>    a prefix to limit its scope to a performance domain? The suggested
>    name of this file would then become something like
>    performance-domain-energy-model.yml?”
>
> For me, “performance-domain-energy-model” sounds weird because the
> performance domain is conceptually under the energy model. If adding a
> prefix to limit the scope, it should be something like “system-energy-
> model”, and the “system” prefix looks redundant to me.
>
> So, the question is what the proper name is for the energy model
> protocol: “em”, “energy-model”, “performance-domain-energy-model”, or
> something else?

I personally would be for something like "device-energy-model", where
"device" may mean any kind of device including CPU devices.

Re: Concerns with em.yaml YNL spec

[Changwoo Min]

On 12/16/25 00:06, Rafael J. Wysocki wrote:
> On Mon, Dec 15, 2025 at 4:01 PM Changwoo Min <changwoo@igalia.com> wrote:
>>
>> Let me provide the context of what has been discussed. Essentially, the
>> question is what the proper name of the netlink protocol is and its file
>> name for the energy model.
>>
>> Donald raised concerns that “em” is too cryptic, so it should be
>> “energy-model”. The following is Donald’s comment:
>>
>>
>>     “- I think the spec could have been called energy-model.yaml and the
>>      family called "energy-model" instead of "em".”
>>
>>
>> Andrew’s opinion is that it would be appropriate to limit the scope of
>> “energy-model” by adding a prefix, for example, “performance-domain-
>> energy-model”. Andrew’s comment is as follows:
>>
>>     “And a dumb question. What is an energy model? A PSE needs some level
>>     of energy model, it needs to know how much energy each PD can consume
>>     in order that it is not oversubscribed. Is the energy model generic
>>     enough that it could be used for this? Or should this energy model get
>>     a prefix to limit its scope to a performance domain? The suggested
>>     name of this file would then become something like
>>     performance-domain-energy-model.yml?”
>>
>> For me, “performance-domain-energy-model” sounds weird because the
>> performance domain is conceptually under the energy model. If adding a
>> prefix to limit the scope, it should be something like “system-energy-
>> model”, and the “system” prefix looks redundant to me.
>>
>> So, the question is what the proper name is for the energy model
>> protocol: “em”, “energy-model”, “performance-domain-energy-model”, or
>> something else?
> 
> I personally would be for something like "device-energy-model", where
> "device" may mean any kind of device including CPU devices.
> 

"device-energy-model" sounds good to me. I will prepare the patchset
using that name. Thanks a lot!

Regards,
Changwoo Min

Re: Concerns with em.yaml YNL spec

[Andrew Lunn]

On Thu, Dec 11, 2025 at 03:54:53PM +0000, Donald Hunter wrote:
> Hi,
> 
> I just spotted the new em.yaml YNL spec that got merged in
> bd26631ccdfd ("PM: EM: Add em.yaml and autogen files") as part of [1]
> because it introduced new yamllint reports:
> 
> make -C tools/net/ynl/ lint
> make: Entering directory '/home/donaldh/net-next/tools/net/ynl'
> yamllint ../../../Documentation/netlink/specs
> ../../../Documentation/netlink/specs/em.yaml
>   3:1       warning  missing document start "---"  (document-start)
>   107:13    error    wrong indentation: expected 10 but found 12  (indentation)
> 
> I guess the patch series was never cced to netdev or the YNL
> maintainers so this is my first opportunity to review it.

Maybe submit a patch to this:

YAML NETLINK (YNL)
M:      Donald Hunter <donald.hunter@gmail.com>
M:      Jakub Kicinski <kuba@kernel.org>
F:      Documentation/netlink/
F:      Documentation/userspace-api/netlink/intro-specs.rst
F:      Documentation/userspace-api/netlink/specs.rst
F:      tools/net/ynl/

adding

F:	Documentation/netlink/specs

I'm also surprised there is no L: line in the entry.

	Andrew

Re: Concerns with em.yaml YNL spec

[Donald Hunter]

On Thu, 11 Dec 2025 at 17:04, Andrew Lunn <andrew@lunn.ch> wrote:
>
> On Thu, Dec 11, 2025 at 03:54:53PM +0000, Donald Hunter wrote:
> > Hi,
> >
> > I just spotted the new em.yaml YNL spec that got merged in
> > bd26631ccdfd ("PM: EM: Add em.yaml and autogen files") as part of [1]
> > because it introduced new yamllint reports:
> >
> > make -C tools/net/ynl/ lint
> > make: Entering directory '/home/donaldh/net-next/tools/net/ynl'
> > yamllint ../../../Documentation/netlink/specs
> > ../../../Documentation/netlink/specs/em.yaml
> >   3:1       warning  missing document start "---"  (document-start)
> >   107:13    error    wrong indentation: expected 10 but found 12  (indentation)
> >
> > I guess the patch series was never cced to netdev or the YNL
> > maintainers so this is my first opportunity to review it.
>
> Maybe submit a patch to this:
>
> YAML NETLINK (YNL)
> M:      Donald Hunter <donald.hunter@gmail.com>
> M:      Jakub Kicinski <kuba@kernel.org>
> F:      Documentation/netlink/
> F:      Documentation/userspace-api/netlink/intro-specs.rst
> F:      Documentation/userspace-api/netlink/specs.rst
> F:      tools/net/ynl/
>
> adding
>
> F:      Documentation/netlink/specs

It is covered by the Documentation/netlink/ entry:

./scripts/get_maintainer.pl Documentation/netlink/specs/em.yaml
Lukasz Luba <lukasz.luba@arm.com> (maintainer:ENERGY MODEL)
"Rafael J. Wysocki" <rafael@kernel.org> (maintainer:ENERGY MODEL)
Donald Hunter <donald.hunter@gmail.com> (maintainer:YAML NETLINK (YNL))
Jakub Kicinski <kuba@kernel.org> (maintainer:YAML NETLINK (YNL))
[...]

>
> I'm also surprised there is no L: line in the entry.

That's something we should address, thanks!

Re: Concerns with em.yaml YNL spec

[Andrew Lunn]

> It is covered by the Documentation/netlink/ entry:
> 
> ./scripts/get_maintainer.pl Documentation/netlink/specs/em.yaml
> Lukasz Luba <lukasz.luba@arm.com> (maintainer:ENERGY MODEL)
> "Rafael J. Wysocki" <rafael@kernel.org> (maintainer:ENERGY MODEL)
> Donald Hunter <donald.hunter@gmail.com> (maintainer:YAML NETLINK (YNL))
> Jakub Kicinski <kuba@kernel.org> (maintainer:YAML NETLINK (YNL))

Yep. So it should of gone flying passed on the netdev list.

But it did not:

https://lore.kernel.org/all/20251014001055.772422-4-changwoo@igalia.com/

Very little of what get_maintainers suggest should be in Cc: is
actually in Cc: :-(

	Andrew

Re: Concerns with em.yaml YNL spec

[Changwoo Min]

Hi Donald,



Thanks for the feedback. I rearranged a paragraph in the original email
for easier reply.


On 12/12/25 00:54, Donald Hunter wrote:
> Hi,
> 

 > I guess the patch series was never cced to netdev or the YNL
 > maintainers so this is my first opportunity to review it.
 >

You are right. I think I ran get_maintainer.pl only before adding
em.yaml. That's my bad.

> I just spotted the new em.yaml YNL spec that got merged in
> bd26631ccdfd ("PM: EM: Add em.yaml and autogen files") as part of [1]
> because it introduced new yamllint reports:
> 
> make -C tools/net/ynl/ lint
> make: Entering directory '/home/donaldh/net-next/tools/net/ynl'
> yamllint ../../../Documentation/netlink/specs
> ../../../Documentation/netlink/specs/em.yaml
>    3:1       warning  missing document start "---"  (document-start)
>    107:13    error    wrong indentation: expected 10 but found 12  (indentation)
>

I will fix these lint warnings. Besides fixing those warnings, it would
be useful to mention running lint somewhere. If there is a general
guideline for adding a new netlink YAML, I will revise it in a separate
patch.

> Other than the lint messages, there are a few concerns with the
> content of the spec:
> 
> - pds, pd and ps might be meaningful to energy model experts but they
> are pretty meaningless to the rest of us. I see they are spelled out
> in the energy model header file so it would be better to use
> perf-domain, perf-table and perf-state here.
> 

That makes sense. I will change as suggested.

> - I think the spec could have been called energy-model.yaml and the
> family called "energy-model" instead of "em".
> 
> - the get-pds should probably be both do and dump which would give
> multi responses without the need for the pds attribute set (unless I'm
> missing something).
 >

TODO


> - there are 2 flags attributes that are bare u64 which should have
> flags definitions in the YNL. Have a look at e.g. netdev.yaml to see
> examples of flags definitions.
> 

Okay. I will add the following (from energy_model.h) for the flags:

#define EM_PERF_DOMAIN_MICROWATTS BIT(0)
#define EM_PERF_DOMAIN_SKIP_INEFFICIENCIES BIT(1)
#define EM_PERF_DOMAIN_ARTIFICIAL BIT(2)

> - the cpus attribute is a string which would appear to be a "%*pb"
> stringification of a bitmap. That's not very consumable for a UAPI and
> should probably use netlink bitmask or an array of cpu numbers or
> something.
> 

Okay. I will change the string representation to an integer array of CPU
numbers.

> - there are no doc strings for any of the attributes. It would be
> great to do better for new YNL specs, esp. since there is better
> information in energy_model.h
> 

Sure, I will add doc strings based on the comments in the
energy_model.h.

> Given that netlink is UAPI, I think we need to address these issues
> before v6.19 gets released.

Sure. I will prepare the changes quickly.

Regards,
Changwoo Min

> 
> Thanks,
> Donald Hunter.
> 
> [1] https://lore.kernel.org/all/20251020220914.320832-4-changwoo@igalia.com/
> 

Re: Concerns with em.yaml YNL spec

[Changwoo Min]

On 12/14/25 20:14, Changwoo Min wrote:

>> - I think the spec could have been called energy-model.yaml and the
>> family called "energy-model" instead of "em".
>>
>> - the get-pds should probably be both do and dump which would give
>> multi responses without the need for the pds attribute set (unless I'm
>> missing something).
>  >
> 

Will change as you suggested.

Regards,
Changwoo Min

Re: Concerns with em.yaml YNL spec

[Donald Hunter]

Changwoo Min <changwoo@igalia.com> writes:

> Hi Donald,
>
> Thanks for the feedback. I rearranged a paragraph in the original email
> for easier reply.
>
> On 12/12/25 00:54, Donald Hunter wrote:
>> Hi,
>>
>> I guess the patch series was never cced to netdev or the YNL
>> maintainers so this is my first opportunity to review it.
>>
>
> You are right. I think I ran get_maintainer.pl only before adding
> em.yaml. That's my bad.
>
>> I just spotted the new em.yaml YNL spec that got merged in
>> bd26631ccdfd ("PM: EM: Add em.yaml and autogen files") as part of [1]
>> because it introduced new yamllint reports:
>> make -C tools/net/ynl/ lint
>> make: Entering directory '/home/donaldh/net-next/tools/net/ynl'
>> yamllint ../../../Documentation/netlink/specs
>> ../../../Documentation/netlink/specs/em.yaml
>>    3:1       warning  missing document start "---"  (document-start)
>>    107:13    error    wrong indentation: expected 10 but found 12  (indentation)
>>
>
> I will fix these lint warnings. Besides fixing those warnings, it would
> be useful to mention running lint somewhere. If there is a general
> guideline for adding a new netlink YAML, I will revise it in a separate
> patch.

I have a patch ready for the next merge window that adds a lint target.
For now you can run:

yamllint Documentation/netlink/specs

You're right, we don't have a guide for adding new netlink YAML but
that's something I should add to the series I have pending.

Thanks,
Donald.