diff options
Diffstat (limited to 'poky/documentation/kernel-dev/common.rst')
| -rw-r--r-- | poky/documentation/kernel-dev/common.rst | 225 |
1 files changed, 75 insertions, 150 deletions
diff --git a/poky/documentation/kernel-dev/common.rst b/poky/documentation/kernel-dev/common.rst index 56217b9d3..3f35d8412 100644 --- a/poky/documentation/kernel-dev/common.rst +++ b/poky/documentation/kernel-dev/common.rst @@ -54,8 +54,7 @@ section: 1. *Initialize the BitBake Environment:* Before building an extensible SDK, you need to initialize the BitBake build environment by sourcing - the build environment script (i.e. :ref:`structure-core-script`): - :: + the build environment script (i.e. :ref:`structure-core-script`):: $ cd poky $ source oe-init-build-env @@ -83,16 +82,14 @@ section: In this example we wish to build for qemux86 so we must set the ``MACHINE`` variable to "qemux86" and also add the "kernel-modules". - As described we do this by appending to ``conf/local.conf``: - :: + As described we do this by appending to ``conf/local.conf``:: MACHINE = "qemux86" MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules" 3. *Create a Layer for Patches:* You need to create a layer to hold patches created for the kernel image. You can use the - ``bitbake-layers create-layer`` command as follows: - :: + ``bitbake-layers create-layer`` command as follows:: $ cd poky/build $ bitbake-layers create-layer ../../meta-mylayer @@ -116,8 +113,7 @@ section: 4. *Inform the BitBake Build Environment About Your Layer:* As directed when you created your layer, you need to add the layer to the :term:`BBLAYERS` variable in the - ``bblayers.conf`` file as follows: - :: + ``bblayers.conf`` file as follows:: $ cd poky/build $ bitbake-layers add-layer ../../meta-mylayer @@ -125,16 +121,14 @@ section: $ 5. *Build the Extensible SDK:* Use BitBake to build the extensible SDK - specifically for use with images to be run using QEMU: - :: + specifically for use with images to be run using QEMU:: $ cd poky/build $ bitbake core-image-minimal -c populate_sdk_ext Once the build finishes, you can find the SDK installer file (i.e. - ``*.sh`` file) in the following directory: - :: + ``*.sh`` file) in the following directory:: poky/build/tmp/deploy/sdk @@ -143,8 +137,7 @@ section: 6. *Install the Extensible SDK:* Use the following command to install the SDK. For this example, install the SDK in the default - ``poky_sdk`` directory: - :: + ``poky_sdk`` directory:: $ cd poky/build/tmp/deploy/sdk $ ./poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-&DISTRO;.sh @@ -172,8 +165,7 @@ section: BitBake shell used to build the installer. After opening a new shell, run the SDK environment setup script as - directed by the output from installing the SDK: - :: + directed by the output from installing the SDK:: $ source poky_sdk/environment-setup-i586-poky-linux "SDK environment now set up; additionally you may now run devtool to perform development tasks. @@ -186,8 +178,7 @@ section: 8. *Build the Clean Image:* The final step in preparing to work on the kernel is to build an initial image using ``devtool`` in the new - terminal you just set up and initialized for SDK work: - :: + terminal you just set up and initialized for SDK work:: $ devtool build-image Parsing recipes: 100% |##########################################| Time: 0:00:05 @@ -269,16 +260,14 @@ section: In this example we wish to build for qemux86 so we must set the ``MACHINE`` variable to "qemux86" and also add the "kernel-modules". - As described we do this by appending to ``conf/local.conf``: - :: + As described we do this by appending to ``conf/local.conf``:: MACHINE = "qemux86" MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules" 3. *Create a Layer for Patches:* You need to create a layer to hold patches created for the kernel image. You can use the - ``bitbake-layers create-layer`` command as follows: - :: + ``bitbake-layers create-layer`` command as follows:: $ cd poky/build $ bitbake-layers create-layer ../../meta-mylayer @@ -301,8 +290,7 @@ section: 4. *Inform the BitBake Build Environment About Your Layer:* As directed when you created your layer, you need to add the layer to the :term:`BBLAYERS` variable in the - ``bblayers.conf`` file as follows: - :: + ``bblayers.conf`` file as follows:: $ cd poky/build $ bitbake-layers add-layer ../../meta-mylayer @@ -350,8 +338,7 @@ section: the ``yocto-4.12`` branch. The following commands show how to create a local copy of the - ``yocto-kernel-cache`` and be in the ``yocto-4.12`` branch: - :: + ``yocto-kernel-cache`` and be in the ``yocto-4.12`` branch:: $ cd ~ $ git clone git://git.yoctoproject.org/yocto-kernel-cache --branch yocto-4.12 @@ -394,8 +381,7 @@ following section describes how to create a layer without the aid of tools. These steps assume creation of a layer named ``mylayer`` in your home directory: -1. *Create Structure*: Create the layer's structure: - :: +1. *Create Structure*: Create the layer's structure:: $ mkdir meta-mylayer $ mkdir meta-mylayer/conf @@ -409,8 +395,7 @@ home directory: 2. *Create the Layer Configuration File*: Move to the ``meta-mylayer/conf`` directory and create the ``layer.conf`` file as - follows: - :: + follows:: # We have a conf and classes directory, add to BBPATH BBPATH .= ":${LAYERDIR}" @@ -429,8 +414,7 @@ home directory: ``meta-mylayer/recipes-kernel/linux`` directory and create the kernel's append file. This example uses the ``linux-yocto-4.12`` kernel. Thus, the name of the append file is - ``linux-yocto_4.12.bbappend``: - :: + ``linux-yocto_4.12.bbappend``:: FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" @@ -483,8 +467,7 @@ The append file should initially extend the :term:`FILESPATH` search path by prepending the directory that contains your files to the :term:`FILESEXTRAPATHS` -variable as follows: -:: +variable as follows:: FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" @@ -492,8 +475,7 @@ The path ``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}`` expands to "linux-yocto" in the current directory for this example. If you add any new files that modify the kernel recipe and you have extended ``FILESPATH`` as described above, you must place the files in -your layer in the following area: -:: +your layer in the following area:: your-layer/recipes-kernel/linux/linux-yocto/ @@ -582,8 +564,7 @@ To group related configurations into multiple files, you perform a similar procedure. Here is an example that groups separate configurations specifically for Ethernet and graphics into their own files and adds the configurations by using a ``SRC_URI`` statement like -the following in your append file: -:: +the following in your append file:: SRC_URI += "file://myconfig.cfg \ file://eth.cfg \ @@ -627,8 +608,7 @@ reference them in :term:`SRC_URI` statements. For example, you can apply a three-patch series by adding the following -lines to your linux-yocto ``.bbappend`` file in your layer: -:: +lines to your linux-yocto ``.bbappend`` file in your layer:: SRC_URI += "file://0001-first-change.patch" SRC_URI += "file://0002-second-change.patch" @@ -658,8 +638,7 @@ If you have a complete, working Linux kernel ``.config`` file you want to use for the configuration, as before, copy that file to the appropriate ``${PN}`` directory in your layer's ``recipes-kernel/linux`` directory, and rename the copied file to "defconfig". Then, add the -following lines to the linux-yocto ``.bbappend`` file in your layer: -:: +following lines to the linux-yocto ``.bbappend`` file in your layer:: FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" SRC_URI += "file://defconfig" @@ -685,8 +664,7 @@ Generally speaking, the preferred approach is to determine the incremental change you want to make and add that as a configuration fragment. For example, if you want to add support for a basic serial console, create a file named ``8250.cfg`` in the ``${PN}`` directory -with the following content (without indentation): -:: +with the following content (without indentation):: CONFIG_SERIAL_8250=y CONFIG_SERIAL_8250_CONSOLE=y @@ -698,8 +676,7 @@ with the following content (without indentation): Next, include this configuration fragment and extend the ``FILESPATH`` variable in your -``.bbappend`` file: -:: +``.bbappend`` file:: FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" SRC_URI += "file://8250.cfg" @@ -718,8 +695,7 @@ It might be desirable to have kernel configuration fragment support through a ``defconfig`` file that is pulled from the kernel source tree for the configured machine. By default, the OpenEmbedded build system looks for ``defconfig`` files in the layer used for Metadata, which is -"out-of-tree", and then configures them using the following: -:: +"out-of-tree", and then configures them using the following:: SRC_URI += "file://defconfig" @@ -732,16 +708,14 @@ append files, you can direct the OpenEmbedded build system to use a ``defconfig`` file that is "in-tree". To specify an "in-tree" ``defconfig`` file, use the following statement -form: -:: +form:: KBUILD_DEFCONFIG_KMACHINE ?= "defconfig_file" Here is an example that assigns the ``KBUILD_DEFCONFIG`` variable based on "raspberrypi2" and provides the path to the "in-tree" ``defconfig`` file to be used for -a Raspberry Pi 2, which is based on the Broadcom 2708/2709 chipset: -:: +a Raspberry Pi 2, which is based on the Broadcom 2708/2709 chipset:: KBUILD_DEFCONFIG_raspberrypi2 ?= "bcm2709_defconfig" @@ -792,8 +766,7 @@ the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Se ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" section for more information. - Use the following ``devtool`` command to check out the code: - :: + Use the following ``devtool`` command to check out the code:: $ devtool modify linux-yocto @@ -819,14 +792,12 @@ the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Se noted where you can find the source files (e.g. ``poky_sdk/workspace/sources/linux-yocto``). Change to where the kernel source code is before making your edits to the - ``calibrate.c`` file: - :: + ``calibrate.c`` file:: $ cd poky_sdk/workspace/sources/linux-yocto 2. *Edit the source file*: Edit the ``init/calibrate.c`` file to have - the following changes: - :: + the following changes:: void calibrate_delay(void) { @@ -846,8 +817,7 @@ the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Se . 3. *Build the Updated Kernel Source:* To build the updated kernel - source, use ``devtool``: - :: + source, use ``devtool``:: $ devtool build linux-yocto @@ -872,8 +842,7 @@ the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Se using QEMU to verify your changes: 1. *Boot the image*: Boot the modified image in the QEMU emulator - using this command: - :: + using this command:: $ runqemu qemux86 @@ -891,8 +860,7 @@ the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Se 6. *Stage and commit your changes*: Within your eSDK terminal, change your working directory to where you modified the ``calibrate.c`` file - and use these Git commands to stage and commit your changes: - :: + and use these Git commands to stage and commit your changes:: $ cd poky_sdk/workspace/sources/linux-yocto $ git status @@ -921,8 +889,7 @@ the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Se image that includes your kernel patches. Execute the following command from your :term:`Build Directory` in the terminal - set up to run BitBake: - :: + set up to run BitBake:: $ cd poky/build $ bitbake core-image-minimal @@ -966,14 +933,12 @@ Section. 1. *Change the working directory*: You need to locate the source files in the local copy of the kernel Git repository. Change to where the kernel source code is before making your edits to the - ``calibrate.c`` file: - :: + ``calibrate.c`` file:: $ cd ~/linux-yocto-4.12/init 2. *Edit the source file*: Edit the ``calibrate.c`` file to have the - following changes: - :: + following changes:: void calibrate_delay(void) { @@ -993,8 +958,7 @@ Section. . 2. *Stage and Commit Your Changes:* Use standard Git commands to stage - and commit the changes you just made: - :: + and commit the changes you just made:: $ git add calibrate.c $ git commit -m "calibrate.c - Added some printk statements" @@ -1009,13 +973,11 @@ Section. updated kernel source files. Add :term:`SRC_URI` and :term:`SRCREV` statements similar - to the following to your ``local.conf``: - :: + to the following to your ``local.conf``:: $ cd poky/build/conf - Add the following to the ``local.conf``: - :: + Add the following to the ``local.conf``:: SRC_URI_pn-linux-yocto = "git:///path-to/linux-yocto-4.12;protocol=file;name=machine;branch=standard/base; \ git:///path-to/yocto-kernel-cache;protocol=file;type=kmeta;name=meta;branch=yocto-4.12;destsuffix=${KMETA}" @@ -1031,16 +993,14 @@ Section. 4. *Build the Image:* With the source modified, your changes staged and committed, and the ``local.conf`` file pointing to the kernel files, - you can now use BitBake to build the image: - :: + you can now use BitBake to build the image:: $ cd poky/build $ bitbake core-image-minimal 5. *Boot the image*: Boot the modified image in the QEMU emulator using this command. When prompted to login to the QEMU console, use "root" - with no password: - :: + with no password:: $ cd poky/build $ runqemu qemux86 @@ -1059,8 +1019,7 @@ Section. 7. *Generate the Patch File:* Once you are sure that your patch works correctly, you can generate a ``*.patch`` file in the kernel source - repository: - :: + repository:: $ cd ~/linux-yocto-4.12/init $ git format-patch -1 @@ -1073,8 +1032,7 @@ Section. ``meta-mylayer``. When the layer was created using the ``yocto-create`` script, no additional hierarchy was created to support patches. Before moving the patch file, you need to add - additional structure to your layer using the following commands: - :: + additional structure to your layer using the following commands:: $ cd ~/meta-mylayer $ mkdir recipes-kernel @@ -1083,8 +1041,7 @@ Section. Once you have created this hierarchy in your layer, you can move the patch file using the - following command: - :: + following command:: $ mv ~/linux-yocto-4.12/init/0001-calibrate.c-Added-some-printk-statements.patch ~/meta-mylayer/recipes-kernel/linux/linux-yocto @@ -1093,8 +1050,7 @@ Section. the OpenEmbedded build system to find the patch. The append file needs to be in your layer's ``recipes-kernel/linux`` directory and it must be named ``linux-yocto_4.12.bbappend`` and have the following - contents: - :: + contents:: FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" SRC_URI_append = "file://0001-calibrate.c-Added-some-printk-statements.patch" @@ -1113,8 +1069,7 @@ Section. To build ``core-image-minimal`` again and see the effects of your patch, you can essentially eliminate the temporary source files saved in ``poky/build/tmp/work/...`` and residual effects of the build by entering - the following sequence of commands: - :: + the following sequence of commands:: $ cd poky/build $ bitbake -c cleanall yocto-linux @@ -1160,8 +1115,7 @@ environment, you must do the following: - You must be sure of the state of your build's configuration in the :term:`Source Directory`. -- Your build host must have the following two packages installed: - :: +- Your build host must have the following two packages installed:: libncurses5-dev libtinfo-dev @@ -1169,8 +1123,7 @@ environment, you must do the following: The following commands initialize the BitBake environment, run the :ref:`ref-tasks-kernel_configme` task, and launch ``menuconfig``. These commands assume the Source -Directory's top-level folder is ``poky``: -:: +Directory's top-level folder is ``poky``:: $ cd poky $ source oe-init-build-env @@ -1232,8 +1185,7 @@ the ``.config`` file would be: Within the ``.config`` file, you can see the kernel settings. For example, the following entry shows that symmetric multi-processor -support is not set: -:: +support is not set:: # CONFIG_SMP is not set @@ -1274,8 +1226,7 @@ your layer's ``recipes-kernel/linux`` directory, and rename the copied file to "defconfig" (e.g. ``~/meta-mylayer/recipes-kernel/linux/linux-yocto/defconfig``). Then, add the following lines to the linux-yocto ``.bbappend`` file in your -layer: -:: +layer:: FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" SRC_URI += "file://defconfig" @@ -1323,8 +1274,7 @@ appear in the ``.config`` file, which is in the :term:`Build Directory`. It is simple to create a configuration fragment. One method is to use shell commands. For example, issuing the following from the shell creates a configuration fragment file named ``my_smp.cfg`` that enables -multi-processor support within the kernel: -:: +multi-processor support within the kernel:: $ echo "CONFIG_SMP=y" >> my_smp.cfg @@ -1342,8 +1292,7 @@ To create a configuration fragment using this method, follow these steps: 1. *Complete a Build Through Kernel Configuration:* Complete a build at - least through the kernel configuration task as follows: - :: + least through the kernel configuration task as follows:: $ bitbake linux-yocto -c kernel_configme -f @@ -1352,8 +1301,7 @@ steps: your build state might become unknown, it is best to run this task prior to starting ``menuconfig``. -2. *Launch menuconfig:* Run the ``menuconfig`` command: - :: +2. *Launch menuconfig:* Run the ``menuconfig`` command:: $ bitbake linux-yocto -c menuconfig @@ -1361,8 +1309,7 @@ steps: to prepare a configuration fragment. The resulting file ``fragment.cfg`` is placed in the ``${``\ :term:`WORKDIR`\ ``}`` - directory: - :: + directory:: $ bitbake linux-yocto -c diffconfig @@ -1387,8 +1334,7 @@ options in a file called ``myconfig.cfg``. If you put that file inside a directory named ``linux-yocto`` that resides in the same directory as the kernel's append file within your layer and then add the following statements to the kernel's append file, those configuration options will -be picked up and applied when the kernel is built: -:: +be picked up and applied when the kernel is built:: FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" SRC_URI += "file://myconfig.cfg" @@ -1397,8 +1343,7 @@ As mentioned earlier, you can group related configurations into multiple files and name them all in the ``SRC_URI`` statement as well. For example, you could group separate configurations specifically for Ethernet and graphics into their own files and add those by using a -``SRC_URI`` statement like the following in your append file: -:: +``SRC_URI`` statement like the following in your append file:: SRC_URI += "file://myconfig.cfg \ file://eth.cfg \ @@ -1409,8 +1354,7 @@ Validating Configuration You can use the :ref:`ref-tasks-kernel_configcheck` -task to provide configuration validation: -:: +task to provide configuration validation:: $ bitbake linux-yocto -c kernel_configcheck -f @@ -1537,8 +1481,7 @@ To streamline the configuration, do the following: successfully. Use this configuration file as your baseline. 2. *Run Configure and Check Tasks:* Separately run the - ``do_kernel_configme`` and ``do_kernel_configcheck`` tasks: - :: + ``do_kernel_configme`` and ``do_kernel_configcheck`` tasks:: $ bitbake linux-yocto -c kernel_configme -f $ bitbake linux-yocto -c kernel_configcheck -f @@ -1572,8 +1515,7 @@ Expanding Variables Sometimes it is helpful to determine what a variable expands to during a build. You can examine the values of variables by examining the output of the ``bitbake -e`` command. The output is long and is more -easily managed in a text file, which allows for easy searches: -:: +easily managed in a text file, which allows for easy searches:: $ bitbake -e virtual/kernel > some_text_file @@ -1590,15 +1532,13 @@ source directory. Follow these steps to clean up the version string: 1. *Discover the Uncommitted Changes:* Go to the kernel's locally cloned Git repository (source directory) and use the following Git command - to list the files that have been changed, added, or removed: - :: + to list the files that have been changed, added, or removed:: $ git status 2. *Commit the Changes:* You should commit those changes to the kernel source tree regardless of whether or not you will save, export, or - use the changes: - :: + use the changes:: $ git add $ git commit -s -a -m "getting rid of -dirty" @@ -1633,8 +1573,7 @@ linux-yocto custom recipe (``linux-yocto-custom.bb``) that uses ``kernel.org`` sources and the Yocto Project Linux kernel tools for managing kernel Metadata. You can find this recipe in the ``poky`` Git repository of the Yocto Project :yocto_git:`Source Repository <>` -at: -:: +at:: poky/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb @@ -1655,8 +1594,7 @@ Here are some basic steps you can use to work with your own sources: ``defconfig`` file or configuration fragment files in your layer. When you use the ``linux-yocto-custom.bb`` recipe, you must specify a configuration. If you do not have a ``defconfig`` file, you can run - the following: - :: + the following:: $ make defconfig @@ -1708,8 +1646,7 @@ Here are some basic steps you can use to work with your own sources: ``LINUX_VERSION`` with the Source Control Manager (SCM) revision as derived from the :term:`SRCPV` variable. The combined results are a string with the following - form: - :: + form:: 3.19.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2 @@ -1723,8 +1660,7 @@ Here are some basic steps you can use to work with your own sources: triggers an explicit build failure. You must change it to match a list of the machines that your new recipe supports. For example, to support the ``qemux86`` and ``qemux86-64`` machines, use the - following form: - :: + following form:: COMPATIBLE_MACHINE = "qemux86|qemux86-64" @@ -1807,8 +1743,7 @@ Typically, you will need to set the following variables: Depending on the build system used by the module sources, you might need to make some adjustments. For example, a typical module ``Makefile`` -looks much like the one provided with the ``hello-mod`` template: -:: +looks much like the one provided with the ``hello-mod`` template:: obj-m := hello.o @@ -1845,8 +1780,7 @@ them appropriately for your machine configuration file: - :term:`MACHINE_EXTRA_RRECOMMENDS` Modules are often not required for boot and can be excluded from certain -build configurations. The following allows for the most flexibility: -:: +build configurations. The following allows for the most flexibility:: MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule" @@ -1895,26 +1829,22 @@ branch. $ git whatchanged origin/standard/base..origin/standard/emenlow -To see short, one line summaries of changes use the ``git log`` command: -:: +To see short, one line summaries of changes use the ``git log`` command:: $ git log --oneline origin/standard/base..origin/standard/emenlow -Use this command to see code differences for the changes: -:: +Use this command to see code differences for the changes:: $ git diff origin/standard/base..origin/standard/emenlow Use this command to see the commit log messages and the text -differences: -:: +differences:: $ git show origin/standard/base..origin/standard/emenlow Use this command to create individual patches for each change. Here is an example that creates patch files for each commit and places them -in your ``Documents`` directory: -:: +in your ``Documents`` directory:: $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow @@ -1923,15 +1853,13 @@ Showing a Particular Feature or Branch Change Tags in the Yocto Project kernel tree divide changes for significant features or branches. The ``git show`` tag command shows changes based -on a tag. Here is an example that shows ``systemtap`` changes: -:: +on a tag. Here is an example that shows ``systemtap`` changes:: $ git show systemtap You can use the ``git branch --contains`` tag command to show the branches that contain a particular feature. This command shows -the branches that contain the ``systemtap`` feature: -:: +the branches that contain the ``systemtap`` feature:: $ git branch --contains systemtap @@ -1986,8 +1914,7 @@ build. searched during the build as potential feature directories. Continuing with the example, suppose the "test.scc" feature you are - adding has a ``test.scc`` file in the following directory: - :: + adding has a ``test.scc`` file in the following directory:: my_recipe | @@ -2001,8 +1928,7 @@ build. a similarly named configuration fragment file ``test.cfg``. 2. *Add the Feature File to SRC_URI:* Add the ``.scc`` file to the - recipe's ``SRC_URI`` statement: - :: + recipe's ``SRC_URI`` statement:: SRC_URI_append = " file://test.scc" @@ -2011,8 +1937,7 @@ build. 3. *Specify the Feature as a Kernel Feature:* Use the ``KERNEL_FEATURES`` statement to specify the feature as a kernel - feature: - :: + feature:: KERNEL_FEATURES_append = " test.scc" |