diff options
Diffstat (limited to 'documentation')
63 files changed, 0 insertions, 12078 deletions
diff --git a/documentation/bsp-guide/Makefile b/documentation/bsp-guide/Makefile deleted file mode 100644 index 7e8d216904..0000000000 --- a/documentation/bsp-guide/Makefile +++ /dev/null @@ -1,35 +0,0 @@ -all: html pdf tarball - -pdf: - ../tools/poky-docbook-to-pdf bsp-guide.xml ../template - -XSLTOPTS = --stringparam html.stylesheet style.css \ - --stringparam chapter.autolabel 1 \ - --stringparam section.autolabel 1 \ - --stringparam section.label.includes.component.label 1 \ - --xinclude - -## -# These URI should be rewritten by your distribution's xml catalog to -# match your localy installed XSL stylesheets. -XSL_BASE_URI = http://docbook.sourceforge.net/release/xsl/current -XSL_XHTML_URI = $(XSL_BASE_URI)/xhtml/docbook.xsl - -html: -# See http://www.sagehill.net/docbookxsl/HtmlOutput.html - xsltproc $(XSLTOPTS) -o bsp-guide.html $(XSL_XHTML_URI) bsp-guide.xml - -tarball: html - tar -cvzf bsp-guide.tgz style.css bsp-guide.html figures/poky-ref-manual.png - -validate: - xmllint --postvalid --xinclude --noout bsp-guide.xml - -OUTPUTS = bsp-guide.pdf bsp-guide.html -SOURCES = *.png *.xml *.css *.svg - -publish: - scp -r $(OUTPUTS) $(SOURCES) o-hand.com:/srv/www/pokylinux.org/doc/ - -clean: - rm -f $(OUTPUTS) diff --git a/documentation/bsp-guide/bsp-guide.xml b/documentation/bsp-guide/bsp-guide.xml deleted file mode 100644 index e90602cb00..0000000000 --- a/documentation/bsp-guide/bsp-guide.xml +++ /dev/null @@ -1,62 +0,0 @@ -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - -<book id='poky-handbook' lang='en' - xmlns:xi="http://www.w3.org/2003/XInclude" - xmlns="http://docbook.org/ns/docbook" - > - <bookinfo> - - <mediaobject> - <imageobject> - <imagedata fileref='poky-ref-manual.png' - format='SVG' - align='center' scalefit='1' width='100%'/> - </imageobject> - </mediaobject> - - <title>Board Support Package (BSP) Developers Guide</title> - - <authorgroup> - <author> - <firstname>Richard</firstname> <surname>Purdie</surname> - <affiliation> - <orgname>Intel Corporation</orgname> - </affiliation> - <email>richard@linux.intel.com</email> - </author> - </authorgroup> - - <revhistory> - <revision> - <revnumber>0.9</revnumber> - <date>27 October 2010</date> - <revremark>Beta Draft</revremark> - </revision> - </revhistory> - - <copyright> - <year>2010</year> - <holder>Linux Foundation</holder> - </copyright> - - <legalnotice> - <para> - Permission is granted to copy, distribute and/or modify this document under - the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-nc-sa/2.0/uk/">Creative Commons Attribution-Non-Commercial-Share Alike 2.0 UK: England & Wales</ulink> as published by Creative Commons. - </para> - </legalnotice> - - </bookinfo> - - <xi:include href="bsp.xml"/> - -<!-- <index id='index'> - <title>Index</title> - </index> ---> - -</book> -<!-- -vim: expandtab tw=80 ts=4 ---> diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml deleted file mode 100644 index 3b4b4818fa..0000000000 --- a/documentation/bsp-guide/bsp.xml +++ /dev/null @@ -1,459 +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 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. - </para> - - <para> - The intent of this document is to define 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. - </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 and OpenEmbedded and thatspecified it will be simple - to extract information and convert it to other formats if required. - Poky, through its standard slyers 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 being used. - </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 you can shipt 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. - </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> - <literallayout class='monospaced'> - 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/ - </literallayout> - </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 by identifying the - contents of the layer and containing information about how Poky should use - it. - Generally, a standard boilerplate file consisting of the following works. - </para> - - <para> - <literallayout class='monospaced'> - # 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" - </literallayout> - </para> - - <para> - This file simply makes bitbake aware of the recipes and conf directories and 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 to which users have set the MACHINE variable. - </para> - - <para> - 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. - </para> - - <para> - At least one machine file is required for a Poky BSP layer. - However, you can supply more than one file. - </para> - - </section> - - <section id="bsp-filelayout-tune"> - <title>Hardware Optimization Options (meta-bsp/conf/machine/include/tune-*.inc)</title> - - <para> - These are shared hardware "tuning" definitions and are commonly used to - pass specific optimization flags to the compiler. - An example is tune-atom.inc: - </para> - <para> - <literallayout class='monospaced'> - BASE_PACKAGE_ARCH = "core2" - TARGET_CC_ARCH = "-m32 -march=core2 -msse3 -mtune=generic -mfpmath=sse" - </literallayout> - </para> - <para> - 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. - </para> - <para> - 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. - </para> - <para> - Both the base package architecuture file and the tune file 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. - Following is an example: - <literallayout class='monospaced'> - meta-bsp/packages/linux/linux-bsp_2.6.50.bb - </literallayout> - 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. - </para> - <para> - 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. - </para> - <para> - <literallayout class='monospaced'> - linux-bsp-2.6.50/*.patch - </literallayout> - </para> - <para> - The above example file contains patches you can apply against the base kernel, wherever - they may have been obtained from. - </para> - <para> - <literallayout class='monospaced'> - meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp - </literallayout> - </para> - <para> - Finally, this last example file contains 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 section describes other pieces of software that the hardware might need for best - operation. - These are examples of the kinds of things that you could encounter. - The examples used in this section are standard <filename>.bb</filename> 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. - </para> - <para> - 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 reflash hardware. - </para> - <para> - <literallayout class='monospaced'> - meta-bsp/packages/bootloader/bootloader_0.1.bb - </literallayout> - </para> - <para> - 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. - </para> - <para> - <literallayout class='monospaced'> - meta-bsp/packages/modem/modem-driver_0.1.bb - meta-bsp/packages/modem/modem-daemon_0.1.bb - </literallayout> - </para> - <para> - Sometimes the device needs an image in a very specific format so that the update - mechanism can accept and reflash it. - Recipes to build the tools needed to do this can be included with the BSP. - Following is an example. - </para> - <para> - <literallayout class='monospaced'> - meta-bsp/packages/image-creator/image-creator-native_0.1.bb - </literallayout> - </para> - </section> - - <section id='bs-filelayout-bbappend'> - <title>Append BSP-Specific Information to Existing Recipes</title> - <para> - 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, which is where - you would also like to specify any machine-specific information associated with your new machine. - Before the <filename>.bbappend</filename> 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. - </para> - <para> - With the <filename>.bbappend</filename> extension, however, your work becomes much easier. - It allows you to easily merge BSP-specific information with the original recipe. - Whenever bitbake finds any <filename>.bbappend</filename> files, they will be - included after bitbake loads the associated <filename>.bb</filename> 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. - </para> - <para> - 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). - </para> - <literallayout class='monospaced'> - FILESEXTRAPATHS := "${THISDIR}/${PN}" - </literallayout> - <para> - 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 <filename>meta-emenlow/packages/formfactor</filename>. - </para> - </section> - - <section id="bsp-filelayout-prebuilds"> - <title>Prebuild Data (meta-bsp/prebuilds/*)</title> - <para> - 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. - </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. |