mirrors/poky
1
0
Fork 0
mirror of https://git.yoctoproject.org/poky synced 2026-05-31 12:49:46 +00:00
Code Issues Projects Releases Wiki Activity

documentation/dev-manual/dev-manual-kernel-appendix.xml: partial updates

Browse Source 
various things going on in the kernel example.  Far from complete.

(From yocto-docs rev: 0c0548b79589a606f91bdb39e5a2ece71f4c108e)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark
2011-08-03 12:05:32 -07:00
committed by Richard Purdie
parent 07544deddc
commit fa1fb04bbb
1 changed files with 322 additions and 217 deletions
Download Patch File Download Diff File Expand all files Collapse all files
documentation/dev-manual/dev-manual-kernel-appendix.xml
+312 -207
View File
@@ -5,248 +5,355 @@
<title>Kernel Modification Example</title> <title>Kernel Modification Example</title>
<para>
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 <filename>menuconfig</filename>
to help make configuration data easily identifiable.
</para>
<para>
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.
<orderedlist>
<listitem><para>Iteratively determine and set kernel configurations and make
kernel recipe changes.</para></listitem>
<listitem><para>Apply your configuration changes to your local kernel layer.
</para></listitem>
<listitem><para>Push your configuration and recipe changes upstream into the
Yocto Project source repositories to make them available to the community.
</para></listitem>
</orderedlist>
</para>
<section id='modifying-a-kernel-example'>
<title>Modifying a Kernel Example</title>
<para> <para>
Kernel modification involves changing or adding configurations to an existing kernel, or The example changes kernel configurations to support the VFAT filesystem and
adding recipes to the kernel that are needed to support specific hardware features. allow the user to print out a simple text file from the mounted VFAT filesystem.
The process is similar to creating a Board Support Package (BSP) except that it invloves The filesystem used will be an image filesystem rather than a filesystem on some
isolating your work in a kernel layer and the use of <filename>menuconfig</filename> external drive such as a USB stick or external drive.
to help make configuration data easily identifiable. The example uses the <filename>linux-yocto-2.6.37</filename> kernel.
</para> </para>
<para> <para>
This section presents a brief overview of the kernel structure and then provides a simple For a general flow of the example, see
example that shows how to modify the kernel. <xref linkend='kernel-modification-workflow'>Kernel Modification Workflow</xref>
earlier in this manual.
</para> </para>
<section id='yocto-project-kernel'> <section id='setting-up-yocto-project-kernel-example'>
<title>Yocto Project Kernel Overview</title> <title>Setting Up Yocto Project</title>
<para> <para>
When one thinks of the source files for a kernel they usually think of a fixed structure You need to have the Yocto Project files available on your host system.
of files that contain kernel patches. You can get files through tarball extraction or by cloning the <filename>poky</filename>
The Yocto Project, however, employs mechanisims that in a sense result in a kernel source Git repository.
generator. See the bulleted item
<link linkend='local-yp-release'>Yocto Project Release</link> in
<xref linkend='getting-setup'>Getting Setup</xref> earlier in this manual
for information on how to get these files.
</para> </para>
<para> <para>
The Yocto Project uses the source code management (SCM) tool Git to manage and track Yocto Once you have the local <filename>poky</filename> Git repository set up,
Project files. you have many development branches from which you can work.
Git employs branching strategies that effectively produce a tree-like structure whose From inside the repository you can see the branch names and the tag names used
branches represent diversions from more general code. in the Git repository using either of the following two commands:
For example, suppose two kernels are basically identical with the exception of a couple <literallayout class='monospaced'>
different features in each. $ git branch -a
In the Yocto Project source repositories managed by Git a main branch can contain the $ git tag -l
common or shared </literallayout>
parts of the kernel source and two branches that diverge from that common branch can For this example we are going to use the Yocto Project 1.1 Release,
each contain the features specific to the respective kernel. which maps to the <filename>1.1</filename> branch in the repository.
The result is a managed tree whose "leaves" represent the end of a specific path that yields These commands create a local branch named <filename>1.1</filename>
a set of kernel source files necessary for a specific piece of hardware and its features. that tracks the remote branch of the same name.
</para> <literallayout class='monospaced'>
$ cd poky
<para> $ git checkout -b 1.1 origin/1.1
A big advantage to this scheme is the sharing of common features by keeping them in Switched to a new branch '1.1'
"larger" branches that are further up the tree. </literallayout>
This practice eliminates redundant storage of similar features shared among kernels.
</para>
<para>
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
<filename>SRC_URI</filename> 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.
</para>
<para>
For a complete discussion of the Yocto Project kernel's architcture and its branching strategy,
see the <ulink url='http://www.yoctoproject.org/docs/1.1/kernel-manual/kernel-manual.html'>
The Yocto Project Kernel Architecture and Use Manual</ulink>.
</para>
<para>
You can find a web interface to the Yocto Project source repository at
<ulink url='http://git.yoctoproject.org/'></ulink>.
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
<ulink url='http://git.yoctoproject.org/'></ulink>:
<itemizedlist>
<listitem><para><emphasis><filename>linux-yocto-2.6.34</filename></emphasis> - The
stable Linux Yocto kernel that is based on the Linux 2.6.34 release.</para></listitem>
<listitem><para><emphasis><filename>linux-yocto-2.6.37</filename></emphasis> - The current
Linux Yocto kernel that is based on the Linux 2.6.37 release.</para></listitem>
<listitem><para><emphasis><filename>linux-yocto-dev</filename></emphasis> - A development
kernel based on the Linux 2.6.39-rc1 release.</para></listitem>
<listitem><para><emphasis><filename>linux-2.6</filename></emphasis> - 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.]</para></listitem>
</itemizedlist>
</para> </para>
</section> </section>
<section id='modifying-a-kernel-example'> <section id='getting-a-local-copy-of-the-kernel-files'>
<title>Modifying a Kernel Example</title> <title>Getting a Local Copy of the Kernel Files</title>
<para> <para>
This section presents a simple example that illustrates kernel modification You need to have a local copy of the Linux Yocto kernel files on your system.
based on the <filename>linux-yocto-2.6.37</filename> kernel. Yocto Project files available on your host system.
The example uses the audio and mixer capabilities supported by the You must create a local Git repository of these files.
<ulink url='http://www.alsa-project.org/main/index.php/Main_Page'>Advanced Linux See the bulleted item
Sound Architecture (ALSA) Project</ulink>. <link linkend='local-kernel-files'>Linux Yocto Kernel</link> in
As the example progresses you will see how to do the following: <xref linkend='getting-setup'>Getting Setup</xref> earlier in this manual
<itemizedlist> for information on how to get these files.
<listitem><para>Iteratively modify a base kernel locally.</para></listitem> </para>
<listitem><para>Provide a recipe-based solution for your modified kernel. </section>
</para></listitem>
<listitem><para>Proved an "in-tree" solution for your modified kernel <section id='create-a-layer-for-your-kernel-work'>
(i.e. make the modifcations part of the Yocto Project).</para></listitem> <title>Create a Layer for Your Kernel Work</title>
</itemizedlist>
<para>
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 <filename>meta-vfatsupport</filename>.
</para> </para>
<para> <para>
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
<ulink url='http://www.yoctoproject.org/docs/1.1/bsp-guide/bsp-guide.html#bsp-filelayout'>
Example Filesystem Layout</ulink> section of the Board Support Package (BSP) Development
Guide.
For kernel layers, you can start with a skeleton layer
named <filename>meta-skeleton</filename> found in your local
Yocto Project file directory structure (the <filename>poky</filename> Git
repository or the directory structure resulting from unpacking the Yocto Project
release tarball).
</para> </para>
<para> <para>
<itemizedlist> To create your kernel layer simply copy the <filename>meta-skeleton</filename>
<listitem><para>Be sure your host development system is set up to support layer and rename it <filename>meta-vfatsupport</filename>.
development using the Yocto Project. The following command sets up the layer inside the <filename>poky</filename>
See Git repository:
<ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#the-linux-distro'> <literallayout class='monospaced'>
The Linux Distributions</ulink> section and $ cd ~/poky
<ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#packages'> $ cp -r meta-skeleton meta-vfatsupport
The Packages</ulink> section both </literallayout>
in the Yocto Project Quick Start for requirements.
You will also need a release of Yocto Project installed on the host.</para></listitem>
<listitem><para>Set up your environment for optimal local kernel development.
</para></listitem>
<listitem><para>Create a layer to isolate your kernel work.</para></listitem>
<listitem><para>Next item.</para></listitem>
<listitem><para>Next item.</para></listitem>
<listitem><para>Next item.</para></listitem>
<listitem><para>Next item.</para></listitem>
</itemizedlist>
</para> </para>
<section id='setting-up-yocto-project-kernel-example'> <para>
<title>Setting Up Yocto Project</title> In the new layer you will find areas for configuration changes
(<filename>conf</filename>) and recipe changes (<filename>recipes-skeleton</filename>).
</para>
<para> <para>
You need to have the Yocto Project files available on your host system. You need to modify the structure a bit for your work.
The process is identical to that described in the These commands add some further structure and names that the Yocto Project build
<xref linkend='getting-setup'>"Getting Setup"</xref> section earlier in this environment expect:
manual. <literallayout class='monospaced'>
Be sure to either set up a local Git repository for <filename>poky</filename> $ mkdir meta-vfatsupport/images
or download and unpack the Yocto Project release tarball. $ mkdir meta-vfatsupport/recipes-bsp
</para> $ mv meta-vfatsupport/recipes-skeleton meta-vfatsupport/recipes-kernel
</section> $ mkdir meta-vfatsupport/recipes-kernel/linux
$ mkdir meta-vfatsupport/recipes-kernel/linux/linux-yocto
</literallayout>
</para>
<section id='create-a-git-repository-of-poky-extras'> <para>
<title>Create a Git Repository of <filename>poky-extras</filename></title> The last piece you need for your layer is a
<filename>linux-yocto_git.bbappend</filename> file inside
<filename>meta-vfatsupport/recipes-kernel/linux</filename>.
This file needs the following content to make the build process aware of the
new layer's location:
<literallayout class='monospaced'>
FILESEXTRAPATHS := "${THISDIR}/${PN}"
</literallayout>
</para>
<para> <para>
Everytime you change a configuration or add a recipe to the kernel you need to [WRITER'S NOTE: We need a better <filename>meta-skeleton</filename> layer
do a fetch from the Linux Yocto kernel source repositories. that is part of <filename>poky</filename>.
This can get tedious and time consuming if you need to fetch the entire It should have a structure that includes <filename>images</filename>,
Linux Yocto 2.6.37 Git repository down from the Internet everytime you make a change <filename>recipes-bsp</filename>, <filename>recipes-kernel</filename>, and
to the kernel. so forth.
</para> For now this step of the example is brute-forcing the structure with shell
commands to set up the minimum structure and include the
<filename>.bbappend</filename> file.
</para>
</section>
<para> <section id='prepare-to-use-menuconfig'>
You can get around this by setting up a <filename>meta-kernel-dev</filename> <title>Prepare to use <filename>menuconfig</filename></title>
area on your local system.
This area contains "append" files for every kernel recipe, which also include
a <filename>KSRC</filename> statement that points to the kernel source files.
You can set up the environment so that the <filename>KSRC</filename> points to the
<filename>meta-kernel-dev</filename>, thus pulling source from a local area.
This setup can speed up development time.
</para>
<para> <para>
To get set up you need to do two things: create a local Git repository The <filename>menuconfig</filename> tool provides an interactive method with which
of the <filename>poky-extras</filename> repository, and create a bare clone of the to set kernel configurations.
Linux Yocto 2.6.37 kernel Git repository. In order to use <filename>menuconfig</filename> from within the BitBake environment
</para> you need to source an environment setup script.
This script is located in the local Yocto Project file structure and is called
<filename>oe-init-build-env</filename>.
</para>
<para> <para>
The following transcript shows how to clone the <filename>poky-extras</filename> The following command sets up the environment:
Git repository into the current working directory, which is <filename>poky</filename> <literallayout class='monospaced'>
in this example. $ cd ~/poky
The command creates the repository in a directory named <filename>poky-extras</filename>: $ source oe-init-build-env
<literallayout class='monospaced'> </literallayout>
$ git clone git://git.yoctoproject.org/poky-extras </para>
Initialized empty Git repository in /home/scottrif/poky/poky-extras/.git/ </section>
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.
</literallayout>
</para>
<para> <section id='make-configuration-changes-to-the-kernel'>
This transcript shows how to clone a bare Git repository of the Linux Yocto <title>Make Configuration Changes to the Kernel</title>
2.6.37 kernel:
<literallayout class='monospaced'>
$ 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.
</literallayout>
</para>
<para> <para>
The bare clone of the Linux Yocto 2.6.37 kernel on your local system mirrors After setting up the environment to run <filename>menuconfig</filename> you are ready
the upstream repository of the kernel. to use the tool to interactively change the kernel configuration.
You can effectively point to this local clone now during development to avoid In this example we are basing our changes on the <filename>linux-yocto-2.6.37</filename>
having to fetch the entire Linux Yocto 2.6.37 kernel every time you make a kernel.
kernel change. The Yocto Project build environment recognizes this kernel as
</para> <filename>linux-yocto</filename>.
</section> Thus, the following command from the shell in which you previously sourced the
environment initialization script launches <filename>menuconfig</filename>:
<literallayout class='monospaced'>
$ bitbake linux-yocto -c menuconfig
</literallayout>
</para>
<section id='create-a-layer-for-your-kernel-work'> <para>
<title>Create a Layer for Your Kernel Work</title> [WRITER'S NOTE: Stuff from here down are crib notes]
</para>
<para> <para>
It is always good to isolate your work using your own layer. Once menuconfig fires up you see all kinds of categories that you can interactively
Doing so allows you to experiment and easily start over should things go wrong. investigate.
This example uses a layer named <filename>meta-amixer</filename>. If they have an "M" in it then the feature is "modularized".
</para> 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.]
</para>
<para> <para>
When you set up a layer for kernel work you should follow the general layout So the tmp/work/ area was created in poky and there is a .config file in there and
guidelines as described for BSP layers. a .config.old file.
This layout is described in the The old one must have been created when I exited from menuconfig after poking around
<ulink url='http://www.yoctoproject.org/docs/1.1/bsp-guide/bsp-guide.html#bsp-filelayout'> a bit.
Example Filesystem Layout</ulink> section of the Board Support Package (BSP) Development Nope - appears to just be created automatically.
Guide. </para>
In the standard layout you will notice a suggested structure for recipes and
configuration information.
[WRITER'S NOTE: The <filename>meta-elc</filename> example uses an
<filename>images</filename> directory.
Currently, <filename>images</filename> is not part of the standard BSP layout.
I need to find out from Darren if this directory is required for kernel work.]
</para>
<para> <para>
[WRITER'S NOTE: I need a paragraph here describing how to set up the layer. A good practice is to first determine what configurations you have for the kernel.
I am not sure if you should copy an existing BSP layer and modify from there. You can see the results by looking in the .config file in the build/tmp/work/qemux86-poky-linux area
Or, if you should just look at a BSP layer and then create your own files. of the local YP files.
Email to Darren on this but no answer yet.] There is a directory named linux-yocto-2.6.37* in the directory.
</para> In that directory is a directory named linux-qemux86-standard-build.
</section> 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.
</para>
<section id='making-changes-to-your-kernel-layer'> <para>
<title>Making Changes to Your Kernel Layer</title> You can prove the point by actually trying it at this point.
Here are the commands:
<literallayout class='monospaced'>
$ 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
<para> $ lsmod [this stuff Darren did to show me ]
In the standard layer structure you have several areas that you need to examine or 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
</literallayout>
</para>
</section>
</section>
</appendix>
<!--
EXTRA STUFF I MIGHT NEED BUT NOW SURE RIGHT NOW.
In the standard layer structure you have several areas that you need to examine or
modify. modify.
For this example the layer contains four areas: For this example the layer contains four areas:
<itemizedlist> <itemizedlist>
@@ -375,10 +482,8 @@
The file can also contain <filename>KERNEL_FEATURES</filename> statements that specify The file can also contain <filename>KERNEL_FEATURES</filename> statements that specify
included kernel configurations that ship with the Yocto Project. included kernel configurations that ship with the Yocto Project.
</para> </para>
</section> -->
</section>
</appendix>
<!-- <!--
vim: expandtab tw=80 ts=4 vim: expandtab tw=80 ts=4
--> -->