diff options
author | Jason M. Bills <jason.m.bills@linux.intel.com> | 2021-03-09 00:45:46 +0300 |
---|---|---|
committer | Jason M. Bills <jason.m.bills@linux.intel.com> | 2021-03-09 00:45:46 +0300 |
commit | 930df2e58b9725756edbccf99fd4979026fc28fd (patch) | |
tree | 8c5fa9f20219e9bc4580bb18e03b8dd8043a9a4f /poky/documentation/bsp-guide/bsp.rst | |
parent | 7c5f8839ec3d71a2170b8f3514a16a67c69d1c7c (diff) | |
parent | 377d8f40e88eeb9ccb1321590a3af3c2caa94dda (diff) | |
download | openbmc-930df2e58b9725756edbccf99fd4979026fc28fd.tar.xz |
Merge tag '0.35' of ssh://git-amr-1.devtools.intel.com:29418/openbmc-openbmc into update
Diffstat (limited to 'poky/documentation/bsp-guide/bsp.rst')
-rw-r--r-- | poky/documentation/bsp-guide/bsp.rst | 79 |
1 files changed, 39 insertions, 40 deletions
diff --git a/poky/documentation/bsp-guide/bsp.rst b/poky/documentation/bsp-guide/bsp.rst index 408620212..068ab6c80 100644 --- a/poky/documentation/bsp-guide/bsp.rst +++ b/poky/documentation/bsp-guide/bsp.rst @@ -44,7 +44,7 @@ machine or platform name, which is "bsp_root_name" in the above form. To help understand the BSP layer concept, consider the BSPs that the Yocto Project supports and provides with each release. You can see the layers in the -:ref:`overview-manual/overview-manual-development-environment:yocto project source repositories` +:ref:`overview-manual/development-environment:yocto project source repositories` through a web interface at :yocto_git:`/`. If you go to that interface, you will find a list of repositories under "Yocto Metadata Layers". @@ -72,7 +72,7 @@ For information on typical BSP development workflow, see the section. For more information on how to set up a local copy of source files from a Git repository, see the -:ref:`dev-manual/dev-manual-start:locating yocto project source files` +:ref:`dev-manual/start:locating yocto project source files` section in the Yocto Project Development Tasks Manual. The BSP layer's base directory (``meta-bsp_root_name``) is the root @@ -81,7 +81,7 @@ directory of that Layer. This directory is what you add to the ``conf/bblayers.conf`` file found in your :term:`Build Directory`, which is established after you run the OpenEmbedded build environment setup -script (i.e. :ref:`ref-manual/ref-structure:\`\`oe-init-build-env\`\``). +script (i.e. :ref:`ref-manual/structure:\`\`oe-init-build-env\`\``). Adding the root directory allows the :term:`OpenEmbedded Build System` to recognize the BSP layer and from it build an image. Here is an example: :: @@ -128,7 +128,7 @@ you want to work with, such as: :: and so on. For more information on layers, see the -":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`" +":ref:`dev-manual/common-tasks:understanding and creating layers`" section of the Yocto Project Development Tasks Manual. Preparing Your Build Host to Work With BSP Layers @@ -146,7 +146,7 @@ section. :ref:`bsp-guide/bsp:example filesystem layout` section. #. *Set Up the Build Environment:* Be sure you are set up to use BitBake - in a shell. See the ":ref:`dev-manual/dev-manual-start:preparing the build host`" + in a shell. See the ":ref:`dev-manual/start:preparing the build host`" section in the Yocto Project Development Tasks Manual for information on how to get a build host ready that is either a native Linux machine or a machine that uses CROPS. @@ -154,10 +154,10 @@ section. #. *Clone the poky Repository:* You need to have a local copy of the Yocto Project :term:`Source Directory` (i.e. a local ``poky`` repository). See the - ":ref:`dev-manual/dev-manual-start:cloning the \`\`poky\`\` repository`" and + ":ref:`dev-manual/start:cloning the \`\`poky\`\` repository`" and possibly the - ":ref:`dev-manual/dev-manual-start:checking out by branch in poky`" or - ":ref:`dev-manual/dev-manual-start:checking out by tag in poky`" + ":ref:`dev-manual/start:checking out by branch in poky`" or + ":ref:`dev-manual/start:checking out by tag in poky`" sections all in the Yocto Project Development Tasks Manual for information on how to clone the ``poky`` repository and check out the appropriate @@ -172,8 +172,7 @@ section. #. *Optionally Clone the meta-intel BSP Layer:* If your hardware is based on current Intel CPUs and devices, you can leverage this BSP layer. For details on the ``meta-intel`` BSP layer, see the layer's - `README <http://git.yoctoproject.org/cgit/cgit.cgi/meta-intel/tree/README>`__ - file. + :yocto_git:`README </meta-intel/tree/README>` file. #. *Navigate to Your Source Directory:* Typically, you set up the ``meta-intel`` Git repository inside the :term:`Source Directory` (e.g. @@ -206,7 +205,7 @@ section. To see the available branch names in a cloned repository, use the ``git branch -al`` command. See the - ":ref:`dev-manual/dev-manual-start:checking out by branch in poky`" + ":ref:`dev-manual/start:checking out by branch in poky`" section in the Yocto Project Development Tasks Manual for more information. @@ -230,7 +229,7 @@ section. #. *Initialize the Build Environment:* While in the root directory of the Source Directory (i.e. ``poky``), run the - :ref:`ref-manual/ref-structure:\`\`oe-init-build-env\`\`` environment + :ref:`ref-manual/structure:\`\`oe-init-build-env\`\`` environment setup script to define the OpenEmbedded build environment on your build host. :: @@ -254,7 +253,7 @@ developers can use this structure with other build systems besides the OpenEmbedded build system. It is also intended that it will be be simple to extract information and convert it to other formats if required. The OpenEmbedded build system, through its standard :ref:`layers mechanism -<overview-manual/overview-manual-yp-intro:the yocto project layer model>`, can +<overview-manual/yp-intro:the yocto project layer model>`, can directly accept the format described as a layer. The BSP layer captures all the hardware-specific details in one place using a standard format, which is useful for any person wishing to use the hardware platform @@ -464,7 +463,7 @@ requirements are handled with the ``COPYING.MIT`` file. Licensing files can be MIT, BSD, GPLv*, and so forth. These files are recommended for the BSP but are optional and totally up to the BSP developer. For information on how to maintain license compliance, see -the ":ref:`dev-manual/dev-manual-common-tasks:maintaining open source license compliance during your product's lifecycle`" +the ":ref:`dev-manual/common-tasks:maintaining open source license compliance during your product's lifecycle`" section in the Yocto Project Development Tasks Manual. README File @@ -590,7 +589,7 @@ filenames correspond to the values to which users have set the These files define things such as the kernel package to use (:term:`PREFERRED_PROVIDER` of -:ref:`virtual/kernel <dev-manual/dev-manual-common-tasks:using virtual providers>`), +:ref:`virtual/kernel <dev-manual/common-tasks:using virtual providers>`), the hardware drivers to include in different types of images, any special software components that are needed, any bootloader information, and also any special image format requirements. @@ -694,7 +693,7 @@ BSP settings to the kernel, thus configuring the kernel for your particular BSP. You can find more information on what your append file should contain in -the ":ref:`kernel-dev/kernel-dev-common:creating the append file`" section +the ":ref:`kernel-dev/common:creating the append file`" section in the Yocto Project Linux Kernel Development Manual. An alternate scenario is when you create your own kernel recipe for the @@ -727,7 +726,7 @@ workflow. :align: center #. *Set up Your Host Development System to Support Development Using the - Yocto Project*: See the ":ref:`dev-manual/dev-manual-start:preparing the build host`" + Yocto Project*: See the ":ref:`dev-manual/start:preparing the build host`" section in the Yocto Project Development Tasks Manual for options on how to get a system ready to use the Yocto Project. @@ -755,9 +754,9 @@ workflow. are kept. The key point for a layer is that it is an isolated area that contains all the relevant information for the project that the OpenEmbedded build system knows about. For more information on - layers, see the ":ref:`overview-manual/overview-manual-yp-intro:the yocto project layer model`" + layers, see the ":ref:`overview-manual/yp-intro:the yocto project layer model`" section in the Yocto Project Overview and Concepts Manual. You can also - reference the ":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`" + reference the ":ref:`dev-manual/common-tasks:understanding and creating layers`" section in the Yocto Project Development Tasks Manual. For more information on BSP layers, see the ":ref:`bsp-guide/bsp:bsp layers`" section. @@ -816,7 +815,7 @@ workflow. key configuration files are configured appropriately: the ``conf/local.conf`` and the ``conf/bblayers.conf`` file. You must make the OpenEmbedded build system aware of your new layer. See the - ":ref:`dev-manual/dev-manual-common-tasks:enabling your layer`" + ":ref:`dev-manual/common-tasks:enabling your layer`" section in the Yocto Project Development Tasks Manual for information on how to let the build system know about your new layer. @@ -827,7 +826,7 @@ workflow. The build process supports several types of images to satisfy different needs. See the - ":ref:`ref-manual/ref-images:Images`" chapter in the Yocto + ":ref:`ref-manual/images:Images`" chapter in the Yocto Project Reference Manual for information on supported images. Requirements and Recommendations for Released BSPs @@ -847,14 +846,14 @@ Before looking at BSP requirements, you should consider the following: layer that can be added to the Yocto Project. For guidelines on creating a layer that meets these base requirements, see the ":ref:`bsp-guide/bsp:bsp layers`" section in this manual and the - ":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`" + ":ref:`dev-manual/common-tasks:understanding and creating layers`" section in the Yocto Project Development Tasks Manual. - The requirements in this section apply regardless of how you package a BSP. You should consult the packaging and distribution guidelines for your specific release process. For an example of packaging and distribution requirements, see the ":yocto_wiki:`Third Party BSP Release - Process </wiki/Third_Party_BSP_Release_Process>`" + Process </Third_Party_BSP_Release_Process>`" wiki page. - The requirements for the BSP as it is made available to a developer @@ -902,13 +901,13 @@ Yocto Project: ``meta-bsp_root_name`` directory. This license covers the BSP Metadata as a whole. You must specify which license to use since no default license exists when one is not specified. See the - :yocto_git:`COPYING.MIT </cgit.cgi/meta-raspberrypi/tree/COPYING.MIT>` + :yocto_git:`COPYING.MIT </meta-raspberrypi/tree/COPYING.MIT>` file for the Raspberry Pi BSP in the ``meta-raspberrypi`` BSP layer as an example. - *README File:* You must include a ``README`` file in the ``meta-bsp_root_name`` directory. See the - :yocto_git:`README.md </cgit.cgi/meta-raspberrypi/tree/README.md>` + :yocto_git:`README.md </meta-raspberrypi/tree/README.md>` file for the Raspberry Pi BSP in the ``meta-raspberrypi`` BSP layer as an example. @@ -929,7 +928,7 @@ Yocto Project: - The name and contact information for the BSP layer maintainer. This is the person to whom patches and questions should be sent. For information on how to find the right person, see the - ":ref:`dev-manual/dev-manual-common-tasks:submitting a change to the yocto project`" + ":ref:`dev-manual/common-tasks:submitting a change to the yocto project`" section in the Yocto Project Development Tasks Manual. - Instructions on how to build the BSP using the BSP layer. @@ -1014,7 +1013,7 @@ If you plan on customizing a recipe for a particular BSP, you need to do the following: - Create a ``*.bbappend`` file for the modified recipe. For information on using - append files, see the ":ref:`dev-manual/dev-manual-common-tasks:using + append files, see the ":ref:`dev-manual/common-tasks:using .bbappend files in your layer`" section in the Yocto Project Development Tasks Manual. @@ -1119,7 +1118,7 @@ list describes them in order of preference: Specifying the matching license string signifies that you agree to the license. Thus, the build system can build the corresponding recipe and include the component in the image. See the - ":ref:`dev-manual/dev-manual-common-tasks:enabling commercially licensed recipes`" + ":ref:`dev-manual/common-tasks:enabling commercially licensed recipes`" section in the Yocto Project Development Tasks Manual for details on how to use these variables. @@ -1171,7 +1170,7 @@ Use these steps to create a BSP layer: ``create-layer`` subcommand to create a new general layer. For instructions on how to create a general layer using the ``bitbake-layers`` script, see the - ":ref:`dev-manual/dev-manual-common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script`" + ":ref:`dev-manual/common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script`" section in the Yocto Project Development Tasks Manual. - *Create a Layer Configuration File:* Every layer needs a layer @@ -1181,16 +1180,16 @@ Use these steps to create a BSP layer: :yocto_git:`Source Repositories <>`. To get examples of what you need in your configuration file, locate a layer (e.g. "meta-ti") and examine the - :yocto_git:`local.conf </cgit/cgit.cgi/meta-ti/tree/conf/layer.conf>` + :yocto_git:`local.conf </meta-ti/tree/conf/layer.conf>` file. - *Create a Machine Configuration File:* Create a ``conf/machine/bsp_root_name.conf`` file. See - :yocto_git:`meta-yocto-bsp/conf/machine </cgit/cgit.cgi/poky/tree/meta-yocto-bsp/conf/machine>` + :yocto_git:`meta-yocto-bsp/conf/machine </poky/tree/meta-yocto-bsp/conf/machine>` for sample ``bsp_root_name.conf`` files. Other samples such as - :yocto_git:`meta-ti </cgit/cgit.cgi/meta-ti/tree/conf/machine>` + :yocto_git:`meta-ti </meta-ti/tree/conf/machine>` and - :yocto_git:`meta-freescale </cgit/cgit.cgi/meta-freescale/tree/conf/machine>` + :yocto_git:`meta-freescale </meta-freescale/tree/conf/machine>` exist from other vendors that have more specific machine and tuning examples. @@ -1198,13 +1197,13 @@ Use these steps to create a BSP layer: ``recipes-kernel/linux`` by either using a kernel append file or a new custom kernel recipe file (e.g. ``yocto-linux_4.12.bb``). The BSP layers mentioned in the previous step also contain different kernel - examples. See the ":ref:`kernel-dev/kernel-dev-common:modifying an existing recipe`" + examples. See the ":ref:`kernel-dev/common:modifying an existing recipe`" section in the Yocto Project Linux Kernel Development Manual for information on how to create a custom kernel. The remainder of this section provides a description of the Yocto Project reference BSP for Beaglebone, which resides in the -:yocto_git:`meta-yocto-bsp </cgit/cgit.cgi/poky/tree/meta-yocto-bsp>` +:yocto_git:`meta-yocto-bsp </poky/tree/meta-yocto-bsp>` layer. BSP Layer Configuration Example @@ -1231,7 +1230,7 @@ configuration files is to examine various files for BSP from the :yocto_git:`Source Repositories <>`. For a detailed description of this particular layer configuration file, -see ":ref:`step 3 <dev-manual/dev-manual-common-tasks:creating your own layer>`" +see ":ref:`step 3 <dev-manual/common-tasks:creating your own layer>`" in the discussion that describes how to create layers in the Yocto Project Development Tasks Manual. @@ -1306,7 +1305,7 @@ the example reference machine configuration file for the BeagleBone development boards. Realize that much more can be defined as part of a machine's configuration file. In general, you can learn about related variables that this example does not have by locating the variables in -the ":ref:`ref-manual/ref-variables:variables glossary`" in the Yocto +the ":ref:`ref-manual/variables:variables glossary`" in the Yocto Project Reference Manual. - :term:`PREFERRED_PROVIDER_virtual/xserver <PREFERRED_PROVIDER>`: @@ -1361,7 +1360,7 @@ Project Reference Manual. `JFFS2 <https://en.wikipedia.org/wiki/JFFS2>`__ image. - :term:`WKS_FILE`: The location of - the :ref:`Wic kickstart <ref-manual/ref-kickstart:openembedded kickstart (\`\`.wks\`\`) reference>` file used + the :ref:`Wic kickstart <ref-manual/kickstart:openembedded kickstart (\`\`.wks\`\`) reference>` file used by the OpenEmbedded build system to create a partitioned image (image.wic). @@ -1413,7 +1412,7 @@ Project Reference Manual. .. note:: For more information on how the SPL variables are used, see the - :yocto_git:`u-boot.inc </cgit/cgit.cgi/poky/tree/meta/recipes-bsp/u-boot/u-boot.inc>` + :yocto_git:`u-boot.inc </poky/tree/meta/recipes-bsp/u-boot/u-boot.inc>` include file. - :term:`UBOOT_* <UBOOT_ENTRYPOINT>`: Defines @@ -1457,7 +1456,7 @@ The ``meta-yocto-bsp/recipes-kernel/linux`` directory in the layer contains metadata used to build the kernel. In this case, a kernel append file (i.e. ``linux-yocto_5.0.bbappend``) is used to override an established kernel recipe (i.e. ``linux-yocto_5.0.bb``), which is located in -:yocto_git:`/cgit/cgit.cgi/poky/tree/meta/recipes-kernel/linux`. +:yocto_git:`/poky/tree/meta/recipes-kernel/linux`. Following is the contents of the append file: :: |