diff --git a/documentation/poky-ref-manual/bsp.xml b/documentation/poky-ref-manual/bsp.xml deleted file mode 100644 index 3256760339..0000000000 --- a/documentation/poky-ref-manual/bsp.xml +++ /dev/null @@ -1,469 +0,0 @@ - - - - Board Support Packages (BSP) - Developers Guide - - - A Board Support Package (BSP) is a collection of information that - defines how to support a particular hardware device, set of devices, or - hardware platform. - The BSP includes information about the hardware features - present on the device and kernel configuration information along with any - additional hardware drivers required. - The BSP also lists any additional software - components required in addition to a generic Linux software stack for both - essential and optional platform features. - - - - This section (or document if you are reading the BSP Developer's Guide) defines - a structure for these components - so that BSPs follow a commonly understood layout. - Providing a common form allows end-users to understand and become familiar - with the layout. - A common form also encourages standardization - of software support of hardware. - - - - The proposed format does have elements that are specific to the Poky and - OpenEmbedded build systems. - It is intended that this information can be - used by other systems besides Poky and OpenEmbedded and that it will be simple - to extract information and convert it to other formats if required. - Poky, through its standard layers mechanism, can directly accept The format - described as a layer. - The BSP captures all - the hardware-specific details in one place in a standard format, which is - useful for any person wishing to use the hardware platform regardless of - the build system they are using. - - - - The BSP specification does not include a build system or other tools - - it is concerned with the hardware-specific components only. - At the end - distribution point you can ship the BSP combined with a build system - and other tools. - However, it is important to maintain the distinction that these - are separate components that happen to be combined in certain end products. - - -
- Example Filesystem Layout - - - The BSP consists of a file structure inside a base directory, meta-bsp in this example, - where "bsp" is a placeholder for the machine or platform name. - Examples of some files that it could contain are: - - - - -meta-bsp/ -meta-bsp/binary/zImage -meta-bsp/binary/poky-image-minimal.directdisk -meta-bsp/conf/layer.conf -meta-bsp/conf/machine/*.conf -meta-bsp/conf/machine/include/tune-*.inc -meta-bsp/packages/bootloader/bootloader_0.1.bb -meta-bsp/packages/linux/linux-bsp-2.6.50/*.patch -meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp -meta-bsp/packages/linux/linux-bsp_2.6.50.bb -meta-bsp/packages/modem/modem-driver_0.1.bb -meta-bsp/packages/modem/modem-daemon_0.1.bb -meta-bsp/packages/image-creator/image-creator-native_0.1.bb -meta-bsp/prebuilds/ - - - - - The following sections detail what these files and directories could contain. - - -
- -
- Prebuilt User Binaries (meta-bsp/binary/*) - - - This optional area contains useful prebuilt kernels and userspace filesystem - images appropriate to the target system. - Users could use these to get a system - running and quickly get started on development tasks. - The exact types of binaries - present are highly hardware-dependent. - However, a README file should be present - that explains how to use them with the target hardware. - If prebuilt binaries are - present, source code to meet licensing requirements must also be provided in - some form. - - -
- -
- Layer Configuration (meta-bsp/conf/layer.conf) - - - This file identifies the structure as a Poky layer, identifies the - contents of the layer and contains information about how Poky should use - it. - Generally, a standard boilerplate file consisting of the following works. - - - - -# We have a conf directory, add to BBPATH -BBPATH := "${BBPATH}${LAYERDIR}" - -# We have a recipes directory containing .bb and .bbappend files, add to BBFILES -BBFILES := "${BBFILES} ${LAYERDIR}/recipes/*/*.bb \ ${LAYERDIR}/recipes/*/*.bbappend" - -BBFILE_COLLECTIONS += "bsp" -BBFILE_PATTERN_bsp := "^${LAYERDIR}/" -BBFILE_PRIORITY_bsp = "5" - - - - - This file simply makes bitbake aware of the recipes and conf directories and is required - for recognition of the BSP by Poky. - - -
- -
- Hardware Configuration Options (meta-bsp/conf/machine/*.conf) - - - The machine files bind together all the information contained elsewhere - in the BSP into a format that Poky/OpenEmbedded can understand. - If the BSP supports multiple machines, multiple machine configuration files - can be present. - These filenames correspond to the values to which users have set the MACHINE variable. - - - - These files define things such as what kernel package to use - (PREFERRED_PROVIDER of virtual/kernel), what hardware drivers to - include in different types of images, any special software components - that are needed, any bootloader information, and also any special image - format requirements. - - - - At least one machine file is required for a Poky BSP layer. - However, you can supply more than one file. - - -
- -
- Hardware Optimization Options (meta-bsp/conf/machine/include/tune-*.inc) - - - These are shared hardware "tuning" definitions and are commonly used to - pass specific optimization flags to the compiler. - An example is tune-atom.inc: - - - -BASE_PACKAGE_ARCH = "core2" -TARGET_CC_ARCH = "-m32 -march=core2 -msse3 -mtune=generic -mfpmath=sse" - - - - This example defines a new package architecture called "core2" and uses the - specified optimization flags, which are carefully chosen to give best - performance on atom processors. - - - The tune file would be included by the machine definition and can be - contained in the BSP or referenced from one of the standard core set of - files included with Poky itself. - - - Both the base package architecuture file and the tune file are optional for a Poky BSP layer. - -
- -
- Linux Kernel Configuration (meta-bsp/packages/linux/*) - - - These files make up the definition of a kernel to use with this - hardware. - In this case, it is a complete self-contained kernel with its own - configuration and patches. - However, kernels can be shared between many machines as well. - Following is an example: - -meta-bsp/packages/linux/linux-bsp_2.6.50.bb - - This example file is the core kernel recipe that details from where to get the kernel - source. - All standard source code locations are supported so this could - be a release tarball, some git repository, or source included in - the directory within the BSP itself. - - - The file then contains information about what patches to apply and how to configure and build them. - It can reuse the main Poky kernel build class, so the definitions here can remain very simple. - - - -linux-bsp-2.6.50/*.patch - - - - The above example file contains patches you can apply against the base kernel, from wherever - they may have been obtained. - - - -meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp - - - - Finally, this last example file contains kernel configuration information. - - - Examples of kernel recipes are available in Poky itself. - These files are optional since a kernel from Poky could be selected, although it - would be unusual not to have a kernel configuration. - -
- -
- Other Software (meta-bsp/packages/*) - - - This section describes other pieces of software that the hardware might need for best - operation. - This section shows examples of the kinds of things that you could encounter. - The examples are standard .bb file recipes in the - usual Poky format. - You can include the source directly by referring to it in the source control system or - the released tarballs of external software projects. - You only need to provide these types of files if the platform requires them. - - - The following file is a bootloader recipe that can be used to generate a new - bootloader binary. - Sometimes these files are included in the final image format and are needed to re-flash hardware. - - - -meta-bsp/packages/bootloader/bootloader_0.1.bb - - - - These next two files are examples of a hardware driver and a hardware daemon that might need - to be included in images to make the hardware useful. - Although the example uses "modem" there may be other components needed, such as firmware. - - - -meta-bsp/packages/modem/modem-driver_0.1.bb -meta-bsp/packages/modem/modem-daemon_0.1.bb - - - - Sometimes the device needs an image in a very specific format so that the update - mechanism can accept and re-flash it. - Recipes to build the tools needed to do this can be included with the BSP. - Following is an example. - - - -meta-bsp/packages/image-creator/image-creator-native_0.1.bb - - -
- -
- Append BSP-Specific Information to Existing Recipes - - Suppose you have a recipe such as 'pointercal' that requires machine-specific information. - At the same time, you have your new BSP code nicely partitioned into a layer through which - you would also like to specify any machine-specific information associated with your new machine. - Before the .bbappend extension was introduced, you would have to copy the whole - pointercal recipe and files into your layer and then add the single file for your machine. - - - With the .bbappend extension, however, your work becomes much easier. - This extension allows you to easily merge BSP-specific information with the original recipe. - Whenever bitbake finds any .bbappend files they will be - included after bitbake loads the associated .bb but before any finalize - or anonymous methods run. - This allows the BSP layer to do whatever it might want to do to customize the original recipe. - - - If your recipe needs to reference extra files it can use the FILESEXTRAPATH variable - to specify their location. - The example below shows extra files contained in a folder called ${PN} (the package name). - - -FILESEXTRAPATHS := "${THISDIR}/${PN}" - - - This technique allows the BSP to add machine-specific configuration files to the layer directory, - which will be picked up by bitbake. - For an example see meta-emenlow/packages/formfactor. - -
- -
- Prebuild Data (meta-bsp/prebuilds/*) - - This location can contain precompiled representations of the source code - contained elsewhere in the BSP layer. - Assuming a compatible configuration is used, Poky can process and use these optional precompiled - representations to provide much faster build times. - -
- -
- BSP 'Click-Through' Licensing Procedure - - This section describes how - click-through licensing is expected to work. - Currently, this functionality is not yet implemented. - - - - In some cases, a BSP contains separately licensed IP - (Intellectual Property) for a component that imposes - upon the user a requirement to accept the terms of a - 'click-through' license. - Once the license is accepted the - Poky build system can then build and include the - corresponding component in the final BSP image. - Some affected components might be essential to the normal - functioning of the system and have no 'free' replacement - (i.e. the resulting system would be non-functional - without them). - On the other hand, other components might be simply - 'good-to-have' or purely elective, or if essential - nonetheless have a 'free' (possibly less-capable) - version that could be used as a in the BSP recipe. - - - - For cases where you can substitute something and still maintain functionality, the Poky website will make - available a 'de-featured' BSP completely free of - the encumbered IP. - In that case you can use the substitution directly and without - any further licensing requirements. - If present, this - fully 'de-featured' BSP will be named meta-bsp (i.e. the - normal default naming convention). - If available, this is the simplest the most preferred option. - This, of course, assumes the resulting functionality meets requirements. - - - - If however, a non-encumbered version is unavailable or - the 'free' version would provide unsuitable - functionality or quality, an encumbered version can be - used. - Encumbered versions of a BSP are given names of - the form meta-bsp-nonfree. - - - - Several methods exist within the Poky build system to satisfy the licensing - requirements for an encumbered BSP. - The following list describes them in preferential order: - - - - - - - Get a license key (or keys) for the encumbered BSP - by visiting - https://pokylinux.org/bsp-keys.html - and give the name of the BSP and your e-mail address in the web form. - - - - [screenshot of dialog box] - - - - After agreeing to any applicable license terms, the - BSP key(s) will be immediately sent to the address - you gave and you can use them by specifying BSPKEY_<keydomain> - environment variables when building the image: - - - - $ BSPKEY_<keydomain>=<key> bitbake poky-image-sato - - - - These steps allow the encumbered image to be built - with no change at all to the normal build process. - - - - Equivalently and probably more conveniently, a line - for each key can instead be put into the user's - local.conf file. - - - - The <keydomain> component of the - BSPKEY_<keydomain> is required because there - might be multiple licenses in effect for a give BSP. - In such cases, a given <keydomain> corresponds to - a particular license. In order for an encumbered - BSP that encompasses multiple key domains to be built - successfully, a <keydomain> entry for each - applicable license must be present in local.conf or - supplied on the command-line. - - - - - Do nothing - build as you normally would. - When a license is needed the build will stop and prompt you with instructions. - Follow the license prompts that originate from the - encumbered BSP. - These prompts usually take the form of instructions - needed to manually fetch the encumbered package(s) - and md5 sums into the required directory (e.g. the poky/build/downloads) - Once the manual package fetch has been - completed, restart the build to continue where - it left off. - During the build the prompt will not appear again since you have satisfied the - requirement. - - - - - Get a full-featured BSP recipe rather than a key, by - visiting - https://pokylinux.org/bsps.html. - Accepting the license agreement(s) presented will - subsequently allow you to download a tarball - containing a full-featured BSP that is legally cleared for - your use by the just-given license agreement(s). - This method will also allow the encumbered image to - be built with no change at all to the normal build - process. - - - - - Note that the third method is also the only option available - when downloading pre-compiled images generated from - non-free BSPs. - Those images are likewise available at - https://pokylinux.org/bsps.html. - -
- -