5092 2013-08-31 16:15:55 +0000 non-standard hardware.cfg content is undocumented 2016-05-11 07:57:03 +0000 1 1 6 Yocto Project Subprojects Kernel kernel-configuration 1.5 x86 Multiple VERIFIED FIXED 04 April 2016: IN PROGRESS REVIEW (docs) Low normal 2.1 1 pab bruce.ashfield bogdanx.a.voiculescu bruce.ashfield dvhart mhalstead randy.macleod sgw srifenbark yp.kernel.watcher yp.watcher bogdanx.a.voiculescu --- --- Done (doc changes complete) oldest_to_newest 36127 0 pab 2013-08-31 16:15:55 +0000 The YPLKDM specifies that .cfg files contain config file fragments, of the standard syntax: CONFIG_SMP=y # CONFIG_SMP is not set (though I don't think it notes that the latter is a directive to disable the feature, while absence of any directive is a directive to accept the default.) The meta directory contains BSP-specific files named hardware.cfg that are simply lists of kernel configuration variables exclusive of value. It lacks documentation on why this file is different, what it's used for, and why a BSP should or should not provide it. (If these files do what I think they do, it'd be worth having a way to compose them; e.g. all systems based on OMAP2/3/4 processors could share a hardware-omap2.cfg file; at this time I don't think that's worth a separate ticket.) 36129 1 bruce.ashfield 2013-09-01 05:27:51 +0000 This should be in the kernel architecture manual, I'll double check. If not, we'll get it into the main docs. 36273 2 dvhart 2013-09-04 16:53:35 +0000 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. 36275 3 bruce.ashfield 2013-09-04 17:00:49 +0000 (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. 36277 4 bruce.ashfield 2013-09-04 17:03:31 +0000 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) 36281 5 pab 2013-09-04 18:08:29 +0000 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. 36284 6 bruce.ashfield 2013-09-04 19:15:44 +0000 (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. 43450 7 bruce.ashfield 2014-05-21 14:58:14 +0000 Moving this to 1.7, since we'll be doing this as part of "developer experience" 49128 8 randy.macleod 2015-02-27 14:49:53 +0000 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. 56634 9 bruce.ashfield 2015-11-19 15:46:45 +0000 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. 60368 10 bruce.ashfield 2016-03-23 21:35:09 +0000 Doc update send to ScottR 60637 11 srifenbark 2016-03-31 23:13:41 +0000 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 60708 12 bruce.ashfield 2016-04-01 20:32:02 +0000 (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. 60752 13 srifenbark 2016-04-04 20:10:14 +0000 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 61016 14 bruce.ashfield 2016-04-11 15:38:26 +0000 (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. 61108 15 srifenbark 2016-04-12 18:21:52 +0000 Thanks... setting the doc flag to "done." Scott 62085 16 bogdanx.a.voiculescu 2016-05-11 07:57:03 +0000 Documentation is done.