| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
| 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
| 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
| 4 | |
| 5 | <chapter id='bsp'> |
| 6 | |
| 7 | <title>Board Support Packages (BSP) - Developer's Guide</title> |
| 8 | |
| 9 | <para> |
| 10 | A Board Support Package (BSP) is a collection of information that |
| 11 | defines how to support a particular hardware device, set of devices, or |
| 12 | hardware platform. |
| 13 | The BSP includes information about the hardware features |
| 14 | present on the device and kernel configuration information along with any |
| 15 | additional hardware drivers required. |
| 16 | The BSP also lists any additional software |
| 17 | components required in addition to a generic Linux software stack for both |
| 18 | essential and optional platform features. |
| 19 | </para> |
| 20 | |
| 21 | <para> |
| 22 | This guide presents information about BSP Layers, defines a structure for components |
| 23 | so that BSPs follow a commonly understood layout, discusses how to customize |
| 24 | a recipe for a BSP, addresses BSP licensing, and provides information that |
| 25 | shows you how to create and manage a |
| 26 | <link linkend='bsp-layers'>BSP Layer</link> using two Yocto Project |
| 27 | <link linkend='using-the-yocto-projects-bsp-tools'>BSP Tools</link>. |
| 28 | </para> |
| 29 | |
| 30 | <section id='bsp-layers'> |
| 31 | <title>BSP Layers</title> |
| 32 | |
| 33 | <para> |
| 34 | A BSP consists of a file structure inside a base directory. |
| 35 | Collectively, you can think of the base directory, its file structure, |
| 36 | and the contents as a BSP Layer. |
| 37 | Although not a strict requirement, layers in the Yocto Project use the |
| 38 | following well-established naming convention: |
| 39 | <literallayout class='monospaced'> |
| 40 | meta-<replaceable>bsp_name</replaceable> |
| 41 | </literallayout> |
| 42 | The string "meta-" is prepended to the machine or platform name, which is |
| 43 | <replaceable>bsp_name</replaceable> in the above form. |
| 44 | <note><title>Tip</title> |
| 45 | Because the BSP layer naming convention is well-established, |
| 46 | it is advisable to follow it when creating layers. |
| 47 | Technically speaking, a BSP layer name does not need to |
| 48 | start with <filename>meta-</filename>. |
| 49 | However, you might run into situations where obscure |
| 50 | scripts assume this convention. |
| 51 | </note> |
| 52 | </para> |
| 53 | |
| 54 | <para> |
| 55 | To help understand the BSP layer concept, consider the BSPs that the |
| 56 | Yocto Project supports and provides with each release. |
| 57 | You can see the layers in the |
| 58 | <ulink url='&YOCTO_DOCS_DEV_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink> |
| 59 | through a web interface at |
| 60 | <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'></ulink>. |
| 61 | If you go to that interface, you will find near the bottom of the list |
| 62 | under "Yocto Metadata Layers" several BSP layers all of which are |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 63 | supported by the Yocto Project (e.g. <filename>meta-raspberrypi</filename> and |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 64 | <filename>meta-intel</filename>). |
| 65 | Each of these layers is a repository unto itself and clicking on a |
| 66 | layer reveals information that includes two links from which you can choose |
| 67 | to set up a clone of the layer's repository on your local host system. |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 68 | Here is an example that clones the Raspberry Pi BSP layer: |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 69 | <literallayout class='monospaced'> |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 70 | $ git clone git://git.yoctoproject.org/meta-raspberrypi |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 71 | </literallayout> |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 72 | </para> |
| 73 | |
| 74 | <para> |
| 75 | In addition to BSP layers near the bottom of that referenced |
| 76 | Yocto Project Source Repository, the |
| 77 | <filename>meta-yocto-bsp</filename> layer is part of the |
| 78 | shipped <filename>poky</filename> repository. |
| 79 | The <filename>meta-yocto-bsp</filename> layer maintains several |
| 80 | BSPs such as the Beaglebone, EdgeRouter, and generic versions of |
| 81 | both 32 and 64-bit IA machines. |
| 82 | </para> |
| 83 | |
| 84 | <para> |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 85 | For information on the BSP development workflow, see the |
| 86 | "<ulink url='&YOCTO_DOCS_DEV_URL;#developing-a-board-support-package-bsp'>Developing a Board Support Package (BSP)</ulink>" |
| 87 | section in the Yocto Project Development Manual. |
| 88 | For more information on how to set up a local copy of source files |
| 89 | from a Git repository, see the |
| 90 | "<ulink url='&YOCTO_DOCS_DEV_URL;#getting-setup'>Getting Set Up</ulink>" |
| 91 | section also in the Yocto Project Development Manual. |
| 92 | </para> |
| 93 | |
| 94 | <para> |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 95 | The layer's base directory |
| 96 | (<filename>meta-<replaceable>bsp_name</replaceable></filename>) |
| 97 | is the root of the BSP Layer. |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 98 | This root is what you add to the |
| 99 | <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink> |
| 100 | variable in the <filename>conf/bblayers.conf</filename> file found in the |
| 101 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>, |
| 102 | which is established after you run one of the OpenEmbedded build environment |
| 103 | setup scripts (i.e. |
| 104 | <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> |
| 105 | and |
| 106 | <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>). |
| 107 | Adding the root allows the OpenEmbedded build system to recognize the BSP |
| 108 | definition and from it build an image. |
| 109 | Here is an example: |
| 110 | <literallayout class='monospaced'> |
| 111 | BBLAYERS ?= " \ |
| 112 | /usr/local/src/yocto/meta \ |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 113 | /usr/local/src/yocto/meta-poky \ |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 114 | /usr/local/src/yocto/meta-yocto-bsp \ |
| 115 | /usr/local/src/yocto/meta-mylayer \ |
| 116 | " |
| 117 | </literallayout> |
| 118 | </para> |
| 119 | |
| 120 | <para> |
| 121 | Some BSPs require additional layers on |
| 122 | top of the BSP's root layer in order to be functional. |
| 123 | For these cases, you also need to add those layers to the |
| 124 | <filename>BBLAYERS</filename> variable in order to build the BSP. |
| 125 | You must also specify in the "Dependencies" section of the BSP's |
| 126 | <filename>README</filename> file any requirements for additional |
| 127 | layers and, preferably, any |
| 128 | build instructions that might be contained elsewhere |
| 129 | in the <filename>README</filename> file. |
| 130 | </para> |
| 131 | |
| 132 | <para> |
| 133 | Some layers function as a layer to hold other BSP layers. |
| 134 | An example of this type of layer is the <filename>meta-intel</filename> layer, |
| 135 | which contains a number of individual BSP sub-layers, as well as a directory |
| 136 | named <filename>common/</filename> full of common content across those layers. |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 137 | Another example is the <filename>meta-yocto-bsp</filename> layer mentioned |
| 138 | earlier. |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 139 | </para> |
| 140 | |
| 141 | <para> |
| 142 | For more detailed information on layers, see the |
| 143 | "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" |
| 144 | section of the Yocto Project Development Manual. |
| 145 | </para> |
| 146 | </section> |
| 147 | |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 148 | <section id="bsp-filelayout"> |
| 149 | <title>Example Filesystem Layout</title> |
| 150 | |
| 151 | <para> |
| 152 | Defining a common BSP directory structure allows end-users to understand and |
| 153 | become familiar with that structure. |
| 154 | A common format also encourages standardization of software support of hardware. |
| 155 | </para> |
| 156 | |
| 157 | <para> |
| 158 | The proposed form does have elements that are specific to the |
| 159 | OpenEmbedded build system. |
| 160 | It is intended that this information can be |
| 161 | used by other build systems besides the OpenEmbedded build system |
| 162 | and that it will be simple |
| 163 | to extract information and convert it to other formats if required. |
| 164 | The OpenEmbedded build system, through its standard layers mechanism, can directly |
| 165 | accept the format described as a layer. |
| 166 | The BSP captures all |
| 167 | the hardware-specific details in one place in a standard format, which is |
| 168 | useful for any person wishing to use the hardware platform regardless of |
| 169 | the build system they are using. |
| 170 | </para> |
| 171 | |
| 172 | <para> |
| 173 | The BSP specification does not include a build system or other tools - |
| 174 | it is concerned with the hardware-specific components only. |
| 175 | At the end-distribution point, you can ship the BSP combined with a build system |
| 176 | and other tools. |
| 177 | However, it is important to maintain the distinction that these |
| 178 | are separate components that happen to be combined in certain end products. |
| 179 | </para> |
| 180 | |
| 181 | <para> |
| 182 | Before looking at the common form for the file structure inside a BSP Layer, |
| 183 | you should be aware that some requirements do exist in order for a BSP to |
| 184 | be considered compliant with the Yocto Project. |
| 185 | For that list of requirements, see the |
| 186 | "<link linkend='released-bsp-requirements'>Released BSP Requirements</link>" |
| 187 | section. |
| 188 | </para> |
| 189 | |
| 190 | <para> |
| 191 | Below is the common form for the file structure inside a BSP Layer. |
| 192 | While you can use this basic form for the standard, realize that the actual structures |
| 193 | for specific BSPs could differ. |
| 194 | |
| 195 | <literallayout class='monospaced'> |
| 196 | meta-<replaceable>bsp_name</replaceable>/ |
| 197 | meta-<replaceable>bsp_name</replaceable>/<replaceable>bsp_license_file</replaceable> |
| 198 | meta-<replaceable>bsp_name</replaceable>/README |
| 199 | meta-<replaceable>bsp_name</replaceable>/README.sources |
| 200 | meta-<replaceable>bsp_name</replaceable>/binary/<replaceable>bootable_images</replaceable> |
| 201 | meta-<replaceable>bsp_name</replaceable>/conf/layer.conf |
| 202 | meta-<replaceable>bsp_name</replaceable>/conf/machine/*.conf |
| 203 | meta-<replaceable>bsp_name</replaceable>/recipes-bsp/* |
| 204 | meta-<replaceable>bsp_name</replaceable>/recipes-core/* |
| 205 | meta-<replaceable>bsp_name</replaceable>/recipes-graphics/* |
| 206 | meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux/linux-yocto_<replaceable>kernel_rev</replaceable>.bbappend |
| 207 | </literallayout> |
| 208 | </para> |
| 209 | |
| 210 | <para> |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 211 | Below is an example of the Raspberry Pi BSP: |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 212 | |
| 213 | <literallayout class='monospaced'> |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 214 | meta-raspberrypi/COPYING.MIT |
| 215 | meta-raspberrypi/README |
| 216 | meta-raspberrypi/classes |
| 217 | meta-raspberrypi/classes/linux-raspberrypi-base.bbclass |
| 218 | meta-raspberrypi/classes/sdcard_image-rpi.bbclass |
| 219 | meta-raspberrypi/conf/ |
| 220 | meta-raspberrypi/conf/layer.conf |
| 221 | meta-raspberrypi/conf/machine/ |
| 222 | meta-raspberrypi/conf/machine/raspberrypi.conf |
| 223 | meta-raspberrypi/conf/machine/raspberrypi0.conf |
| 224 | meta-raspberrypi/conf/machine/raspberrypi2.conf |
| 225 | meta-raspberrypi/conf/machine/raspberrypi3.conf |
| 226 | meta-raspberrypi/conf/machine/include |
| 227 | meta-raspberrypi/conf/machine/include/rpi-base.inc |
| 228 | meta-raspberrypi/conf/machine/include/rpi-default-providers.inc |
| 229 | meta-raspberrypi/conf/machine/include/rpi-default-settings.inc |
| 230 | meta-raspberrypi/conf/machine/include/rpi-default-versions.inc |
| 231 | meta-raspberrypi/conf/machine/include/rpi-tune-arm1176jzf-s.inc |
| 232 | meta-raspberrypi/files |
| 233 | meta-raspberrypi/files/custom-licenses |
| 234 | meta-raspberrypi/files/custom-licenses/Broadcom |
| 235 | meta-raspberrypi/recipes-bsp |
| 236 | meta-raspberrypi/recipes-bsp/bootfiles |
| 237 | meta-raspberrypi/recipes-bsp/bootfiles/bcm2835-bootfiles.bb |
| 238 | meta-raspberrypi/recipes-bsp/bootfiles/rpi-config_git.bb |
| 239 | meta-raspberrypi/recipes-bsp/common |
| 240 | meta-raspberrypi/recipes-bsp/common/firmware.inc |
| 241 | meta-raspberrypi/recipes-bsp/formfactor_00.bbappend |
| 242 | meta-raspberrypi/recipes-bsp/formfactor/raspberrypi/machconfig |
| 243 | meta-raspberrypi/recipes-bsp/rpi-mkimage_git.bb |
| 244 | meta-raspberrypi/recipes-bsp/rpi-mkimage/License |
| 245 | meta-raspberrypi/recipes-bsp/rpi-mkimage/open-files-relative-to-script.patch |
| 246 | meta-raspberrypi/recipes-bsp/u-boot/u-boot-rpi_git.bb |
| 247 | meta-raspberrypi/recipes-core |
| 248 | meta-raspberrypi/recipes-core/images |
| 249 | meta-raspberrypi/recipes-core/images/rpi-basic-image.bb |
| 250 | meta-raspberrypi/recipes-core/images/rpi-hwup-image.bb |
| 251 | meta-raspberrypi/recipes-core/images/rpi-test-image.bb |
| 252 | meta-raspberrypi/recipes-core/packagegroups |
| 253 | meta-raspberrypi/recipes-core/packagegroups/packagegroup-rpi-test.bb |
| 254 | meta-raspberrypi/recipes-core/psplash |
| 255 | meta-raspberrypi/recipes-core/psplash/files |
| 256 | meta-raspberrypi/recipes-core/psplash/psplash_git.bbappend |
| 257 | meta-raspberrypi/recipes-core/psplash/files/psplash-raspberrypi-img.h |
| 258 | meta-raspberrypi/recipes-devtools |
| 259 | meta-raspberrypi/recipes-devtools/bcm2835 |
| 260 | meta-raspberrypi/recipes-devtools/bcm2835/bcm2835_1.46.bb |
| 261 | meta-raspberrypi/recipes-devtools/pi-blaster |
| 262 | meta-raspberrypi/recipes-devtools/pi-blaster/files |
| 263 | meta-raspberrypi/recipes-devtools/pi-blaster/*.patch |
| 264 | meta-raspberrypi/recipes-devtools/pi-blaster/pi-blaster.inc |
| 265 | meta-raspberrypi/recipes-devtools/pi-blaster/pi-blaster_git.bb |
| 266 | meta-raspberrypi/recipes-devtools/python |
| 267 | meta-raspberrypi/recipes-devtools/python/python-rtimu |
| 268 | meta-raspberrypi/recipes-devtools/python/python-rtimu/*.patch |
| 269 | meta-raspberrypi/recipes-devtools/python/python-rtimu_git.bb |
| 270 | meta-raspberrypi/recipes-devtools/python/python-sense-hat_2.1.0.bb |
| 271 | meta-raspberrypi/recipes-devtools/python/rpi-gpio |
| 272 | meta-raspberrypi/recipes-devtools/python/rpi-gpio/*.patch |
| 273 | meta-raspberrypi/recipes-devtools/python/rpi-gpio_0.6.1.bb |
| 274 | meta-raspberrypi/recipes-devtools/python/rpio |
| 275 | meta-raspberrypi/recipes-devtools/python/rpio/*.patch |
| 276 | meta-raspberrypi/recipes-devtools/python/rpio_0.10.0.bb |
| 277 | meta-raspberrypi/recipes-devtools/wiringPi |
| 278 | meta-raspberrypi/recipes-devtools/wiringPi/files |
| 279 | meta-raspberrypi/recipes-devtools/wiringPi/files/*.patch |
| 280 | meta-raspberrypi/recipes-devtools/wiringPi/wiringpi |
| 281 | meta-raspberrypi/recipes-devtools/wiringPi/wiringpi/*.patch |
| 282 | meta-raspberrypi/recipes-devtools/wiringPi/wiringpi_git.bb |
| 283 | meta-raspberrypi/recipes-graphics |
| 284 | meta-raspberrypi/recipes-graphics/eglinfo |
| 285 | meta-raspberrypi/recipes-graphics/eglinfo/eglinfo-fb_%.bbappend |
| 286 | meta-raspberrypi/recipes-graphics/eglinfo/eglinfo-x11_%.bbappend |
| 287 | meta-raspberrypi/recipes-graphics/userland |
| 288 | meta-raspberrypi/recipes-graphics/userland/userland |
| 289 | meta-raspberrypi/recipes-graphics/userland/userland/*.patch |
| 290 | meta-raspberrypi/recipes-graphics/userland/userland_git.bb |
| 291 | meta-raspberrypi/recipes-graphics/vc-graphics |
| 292 | meta-raspberrypi/recipes-graphics/vc-graphics/files |
| 293 | meta-raspberrypi/recipes-graphics/vc-graphics/files/egl.pc |
| 294 | meta-raspberrypi/recipes-graphics/vc-graphics/files/vchiq.sh |
| 295 | meta-raspberrypi/recipes-graphics/vc-graphics/vc-graphics-hardfp.bb |
| 296 | meta-raspberrypi/recipes-graphics/vc-graphics/vc-graphics.bb |
| 297 | meta-raspberrypi/recipes-graphics/vc-graphics/vc-graphics.inc |
| 298 | meta-raspberrypi/recipes-graphics/wayland |
| 299 | meta-raspberrypi/recipes-graphics/wayland/weston_%.bbappend |
| 300 | meta-raspberrypi/recipes-graphics/weston |
| 301 | meta-raspberrypi/recipes-graphics/weston/weston_%.bbappend |
| 302 | meta-raspberrypi/recipes-graphics/xorg-xserver |
| 303 | meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config |
| 304 | meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi |
| 305 | meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf |
| 306 | meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d |
| 307 | meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/10-evdev.conf |
| 308 | meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/99-pitft.conf |
| 309 | meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend |
| 310 | meta-raspberrypi/recipes-kernel |
| 311 | meta-raspberrypi/recipes-kernel/linux-firmware |
| 312 | meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware |
| 313 | meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware/LICENSE.broadcom_brcm80211 |
| 314 | meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware/brcmfmac43430-sdio.bin |
| 315 | meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware/brcmfmac43430-sdio.txt |
| 316 | meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware_git.bbappend |
| 317 | meta-raspberrypi/recipes-kernel/linux |
| 318 | meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-3.14 |
| 319 | meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-3.14/*.patch |
| 320 | meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-3.18 |
| 321 | meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-3.18/*.patch |
| 322 | meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-4.1 |
| 323 | meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-4.1/*.patch |
| 324 | meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi.inc |
| 325 | meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi |
| 326 | meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi/defconfig |
| 327 | meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_3.14.bb |
| 328 | meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_3.18.bb |
| 329 | meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_4.1.bb |
| 330 | meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_4.4.bb |
| 331 | meta-raspberrypi/recipes-kernel/linux/linux.inc |
| 332 | meta-raspberrypi/recipes-multimedia |
| 333 | meta-raspberrypi/recipes-multimedia/gstreamer |
| 334 | meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx |
| 335 | meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx/*.patch |
| 336 | meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx_%.bbappend |
| 337 | meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-plugins-bad_%.bbappend |
| 338 | meta-raspberrypi/recipes-multimedia/omxplayer |
| 339 | meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer |
| 340 | meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer/*.patch |
| 341 | meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer_git.bb |
| 342 | meta-raspberrypi/scripts |
| 343 | meta-raspberrypi/scripts/lib |
| 344 | meta-raspberrypi/scripts/lib/image |
| 345 | meta-raspberrypi/scripts/lib/image/canned-wks |
| 346 | meta-raspberrypi/scripts/lib/image/canned-wks/sdimage-raspberrypi.wks |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 347 | </literallayout> |
| 348 | </para> |
| 349 | |
| 350 | <para> |
| 351 | The following sections describe each part of the proposed BSP format. |
| 352 | </para> |
| 353 | |
| 354 | <section id="bsp-filelayout-license"> |
| 355 | <title>License Files</title> |
| 356 | |
| 357 | <para> |
| 358 | You can find these files in the BSP Layer at: |
| 359 | <literallayout class='monospaced'> |
| 360 | meta-<replaceable>bsp_name</replaceable>/<replaceable>bsp_license_file</replaceable> |
| 361 | </literallayout> |
| 362 | </para> |
| 363 | |
| 364 | <para> |
| 365 | These optional files satisfy licensing requirements for the BSP. |
| 366 | The type or types of files here can vary depending on the licensing requirements. |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 367 | For example, in the Raspberry Pi BSP all licensing requirements are handled with the |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 368 | <filename>COPYING.MIT</filename> file. |
| 369 | </para> |
| 370 | |
| 371 | <para> |
| 372 | Licensing files can be MIT, BSD, GPLv*, and so forth. |
| 373 | These files are recommended for the BSP but are optional and totally up to the BSP developer. |
| 374 | </para> |
| 375 | </section> |
| 376 | |
| 377 | <section id="bsp-filelayout-readme"> |
| 378 | <title>README File</title> |
| 379 | <para> |
| 380 | You can find this file in the BSP Layer at: |
| 381 | <literallayout class='monospaced'> |
| 382 | meta-<replaceable>bsp_name</replaceable>/README |
| 383 | </literallayout> |
| 384 | </para> |
| 385 | |
| 386 | <para> |
| 387 | This file provides information on how to boot the live images that are optionally |
| 388 | included in the <filename>binary/</filename> directory. |
| 389 | The <filename>README</filename> file also provides special information needed for |
| 390 | building the image. |
| 391 | </para> |
| 392 | |
| 393 | <para> |
| 394 | At a minimum, the <filename>README</filename> file must |
| 395 | contain a list of dependencies, such as the names of |
| 396 | any other layers on which the BSP depends and the name of |
| 397 | the BSP maintainer with his or her contact information. |
| 398 | </para> |
| 399 | </section> |
| 400 | |
| 401 | <section id="bsp-filelayout-readme-sources"> |
| 402 | <title>README.sources File</title> |
| 403 | <para> |
| 404 | You can find this file in the BSP Layer at: |
| 405 | <literallayout class='monospaced'> |
| 406 | meta-<replaceable>bsp_name</replaceable>/README.sources |
| 407 | </literallayout> |
| 408 | </para> |
| 409 | |
| 410 | <para> |
| 411 | This file provides information on where to locate the BSP |
| 412 | source files used to build the images (if any) that reside in |
| 413 | <filename>meta-<replaceable>bsp_name</replaceable>/binary</filename>. |
| 414 | Images in the <filename>binary</filename> would be images |
| 415 | released with the BSP. |
| 416 | The information in the <filename>README.sources</filename> |
| 417 | file also helps you find the |
| 418 | <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> |
| 419 | used to generate the images that ship with the BSP. |
| 420 | <note> |
| 421 | If the BSP's <filename>binary</filename> directory is |
| 422 | missing or the directory has no images, an existing |
| 423 | <filename>README.sources</filename> file is |
| 424 | meaningless. |
| 425 | </note> |
| 426 | </para> |
| 427 | </section> |
| 428 | |
| 429 | <section id="bsp-filelayout-binary"> |
| 430 | <title>Pre-built User Binaries</title> |
| 431 | <para> |
| 432 | You can find these files in the BSP Layer at: |
| 433 | <literallayout class='monospaced'> |
| 434 | meta-<replaceable>bsp_name</replaceable>/binary/<replaceable>bootable_images</replaceable> |
| 435 | </literallayout> |
| 436 | </para> |
| 437 | |
| 438 | <para> |
| 439 | This optional area contains useful pre-built kernels and |
| 440 | user-space filesystem images released with the BSP that are |
| 441 | appropriate to the target system. |
| 442 | This directory typically contains graphical (e.g. Sato) and |
| 443 | minimal live images when the BSP tarball has been created and |
| 444 | made available in the |
| 445 | <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink> website. |
| 446 | You can use these kernels and images to get a system running |
| 447 | and quickly get started on development tasks. |
| 448 | </para> |
| 449 | |
| 450 | <para> |
| 451 | The exact types of binaries present are highly |
| 452 | hardware-dependent. |
| 453 | The <filename>README</filename> file should be present in the |
| 454 | BSP Layer and it will explain how to use the images with the |
| 455 | target hardware. |
| 456 | Additionally, the <filename>README.sources</filename> file |
| 457 | should be present to locate the sources used to build the |
| 458 | images and provide information on the Metadata. |
| 459 | </para> |
| 460 | </section> |
| 461 | |
| 462 | <section id='bsp-filelayout-layer'> |
| 463 | <title>Layer Configuration File</title> |
| 464 | <para> |
| 465 | You can find this file in the BSP Layer at: |
| 466 | <literallayout class='monospaced'> |
| 467 | meta-<replaceable>bsp_name</replaceable>/conf/layer.conf |
| 468 | </literallayout> |
| 469 | </para> |
| 470 | |
| 471 | <para> |
| 472 | The <filename>conf/layer.conf</filename> file identifies the file structure as a |
| 473 | layer, identifies the |
| 474 | contents of the layer, and contains information about how the build |
| 475 | system should use it. |
| 476 | Generally, a standard boilerplate file such as the following works. |
| 477 | In the following example, you would replace "<replaceable>bsp</replaceable>" and |
| 478 | "<replaceable>_bsp</replaceable>" with the actual name |
| 479 | of the BSP (i.e. <replaceable>bsp_name</replaceable> from the example template). |
| 480 | </para> |
| 481 | |
| 482 | <para> |
| 483 | <literallayout class='monospaced'> |
| 484 | # We have a conf and classes directory, add to BBPATH |
| 485 | BBPATH .= ":${LAYERDIR}" |
| 486 | |
| 487 | # We have a recipes directory, add to BBFILES |
| 488 | BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 489 | ${LAYERDIR}/recipes-*/*/*.bbappend" |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 490 | |
| 491 | BBFILE_COLLECTIONS += "<replaceable>bsp</replaceable>" |
| 492 | BBFILE_PATTERN_<replaceable>bsp</replaceable> = "^${LAYERDIR}/" |
| 493 | BBFILE_PRIORITY_<replaceable>bsp</replaceable> = "6" |
| 494 | |
| 495 | LAYERDEPENDS_<replaceable>bsp</replaceable> = "intel" |
| 496 | </literallayout> |
| 497 | </para> |
| 498 | |
| 499 | <para> |
| 500 | To illustrate the string substitutions, here are the corresponding statements |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 501 | from the Raspberry Pi <filename>conf/layer.conf</filename> file: |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 502 | <literallayout class='monospaced'> |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 503 | # We have a conf and classes directory, append to BBPATH |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 504 | BBPATH .= ":${LAYERDIR}" |
| 505 | |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 506 | # We have a recipes directory containing .bb and .bbappend files, add to BBFILES |
| 507 | BBFILES += "${LAYERDIR}/recipes*/*/*.bb \ |
| 508 | ${LAYERDIR}/recipes*/*/*.bbappend" |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 509 | |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 510 | BBFILE_COLLECTIONS += "raspberrypi" |
| 511 | BBFILE_PATTERN_raspberrypi := "^${LAYERDIR}/" |
| 512 | BBFILE_PRIORITY_raspberrypi = "9" |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 513 | |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 514 | # Additional license directories. |
| 515 | LICENSE_PATH += "${LAYERDIR}/files/custom-licenses" |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 516 | </literallayout> |
| 517 | </para> |
| 518 | |
| 519 | <para> |
| 520 | This file simply makes |
| 521 | <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink> |
| 522 | aware of the recipes and configuration directories. |
| 523 | The file must exist so that the OpenEmbedded build system can recognize the BSP. |
| 524 | </para> |
| 525 | </section> |
| 526 | |
| 527 | <section id="bsp-filelayout-machine"> |
| 528 | <title>Hardware Configuration Options</title> |
| 529 | <para> |
| 530 | You can find these files in the BSP Layer at: |
| 531 | <literallayout class='monospaced'> |
| 532 | meta-<replaceable>bsp_name</replaceable>/conf/machine/*.conf |
| 533 | </literallayout> |
| 534 | </para> |
| 535 | |
| 536 | <para> |
| 537 | The machine files bind together all the information contained elsewhere |
| 538 | in the BSP into a format that the build system can understand. |
| 539 | If the BSP supports multiple machines, multiple machine configuration files |
| 540 | can be present. |
| 541 | These filenames correspond to the values to which users have set the |
| 542 | <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable. |
| 543 | </para> |
| 544 | |
| 545 | <para> |
| 546 | These files define things such as the kernel package to use |
| 547 | (<ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink> |
| 548 | of virtual/kernel), the hardware drivers to |
| 549 | include in different types of images, any special software components |
| 550 | that are needed, any bootloader information, and also any special image |
| 551 | format requirements. |
| 552 | </para> |
| 553 | |
| 554 | <para> |
| 555 | Each BSP Layer requires at least one machine file. |
| 556 | However, you can supply more than one file. |
| 557 | </para> |
| 558 | |
| 559 | <para> |
| 560 | This configuration file could also include a hardware "tuning" |
| 561 | file that is commonly used to define the package architecture |
| 562 | and specify optimization flags, which are carefully chosen |
| 563 | to give best performance on a given processor. |
| 564 | </para> |
| 565 | |
| 566 | <para> |
| 567 | Tuning files are found in the <filename>meta/conf/machine/include</filename> |
| 568 | directory within the |
| 569 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. |
| 570 | For example, the <filename>ia32-base.inc</filename> file resides in the |
| 571 | <filename>meta/conf/machine/include</filename> directory. |
| 572 | </para> |
| 573 | |
| 574 | <para> |
| 575 | To use an include file, you simply include them in the |
| 576 | machine configuration file. |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 577 | For example, the Raspberry Pi BSP |
| 578 | <filename>raspberrypi3.conf</filename> contains the |
| 579 | following statement: |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 580 | <literallayout class='monospaced'> |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 581 | include conf/machine/raspberrypi2.conf |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 582 | </literallayout> |
| 583 | </para> |
| 584 | </section> |
| 585 | |
| 586 | <section id='bsp-filelayout-misc-recipes'> |
| 587 | <title>Miscellaneous BSP-Specific Recipe Files</title> |
| 588 | <para> |
| 589 | You can find these files in the BSP Layer at: |
| 590 | <literallayout class='monospaced'> |
| 591 | meta-<replaceable>bsp_name</replaceable>/recipes-bsp/* |
| 592 | </literallayout> |
| 593 | </para> |
| 594 | |
| 595 | <para> |
| 596 | This optional directory contains miscellaneous recipe files for |
| 597 | the BSP. |
| 598 | Most notably would be the formfactor files. |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 599 | For example, in the Raspberry Pi BSP there is the |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 600 | <filename>formfactor_0.0.bbappend</filename> file, which is an |
| 601 | append file used to augment the recipe that starts the build. |
| 602 | Furthermore, there are machine-specific settings used during |
| 603 | the build that are defined by the |
| 604 | <filename>machconfig</filename> file further down in the |
| 605 | directory. |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 606 | Here is the <filename>machconfig</filename> |
| 607 | file for the Raspberry Pi BSP: |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 608 | <literallayout class='monospaced'> |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 609 | HAVE_TOUCHSCREEN=0 |
| 610 | HAVE_KEYBOARD=1 |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 611 | |
| 612 | DISPLAY_CAN_ROTATE=0 |
| 613 | DISPLAY_ORIENTATION=0 |
| 614 | DISPLAY_DPI=133 |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 615 | </literallayout> |
| 616 | </para> |
| 617 | |
| 618 | <note><para> |
| 619 | If a BSP does not have a formfactor entry, defaults are established according to |
| 620 | the formfactor configuration file that is installed by the main |
| 621 | formfactor recipe |
| 622 | <filename>meta/recipes-bsp/formfactor/formfactor_0.0.bb</filename>, |
| 623 | which is found in the |
| 624 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. |
| 625 | </para></note> |
| 626 | </section> |
| 627 | |
| 628 | <section id='bsp-filelayout-recipes-graphics'> |
| 629 | <title>Display Support Files</title> |
| 630 | <para> |
| 631 | You can find these files in the BSP Layer at: |
| 632 | <literallayout class='monospaced'> |
| 633 | meta-<replaceable>bsp_name</replaceable>/recipes-graphics/* |
| 634 | </literallayout> |
| 635 | </para> |
| 636 | |
| 637 | <para> |
| 638 | This optional directory contains recipes for the BSP if it has |
| 639 | special requirements for graphics support. |
| 640 | All files that are needed for the BSP to support a display are |
| 641 | kept here. |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 642 | </para> |
| 643 | </section> |
| 644 | |
| 645 | <section id='bsp-filelayout-kernel'> |
| 646 | <title>Linux Kernel Configuration</title> |
| 647 | <para> |
| 648 | You can find these files in the BSP Layer at: |
| 649 | <literallayout class='monospaced'> |
| 650 | meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux/linux-yocto*.bbappend |
| 651 | </literallayout> |
| 652 | </para> |
| 653 | |
| 654 | <para> |
| 655 | These files append your specific changes to the main kernel recipe you are using. |
| 656 | </para> |
| 657 | <para> |
| 658 | For your BSP, you typically want to use an existing Yocto Project kernel recipe found in the |
| 659 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> |
| 660 | at <filename>meta/recipes-kernel/linux</filename>. |
| 661 | You can append your specific changes to the kernel recipe by using a |
| 662 | similarly named append file, which is located in the BSP Layer (e.g. |
| 663 | the <filename>meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux</filename> directory). |
| 664 | </para> |
| 665 | <para> |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 666 | Suppose you are using the <filename>linux-yocto_4.4.bb</filename> recipe to build |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 667 | the kernel. |
| 668 | In other words, you have selected the kernel in your |
| 669 | <replaceable>bsp_name</replaceable><filename>.conf</filename> file by adding these types |
| 670 | of statements: |
| 671 | <literallayout class='monospaced'> |
| 672 | PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 673 | PREFERRED_VERSION_linux-yocto ?= "4.4%" |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 674 | </literallayout> |
| 675 | <note> |
| 676 | When the preferred provider is assumed by default, the |
| 677 | <filename>PREFERRED_PROVIDER</filename> statement does not appear in the |
| 678 | <replaceable>bsp_name</replaceable><filename>.conf</filename> file. |
| 679 | </note> |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 680 | You would use the <filename>linux-yocto_4.4.bbappend</filename> |
| 681 | file to append specific BSP settings to the kernel, thus |
| 682 | configuring the kernel for your particular BSP. |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 683 | </para> |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 684 | |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 685 | <para> |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 686 | As an example, consider the following append file |
| 687 | used by the BSPs in <filename>meta-yocto-bsp</filename>: |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 688 | <literallayout class='monospaced'> |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 689 | meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.4.bbappend |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 690 | </literallayout> |
| 691 | The following listing shows the file. |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 692 | Be aware that the actual commit ID strings in this |
| 693 | example listing might be different than the actual strings |
| 694 | in the file from the <filename>meta-yocto-bsp</filename> |
| 695 | layer upstream. |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 696 | <literallayout class='monospaced'> |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 697 | KBRANCH_genericx86 = "standard/base" |
| 698 | KBRANCH_genericx86-64 = "standard/base" |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 699 | |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 700 | KMACHINE_genericx86 ?= "common-pc" |
| 701 | KMACHINE_genericx86-64 ?= "common-pc-64" |
| 702 | KBRANCH_edgerouter = "standard/edgerouter" |
| 703 | KBRANCH_beaglebone = "standard/beaglebone" |
| 704 | KBRANCH_mpc8315e-rdb = "standard/fsl-mpc8315e-rdb" |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 705 | |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 706 | SRCREV_machine_genericx86 ?= "ff4c4ef15b51f45b9106d71bf1f62fe7c02e63c2" |
| 707 | SRCREV_machine_genericx86-64 ?= "ff4c4ef15b51f45b9106d71bf1f62fe7c02e63c2" |
| 708 | SRCREV_machine_edgerouter ?= "ff4c4ef15b51f45b9106d71bf1f62fe7c02e63c2" |
| 709 | SRCREV_machine_beaglebone ?= "ff4c4ef15b51f45b9106d71bf1f62fe7c02e63c2" |
| 710 | SRCREV_machine_mpc8315e-rdb ?= "df00877ef9387b38b9601c82db57de2a1b23ce53" |
| 711 | |
| 712 | COMPATIBLE_MACHINE_genericx86 = "genericx86" |
| 713 | COMPATIBLE_MACHINE_genericx86-64 = "genericx86-64" |
| 714 | COMPATIBLE_MACHINE_edgerouter = "edgerouter" |
| 715 | COMPATIBLE_MACHINE_beaglebone = "beaglebone" |
| 716 | COMPATIBLE_MACHINE_mpc8315e-rdb = "mpc8315e-rdb" |
| 717 | |
| 718 | LINUX_VERSION_genericx86 = "4.4.3" |
| 719 | LINUX_VERSION_genericx86-64 = "4.4.3" |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 720 | </literallayout> |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 721 | This append file contains statements used to support |
| 722 | several BSPs that ship with the Yocto Project. |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 723 | The file defines machines using the |
| 724 | <ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink> |
| 725 | variable and uses the |
| 726 | <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink> |
| 727 | variable to ensure the machine name used by the OpenEmbedded |
| 728 | build system maps to the machine name used by the Linux Yocto |
| 729 | kernel. |
| 730 | The file also uses the optional |
| 731 | <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink> |
| 732 | variable to ensure the build process uses the |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 733 | appropriate kernel branch. |
| 734 | </para> |
| 735 | |
| 736 | <para> |
| 737 | Although this particular example does not use it, the |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 738 | <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink> |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 739 | variable could be used to enable features specific to |
| 740 | the kernel. |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 741 | The append file points to specific commits in the |
| 742 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> |
| 743 | Git repository and the <filename>meta</filename> Git repository |
| 744 | branches to identify the exact kernel needed to build the |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 745 | BSP. |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 746 | </para> |
| 747 | |
| 748 | <para> |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 749 | One thing missing in this particular BSP, which you will |
| 750 | typically need when developing a BSP, is the kernel configuration |
| 751 | file (<filename>.config</filename>) for your BSP. |
| 752 | When developing a BSP, you probably have a kernel configuration |
| 753 | file or a set of kernel configuration files that, when taken |
| 754 | together, define the kernel configuration for your BSP. |
| 755 | You can accomplish this definition by putting the configurations |
| 756 | in a file or a set of files inside a directory located at the |
| 757 | same level as your kernel's append file and having the same |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 758 | name as the kernel's main recipe file. |
| 759 | With all these conditions met, simply reference those files in the |
| 760 | <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> |
| 761 | statement in the append file. |
| 762 | </para> |
| 763 | |
| 764 | <para> |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 765 | For example, suppose you had some configuration options |
| 766 | in a file called <filename>network_configs.cfg</filename>. |
| 767 | You can place that file inside a directory named |
| 768 | <filename>linux-yocto</filename> and then add |
| 769 | a <filename>SRC_URI</filename> statement such as the |
| 770 | following to the append file. |
| 771 | When the OpenEmbedded build system builds the kernel, the |
| 772 | configuration options are picked up and applied. |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 773 | <literallayout class='monospaced'> |
| 774 | SRC_URI += "file://network_configs.cfg" |
| 775 | </literallayout> |
| 776 | </para> |
| 777 | |
| 778 | <para> |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 779 | To group related configurations into multiple files, you |
| 780 | perform a similar procedure. |
| 781 | Here is an example that groups separate configurations |
| 782 | specifically for Ethernet and graphics into their own |
| 783 | files and adds the configurations by using a |
| 784 | <filename>SRC_URI</filename> statement like the following |
| 785 | in your append file: |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 786 | <literallayout class='monospaced'> |
| 787 | SRC_URI += "file://myconfig.cfg \ |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 788 | file://eth.cfg \ |
| 789 | file://gfx.cfg" |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 790 | </literallayout> |
| 791 | </para> |
| 792 | |
| 793 | <para> |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 794 | Another variable you can use in your kernel recipe append |
| 795 | file is the |
| 796 | <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> |
| 797 | variable. |
| 798 | When you use this statement, you are extending the locations |
| 799 | used by the OpenEmbedded system to look for files and |
| 800 | patches as the recipe is processed. |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 801 | </para> |
| 802 | |
| 803 | <note> |
| 804 | <para> |
| 805 | Other methods exist to accomplish grouping and defining configuration options. |
| 806 | For example, if you are working with a local clone of the kernel repository, |
| 807 | you could checkout the kernel's <filename>meta</filename> branch, make your changes, |
| 808 | and then push the changes to the local bare clone of the kernel. |
| 809 | The result is that you directly add configuration options to the |
| 810 | <filename>meta</filename> branch for your BSP. |
| 811 | The configuration options will likely end up in that location anyway if the BSP gets |
| 812 | added to the Yocto Project. |
| 813 | </para> |
| 814 | |
| 815 | <para> |
| 816 | In general, however, the Yocto Project maintainers take care of moving the |
| 817 | <filename>SRC_URI</filename>-specified |
| 818 | configuration options to the kernel's <filename>meta</filename> branch. |
| 819 | Not only is it easier for BSP developers to not have to worry about putting those |
| 820 | configurations in the branch, but having the maintainers do it allows them to apply |
| 821 | 'global' knowledge about the kinds of common configuration options multiple BSPs in |
| 822 | the tree are typically using. |
| 823 | This allows for promotion of common configurations into common features. |
| 824 | </para> |
| 825 | </note> |
| 826 | </section> |
| 827 | </section> |
| 828 | |
| 829 | <section id='requirements-and-recommendations-for-released-bsps'> |
| 830 | <title>Requirements and Recommendations for Released BSPs</title> |
| 831 | |
| 832 | <para> |
| 833 | Certain requirements exist for a released BSP to be considered |
| 834 | compliant with the Yocto Project. |
| 835 | Additionally, recommendations also exist. |
| 836 | This section describes the requirements and recommendations for |
| 837 | released BSPs. |
| 838 | </para> |
| 839 | |
| 840 | <section id='released-bsp-requirements'> |
| 841 | <title>Released BSP Requirements</title> |
| 842 | |
| 843 | <para> |
| 844 | Before looking at BSP requirements, you should consider the following: |
| 845 | <itemizedlist> |
| 846 | <listitem><para>The requirements here assume the BSP layer is a well-formed, "legal" |
| 847 | layer that can be added to the Yocto Project. |
| 848 | For guidelines on creating a layer that meets these base requirements, see the |
| 849 | "<link linkend='bsp-layers'>BSP Layers</link>" and the |
| 850 | "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding |
| 851 | and Creating Layers"</ulink> in the Yocto Project Development Manual.</para></listitem> |
| 852 | <listitem><para>The requirements in this section apply regardless of how you |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 853 | package a BSP. |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 854 | You should consult the packaging and distribution guidelines for your |
| 855 | specific release process. |
| 856 | For an example of packaging and distribution requirements, see the |
| 857 | "<ulink url='https://wiki.yoctoproject.org/wiki/Third_Party_BSP_Release_Process'>Third Party BSP Release Process</ulink>" |
| 858 | wiki page.</para></listitem> |
| 859 | <listitem><para>The requirements for the BSP as it is made available to a developer |
| 860 | are completely independent of the released form of the BSP. |
| 861 | For example, the BSP Metadata can be contained within a Git repository |
| 862 | and could have a directory structure completely different from what appears |
| 863 | in the officially released BSP layer.</para></listitem> |
| 864 | <listitem><para>It is not required that specific packages or package |
| 865 | modifications exist in the BSP layer, beyond the requirements for general |
| 866 | compliance with the Yocto Project. |
| 867 | For example, no requirement exists dictating that a specific kernel or |
| 868 | kernel version be used in a given BSP.</para></listitem> |
| 869 | </itemizedlist> |
| 870 | </para> |
| 871 | |
| 872 | <para> |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 873 | Following are the requirements for a released BSP that conform to the |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 874 | Yocto Project: |
| 875 | <itemizedlist> |
| 876 | <listitem><para><emphasis>Layer Name:</emphasis> |
| 877 | The BSP must have a layer name that follows the Yocto |
| 878 | Project standards. |
| 879 | For information on BSP layer names, see the |
| 880 | "<link linkend='bsp-layers'>BSP Layers</link>" section. |
| 881 | </para></listitem> |
| 882 | <listitem><para><emphasis>File System Layout:</emphasis> |
| 883 | When possible, use the same directory names in your |
| 884 | BSP layer as listed in the <filename>recipes.txt</filename> file. |
| 885 | In particular, you should place recipes |
| 886 | (<filename>.bb</filename> files) and recipe |
| 887 | modifications (<filename>.bbappend</filename> files) into |
| 888 | <filename>recipes-*</filename> subdirectories by functional area |
| 889 | as outlined in <filename>recipes.txt</filename>. |
| 890 | If you cannot find a category in <filename>recipes.txt</filename> |
| 891 | to fit a particular recipe, you can make up your own |
| 892 | <filename>recipes-*</filename> subdirectory. |
| 893 | You can find <filename>recipes.txt</filename> in the |
| 894 | <filename>meta</filename> directory of the |
| 895 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>, |
| 896 | or in the OpenEmbedded Core Layer |
| 897 | (<filename>openembedded-core</filename>) found at |
| 898 | <ulink url='http://git.openembedded.org/openembedded-core/tree/meta'></ulink>. |
| 899 | </para> |
| 900 | <para>Within any particular <filename>recipes-*</filename> category, the layout |
| 901 | should match what is found in the OpenEmbedded Core |
| 902 | Git repository (<filename>openembedded-core</filename>) |
| 903 | or the Source Directory (<filename>poky</filename>). |
| 904 | In other words, make sure you place related files in appropriately |
| 905 | related <filename>recipes-*</filename> subdirectories specific to the |
| 906 | recipe's function, or within a subdirectory containing a set of closely-related |
| 907 | recipes. |
| 908 | The recipes themselves should follow the general guidelines |
| 909 | for recipes used in the Yocto Project found in the |
| 910 | "<ulink url='http://openembedded.org/wiki/Styleguide'>OpenEmbedded Style Guide</ulink>". |
| 911 | </para></listitem> |
| 912 | <listitem><para><emphasis>License File:</emphasis> |
| 913 | You must include a license file in the |
| 914 | <filename>meta-<replaceable>bsp_name</replaceable></filename> directory. |
| 915 | This license covers the BSP Metadata as a whole. |
| 916 | You must specify which license to use since there is no |
| 917 | default license if one is not specified. |
| 918 | See the |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 919 | <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/COPYING.MIT'><filename>COPYING.MIT</filename></ulink> |
| 920 | file for the Raspberry Pi BSP in the |
| 921 | <filename>meta-raspberrypi</filename> BSP layer as an example. |
| 922 | </para></listitem> |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 923 | <listitem><para><emphasis>README File:</emphasis> |
| 924 | You must include a <filename>README</filename> file in the |
| 925 | <filename>meta-<replaceable>bsp_name</replaceable></filename> directory. |
| 926 | See the |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 927 | <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/README'><filename>README</filename></ulink> |
| 928 | file for the Raspberry Pi BSP in the <filename>meta-raspberrypi</filename> BSP layer |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 929 | as an example.</para> |
| 930 | <para>At a minimum, the <filename>README</filename> file should |
| 931 | contain the following: |
| 932 | <itemizedlist> |
| 933 | <listitem><para>A brief description about the hardware the BSP |
| 934 | targets.</para></listitem> |
| 935 | <listitem><para>A list of all the dependencies |
| 936 | on which a BSP layer depends. |
| 937 | These dependencies are typically a list of required layers needed |
| 938 | to build the BSP. |
| 939 | However, the dependencies should also contain information regarding |
| 940 | any other dependencies the BSP might have.</para></listitem> |
| 941 | <listitem><para>Any required special licensing information. |
| 942 | For example, this information includes information on |
| 943 | special variables needed to satisfy a EULA, |
| 944 | or instructions on information needed to build or distribute |
| 945 | binaries built from the BSP Metadata.</para></listitem> |
| 946 | <listitem><para>The name and contact information for the |
| 947 | BSP layer maintainer. |
| 948 | This is the person to whom patches and questions should |
| 949 | be sent. |
| 950 | For information on how to find the right person, see the |
| 951 | "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>How to Submit a Change</ulink>" |
| 952 | section in the Yocto Project Development Manual. |
| 953 | </para></listitem> |
| 954 | <listitem><para>Instructions on how to build the BSP using the BSP |
| 955 | layer.</para></listitem> |
| 956 | <listitem><para>Instructions on how to boot the BSP build from |
| 957 | the BSP layer.</para></listitem> |
| 958 | <listitem><para>Instructions on how to boot the binary images |
| 959 | contained in the <filename>binary</filename> directory, |
| 960 | if present.</para></listitem> |
| 961 | <listitem><para>Information on any known bugs or issues that users |
| 962 | should know about when either building or booting the BSP |
| 963 | binaries.</para></listitem> |
| 964 | </itemizedlist></para></listitem> |
| 965 | <listitem><para><emphasis>README.sources File:</emphasis> |
| 966 | You must include a <filename>README.sources</filename> in the |
| 967 | <filename>meta-<replaceable>bsp_name</replaceable></filename> directory. |
| 968 | This file specifies exactly where you can find the sources used to |
| 969 | generate the binary images contained in the |
| 970 | <filename>binary</filename> directory, if present. |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 971 | </para></listitem> |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 972 | <listitem><para><emphasis>Layer Configuration File:</emphasis> |
| 973 | You must include a <filename>conf/layer.conf</filename> in the |
| 974 | <filename>meta-<replaceable>bsp_name</replaceable></filename> directory. |
| 975 | This file identifies the <filename>meta-<replaceable>bsp_name</replaceable></filename> |
| 976 | BSP layer as a layer to the build system.</para></listitem> |
| 977 | <listitem><para><emphasis>Machine Configuration File:</emphasis> |
| 978 | You must include one or more |
| 979 | <filename>conf/machine/<replaceable>bsp_name</replaceable>.conf</filename> |
| 980 | files in the <filename>meta-<replaceable>bsp_name</replaceable></filename> directory. |
| 981 | These configuration files define machine targets that can be built |
| 982 | using the BSP layer. |
| 983 | Multiple machine configuration files define variations of machine |
| 984 | configurations that are supported by the BSP. |
| 985 | If a BSP supports multiple machine variations, you need to |
| 986 | adequately describe each variation in the BSP |
| 987 | <filename>README</filename> file. |
| 988 | Do not use multiple machine configuration files to describe disparate |
| 989 | hardware. |
| 990 | If you do have very different targets, you should create separate |
| 991 | BSP layers for each target. |
| 992 | <note>It is completely possible for a developer to structure the |
| 993 | working repository as a conglomeration of unrelated BSP |
| 994 | files, and to possibly generate BSPs targeted for release |
| 995 | from that directory using scripts or some other mechanism |
| 996 | (e.g. <filename>meta-yocto-bsp</filename> layer). |
| 997 | Such considerations are outside the scope of this document.</note> |
| 998 | </para></listitem> |
| 999 | </itemizedlist> |
| 1000 | </para> |
| 1001 | </section> |
| 1002 | |
| 1003 | <section id='released-bsp-recommendations'> |
| 1004 | <title>Released BSP Recommendations</title> |
| 1005 | |
| 1006 | <para> |
| 1007 | Following are recommendations for a released BSP that conforms to the |
| 1008 | Yocto Project: |
| 1009 | <itemizedlist> |
| 1010 | <listitem><para><emphasis>Bootable Images:</emphasis> |
| 1011 | BSP releases |
| 1012 | can contain one or more bootable images. |
| 1013 | Including bootable images allows users to easily try out the BSP |
| 1014 | on their own hardware.</para> |
| 1015 | <para>In some cases, it might not be convenient to include a |
| 1016 | bootable image. |
| 1017 | In this case, you might want to make two versions of the |
| 1018 | BSP available: one that contains binary images, and one |
| 1019 | that does not. |
| 1020 | The version that does not contain bootable images avoids |
| 1021 | unnecessary download times for users not interested in the images. |
| 1022 | </para> |
| 1023 | <para>If you need to distribute a BSP and include bootable images or build kernel and |
| 1024 | filesystems meant to allow users to boot the BSP for evaluation |
| 1025 | purposes, you should put the images and artifacts within a |
| 1026 | <filename>binary/</filename> subdirectory located in the |
| 1027 | <filename>meta-<replaceable>bsp_name</replaceable></filename> directory. |
| 1028 | <note>If you do include a bootable image as part of the BSP and the image |
| 1029 | was built by software covered by the GPL or other open source licenses, |
| 1030 | it is your responsibility to understand |
| 1031 | and meet all licensing requirements, which could include distribution |
| 1032 | of source files.</note></para></listitem> |
| 1033 | <listitem><para><emphasis>Use a Yocto Linux Kernel:</emphasis> |
| 1034 | Kernel recipes in the BSP should be based on a Yocto Linux kernel. |
| 1035 | Basing your recipes on these kernels reduces the costs for maintaining |
| 1036 | the BSP and increases its scalability. |
| 1037 | See the <filename>Yocto Linux Kernel</filename> category in the |
| 1038 | <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>Source Repositories</ulink> |
| 1039 | for these kernels.</para></listitem> |
| 1040 | </itemizedlist> |
| 1041 | </para> |
| 1042 | </section> |
| 1043 | </section> |
| 1044 | |
| 1045 | <section id='customizing-a-recipe-for-a-bsp'> |
| 1046 | <title>Customizing a Recipe for a BSP</title> |
| 1047 | |
| 1048 | <para> |
| 1049 | If you plan on customizing a recipe for a particular BSP, you need to do the |
| 1050 | following: |
| 1051 | <itemizedlist> |
| 1052 | <listitem><para>Create a <filename>.bbappend</filename> |
| 1053 | file for the modified recipe. |
| 1054 | For information on using append files, see the |
| 1055 | "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files</ulink>" |
| 1056 | section in the Yocto Project Development Manual. |
| 1057 | </para></listitem> |
| 1058 | <listitem><para> |
| 1059 | Ensure your directory structure in the BSP layer |
| 1060 | that supports your machine is such that it can be found |
| 1061 | by the build system. |
| 1062 | See the example later in this section for more information. |
| 1063 | </para></listitem> |
| 1064 | <listitem><para> |
| 1065 | Put the append file in a directory whose name matches |
| 1066 | the machine's name and is located in an appropriate |
| 1067 | sub-directory inside the BSP layer (i.e. |
| 1068 | <filename>recipes-bsp</filename>, <filename>recipes-graphics</filename>, |
| 1069 | <filename>recipes-core</filename>, and so forth). |
| 1070 | </para></listitem> |
| 1071 | <listitem><para>Place the BSP-specific files in the proper directory |
| 1072 | inside the BSP layer. |
| 1073 | How expansive the layer is affects where you must place these files. |
| 1074 | For example, if your layer supports several different machine types, |
| 1075 | you need to be sure your layer's directory structure includes hierarchy |
| 1076 | that separates the files out according to machine. |
| 1077 | If your layer does not support multiple machines, the layer would not |
| 1078 | have that additional hierarchy and the files would obviously not be |
| 1079 | able to reside in a machine-specific directory. |
| 1080 | </para></listitem> |
| 1081 | </itemizedlist> |
| 1082 | </para> |
| 1083 | |
| 1084 | <para> |
| 1085 | Following is a specific example to help you better understand the process. |
| 1086 | Consider an example that customizes a recipe by adding |
| 1087 | a BSP-specific configuration file named <filename>interfaces</filename> to the |
| 1088 | <filename>init-ifupdown_1.0.bb</filename> recipe for machine "xyz" where the |
| 1089 | BSP layer also supports several other machines. |
| 1090 | Do the following: |
| 1091 | <orderedlist> |
| 1092 | <listitem><para>Edit the <filename>init-ifupdown_1.0.bbappend</filename> file so that it |
| 1093 | contains the following: |
| 1094 | <literallayout class='monospaced'> |
| 1095 | FILESEXTRAPATHS_prepend := "${THISDIR}/files:" |
| 1096 | </literallayout> |
| 1097 | The append file needs to be in the |
| 1098 | <filename>meta-xyz/recipes-core/init-ifupdown</filename> directory. |
| 1099 | </para></listitem> |
| 1100 | <listitem><para>Create and place the new <filename>interfaces</filename> |
| 1101 | configuration file in the BSP's layer here: |
| 1102 | <literallayout class='monospaced'> |
| 1103 | meta-xyz/recipes-core/init-ifupdown/files/xyz-machine-one/interfaces |
| 1104 | </literallayout> |
| 1105 | <note> |
| 1106 | If the <filename>meta-xyz</filename> layer did not support |
| 1107 | multiple machines, you would place the |
| 1108 | <filename>interfaces</filename> configuration file in the |
| 1109 | layer here: |
| 1110 | <literallayout class='monospaced'> |
| 1111 | meta-xyz/recipes-core/init-ifupdown/files/interfaces |
| 1112 | </literallayout> |
| 1113 | </note> |
| 1114 | The |
| 1115 | <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> |
| 1116 | variable in the append files extends the search path |
| 1117 | the build system uses to find files during the build. |
| 1118 | Consequently, for this example you need to have the |
| 1119 | <filename>files</filename> directory in the same location |
| 1120 | as your append file.</para></listitem> |
| 1121 | </orderedlist> |
| 1122 | </para> |
| 1123 | </section> |
| 1124 | |
| 1125 | <section id='bsp-licensing-considerations'> |
| 1126 | <title>BSP Licensing Considerations</title> |
| 1127 | |
| 1128 | <para> |
| 1129 | In some cases, a BSP contains separately licensed Intellectual Property (IP) |
| 1130 | for a component or components. |
| 1131 | For these cases, you are required to accept the terms of a commercial or other |
| 1132 | type of license that requires some kind of explicit End User License Agreement (EULA). |
| 1133 | Once the license is accepted, the OpenEmbedded build system can then build and |
| 1134 | include the corresponding component in the final BSP image. |
| 1135 | If the BSP is available as a pre-built image, you can download the image after |
| 1136 | agreeing to the license or EULA. |
| 1137 | </para> |
| 1138 | |
| 1139 | <para> |
| 1140 | You could find that some separately licensed components that are essential |
| 1141 | for normal operation of the system might not have an unencumbered (or free) |
| 1142 | substitute. |
| 1143 | Without these essential components, the system would be non-functional. |
| 1144 | Then again, you might find that other licensed components that are simply |
| 1145 | 'good-to-have' or purely elective do have an unencumbered, free replacement |
| 1146 | component that you can use rather than agreeing to the separately licensed component. |
| 1147 | Even for components essential to the system, you might find an unencumbered component |
| 1148 | that is not identical but will work as a less-capable version of the |
| 1149 | licensed version in the BSP recipe. |
| 1150 | </para> |
| 1151 | |
| 1152 | <para> |
| 1153 | For cases where you can substitute a free component and still |
| 1154 | maintain the system's functionality, the "Downloads" page from the |
| 1155 | <ulink url='&YOCTO_HOME_URL;'>Yocto Project website's</ulink> |
| 1156 | makes available de-featured BSPs |
| 1157 | that are completely free of any IP encumbrances. |
| 1158 | For these cases, you can use the substitution directly and |
| 1159 | without any further licensing requirements. |
| 1160 | If present, these fully de-featured BSPs are named appropriately |
| 1161 | different as compared to the names of the respective |
| 1162 | encumbered BSPs. |
| 1163 | If available, these substitutions are your |
| 1164 | simplest and most preferred options. |
| 1165 | Use of these substitutions of course assumes the resulting functionality meets |
| 1166 | system requirements. |
| 1167 | </para> |
| 1168 | |
| 1169 | <para> |
| 1170 | If however, a non-encumbered version is unavailable or |
| 1171 | it provides unsuitable functionality or quality, you can use an encumbered |
| 1172 | version. |
| 1173 | </para> |
| 1174 | |
| 1175 | <para> |
| 1176 | A couple different methods exist within the OpenEmbedded build system to |
| 1177 | satisfy the licensing requirements for an encumbered BSP. |
| 1178 | The following list describes them in order of preference: |
| 1179 | <orderedlist> |
| 1180 | <listitem><para><emphasis>Use the |
| 1181 | <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink> |
| 1182 | variable to define the recipes that have commercial or other |
| 1183 | types of specially-licensed packages:</emphasis> |
| 1184 | For each of those recipes, you can |
| 1185 | specify a matching license string in a |
| 1186 | <filename>local.conf</filename> variable named |
| 1187 | <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></ulink>. |
| 1188 | Specifying the matching license string signifies that you agree to the license. |
| 1189 | Thus, the build system can build the corresponding recipe and include |
| 1190 | the component in the image. |
| 1191 | See the |
| 1192 | "<ulink url='&YOCTO_DOCS_REF_URL;#enabling-commercially-licensed-recipes'>Enabling |
| 1193 | Commercially Licensed Recipes</ulink>" section in the Yocto Project Reference |
| 1194 | Manual for details on how to use these variables.</para> |
| 1195 | <para>If you build as you normally would, without |
| 1196 | specifying any recipes in the |
| 1197 | <filename>LICENSE_FLAGS_WHITELIST</filename>, the build stops and |
| 1198 | provides you with the list of recipes that you have |
| 1199 | tried to include in the image that need entries in |
| 1200 | the <filename>LICENSE_FLAGS_WHITELIST</filename>. |
| 1201 | Once you enter the appropriate license flags into the whitelist, |
| 1202 | restart the build to continue where it left off. |
| 1203 | During the build, the prompt will not appear again |
| 1204 | since you have satisfied the requirement.</para> |
| 1205 | <para>Once the appropriate license flags are on the white list |
| 1206 | in the <filename>LICENSE_FLAGS_WHITELIST</filename> variable, you |
| 1207 | can build the encumbered image with no change at all |
| 1208 | to the normal build process.</para></listitem> |
| 1209 | <listitem><para><emphasis>Get a pre-built version of the BSP:</emphasis> |
| 1210 | You can get this type of BSP by visiting the |
| 1211 | "Downloads" page of the |
| 1212 | <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink>. |
| 1213 | You can download BSP tarballs that contain proprietary components |
| 1214 | after agreeing to the licensing |
| 1215 | requirements of each of the individually encumbered |
| 1216 | packages as part of the download process. |
| 1217 | Obtaining the BSP this way allows you to access an encumbered |
| 1218 | image immediately after agreeing to the |
| 1219 | click-through license agreements presented by the |
| 1220 | website. |
| 1221 | Note that if you want to build the image |
| 1222 | yourself using the recipes contained within the BSP |
| 1223 | tarball, you will still need to create an |
| 1224 | appropriate <filename>LICENSE_FLAGS_WHITELIST</filename> to match the |
| 1225 | encumbered recipes in the BSP.</para></listitem> |
| 1226 | </orderedlist> |
| 1227 | </para> |
| 1228 | |
| 1229 | <note> |
| 1230 | Pre-compiled images are bundled with |
| 1231 | a time-limited kernel that runs for a |
| 1232 | predetermined amount of time (10 days) before it forces |
| 1233 | the system to reboot. |
| 1234 | This limitation is meant to discourage direct redistribution |
| 1235 | of the image. |
| 1236 | You must eventually rebuild the image if you want to remove this restriction. |
| 1237 | </note> |
| 1238 | </section> |
| 1239 | |
| 1240 | <section id='using-the-yocto-projects-bsp-tools'> |
| 1241 | <title>Using the Yocto Project's BSP Tools</title> |
| 1242 | |
| 1243 | <para> |
| 1244 | The Yocto Project includes a couple of tools that enable |
| 1245 | you to create a <link linkend='bsp-layers'>BSP layer</link> |
| 1246 | from scratch and do basic configuration and maintenance |
| 1247 | of the kernel without ever looking at a Metadata file. |
| 1248 | These tools are <filename>yocto-bsp</filename> and <filename>yocto-kernel</filename>, |
| 1249 | respectively. |
| 1250 | </para> |
| 1251 | |
| 1252 | <para> |
| 1253 | The following sections describe the common location and help features as well |
| 1254 | as provide details for the |
| 1255 | <filename>yocto-bsp</filename> and <filename>yocto-kernel</filename> tools. |
| 1256 | </para> |
| 1257 | |
| 1258 | <section id='common-features'> |
| 1259 | <title>Common Features</title> |
| 1260 | |
| 1261 | <para> |
| 1262 | Designed to have a command interface somewhat like |
| 1263 | <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>, each |
| 1264 | tool is structured as a set of sub-commands under a |
| 1265 | top-level command. |
| 1266 | The top-level command (<filename>yocto-bsp</filename> |
| 1267 | or <filename>yocto-kernel</filename>) itself does |
| 1268 | nothing but invoke or provide help on the sub-commands |
| 1269 | it supports. |
| 1270 | </para> |
| 1271 | |
| 1272 | <para> |
| 1273 | Both tools reside in the <filename>scripts/</filename> subdirectory |
| 1274 | of the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. |
| 1275 | Consequently, to use the scripts, you must <filename>source</filename> the |
| 1276 | environment just as you would when invoking a build: |
| 1277 | <literallayout class='monospaced'> |
| 1278 | $ source oe-init-build-env <replaceable>build_dir</replaceable> |
| 1279 | </literallayout> |
| 1280 | </para> |
| 1281 | |
| 1282 | <para> |
| 1283 | The most immediately useful function is to get help on both tools. |
| 1284 | The built-in help system makes it easy to drill down at |
| 1285 | any time and view the syntax required for any specific command. |
| 1286 | Simply enter the name of the command with the <filename>help</filename> |
| 1287 | switch: |
| 1288 | <literallayout class='monospaced'> |
| 1289 | $ yocto-bsp help |
| 1290 | Usage: |
| 1291 | |
| 1292 | Create a customized Yocto BSP layer. |
| 1293 | |
| 1294 | usage: yocto-bsp [--version] [--help] COMMAND [ARGS] |
| 1295 | |
| 1296 | Current 'yocto-bsp' commands are: |
| 1297 | create Create a new Yocto BSP |
| 1298 | list List available values for options and BSP properties |
| 1299 | |
| 1300 | See 'yocto-bsp help COMMAND' for more information on a specific command. |
| 1301 | |
| 1302 | |
| 1303 | Options: |
| 1304 | --version show program's version number and exit |
| 1305 | -h, --help show this help message and exit |
| 1306 | -D, --debug output debug information |
| 1307 | </literallayout> |
| 1308 | </para> |
| 1309 | |
| 1310 | <para> |
| 1311 | Similarly, entering just the name of a sub-command shows the detailed usage |
| 1312 | for that sub-command: |
| 1313 | <literallayout class='monospaced'> |
| 1314 | $ yocto-bsp create |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 1315 | ERROR:root:Wrong number of arguments, exiting |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 1316 | |
| 1317 | Usage: |
| 1318 | |
| 1319 | Create a new Yocto BSP |
| 1320 | |
| 1321 | usage: yocto-bsp create <bsp-name> <karch> [-o <DIRNAME> | --outdir <DIRNAME>] |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 1322 | [-i <JSON PROPERTY FILE> | --infile <JSON PROPERTY_FILE>] |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 1323 | |
| 1324 | This command creates a Yocto BSP based on the specified parameters. |
| 1325 | The new BSP will be a new Yocto BSP layer contained by default within |
| 1326 | the top-level directory specified as 'meta-bsp-name'. The -o option |
| 1327 | can be used to place the BSP layer in a directory with a different |
| 1328 | name and location. |
| 1329 | |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 1330 | The value of the 'karch' parameter determines the set of files that |
| 1331 | will be generated for the BSP, along with the specific set of |
| 1332 | 'properties' that will be used to fill out the BSP-specific portions |
| 1333 | of the BSP. The possible values for the 'karch' parameter can be |
| 1334 | listed via 'yocto-bsp list karch'. |
| 1335 | |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 1336 | ... |
| 1337 | </literallayout> |
| 1338 | </para> |
| 1339 | |
| 1340 | <para> |
| 1341 | For any sub-command, you can use the word "help" option just before the |
| 1342 | sub-command to get more extensive documentation: |
| 1343 | <literallayout class='monospaced'> |
| 1344 | $ yocto-bsp help create |
| 1345 | |
| 1346 | NAME |
| 1347 | yocto-bsp create - Create a new Yocto BSP |
| 1348 | |
| 1349 | SYNOPSIS |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 1350 | yocto-bsp create <bsp-name> <karch> [-o <DIRNAME> | --outdir <DIRNAME>] |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 1351 | [-i <JSON PROPERTY FILE> | --infile <JSON PROPERTY_FILE>] |
| 1352 | |
| 1353 | DESCRIPTION |
| 1354 | This command creates a Yocto BSP based on the specified |
| 1355 | parameters. The new BSP will be a new Yocto BSP layer contained |
| 1356 | by default within the top-level directory specified as |
| 1357 | 'meta-bsp-name'. The -o option can be used to place the BSP layer |
| 1358 | in a directory with a different name and location. |
| 1359 | |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 1360 | ... |
| 1361 | </literallayout> |
| 1362 | </para> |
| 1363 | |
| 1364 | <para> |
| 1365 | Now that you know where these two commands reside and how to access information |
| 1366 | on them, you should find it relatively straightforward to discover the commands |
| 1367 | necessary to create a BSP and perform basic kernel maintenance on that BSP using |
| 1368 | the tools. |
| 1369 | <note> |
| 1370 | You can also use the <filename>yocto-layer</filename> tool to create |
| 1371 | a "generic" layer. |
| 1372 | For information on this tool, see the |
| 1373 | "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</ulink>" |
| 1374 | section in the Yocto Project Development Guide. |
| 1375 | </note> |
| 1376 | </para> |
| 1377 | |
| 1378 | <para> |
| 1379 | The next sections provide a concrete starting point to expand on a few points that |
| 1380 | might not be immediately obvious or that could use further explanation. |
| 1381 | </para> |
| 1382 | </section> |
| 1383 | |
| 1384 | |
| 1385 | <section id='creating-a-new-bsp-layer-using-the-yocto-bsp-script'> |
| 1386 | <title>Creating a new BSP Layer Using the yocto-bsp Script</title> |
| 1387 | |
| 1388 | <para> |
| 1389 | The <filename>yocto-bsp</filename> script creates a new |
| 1390 | <link linkend='bsp-layers'>BSP layer</link> for any architecture supported |
| 1391 | by the Yocto Project, as well as QEMU versions of the same. |
| 1392 | The default mode of the script's operation is to prompt you for information needed |
| 1393 | to generate the BSP layer. |
| 1394 | </para> |
| 1395 | |
| 1396 | <para> |
| 1397 | For the current set of BSPs, the script prompts you for various important |
| 1398 | parameters such as: |
| 1399 | <itemizedlist> |
| 1400 | <listitem><para>The kernel to use</para></listitem> |
| 1401 | <listitem><para>The branch of that kernel to use (or re-use)</para></listitem> |
| 1402 | <listitem><para>Whether or not to use X, and if so, which drivers to use</para></listitem> |
| 1403 | <listitem><para>Whether to turn on SMP</para></listitem> |
| 1404 | <listitem><para>Whether the BSP has a keyboard</para></listitem> |
| 1405 | <listitem><para>Whether the BSP has a touchscreen</para></listitem> |
| 1406 | <listitem><para>Remaining configurable items associated with the BSP</para></listitem> |
| 1407 | </itemizedlist> |
| 1408 | </para> |
| 1409 | |
| 1410 | <para> |
| 1411 | You use the <filename>yocto-bsp create</filename> sub-command to create |
| 1412 | a new BSP layer. |
| 1413 | This command requires you to specify a particular kernel architecture |
| 1414 | (<filename>karch</filename>) on which to base the BSP. |
| 1415 | Assuming you have sourced the environment, you can use the |
| 1416 | <filename>yocto-bsp list karch</filename> sub-command to list the |
| 1417 | architectures available for BSP creation as follows: |
| 1418 | <literallayout class='monospaced'> |
| 1419 | $ yocto-bsp list karch |
| 1420 | Architectures available: |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 1421 | powerpc |
| 1422 | x86_64 |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 1423 | i386 |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 1424 | arm |
| 1425 | qemu |
| 1426 | mips |
| 1427 | mips64 |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 1428 | </literallayout> |
| 1429 | </para> |
| 1430 | |
| 1431 | <para> |
| 1432 | The remainder of this section presents an example that uses |
| 1433 | <filename>myarm</filename> as the machine name and <filename>qemu</filename> |
| 1434 | as the machine architecture. |
| 1435 | Of the available architectures, <filename>qemu</filename> is the only architecture |
| 1436 | that causes the script to prompt you further for an actual architecture. |
| 1437 | In every other way, this architecture is representative of how creating a BSP for |
| 1438 | an actual machine would work. |
| 1439 | The reason the example uses this architecture is because it is an emulated architecture |
| 1440 | and can easily be followed without requiring actual hardware. |
| 1441 | </para> |
| 1442 | |
| 1443 | <para> |
| 1444 | As the <filename>yocto-bsp create</filename> command runs, default values for |
| 1445 | the prompts appear in brackets. |
| 1446 | Pressing enter without supplying anything on the command line or pressing enter |
| 1447 | with an invalid response causes the script to accept the default value. |
| 1448 | Once the script completes, the new <filename>meta-myarm</filename> BSP layer |
| 1449 | is created in the current working directory. |
| 1450 | This example assumes you have sourced the |
| 1451 | <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> |
| 1452 | setup script. |
| 1453 | </para> |
| 1454 | |
| 1455 | <para> |
| 1456 | Following is the complete example: |
| 1457 | <literallayout class='monospaced'> |
| 1458 | $ yocto-bsp create myarm qemu |
| 1459 | Checking basic git connectivity... |
| 1460 | Done. |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 1461 | |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 1462 | Which qemu architecture would you like to use? [default: i386] |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 1463 | 1) i386 (32-bit) |
| 1464 | 2) x86_64 (64-bit) |
| 1465 | 3) ARM (32-bit) |
| 1466 | 4) PowerPC (32-bit) |
| 1467 | 5) MIPS (32-bit) |
| 1468 | 6) MIPS64 (64-bit) |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 1469 | 3 |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 1470 | Would you like to use the default (4.1) kernel? (y/n) [default: y] |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 1471 | Do you need a new machine branch for this BSP (the alternative is to re-use an existing branch)? [y/n] [default: y] |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 1472 | Getting branches from remote repo git://git.yoctoproject.org/linux-yocto-4.1.git... |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 1473 | Please choose a machine branch to base your new BSP branch on: [default: standard/base] |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 1474 | 1) standard/arm-versatile-926ejs |
| 1475 | 2) standard/base |
| 1476 | 3) standard/beagleboard |
| 1477 | 4) standard/beaglebone |
| 1478 | 5) standard/edgerouter |
| 1479 | 6) standard/fsl-mpc8315e-rdb |
| 1480 | 7) standard/mti-malta32 |
| 1481 | 8) standard/mti-malta64 |
| 1482 | 9) standard/qemuarm64 |
| 1483 | 10) standard/qemuppc |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 1484 | 1 |
| 1485 | Would you like SMP support? (y/n) [default: y] |
| 1486 | Does your BSP have a touchscreen? (y/n) [default: n] |
| 1487 | Does your BSP have a keyboard? (y/n) [default: y] |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 1488 | |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 1489 | New qemu BSP created in meta-myarm |
| 1490 | </literallayout> |
| 1491 | Take a closer look at the example now: |
| 1492 | <orderedlist> |
| 1493 | <listitem><para>For the QEMU architecture, |
| 1494 | the script first prompts you for which emulated architecture to use. |
| 1495 | In the example, we use the ARM architecture. |
| 1496 | </para></listitem> |
| 1497 | <listitem><para>The script then prompts you for the kernel. |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 1498 | The default 4.4 kernel is acceptable. |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 1499 | So, the example accepts the default. |
| 1500 | If you enter 'n', the script prompts you to further enter the kernel |
| 1501 | you do want to use.</para></listitem> |
| 1502 | <listitem><para>Next, the script asks whether you would like to have a new |
| 1503 | branch created especially for your BSP in the local |
| 1504 | <ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Linux Yocto Kernel</ulink> |
| 1505 | Git repository . |
| 1506 | If not, then the script re-uses an existing branch.</para> |
| 1507 | <para>In this example, the default (or "yes") is accepted. |
| 1508 | Thus, a new branch is created for the BSP rather than using a common, shared |
| 1509 | branch. |
| 1510 | The new branch is the branch committed to for any patches you might later add. |
| 1511 | The reason a new branch is the default is that typically |
| 1512 | new BSPs do require BSP-specific patches. |
| 1513 | The tool thus assumes that most of time a new branch is required. |
| 1514 | </para></listitem> |
| 1515 | <listitem><para>Regardless of which choice you make in the previous step, |
| 1516 | you are now given the opportunity to select a particular machine branch on |
| 1517 | which to base your new BSP-specific machine branch |
| 1518 | (or to re-use if you had elected to not create a new branch). |
| 1519 | Because this example is generating an ARM-based BSP, the example |
| 1520 | uses <filename>#1</filename> at the prompt, which selects the ARM-versatile branch. |
| 1521 | </para></listitem> |
| 1522 | <listitem><para>The remainder of the prompts are routine. |
| 1523 | Defaults are accepted for each.</para></listitem> |
| 1524 | <listitem><para>By default, the script creates the new BSP Layer in the |
| 1525 | current working directory of the |
| 1526 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>, |
| 1527 | (i.e. <filename>poky/build</filename>). |
| 1528 | </para></listitem> |
| 1529 | </orderedlist> |
| 1530 | </para> |
| 1531 | |
| 1532 | <para> |
| 1533 | Once the BSP Layer is created, you must add it to your |
| 1534 | <filename>bblayers.conf</filename> file. |
| 1535 | Here is an example: |
| 1536 | <literallayout class='monospaced'> |
| 1537 | BBLAYERS = ? " \ |
| 1538 | /usr/local/src/yocto/meta \ |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 1539 | /usr/local/src/yocto/meta-poky \ |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 1540 | /usr/local/src/yocto/meta-yocto-bsp \ |
| 1541 | /usr/local/src/yocto/meta-myarm \ |
| 1542 | " |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 1543 | </literallayout> |
| 1544 | Adding the layer to this file allows the build system to build the BSP and |
| 1545 | the <filename>yocto-kernel</filename> tool to be able to find the layer and |
| 1546 | other Metadata it needs on which to operate. |
| 1547 | </para> |
| 1548 | </section> |
| 1549 | |
| 1550 | <section id='managing-kernel-patches-and-config-items-with-yocto-kernel'> |
| 1551 | <title>Managing Kernel Patches and Config Items with yocto-kernel</title> |
| 1552 | |
| 1553 | <para> |
| 1554 | Assuming you have created a <link linkend='bsp-layers'>BSP Layer</link> using |
| 1555 | <link linkend='creating-a-new-bsp-layer-using-the-yocto-bsp-script'> |
| 1556 | <filename>yocto-bsp</filename></link> and you added it to your |
| 1557 | <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink> |
| 1558 | variable in the <filename>bblayers.conf</filename> file, you can now use |
| 1559 | the <filename>yocto-kernel</filename> script to add patches and configuration |
| 1560 | items to the BSP's kernel. |
| 1561 | </para> |
| 1562 | |
| 1563 | <para> |
| 1564 | The <filename>yocto-kernel</filename> script allows you to add, remove, and list patches |
| 1565 | and kernel config settings to a BSP's kernel |
| 1566 | <filename>.bbappend</filename> file. |
| 1567 | All you need to do is use the appropriate sub-command. |
| 1568 | Recall that the easiest way to see exactly what sub-commands are available |
| 1569 | is to use the <filename>yocto-kernel</filename> built-in help as follows: |
| 1570 | <literallayout class='monospaced'> |
| 1571 | $ yocto-kernel --help |
| 1572 | Usage: |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 1573 | |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 1574 | Modify and list Yocto BSP kernel config items and patches. |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 1575 | |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 1576 | usage: yocto-kernel [--version] [--help] COMMAND [ARGS] |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 1577 | |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 1578 | Current 'yocto-kernel' commands are: |
| 1579 | config list List the modifiable set of bare kernel config options for a BSP |
| 1580 | config add Add or modify bare kernel config options for a BSP |
| 1581 | config rm Remove bare kernel config options from a BSP |
| 1582 | patch list List the patches associated with a BSP |
| 1583 | patch add Patch the Yocto kernel for a BSP |
| 1584 | patch rm Remove patches from a BSP |
| 1585 | feature list List the features used by a BSP |
| 1586 | feature add Have a BSP use a feature |
| 1587 | feature rm Have a BSP stop using a feature |
| 1588 | features list List the features available to BSPs |
| 1589 | feature describe Describe a particular feature |
| 1590 | feature create Create a new BSP-local feature |
| 1591 | feature destroy Remove a BSP-local feature |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 1592 | |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 1593 | See 'yocto-kernel help COMMAND' for more information on a specific command. |
| Patrick Williams | d8c66bc | 2016-06-20 12:57:21 -0500 | [diff] [blame] | 1594 | |
| 1595 | |
| 1596 | |
| Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 1597 | Options: |
| 1598 | --version show program's version number and exit |
| 1599 | -h, --help show this help message and exit |
| 1600 | -D, --debug output debug information |
| 1601 | </literallayout> |
| 1602 | </para> |
| 1603 | |
| 1604 | <para> |
| 1605 | The <filename>yocto-kernel patch add</filename> sub-command allows you to add a |
| 1606 | patch to a BSP. |
| 1607 | The following example adds two patches to the <filename>myarm</filename> BSP: |
| 1608 | <literallayout class='monospaced'> |
| 1609 | $ yocto-kernel patch add myarm ~/test.patch |
| 1610 | Added patches: |
| 1611 | test.patch |
| 1612 | |
| 1613 | $ yocto-kernel patch add myarm ~/yocto-testmod.patch |
| 1614 | Added patches: |
| 1615 | yocto-testmod.patch |
| 1616 | </literallayout> |
| 1617 | <note>Although the previous example adds patches one at a time, it is possible |
| 1618 | to add multiple patches at the same time.</note> |
| 1619 | </para> |
| 1620 | |
| 1621 | <para> |
| 1622 | You can verify patches have been added by using the |
| 1623 | <filename>yocto-kernel patch list</filename> sub-command. |
| 1624 | Here is an example: |
| 1625 | <literallayout class='monospaced'> |
| 1626 | $ yocto-kernel patch list myarm |
| 1627 | The current set of machine-specific patches for myarm is: |
| 1628 | 1) test.patch |
| 1629 | 2) yocto-testmod.patch |
| 1630 | </literallayout> |
| 1631 | </para> |
| 1632 | |
| 1633 | <para> |
| 1634 | You can also use the <filename>yocto-kernel</filename> script to |
| 1635 | remove a patch using the <filename>yocto-kernel patch rm</filename> sub-command. |
| 1636 | Here is an example: |
| 1637 | <literallayout class='monospaced'> |
| 1638 | $ yocto-kernel patch rm myarm |
| 1639 | Specify the patches to remove: |
| 1640 | 1) test.patch |
| 1641 | 2) yocto-testmod.patch |
| 1642 | 1 |
| 1643 | Removed patches: |
| 1644 | test.patch |
| 1645 | </literallayout> |
| 1646 | </para> |
| 1647 | |
| 1648 | <para> |
| 1649 | Again, using the <filename>yocto-kernel patch list</filename> sub-command, |
| 1650 | you can verify that the patch was in fact removed: |
| 1651 | <literallayout class='monospaced'> |
| 1652 | $ yocto-kernel patch list myarm |
| 1653 | The current set of machine-specific patches for myarm is: |
| 1654 | 1) yocto-testmod.patch |
| 1655 | </literallayout> |
| 1656 | </para> |
| 1657 | |
| 1658 | <para> |
| 1659 | In a completely similar way, you can use the <filename>yocto-kernel config add</filename> |
| 1660 | sub-command to add one or more kernel config item settings to a BSP. |
| 1661 | The following commands add a couple of config items to the |
| 1662 | <filename>myarm</filename> BSP: |
| 1663 | <literallayout class='monospaced'> |
| 1664 | $ yocto-kernel config add myarm CONFIG_MISC_DEVICES=y |
| 1665 | Added item: |
| 1666 | CONFIG_MISC_DEVICES=y |
| 1667 | |
| 1668 | $ yocto-kernel config add myarm CONFIG_YOCTO_TESTMOD=y |
| 1669 | Added item: |
| 1670 | CONFIG_YOCTO_TESTMOD=y |
| 1671 | </literallayout> |
| 1672 | <note> |
| 1673 | Although the previous example adds config items one at a time, it is possible |
| 1674 | to add multiple config items at the same time. |
| 1675 | </note> |
| 1676 | </para> |
| 1677 | |
| 1678 | <para> |
| 1679 | You can list the config items now associated with the BSP. |
| 1680 | Doing so shows you the config items you added as well as others associated |
| 1681 | with the BSP: |
| 1682 | <literallayout class='monospaced'> |
| 1683 | $ yocto-kernel config list myarm |
| 1684 | The current set of machine-specific kernel config items for myarm is: |
| 1685 | 1) CONFIG_MISC_DEVICES=y |
| 1686 | 2) CONFIG_YOCTO_TESTMOD=y |
| 1687 | </literallayout> |
| 1688 | </para> |
| 1689 | |
| 1690 | <para> |
| 1691 | Finally, you can remove one or more config items using the |
| 1692 | <filename>yocto-kernel config rm</filename> sub-command in a manner |
| 1693 | completely analogous to <filename>yocto-kernel patch rm</filename>. |
| 1694 | </para> |
| 1695 | </section> |
| 1696 | </section> |
| 1697 | </chapter> |