Bug 5092

This should be in the kernel architecture manual, I'll double check. If not, we'll get it into the main docs.

We need to cautious regarding what we put in the architecture manual. If the information is needed to make use of the linux-yocto tooling for BSPs or recipes, it belongs in the development manual. This particular bit strikes me as borderline. You can certainly make use of the tooling without knowing about this file. In regards to Peter's complaint, I think perhaps just renaming hardware.cfg that doesn't make it look like a config fragment would be a reasonable thing to do.

(In reply to comment #2)
> We need to cautious regarding what we put in the architecture manual. If the
> information is needed to make use of the linux-yocto tooling for BSPs or
> recipes, it belongs in the development manual. This particular bit strikes
> me as borderline. You can certainly make use of the tooling without knowing
> about this file. In regards to Peter's complaint, I think perhaps just
> renaming hardware.cfg that doesn't make it look like a config fragment would
> be a reasonable thing to do.

Long term .. sure, but there are a lot of layers and directories with hardware.cfg files
around, so the tools will need to keep compatibility with the old name.

I've considered renaming it in the past, and never got around to it before. 

Something to look into for 1.6 indeed.

For the manual updates on this, we can say:

hardware.cfg is a special file that contains kernel configuration audit information, 
that when found in the directory of a kernel feature description (.scc file) indicates
the kernel options listed in that file should be considered hardware. Hardware 
options are valid for BSPs, and hence, no warning will be issued if they are set.

They are an unordered, list of options without assigned values (CONFIG_FOO
versus CONFIG_FOO=y)

The suggested manual addition tells me what it is, but not how to use it.

I definitely think it needs to be in whatever manual you expect to be consulted by people who are developing a new BSP.  For example, my target is a gumstix OMAP DM3730 board much like but not the same as the beagleboard.  The beagleboard hardware.cfg I used as a model has stuff in it that's not right (e.g. wifi hardware that doesn't exist on the gumstix or even on a stock beagleboard AFAIK).

If the tooling is going to try to help me by validating my configuration, I need to feed it the right information so its information is useful.  Which means I need a correct hardware.cfg file, which means I need to know what goes into it, what doesn't, and why.  More, how the thing is found and processed should be documented, since it's not explicitly referenced in the root BSP scc file, and it's not at all clear that a recipe-space version can be provided, or that one can split it into different chunks (e.g. share a DM3730 hardware.cfg but augment it with hardware specific to a particular board).  Without that information, the distinction between hardware and non-hardware configuration items has no significance.

The file absolutely should have a different extension since .cfg is clearly documented to use a format this does not match.  It seems reasonable to do that early in 1.6.  Whether the tools will accept "hardware.cfg" instead of "hardware.kvars" or whatever is a design decision but any examples that are publicly found should be renamed, otherwise we carry brokenness and confusion with us forever.

(In reply to comment #5)
> The suggested manual addition tells me what it is, but not how to use it.
> 
> I definitely think it needs to be in whatever manual you expect to be
> consulted by people who are developing a new BSP.  For example, my target is
> a gumstix OMAP DM3730 board much like but not the same as the beagleboard. 
> The beagleboard hardware.cfg I used as a model has stuff in it that's not
> right (e.g. wifi hardware that doesn't exist on the gumstix or even on a
> stock beagleboard AFAIK).
> 
> If the tooling is going to try to help me by validating my configuration, I
> need to feed it the right information so its information is useful.  Which

To be honest, most users have indicated they aren't interested in the audit
output, so we are a small few that really care :)

But yes, I completely agree.

> means I need a correct hardware.cfg file, which means I need to know what
> goes into it, what doesn't, and why.  More, how the thing is found and
> processed should be documented, since it's not explicitly referenced in the
> root BSP scc file, and it's not at all clear that a recipe-space version can
> be provided, or that one can split it into different chunks (e.g. share a
> DM3730 hardware.cfg but augment it with hardware specific to a particular
> board).  Without that information, the distinction between hardware and
> non-hardware configuration items has no significance.

To be clear, this is an internal file for the most part, and it already has some
pending replacements that are in 1.6, see the "required" and "optional" keywords
that have been pre-positioned in the tools and will start replacing the hadware
and non-hardware designations in 16. At that time, the plan is to have a full
doc update, so as it stands, we want to keep hardware.cfg and non-hardware.cfg
under the covers as much as possible. No sense increasing migration pain right
before the change over.

We are talking about a much more in depth use case than 95% of the existing
users are interested in, and it can't be presented first in the manuals, since it
is exactly the barrier to entry that we've been removing. 

This is what I hoped would happen, someone with a deeper use case would
ask, and we can generate the right updates as a result, and put it somewhere
that more can find.

