diff options
Diffstat (limited to 'handbook/bsp.xml')
| -rw-r--r-- | handbook/bsp.xml | 451 |
1 files changed, 0 insertions, 451 deletions
diff --git a/handbook/bsp.xml b/handbook/bsp.xml deleted file mode 100644 index e0ca31732..000000000 --- a/handbook/bsp.xml +++ /dev/null @@ -1,451 +0,0 @@ -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - -<chapter id='bsp'> - - <title>Board Support Packages (BSP) - Developers Guide</title> - - <para> - A Board Support Package (BSP) is a collection of information which together - defines how to support a particular hardware device, set of devices, or - hardware platform. It will include information about the hardware features - present on the device and kernel configuration information along with any - additional hardware drivers required. It will also list any additional software - components required in addition to a generic Linux software stack for both - essential and optional platform features. - </para> - - <para> - The intent of this document is to define a structure for these components - so that BSPs follow a commonly understood layout, allowing them to be - provided in a common form that everyone understands. It also allows end-users - to become familiar with one common format and encourages standardisation - of software support of hardware. - </para> - - <para> - 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/OpenEmbedded and that it will be simple - to extract information and convert to other formats if required. The format - described can be directly accepted as a layer by Poky using its standard - layers mechanism, but it is important to recognise that 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 in use. - </para> - - <para> - 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 the BSP may be shipped combined with a build system - and other tools, but it is important to maintain the distinction that these - are separate components which may just be combined in certain end products. - </para> - - <section id='bsp-filelayout'> - <title>Example Filesystem Layout</title> - - <para> - 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: - </para> - - <para> - <programlisting> -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/ - - </programlisting> - </para> - - <para> - The following sections detail what these files and directories could contain. - </para> - - </section> - - <section id='bsp-filelayout-binary'> - <title>Prebuilt User Binaries (meta-bsp/binary/*)</title> - - <para> - 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 will be highly hardware-dependent but a README file should be present - explaining 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. - </para> - - </section> - - <section id='bsp-filelayout-layer'> - <title>Layer Configuration (meta-bsp/conf/layer.conf)</title> - - <para> - This file identifies the structure as a Poky layer. This file identifies the - contents of the layer and contains information about how Poky should use - it. In general it will most likely be a standard boilerplate file consisting of: - </para> - - <para> - <programlisting> -# We have a conf directory, add to BBPATH -BBPATH := "${BBPATH}${LAYERDIR}" - -# We have a packages directory, add to BBFILES -BBFILES := "${BBFILES} ${LAYERDIR}/packages/*/*.bb" - -BBFILE_COLLECTIONS += "bsp" -BBFILE_PATTERN_bsp := "^${LAYERDIR}/" -BBFILE_PRIORITY_bsp = "5" - </programlisting> - </para> - - <para> - which simply makes bitbake aware of the packages and conf directories. - </para> - - <para> - This file is required for recognition of the BSP by Poky. - </para> - - </section> - - <section id='bsp-filelayout-machine'> - <title>Hardware Configuration Options (meta-bsp/conf/machine/*.conf)</title> - - <para> - 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 users set the - MACHINE variable to. - </para> - - <para> - These files would define things like which kernel package to use - (PREFERRED_PROVIDER of virtual/kernel), which 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. - </para> - - <para> - At least one machine file is required for a Poky BSP layer but more than one may be present. - </para> - - </section> - - <section id='bsp-filelayout-tune'> - <title>Hardware Optimisation Options (meta-bsp/conf/machine/include/tune-*.inc)</title> - - <para> - These are shared hardware "tuning" definitions and are commonly used to - pass specific optimisation flags to the compiler. An example is - tune-atom.inc: - </para> - <para> - <programlisting> -BASE_PACKAGE_ARCH = "core2" -TARGET_CC_ARCH = "-m32 -march=core2 -msse3 -mtune=generic -mfpmath=sse" - </programlisting> - </para> - <para> - which defines a new package architecture called "core2" and uses the - optimization flags specified, which are carefully chosen to give best - performance on atom cpus. - </para> - <para> - The tune file would be included by the machine definition and can be - contained in the BSP or reference one from the standard core set of - files included with Poky itself. - </para> - <para> - These files are optional for a Poky BSP layer. - </para> - </section> - <section id='bsp-filelayout-kernel'> - <title>Linux Kernel Configuration (meta-bsp/packages/linux/*)</title> - - <para> - 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 but kernels can be shared between many - machines as well. Taking some specific example files: - </para> - <para> - <programlisting> -meta-bsp/packages/linux/linux-bsp_2.6.50.bb - </programlisting> - </para> - <para> - which is the core kernel recipe which firstly details where to get the kernel - source from. 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. It then contains information about which - patches to apply and how to configure and build it. It can reuse the main - Poky kernel build class, so the definitions here can remain very simple. - </para> - <para> - <programlisting> -linux-bsp-2.6.50/*.patch - </programlisting> - </para> - <para> - which are patches which may be applied against the base kernel, wherever - they may have been obtained from. - </para> - <para> - <programlisting> -meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp - </programlisting> - </para> - <para> - which is the configuration information to use to configure the kernel. - </para> - <para> - Examples of kernel recipes are available in Poky itself. These files are - optional since a kernel from Poky itself could be selected, although it - would be unusual not to have a kernel configuration. - </para> - </section> - - <section id='bsp-filelayout-packages'> - <title>Other Software (meta-bsp/packages/*)</title> - - <para> - This area includes other pieces of software which the hardware may need for best - operation. These are just examples of the kind of things that may be - encountered. These are standard .bb file recipes in the usual Poky format, - so for examples, see standard Poky recipes. The source can be included directly, - referred to in source control systems or release tarballs of external software projects. - </para> - <para> - <programlisting> -meta-bsp/packages/bootloader/bootloader_0.1.bb - </programlisting> - </para> - <para> - Some kind of bootloader recipe which may be used to generate a new - bootloader binary. Sometimes these are included in the final image - format and needed to reflash hardware. - </para> - <para> - <programlisting> -meta-bsp/packages/modem/modem-driver_0.1.bb -meta-bsp/packages/modem/modem-daemon_0.1.bb - </programlisting> - </para> - <para> - These are examples of a hardware driver and also a hardware daemon which - may need to be included in images to make the hardware useful. "modem" - is one example but there may be other components needed like firmware. - </para> - <para> - <programlisting> -meta-bsp/packages/image-creator/image-creator-native_0.1.bb - </programlisting> - </para> - <para> - Sometimes the device will need an image in a very specific format for - its update mechanism to accept and reflash with it. Recipes to build the - tools needed to do this can be included with the BSP. - </para> - <para> - These files only need be provided if the platform requires them. - </para> - </section> - - <section id='bs-filelayout-bbappend'> - <title>Append BSP specific information to existing recipes</title> - - <para> - Say you have a recipe like pointercal which has machine-specific information in it, - and then you have your new BSP code in a layer. Before the .bbappend extension was - introduced, you'd have to copy the whole pointercal recipe and files into your layer, - and then add the single file for your machine, which is ugly. - - .bbappend makes the above work much easier, to allow BSP-specific information to be merged - with the original recipe easily. When bitbake finds any X.bbappend files, they will be - included after bitbake loads X.bb but before finalise or anonymous methods run. - This allows the BSP layer to poke around and do whatever it might want to customise - the original recipe. - - .bbappend is expected to include the below two lines in the head (which may be changed - in the future): - </para> - - <programlisting> -THISDIR := "${@os.path.dirname(bb.data.getVar('FILE', d, True))}" -FILESPATH =. "${@base_set_filespath(["${THISDIR}/${PN}"], d)}:" - </programlisting> - - <para> - Then the BSP could add machine-specific config files in layer directory, which will be - added by bitbake. You can look at meta-emenlow/packages/formfactor as an example. - </para> - </section> - - <section id='bsp-filelayout-prebuilds'> - <title>Prebuild Data (meta-bsp/prebuilds/*)</title> - - <para> - The location can contain a precompiled representation of the source code - contained elsewhere in the BSP layer. It can be processed and used by - Poky to provide much faster build times, assuming a compatible configuration is used. - </para> - - <para> - These files are optional. - </para> - - </section> - - <section id='bsp-click-through-licensing'> - <title>BSP 'Click-through' Licensing Procedure</title> - - <note><para> This section is here as a description of how - click-through licensing is expected to work, and is - not yet not impemented. - </para></note> - - <para> - In some cases, a BSP may contain separately licensed IP - (Intellectual Property) for a component, which imposes - upon the user a requirement to accept the terms of a - 'click-through' license. Once the license is accepted - (in whatever form that may be, see details below) the - Poky build system can then build and include the - corresponding component in the final BSP image. Some - affected components may 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. Other components may be simply - 'good-to-have' or purely elective, or if essential - nonetheless have a 'free' (possibly less-capable) - version which may substituted for in the BSP recipe. - </para> - - <para> - For the latter cases, where it is possible to do so from - a functionality perspective, the Poky website will make - available a 'de-featured' BSP completely free of - encumbered IP, which can be used 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). This is the simplest - and therefore preferred option if available, assuming - the resulting functionality meets requirements. - </para> - - <para> - 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. There are several ways - within the Poky build system to satisfy the licensing - requirements for an encumbered BSP, in roughly the - following order of preference: - </para> - - <itemizedlist> - <listitem> - - <para> - Get a license key (or keys) for the encumbered BSP - by - visiting <ulink url='https://pokylinux.org/bsp-keys.html'>https://pokylinux.org/bsp-keys.html</ulink> - and give the web form there the name of the BSP - and your e-mail address. - </para> - - <programlisting> - [screenshot of dialog box] - </programlisting> - - <para> - After agreeing to any applicable license terms, the - BSP key(s) will be immediately sent to the address - given and can be used by specifying BSPKEY_<keydomain> - environment variables when building the image: - </para> - - <programlisting> - $ BSPKEY_<keydomain>=<key> bitbake poky-image-sato - </programlisting> - - <para> - This will allow the encumbered image to be built - with no change at all to the normal build process. - </para> - - <para> - Equivalently and probably more conveniently, a line - for each key can instead be put into the user's - local.conf file. - </para> - - <para> - The <keydomain> component of the - BSPKEY_<keydomain> is required because there - may be multiple licenses in effect for a give BSP; a - given <keydomain> in such cases corresponds to - a particular license. In order for an encumbered - BSP encompassing 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. - </para> - </listitem> - <listitem> - <para> - Do nothing - build as you normally would, and follow - any license prompts that originate from the - encumbered BSP (the build will cleanly stop at this - point). These usually take the form of instructions - needed to manually fetch the encumbered package(s) - and md5 sums into e.g. the poky/build/downloads - directory. Once the manual package fetch has been - completed, restarting the build will continue where - it left off, this time without the prompt since the - license requirements will have been satisfied. - </para> - </listitem> - <listitem> - <para> - Get a full-featured BSP recipe rather than a key, by - visiting - <ulink url='https://pokylinux.org/bsps.html'>https://pokylinux.org/bsps.html</ulink>. - Accepting the license agreement(s) presented will - subsequently allow you to download a tarball - containing a full-featured BSP 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. - </para> - </listitem> - </itemizedlist> - <para> - Note that method 3 is also the only option available - when downloading pre-compiled images generated from - non-free BSPs. Those images are likewise available at - <ulink url='https://pokylinux.org/bsps.html'>https://pokylinux.org/bsps.html</ulink>. - </para> - </section> - -</chapter> |