diff --git a/documentation/dev-manual/dev-manual-kernel-appendix.xml b/documentation/dev-manual/dev-manual-kernel-appendix.xml
index 8a80d54356..787be3df5d 100644
--- a/documentation/dev-manual/dev-manual-kernel-appendix.xml
+++ b/documentation/dev-manual/dev-manual-kernel-appendix.xml
@@ -5,248 +5,355 @@
Kernel Modification Example
+
+ Kernel modification involves changing or adding configurations to an existing kernel, or
+ adding recipes to the kernel that are needed to support specific hardware features.
+ The process is similar to creating a Board Support Package (BSP) except that it invloves
+ isolating your work in a kernel layer and the use of menuconfig
+ to help make configuration data easily identifiable.
+
+
+
+ This section presents a simple example that shows how to modify the kernel.
+ The example uses a three-step approach that is convenient for making kernel modifications.
+
+ Iteratively determine and set kernel configurations and make
+ kernel recipe changes.
+ Apply your configuration changes to your local kernel layer.
+
+ Push your configuration and recipe changes upstream into the
+ Yocto Project source repositories to make them available to the community.
+
+
+
+
+
+ Modifying a Kernel Example
+
- Kernel modification involves changing or adding configurations to an existing kernel, or
- adding recipes to the kernel that are needed to support specific hardware features.
- The process is similar to creating a Board Support Package (BSP) except that it invloves
- isolating your work in a kernel layer and the use of menuconfig
- to help make configuration data easily identifiable.
+ The example changes kernel configurations to support the VFAT filesystem and
+ allow the user to print out a simple text file from the mounted VFAT filesystem.
+ The filesystem used will be an image filesystem rather than a filesystem on some
+ external drive such as a USB stick or external drive.
+ The example uses the linux-yocto-2.6.37 kernel.
- This section presents a brief overview of the kernel structure and then provides a simple
- example that shows how to modify the kernel.
+ For a general flow of the example, see
+ Kernel Modification Workflow
+ earlier in this manual.
-
- Yocto Project Kernel Overview
+
+ Setting Up Yocto Project
- When one thinks of the source files for a kernel they usually think of a fixed structure
- of files that contain kernel patches.
- The Yocto Project, however, employs mechanisims that in a sense result in a kernel source
- generator.
+ You need to have the Yocto Project files available on your host system.
+ You can get files through tarball extraction or by cloning the poky
+ Git repository.
+ See the bulleted item
+ Yocto Project Release in
+ Getting Setup earlier in this manual
+ for information on how to get these files.
- The Yocto Project uses the source code management (SCM) tool Git to manage and track Yocto
- Project files.
- Git employs branching strategies that effectively produce a tree-like structure whose
- branches represent diversions from more general code.
- For example, suppose two kernels are basically identical with the exception of a couple
- different features in each.
- In the Yocto Project source repositories managed by Git a main branch can contain the
- common or shared
- parts of the kernel source and two branches that diverge from that common branch can
- each contain the features specific to the respective kernel.
- The result is a managed tree whose "leaves" represent the end of a specific path that yields
- a set of kernel source files necessary for a specific piece of hardware and its features.
-
-
-
- A big advantage to this scheme is the sharing of common features by keeping them in
- "larger" branches that are further up the tree.
- This practice eliminates redundant storage of similar features shared among kernels.
-
-
-
- When you build the kernel on your development system all files needed for the build
- are taken from the Yocto Project source repositories pointed to by the
- SRC_URI variable and gathered in a temporary work area
- where they are subsequently used to create the unique kernel.
- Thus, in a sense, the process constructs a local source tree specific to your
- kernel to generate the new kernel image - a source generator if you will.
-
-
-
- For a complete discussion of the Yocto Project kernel's architcture and its branching strategy,
- see the
- The Yocto Project Kernel Architecture and Use Manual.
-
-
-
- You can find a web interface to the Yocto Project source repository at
- .
- Within the interface you will see groups of related source code, each of which can
- be cloned using Git to result in a working Git repository on your local system
- (referred to as the "local Yocto Project files" in this manual).
- The Yocto Project supports four types of kernels in its source repositories at
- :
-
- linux-yocto-2.6.34 - The
- stable Linux Yocto kernel that is based on the Linux 2.6.34 release.
- linux-yocto-2.6.37 - The current
- Linux Yocto kernel that is based on the Linux 2.6.37 release.
- linux-yocto-dev - A development
- kernel based on the Linux 2.6.39-rc1 release.
- linux-2.6 - A kernel based on
- minimal Linux mainline tracking.
- [WRITER'S NOTE: I don't know which Git repository the user needs to clone to get this
- repository on their development system.]
-
+ Once you have the local poky Git repository set up,
+ you have many development branches from which you can work.
+ From inside the repository you can see the branch names and the tag names used
+ in the Git repository using either of the following two commands:
+
+ $ git branch -a
+ $ git tag -l
+
+ For this example we are going to use the Yocto Project 1.1 Release,
+ which maps to the 1.1 branch in the repository.
+ These commands create a local branch named 1.1
+ that tracks the remote branch of the same name.
+
+ $ cd poky
+ $ git checkout -b 1.1 origin/1.1
+ Switched to a new branch '1.1'
+
-
- Modifying a Kernel Example
+
+ Getting a Local Copy of the Kernel Files
- This section presents a simple example that illustrates kernel modification
- based on the linux-yocto-2.6.37 kernel.
- The example uses the audio and mixer capabilities supported by the
- Advanced Linux
- Sound Architecture (ALSA) Project.
- As the example progresses you will see how to do the following:
-
- Iteratively modify a base kernel locally.
- Provide a recipe-based solution for your modified kernel.
-
- Proved an "in-tree" solution for your modified kernel
- (i.e. make the modifcations part of the Yocto Project).
-
+ You need to have a local copy of the Linux Yocto kernel files on your system.
+ Yocto Project files available on your host system.
+ You must create a local Git repository of these files.
+ See the bulleted item
+ Linux Yocto Kernel in
+ Getting Setup earlier in this manual
+ for information on how to get these files.
+
+
+
+
+ Create a Layer for Your Kernel Work
+
+
+ It is always good to isolate your work using your own layer.
+ Doing so allows you to experiment and easily start over should things go wrong.
+ This example uses a layer named meta-vfatsupport.
- The example flows as follows:
+ When you set up a layer for kernel work you should follow general layout
+ guidelines layers.
+ For example, if you were creating a BSP you would want to follow the layout
+ described in the
+
+ Example Filesystem Layout section of the Board Support Package (BSP) Development
+ Guide.
+ For kernel layers, you can start with a skeleton layer
+ named meta-skeleton found in your local
+ Yocto Project file directory structure (the poky Git
+ repository or the directory structure resulting from unpacking the Yocto Project
+ release tarball).
+
+
+
+ To create your kernel layer simply copy the meta-skeleton
+ layer and rename it meta-vfatsupport.
+ The following command sets up the layer inside the poky
+ Git repository:
+
+ $ cd ~/poky
+ $ cp -r meta-skeleton meta-vfatsupport
+
-
- Be sure your host development system is set up to support
- development using the Yocto Project.
- See
-
- The Linux Distributions section and
-
- The Packages section both
- in the Yocto Project Quick Start for requirements.
- You will also need a release of Yocto Project installed on the host.
- Set up your environment for optimal local kernel development.
-
- Create a layer to isolate your kernel work.
- Next item.
- Next item.
- Next item.
- Next item.
-
+ In the new layer you will find areas for configuration changes
+ (conf) and recipe changes (recipes-skeleton).
-
- Setting Up Yocto Project
+
+ You need to modify the structure a bit for your work.
+ These commands add some further structure and names that the Yocto Project build
+ environment expect:
+
+ $ mkdir meta-vfatsupport/images
+ $ mkdir meta-vfatsupport/recipes-bsp
+ $ mv meta-vfatsupport/recipes-skeleton meta-vfatsupport/recipes-kernel
+ $ mkdir meta-vfatsupport/recipes-kernel/linux
+ $ mkdir meta-vfatsupport/recipes-kernel/linux/linux-yocto
+
+
-
- You need to have the Yocto Project files available on your host system.
- The process is identical to that described in the
- "Getting Setup" section earlier in this
- manual.
- Be sure to either set up a local Git repository for poky
- or download and unpack the Yocto Project release tarball.
-
-
+
+ The last piece you need for your layer is a
+ linux-yocto_git.bbappend file inside
+ meta-vfatsupport/recipes-kernel/linux.
+ This file needs the following content to make the build process aware of the
+ new layer's location:
+
+ FILESEXTRAPATHS := "${THISDIR}/${PN}"
+
+
-
- Create a Git Repository of <filename>poky-extras</filename>
+
+ [WRITER'S NOTE: We need a better meta-skeleton layer
+ that is part of poky.
+ It should have a structure that includes images,
+ recipes-bsp, recipes-kernel, and
+ so forth.
+ For now this step of the example is brute-forcing the structure with shell
+ commands to set up the minimum structure and include the
+ .bbappend file.
+
+
-
- Everytime you change a configuration or add a recipe to the kernel you need to
- do a fetch from the Linux Yocto kernel source repositories.
- This can get tedious and time consuming if you need to fetch the entire
- Linux Yocto 2.6.37 Git repository down from the Internet everytime you make a change
- to the kernel.
-
-
-
- You can get around this by setting up a meta-kernel-dev
- area on your local system.
- This area contains "append" files for every kernel recipe, which also include
- a KSRC statement that points to the kernel source files.
- You can set up the environment so that the KSRC points to the
- meta-kernel-dev, thus pulling source from a local area.
- This setup can speed up development time.
-
-
-
- To get set up you need to do two things: create a local Git repository
- of the poky-extras repository, and create a bare clone of the
- Linux Yocto 2.6.37 kernel Git repository.
-
-
-
- The following transcript shows how to clone the poky-extras
- Git repository into the current working directory, which is poky
- in this example.
- The command creates the repository in a directory named poky-extras:
-
- $ git clone git://git.yoctoproject.org/poky-extras
- Initialized empty Git repository in /home/scottrif/poky/poky-extras/.git/
- remote: Counting objects: 532, done.
- remote: Compressing objects: 100% (472/472), done.
- remote: Total 532 (delta 138), reused 307 (delta 39)
- Receiving objects: 100% (532/532), 534.28 KiB | 362 KiB/s, done.
- Resolving deltas: 100% (138/138), done.
-
-
-
-
- This transcript shows how to clone a bare Git repository of the Linux Yocto
- 2.6.37 kernel:
-
- $ git clone --bare git://git.yoctoproject.org/linux-yocto-2.6.37
- Initialized empty Git repository in /home/scottrif/linux-yocto-2.6.37.git/
- remote: Counting objects: 1886034, done.
- remote: Compressing objects: 100% (314326/314326), done.
- remote: Total 1886034 (delta 1570202), reused 1870335 (delta 1554798)
- Receiving objects: 100% (1886034/1886034), 401.51 MiB | 714 KiB/s, done.
- Resolving deltas: 100% (1570202/1570202), done.
-
-
-
-
- The bare clone of the Linux Yocto 2.6.37 kernel on your local system mirrors
- the upstream repository of the kernel.
- You can effectively point to this local clone now during development to avoid
- having to fetch the entire Linux Yocto 2.6.37 kernel every time you make a
- kernel change.
-
-
-
-
- Create a Layer for Your Kernel Work
-
-
- It is always good to isolate your work using your own layer.
- Doing so allows you to experiment and easily start over should things go wrong.
- This example uses a layer named meta-amixer.
-
-
-
- When you set up a layer for kernel work you should follow the general layout
- guidelines as described for BSP layers.
- This layout is described in the
-
- Example Filesystem Layout section of the Board Support Package (BSP) Development
- Guide.
- In the standard layout you will notice a suggested structure for recipes and
- configuration information.
- [WRITER'S NOTE: The meta-elc example uses an
- images directory.
- Currently, images is not part of the standard BSP layout.
- I need to find out from Darren if this directory is required for kernel work.]
-
-
-
- [WRITER'S NOTE: I need a paragraph here describing how to set up the layer.
- I am not sure if you should copy an existing BSP layer and modify from there.
- Or, if you should just look at a BSP layer and then create your own files.
- Email to Darren on this but no answer yet.]
-
-
-
-
- Making Changes to Your Kernel Layer
+
+ Prepare to use <filename>menuconfig</filename>
-
- In the standard layer structure you have several areas that you need to examine or
+
+ The menuconfig tool provides an interactive method with which
+ to set kernel configurations.
+ In order to use menuconfig from within the BitBake environment
+ you need to source an environment setup script.
+ This script is located in the local Yocto Project file structure and is called
+ oe-init-build-env.
+
+
+
+ The following command sets up the environment:
+
+ $ cd ~/poky
+ $ source oe-init-build-env
+
+
+
+
+
+ Make Configuration Changes to the Kernel
+
+
+ After setting up the environment to run menuconfig you are ready
+ to use the tool to interactively change the kernel configuration.
+ In this example we are basing our changes on the linux-yocto-2.6.37
+ kernel.
+ The Yocto Project build environment recognizes this kernel as
+ linux-yocto.
+ Thus, the following command from the shell in which you previously sourced the
+ environment initialization script launches menuconfig:
+
+ $ bitbake linux-yocto -c menuconfig
+
+
+
+
+ [WRITER'S NOTE: Stuff from here down are crib notes]
+
+
+
+ Once menuconfig fires up you see all kinds of categories that you can interactively
+ investigate.
+ If they have an "M" in it then the feature is "modularized".
+ I guess that means that means that it needs to be manually linked in when the
+ kernel is booted??? (Not sure).
+ If they have an "*" then the feature is automatically part of the kernel.]
+
+
+
+ So the tmp/work/ area was created in poky and there is a .config file in there and
+ a .config.old file.
+ The old one must have been created when I exited from menuconfig after poking around
+ a bit.
+ Nope - appears to just be created automatically.
+
+
+
+ A good practice is to first determine what configurations you have for the kernel.
+ You can see the results by looking in the .config file in the build/tmp/work/qemux86-poky-linux area
+ of the local YP files.
+ There is a directory named linux-yocto-2.6.37* in the directory.
+ In that directory is a directory named linux-qemux86-standard-build.
+ In that directory you will find a file named .config that is the configuration file
+ for the kernel that will be used when you build the kernel.
+ You can open that file up and examine it.
+ If you do a search for "VFAT" you will see that that particular configuration is not
+ enabled for the kernel.
+ This means that you cannot print a VFAT text file, or for that matter, even mount one
+ from the image if you were to build it at this point.
+
+
+
+ You can prove the point by actually trying it at this point.
+ Here are the commands:
+
+ $ mkdir ~/vfat-test
+ $ cd ~/vfat-test
+ $ dd if=/dev/zero of=vfat.img bs=1024 count=5000 [creates a 5MB disk image]
+ 5+0 records in
+ 5+0 records out
+ 5242880 bytes (5.2 MB) copied, 0.00798912 s, 656 MB/s
+ $ ls -lah [lists the contents of the new image. l=long, a=all, h=human readable]
+ total 5.1M
+ drwxr-xr-x 2 srifenbark scottrif 4.0K 2011-08-01 08:18 .
+ drwxr-xr-x 66 srifenbark scottrif 4.0K 2011-08-01 08:14 ..
+ -rw-r--r-- 1 srifenbark scottrif 5.0M 2011-08-01 08:18 vfat.img
+ $ mkfs.vfat vfat.img [formats the disk image]
+ mkfs.vfat 3.0.7 (24 Dec 2009)
+ $ mkdir mnt [mounts the disk image]
+ $ sudo su [gives you root privilege]
+ # mount -o loop vfat.img mnt [mounts it as a loop device]
+ # ls mnt [shows nothing in mnt]
+ # mount [lists the mounted filesystems - note/dev/loop0]
+ /dev/sda1 on / type ext4 (rw,errors=remount-ro)
+ proc on /proc type proc (rw,noexec,nosuid,nodev)
+ none on /sys type sysfs (rw,noexec,nosuid,nodev)
+ none on /sys/fs/fuse/connections type fusectl (rw)
+ none on /sys/kernel/debug type debugfs (rw)
+ none on /sys/kernel/security type securityfs (rw)
+ none on /dev type devtmpfs (rw,mode=0755)
+ none on /dev/pts type devpts (rw,noexec,nosuid,gid=5,mode=0620)
+ none on /dev/shm type tmpfs (rw,nosuid,nodev)
+ none on /var/run type tmpfs (rw,nosuid,mode=0755)
+ none on /var/lock type tmpfs (rw,noexec,nosuid,nodev)
+ none on /lib/init/rw type tmpfs (rw,nosuid,mode=0755)
+ binfmt_misc on /proc/sys/fs/binfmt_misc type binfmt_misc (rw,noexec,nosuid,nodev)
+ gvfs-fuse-daemon on /home/scottrif/.gvfs type fuse.gvfs-fuse-daemon (rw,nosuid,nodev,user=srifenbark)
+ /dev/loop0 on /home/scottrif/vfat-test/mnt type vfat (rw)
+ # echo "hello world" > mnt/hello.txt [creates a text file in the mounted VFAT system]
+ # ls mnt [verifies the file is there]
+ hello.txt
+ # cat mnt/hello.txt [displays the contents of the file created]
+ hello world
+ # umount mnt [unmounts the system and destroys the loop]
+ # exit [gets out of privileged user mode]
+ exit
+
+ $ lsmod [this stuff Darren did to show me ]
+ Module Size Used by [the status of modules in the regular linux kernel]
+ nls_iso8859_1 4633 0
+ nls_cp437 6351 0
+ vfat 10866 0
+ fat 55350 1 vfat
+ snd_hda_codec_atihdmi 3023 1
+ binfmt_misc 7960 1
+ snd_hda_codec_realtek 279008 1
+ ppdev 6375 0
+ snd_hda_intel 25805 2
+ fbcon 39270 71
+ tileblit 2487 1 fbcon
+ font 8053 1 fbcon
+ bitblit 5811 1 fbcon
+ snd_hda_codec 85759 3 snd_hda_codec_atihdmi,snd_hda_codec_realtek,snd_hda_intel
+ softcursor 1565 1 bitblit
+ snd_seq_dummy 1782 0
+ snd_hwdep 6924 1 snd_hda_codec
+ vga16fb 12757 0
+ snd_pcm_oss 41394 0
+ snd_mixer_oss 16299 1 snd_pcm_oss
+ snd_pcm 87946 3 snd_hda_intel,snd_hda_codec,snd_pcm_oss
+ vgastate 9857 1 vga16fb
+ snd_seq_oss 31191 0
+ snd_seq_midi 5829 0
+ snd_rawmidi 23420 1 snd_seq_midi
+ radeon 744506 3
+ snd_seq_midi_event 7267 2 snd_seq_oss,snd_seq_midi
+ ttm 61007 1 radeon
+ snd_seq 57481 6 snd_seq_dummy,snd_seq_oss,snd_seq_midi,snd_seq_midi_event
+ drm_kms_helper 30742 1 radeon
+ snd_timer 23649 2 snd_pcm,snd_seq
+ snd_seq_device 6888 5 snd_seq_dummy,snd_seq_oss,snd_seq_midi,snd_rawmidi,snd_seq
+ usb_storage 50377 0
+ snd 71283 16 \
+ snd_hda_codec_realtek,snd_hda_intel,snd_hda_codec, \
+ snd_hwdep,snd_pcm_oss,snd_mixer_oss,snd_pcm, \
+ snd_seq_oss,snd_rawmidi,snd_seq,snd_timer,snd_seq_device
+ soundcore 8052 1 snd
+ psmouse 65040 0
+ drm 198886 5 radeon,ttm,drm_kms_helper
+ i2c_algo_bit 6024 1 radeon
+ serio_raw 4918 0
+ snd_page_alloc 8500 2 snd_hda_intel,snd_pcm
+ dell_wmi 2177 0
+ dcdbas 6886 0
+ lp 9336 0
+ parport 37160 2 ppdev,lp
+ usbhid 41116 0
+ ohci1394 30260 0
+ hid 83888 1 usbhid
+ ieee1394 94771 1 ohci1394
+ tg3 122382 0
+
+
+
+
+
+
+
+
-