From fa1fb04bbb73e45b146d0715d6131434887d4d00 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Wed, 3 Aug 2011 12:05:32 -0700 Subject: documentation/dev-manual/dev-manual-kernel-appendix.xml: partial updates various things going on in the kernel example. Far from complete. (From yocto-docs rev: 0c0548b79589a606f91bdb39e5a2ece71f4c108e) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-kernel-appendix.xml | 505 +++++++++++++-------- 1 file changed, 305 insertions(+), 200 deletions(-) (limited to 'documentation/dev-manual') 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. + 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' + - +
+ +
+ Getting a Local Copy of the Kernel Files + - 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. + 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 - 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. + 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. - 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. + 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). - 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.] - + 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 + -
-
- Modifying a Kernel Example + + In the new layer you will find areas for configuration changes + (conf) and recipe changes (recipes-skeleton). + - 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 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 + - The example flows as follows: + 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}" + - - 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. - + [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. +
-
- Setting Up Yocto Project +
+ Prepare to use <filename>menuconfig</filename> + + + 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. + - - 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 following command sets up the environment: + + $ cd ~/poky + $ source oe-init-build-env + + +
-
- Create a Git Repository of <filename>poky-extras</filename> +
+ 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 + + - - 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. - + + [WRITER'S NOTE: Stuff from here down are crib notes] + - - 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. - - + + 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.] + - - 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. - - + + 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. + - - 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. - -
+ + 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. + -
- Create a Layer for Your Kernel Work + + 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 + + +
+
+ - - 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.] - + - -- cgit v1.2.3-54-g00ecf