So my suggestion is that this goes into an appendix/extra use case doc for 
1.5,and then migrated in 1.6.

I can provide the updates, but I don't want this overly visible for 1.5.

> 
> The file absolutely should have a different extension since .cfg is clearly
> documented to use a format this does not match.  It seems reasonable to do
> that early in 1.6.  Whether the tools will accept "hardware.cfg" instead of
> "hardware.kvars" or whatever is a design decision but any examples that are
> publicly found should be renamed, otherwise we carry brokenness and

For 1.5, no such renaming will happen, public of not. For 1.6, optional/required
will come into play and the move will happen then.

> confusion with us forever.

Moving this to 1.7, since we'll be doing this as part of "developer experience"

I spoke with Bruce yesterday about this bug.
It might still get addressed for 1.8-M4 but it's a low priority so 1.9, which is what Saul set this to yesterday is fine.

I'll keep this. no need to re-assign it. There are some larger meta data changes in 2.1, so I'll take care of all the doc updates then.

Doc update send to ScottR

I looked at the stuff Bruce gave me in an email for this bug.  It basically describes part of the kernel configuration audit phase.  Bruce describes how hardware and non-hardware features are figured out and the use of .cfg and .kcf files are used.

I am not sure where to provide this low-level conceptual information.  There is a section in the dev-manual (http://www.yoctoproject.org/docs/2.1/dev-manual/dev-manual.html#configuring-the-kernel) where we could create a new subsection to describe this audit stuff.  There is also this section in the kernel-dev manual (http://www.yoctoproject.org/docs/2.1/kernel-dev/kernel-dev.html#configuration) where configuration is described a bit and mentions the audit part near the end.  

I need some help on where we want to put this information.

Thanks, 
Scott

(In reply to comment #11)
> I looked at the stuff Bruce gave me in an email for this bug.  It basically
> describes part of the kernel configuration audit phase.  Bruce describes how
> hardware and non-hardware features are figured out and the use of .cfg and
> .kcf files are used.
> 
> I am not sure where to provide this low-level conceptual information.  There
> is a section in the dev-manual
> (http://www.yoctoproject.org/docs/2.1/dev-manual/dev-manual.html#configuring-
> the-kernel) where we could create a new subsection to describe this audit
> stuff.  There is also this section in the kernel-dev manual
> (http://www.yoctoproject.org/docs/2.1/kernel-dev/kernel-dev.
> html#configuration) where configuration is described a bit and mentions the
> audit part near the end.  
> 
> I need some help on where we want to put this information.
> 
> Thanks, 
> Scott

A new subsection in: http://www.yoctoproject.org/docs/2.1/dev-manual/dev-manual.html#configuring-the-kernel, seems like the best place .. not perfect, but best.

This is fairly low level info, and isn't normally something to worry about, so we should put a disclaimer to that effect in the section.

Hi, 

Here is the new subsection in the dev-manual - http://www.yoctoproject.org/docs/2.1/dev-manual/dev-manual.html#determining-hardware-and-non-hardware-features-for-the-kernel-configuration-audit-phase.  I am not happy with the title as it seems very long.  However, I did not really know what to put there as a title.  To me, this is what the section is about.  If anyone can better describe what we are really talking about it would be better.

Please look the text over as I adapted it from what Bruce sent me.  There might be issues with it that need correction.  Sometimes rewriting stuff changes the meaning unintentionally.  

Note that I am not messing with the status of this bug (IN PROGRESS DESIGN) since I am not the owner of the bug at the moment.

Thanks, 
Scott

(In reply to comment #13)
> Hi, 
> 
> Here is the new subsection in the dev-manual -
> http://www.yoctoproject.org/docs/2.1/dev-manual/dev-manual.html#determining-
> hardware-and-non-hardware-features-for-the-kernel-configuration-audit-phase.
> I am not happy with the title as it seems very long.  However, I did not
> really know what to put there as a title.  To me, this is what the section
> is about.  If anyone can better describe what we are really talking about it
> would be better.
> 
> Please look the text over as I adapted it from what Bruce sent me.  There
> might be issues with it that need correction.  Sometimes rewriting stuff
> changes the meaning unintentionally.  
> 
> Note that I am not messing with the status of this bug (IN PROGRESS DESIGN)
> since I am not the owner of the bug at the moment.
> 
> Thanks, 
> Scott

I read the section, and this captures it quite well. Actually, I have no suggestions for changes :)

I'm marking this as 'resolved', since I assume that after this review the doc change will make it into public versions.

Thanks... setting the doc flag to "done."

Scott

Documentation is done.