Bug 7753

(In reply to comment #0)
> We are missing some variables in the reference manual relating to the kernel:
> 
> * KERNEL_DEVICETREE (specific to linux-yocto kernels, or kernel recipes that
> include meta/recipes-kernel/linux/linux-dtb.inc)

Looks like KERNEL_DEVICETREE is used in the http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/recipes-kernel/linux/linux-dtb.inc type files a lot.  I don't understand the bigger of how this is used.  I need some further explanation.

> 
> * KERNEL_ALT_IMAGETYPE

This one looks like it is used in machine configuration files and similarly in some scripts.  I will need some general and specific information for it.

> 
> * KERNELDEPMODDEPEND (added recently by Martin:
> http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/
> ?id=50c2ef0a5d03626ddf037085553dc84369c72234 )

KERNELDEPMODDEPEND looks like you either leave it alone in image.bbclass if you are building a small, initramfs image.  Otherwise, you leave KERNELDEPMODDEPEND ?= "virtual/kernel:do_packagedata" as it is in the .bbclass file.  Is this right?  The user goes in and either uses this setting or comments it out?  Are there other potential settings they could use?  

The main purpose of KERNELDEPMODDEPEND is to have depmod data in PKGDATA_DIR.  We do document PKGDATA_DIR.  I don't know what "depmod" data is.  I suspect I will have to understand that to create the KERNELDEPMODDEPEND variable entry.

> 
> * We also use KERNEL_VERSION in a lot of places, although it isn't meant to
> be set by the user they might need to know it exists.

KERNEL_VERSION is in too many places for me to guess at its intent.  Is it simply "the version of the kernel"?  

> 
> * We may also want to add STAGING_KERNEL_BUILDDIR.

Looks like this is set in the bitbake configuration file as STAGING_KERNEL_BUILDDIR = "${TMPDIR}/work-shared/${MACHINE}/kernel-build-artifacts".  Does the user ever set this?  Is it simply the path to a staging directory used by the build system when it is building a kernel image?

> 
> * We need to add do_kernel_metadata and do_shared_workdir to
> documentation.conf and the task reference (8.4. Kernel-Related Tasks).

For do_kernel_metadata - It looks like the function in kernel-yocto.bbclass pretty much figures out where kernel tools are (in-tree or external) and figures out where (if any) defconfig is coming from (in or out of tree).  Are these two things the reason for the do_kernel_metadata task?

For do_shared_workdir - Not sure on this.  I found it in the kernel.bbclass file.  Looks like it saves off the kernel version and does some file copying.  I don't know enough about it to write anything really.

So I was kind of hoping I wouldn't have to dig out all the information for these, but here goes:

* KERNEL_DEVICETREE specifies name of the Linux kernel device tree .dtb file to generate. (There is also  legacy support for specifying the the full path to the .dts file, but the .dtb name is preferred). Note that in order to use this variable you must have require recipes-kernel/linux/linux-dtb.inc (or require recipes-kernel/linux/linux-yocto.inc which itself does the former) in your kernel recipe.

* KERNEL_ALT_IMAGETYPE specifies an alternate kernel image type to be created in addition to KERNEL_IMAGETYPE.

* For KERNELDEPMODDEPEND, the reference to PKGDATA_DIR is somewhat confusing - KERNELDEPMODDEPEND doesn't control the data being there, ultimately it specifies whether that data is needed or not - you'd set it in your initramfs image recipe if you do not need this data (and you want to avoid the potential dependency loop).

* KERNEL_VERSION is the version of the kernel as extracted from version.h or utsrelease.h within the kernel sources. This won't be valid until the kernel has been configured, so attempting to refer to this variable in contexts before that happens will not work.

* STAGING_KERNEL_BUILDDIR points to the directory containing the kernel build artifacts. Recipes building software that needs to access kernel build artifacts (one example being systemtap-uprobes) can look in this directory to find them after the kernel has been built.

* do_kernel_metadata: collects kernel metadata for a linux-yocto style kernel.

* do_shared_workdir: creates the shared workdir for the kernel.

As an aside, the descriptions for some of the kernel tasks in the ref manual (including the two above we are adding) are very thin. If we want something better I suspect Bruce, Richard or someone else with a better ability to explain what these tasks do will need to expand them.

Moving out of NEEDINFO

(In reply to comment #2)
> So I was kind of hoping I wouldn't have to dig out all the information for
> these, but here goes:
> 
> * KERNEL_DEVICETREE specifies name of the Linux kernel device tree .dtb file
> to generate. (There is also  legacy support for specifying the the full path
> to the .dts file, but the .dtb name is preferred). Note that in order to use
> this variable you must have require recipes-kernel/linux/linux-dtb.inc (or
> require recipes-kernel/linux/linux-yocto.inc which itself does the former)
> in your kernel recipe.

See http://www.yoctoproject.org/docs/1.9/ref-manual/ref-manual.html#var-KERNEL_DEVICETREE

> 
> * KERNEL_ALT_IMAGETYPE specifies an alternate kernel image type to be
> created in addition to KERNEL_IMAGETYPE.

http://www.yoctoproject.org/docs/1.9/ref-manual/ref-manual.html#var-KERNEL_ALT_IMAGETYPE

> 
> * For KERNELDEPMODDEPEND, the reference to PKGDATA_DIR is somewhat confusing
> - KERNELDEPMODDEPEND doesn't control the data being there, ultimately it
> specifies whether that data is needed or not - you'd set it in your
> initramfs image recipe if you do not need this data (and you want to avoid
> the potential dependency loop).

See http://www.yoctoproject.org/docs/1.9/ref-manual/ref-manual.html#var-KERNELDEPMODDEPEND

> 
> * KERNEL_VERSION is the version of the kernel as extracted from version.h or
> utsrelease.h within the kernel sources. This won't be valid until the kernel
> has been configured, so attempting to refer to this variable in contexts
> before that happens will not work.

See http://www.yoctoproject.org/docs/1.9/ref-manual/ref-manual.html#var-KERNEL_VERSION

> 
> * STAGING_KERNEL_BUILDDIR points to the directory containing the kernel
> build artifacts. Recipes building software that needs to access kernel build
> artifacts (one example being systemtap-uprobes) can look in this directory
> to find them after the kernel has been built.

See http://www.yoctoproject.org/docs/1.9/ref-manual/ref-manual.html#var-STAGING_KERNEL_BUILDDIR

> 
> * do_kernel_metadata: collects kernel metadata for a linux-yocto style
> kernel.

See http://www.yoctoproject.org/docs/1.9/ref-manual/ref-manual.html#ref-tasks-kernel_metadata

> 
> * do_shared_workdir: creates the shared workdir for the kernel.

See http://www.yoctoproject.org/docs/1.9/ref-manual/ref-manual.html#ref-tasks-shared_workdir

> 
> As an aside, the descriptions for some of the kernel tasks in the ref manual
> (including the two above we are adding) are very thin. If we want something
> better I suspect Bruce, Richard or someone else with a better ability to
> explain what these tasks do will need to expand them.

I will open an enhancement bug for this.

I set to 2.1 M4 for this.  I still need to file the bug on generally enhancing the set of descriptions.  For this bug, though, I still need someone to okay the changes I have made.  Once that is done, we can close it.

Scott

Hi, 

I am setting this bug to RESOLVED and marking the doc flag to "done."  I have opened a new bug 9376 that requests enhancing the kernel task descriptions in the ref-manual. 

Scott