summaryrefslogtreecommitdiff
path: root/documentation/bsp-guide
diff options
context:
space:
mode:
authorRichard Purdie <richard.purdie@linuxfoundation.org>2011-04-20 14:20:19 +0100
committerRichard Purdie <richard.purdie@linuxfoundation.org>2011-04-20 15:49:17 +0100
commit50021cba20a09b1ed685db5466f940b17d4880ac (patch)
tree3bdafb797e6466ad58727b002f1235933010ab11 /documentation/bsp-guide
parent690e87a2ffe8caa16379be26eb356c5bded17c1f (diff)
downloadopenembedded-core-50021cba20a09b1ed685db5466f940b17d4880ac.tar.gz
openembedded-core-50021cba20a09b1ed685db5466f940b17d4880ac.tar.bz2
openembedded-core-50021cba20a09b1ed685db5466f940b17d4880ac.zip
Drop documentation directory, this is replaced by the new yocto-docs repository
Diffstat (limited to 'documentation/bsp-guide')
-rw-r--r--documentation/bsp-guide/Makefile35
-rw-r--r--documentation/bsp-guide/bsp-guide-customization.xsl6
-rw-r--r--documentation/bsp-guide/bsp-guide.xml68
-rw-r--r--documentation/bsp-guide/bsp.xml654
-rw-r--r--documentation/bsp-guide/figures/bsp-title.pngbin14940 -> 0 bytes
-rw-r--r--documentation/bsp-guide/figures/poky-ref-manual.pngbin17829 -> 0 bytes
-rw-r--r--documentation/bsp-guide/style.css958
7 files changed, 0 insertions, 1721 deletions
diff --git a/documentation/bsp-guide/Makefile b/documentation/bsp-guide/Makefile
deleted file mode 100644
index fdb45ecd13..0000000000
--- a/documentation/bsp-guide/Makefile
+++ /dev/null
@@ -1,35 +0,0 @@
-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
-
-all: html pdf tarball
-
-pdf:
- ../tools/poky-docbook-to-pdf bsp-guide.xml ../template
-
-html:
-# See http://www.sagehill.net/docbookxsl/HtmlOutput.html
- xsltproc $(XSLTOPTS) -o bsp-guide.html bsp-guide-customization.xsl bsp-guide.xml
-
-tarball: html
- tar -cvzf bsp-guide.tgz style.css bsp-guide.html bsp-guide.pdf figures/bsp-title.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-customization.xsl b/documentation/bsp-guide/bsp-guide-customization.xsl
deleted file mode 100644
index 362ebed131..0000000000
--- a/documentation/bsp-guide/bsp-guide-customization.xsl
+++ /dev/null
@@ -1,6 +0,0 @@
-<?xml version='1.0'?>
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
-
- <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl" />
-
-</xsl:stylesheet>
diff --git a/documentation/bsp-guide/bsp-guide.xml b/documentation/bsp-guide/bsp-guide.xml
deleted file mode 100644
index fd409bc74c..0000000000
--- a/documentation/bsp-guide/bsp-guide.xml
+++ /dev/null
@@ -1,68 +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='bsp-guide' lang='en'
- xmlns:xi="http://www.w3.org/2003/XInclude"
- xmlns="http://docbook.org/ns/docbook"
- >
- <bookinfo>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref='figures/bsp-title.png'
- format='SVG'
- align='center' scalefit='1' width='100%'/>
- </imageobject>
- </mediaobject>
-
- <title></title>
-
- <authorgroup>
- <author>
- <firstname>Richard</firstname> <surname>Purdie</surname>
- <affiliation>
- <orgname>Intel Corporation</orgname>
- </affiliation>
- <email>richard.purdie@linuxfoundation.org</email>
- </author>
- </authorgroup>
-
- <revhistory>
- <revision>
- <revnumber>0.9</revnumber>
- <date>27 October 2010</date>
- <revremark>This manual revision is the initial manual and corresponds to the
- Yocto Project 0.9 Release.</revremark>
- </revision>
- <revision>
- <revnumber>1.0</revnumber>
- <date>6 April 2011</date>
- <revremark>This manual revision corresponds to the Yocto Project 1.0 Release.</revremark>
- </revision>
- </revhistory>
-
- <copyright>
- <year>2010-2011</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 &amp; 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 36715f33b7..0000000000
--- a/documentation/bsp-guide/bsp.xml
+++ /dev/null
@@ -1,654 +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>
- 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.
- </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 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.
- </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 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.
- </para>
-
- <section id="bsp-filelayout">
- <title>Example Filesystem Layout</title>
-
- <para>
- The BSP consists of a file structure inside a base directory, which uses the following
- naming convention:
- <literallayout class='monospaced'>
- meta-&lt;bsp_name&gt;
- </literallayout>
- "bsp_name" is a placeholder for the machine or platform name.
- Here are some example base directory names:
- <literallayout class='monospaced'>
- meta-emenlow
- meta-intel_n450
- meta-beagleboard
- </literallayout>
- </para>
-
- <para>
- Below is the common form for the file structure inside a base directory.
- While you can use this basic form for the standard, realize that the actual structures
- for specific BSPs could differ.
-
- <programlisting>
-meta-&lt;bsp_name&gt;/
-meta-&lt;bsp_name&gt;/&lt;bsp_license_file&gt;
-meta-&lt;bsp_name&gt;/README
-meta-&lt;bsp_name&gt;/binary/&lt;bootable_images&gt;
-meta-&lt;bsp_name&gt;/conf/layer.conf
-meta-&lt;bsp_name&gt;/conf/machine/*.conf
-meta-&lt;bsp_name&gt;/recipes-bsp/*
-meta-&lt;bsp_name&gt;/recipes-graphics/*
-meta-&lt;bsp_name&gt;/recipes-kernel/linux/linux-yocto_git.bbappend
- </programlisting>
- </para>
-
- <para>
- Below is an example of the crownbay BSP:
-
- <programlisting>
-meta-crownbay/COPYING.MIT
-meta-crownbay/README
-meta-crownbay/binary/.gitignore
-meta-crownbay/conf/layer.conf
-meta-crownbay/conf/machine/crownbay.conf
-meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay/machconfig
-meta-crownbay/recipes-bsp/formfactor/formfactor_0.0.bbappend
-meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay/xcorg.conf
-meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend
-meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd-bin/.gitignore
-meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd-bin_1.7.99.2.bb
-meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/crosscompile.patch
-meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/fix_open_max_preprocessor_error.patch
-meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/macro_tweak.patch
-meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/nodolt.patch
-meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd_1.7.99.2.bb
-meta-crownbay/recipes-kernel/linux/linux-yocto_git.bbappend
- </programlisting>
- </para>
-
- <para>
- The following sections describe each part of the proposed BSP format.
- </para>
-
- <section id="bsp-filelayout-license">
- <title>License Files</title>
- <programlisting>
-meta-&lt;bsp_name&gt;/&lt;bsp_license_file&gt;
- </programlisting>
-
- <para>
- These optional files satisfy licensing requirements for the BSP.
- The type or types of files here can vary depending on the licensing requirements.
- For example, in the crownbay BSP all licensing requirements are handled with the
- <filename>COPYING.MIT</filename> file.
- </para>
-
- <para>
- Licensing files can be MIT, BSD, GPLv*, and so forth.
- These files are recommended for the BSP but are optional and totally up to the BSP developer.
- </para>
- </section>
-
- <section id="bsp-filelayout-readme">
- <title>README File</title>
- <programlisting>
-meta-&lt;bsp_name&gt;/README
- </programlisting>
-
- <para>
- This file provides information on how to boot the live images that are optionally
- included in the <filename>/binary</filename> directory.
- The <filename>README</filename> file also provides special information needed for
- building the image.
- </para>
-
- <para>
- Technically speaking a <filename>README</filename> is optional but it is highly
- recommended that every BSP has one.
- </para>
- </section>
-
- <section id="bsp-filelayout-binary">
- <title>Pre-built User Binaries</title>
- <programlisting>
-meta-&lt;bsp_name&gt;/binary/&lt;bootable_images&gt;
- </programlisting>
-
- <para>
- This optional area contains useful pre-built kernels and user-space filesystem
- images appropriate to the target system.
- This directory contains the Application Development Toolkit (ADT) and minimal
- live images when the BSP is has been "tar-balled" and placed on the Yocto Project website.
- You can use these kernels and images to get a system running and quickly get started
- on development tasks.
- </para>
-
- <para>
- The exact types of binaries present are highly hardware-dependent.
- However, a README file should be present in the BSP file structure that explains how to use
- the kernels and images with the target hardware.
- If pre-built 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 File</title>
- <programlisting>
-meta-&lt;bsp_name&gt;/conf/layer.conf
- </programlisting>
-
- <para>
- 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 such as the following works.
- In the following example you would replace "bsp" and "_bsp" with the actual name
- of the BSP (i.e. &lt;bsp_name&gt; from the example template).
- </para>
-
- <para>
- <programlisting>
-# 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"
- </programlisting>
- </para>
-
- <para>
- This file simply makes BitBake aware of the recipes and configuration directories.
- This file must exist so that Poky can recognize the BSP.
- </para>
- </section>
-
- <section id="bsp-filelayout-machine">
- <title>Hardware Configuration Options</title>
- <programlisting>
-meta-&lt;bsp_name&gt;/conf/machine/*.conf
- </programlisting>
-
- <para>
- The machine files bind together all the information contained elsewhere
- in the BSP into a format that Poky 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 the kernel package to use
- (PREFERRED_PROVIDER of virtual/kernel), the hardware drivers to
- include in different types of images, any special software components
- that are needed, any bootloader information, and also any special image
- format requirements.
- </para>
-
- <para>
- At least one machine file is required for a BSP layer.
- However, you can supply more than one file.
- </para>
-
- <para>
- This directory could also contain shared hardware "tuning" definitions that are commonly used to
- pass specific optimization flags to the compiler.
- An example is <filename>tune-atom.inc</filename>:
- </para>
- <para>
- <programlisting>
-BASE_PACKAGE_ARCH = "core2"
-TARGET_CC_ARCH = "-m32 -march=core2 -msse3 -mtune=generic -mfpmath=sse"
- </programlisting>
- </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 architecture file and the tune file are optional for a Poky BSP layer.
- </para>
- </section>
-
- <section id='bsp-filelayout-misc-recipes'>
- <title>Miscellaneous Recipe Files</title>
- <programlisting>
-meta-&lt;bsp_name&gt;/recipes-bsp/*
- </programlisting>
-
- <para>
- This optional directory contains miscellaneous recipe files for the BSP.
- Most notably would be the formfactor files.
- For example, in the crownbay BSP there is a <filename>machconfig</filename> file and a
- <filename>formfactor_0.0.bbappend</filename> file:
- <programlisting>
-meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay/machconfig
-meta-crownbay/recipes-bsp/formfactor/formfactor_0.0.bbappend
- </programlisting>
- </para>
-
- <note><para>
- If a BSP does not have a formfactor entry, defaults are established according to
- the configuration script.
- </para></note>
- </section>
-
- <section id='bsp-filelayout-recipes-graphics'>
- <title>Display Support Files</title>
- <programlisting>
-meta-&lt;bsp_name&gt;/recipes-graphics/*
- </programlisting>
-
- <para>
- This optional directory contains recipes for the BSP if it has
- special requirements for graphics support.
- All files that are needed for the BSP to support a display are kept here.
- For example, in the crownbay BSP several display support files exist:
- <programlisting>
-meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay/xcorg.conf
-meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend
-meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd-bin/.gitignore
-meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd-bin_1.7.99.2.bb
-meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/crosscompile.patch
-meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/fix_open_max_preprocessor_error.patch
-meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/macro_tweak.patch
-meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd/nodolt.patch
-meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-emgd_1.7.99.2.bb
- </programlisting>
- </para>
- </section>
-
- <section id='bsp-filelayout-kernel'>
- <title>Linux Kernel Configuration</title>
- <programlisting>
-meta-&lt;bsp_name&gt;/recipes-kernel/linux/linux-yocto_git.bbappend
- </programlisting>
-
- <para>
- This file appends your specific changes to the kernel you are using.
- </para>
- <para>
- For your BSP you typically want to use an existing Poky kernel found in the
- Poky repository at <filename class='directory'>meta/recipes-kernel/kernel</filename>.
- You can append your specific changes to the kernel recipe by using an append file,
- which is located in the
- <filename class='directory'>meta-&lt;bsp_name&gt;/recipes-kernel/linux</filename>
- directory.
- </para>
- <para>
- Suppose you use a BSP that uses the <filename>linux-yocto_git.bb</filename> kernel,
- which is the preferred kernel to use for developing a new BSP using the Yocto Project.
- In other words, you have selected the kernel in your
- <filename>&lt;bsp_name&gt;.conf</filename> file by adding the following statement:
- <programlisting>
-PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
- </programlisting>
- You would use the <filename>linux-yocto_git.bbappend</filename> file to append
- specific BSP settings to the kernel, thus configuring the kernel for your particular BSP.
- </para>
- <para>
- Now take a look at the existing "crownbay" BSP.
- The append file used is:
- <programlisting>
-meta-crownbay/recipes-kernel/linux/linux-yocto_git.bbappend
- </programlisting>
- The file contains the following:
- <programlisting>
-FILESEXTRAPATHS := "${THISDIR}/${PN}"
-COMPATIBLE_MACHINE_crownbay = "crownbay"
-KMACHINE_crownbay = "yocto/standard/crownbay"
- </programlisting>
- This append file adds "crownbay" as a compatible machine,
- and additionally sets a Yocto Kernel-specific variable that identifies the name of the
- BSP branch to use in the GIT repository to find configuration information.
- </para>
- <para>
- One thing missing in this particular BSP, which you will typically need when
- developing a BSP, is the kernel configuration (.config) for your BSP.
- When developing a BSP, you probably have a kernel configuration file or a set of kernel
- configuration files that, when taken together, define the kernel configuration for your BSP.
- You can accomplish this definition by putting the configurations in a file or a set of files
- inside a directory located at the same level as your append file and having the same name
- as the kernel.
- With all these conditions met simply reference those files in a SRC_URI statement in the append
- file.
- </para>
- <para>
- For example, suppose you had a set of configuration options in a file called
- <filename>defconfig</filename>.
- If you put that file inside a directory named
- <filename class='directory'>/linux-yocto</filename> and then added
- a SRC_URI statement such as the following to the append file, those configuration
- options will be picked up and applied when the kernel is built.
- <programlisting>
-SRC_URI += "file://defconfig"
- </programlisting>
- </para>
- <para>
- As mentioned earlier, you can group related configurations into multiple files and
- name them all in the SRC_URI statement as well.
- For example, you could group separate configurations specifically for Ethernet and graphics
- into their own files and add those by using a SRC_URI statement like the
- following in your append file:
- <programlisting>
-SRC_URI += "file://defconfig \
- file://eth.cfg \
- file://gfx.cfg"
- </programlisting>
- </para>
- <para>
- The FILESEXTRAPATHS variable is in boilerplate form here in order to make it easy
- to do that.
- It basically allows those configuration files to be found by the build process.
- </para>
- <note><para>
- Other methods exist to accomplish grouping and defining configuration options.
- For example, you could directly add configuration options to the Yocto kernel
- <filename class='directory'>meta</filename> branch for your BSP.
- The configuration options will likely end up in that location anyway if the BSP gets
- added to the Yocto Project.
- For information on how to add these configurations directly, see the
- "Yocto Project Kernel Architecture and Use Manual" on the
- <ulink url="http://yoctoproject.org/community/documentation">Yocto Project website
- Documentation Page</ulink>
- </para>
- <para>
- In general, however, the Yocto Project maintainers take care of moving the SRC_URI-specified
- configuration options to the <filename class='directory'>meta</filename> branch.
- Not only is it easier for BSP developers to not have to worry about putting those
- configurations in the branch, but having the maintainers do it allows them to apply
- 'global' knowledge about the kinds of common configuration options multiple BSPs in
- the tree are typically using.
- This allows for promotion of common configurations into common features.
- </para></note>
- </section>
-
-<!-- <section id='bsp-filelayout-packages'>
- <title>Other Software (meta-&lt;bsp_name&gt;/recipes-kernel/*)</title>
-
- <para>
- This section describes other pieces of software that the hardware might need for best
- operation.
- Examples show some of the things you could encounter.
- The examples 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 re-flash hardware.
- </para>
- <para>
- <programlisting>
-meta-Emenlow/recipes-kernel/bootloader/bootloader_0.1.bb
- </programlisting>
- </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>
- <programlisting>
-meta-Emenlow/recipes-Emenlow/modem/modem-driver_0.1.bb
-meta-Emenlow/recipes-Emenlow/modem/modem-daemon_0.1.bb
- </programlisting>
- </para>
- <para>
- 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.
- </para>
- <para>
- <programlisting>
-meta-Emenlow/recipes-Emenlow/image-creator/image-creator-native_0.1.bb
- </programlisting>
- </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 through which
- 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.
- This extension allows you to easily merge BSP-specific information with the original recipe.
- Whenever BitBake finds any <filename>.bbappend</filename> files BitBake will include them after
- it loads the associated <filename>.bb</filename> file but before any finalize
- or anonymous methods are 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 FILESEXTRAPATHS variable
- to specify their location.
- The example below shows extra files contained in a folder called ${PN} (the package name).
- </para>
- <programlisting>
-FILESEXTRAPATHS := "${THISDIR}/${PN}"
- </programlisting>
- <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>Pre-build Data (meta-&lt;bsp_name&gt;/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 pre-compiled
- representations to provide much faster build times.
- </para>
- </section> -->
- </section>
-
- <section id='bsp-click-through-licensing'>
- <title>BSP 'Click-Through' Licensing Procedure</title>
-
- <note><para> This section describes how
- click-through licensing is expected to work.
- Currently, this functionality is not yet implemented.
- </para></note>
-
- <para>
- 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.
- </para>
-
- <para>
- For cases where you can substitute something and still maintain functionality,
- the Yocto Project website at
- <ulink url='http://yoctoproject.org/download/board-support-package-bsp-downloads'></ulink>
- 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 appropriately different
- than the normal encumbered BSP.
- If available, this substitution is the simplest and most preferred option.
- This, of course, assumes 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, you can use
- an encumbered version.
- </para>
-
- <para>
- 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:
- </para>
-
- <orderedlist>
- <listitem>
-
- <para>
- Get a license key (or keys) for the encumbered BSP by visiting
- a website and providing the name of the BSP and your email address
- through a web form.
- </para>
-
-<!--
- <ulink url='https://pokylinux.org/bsp-keys.html'>https://pokylinux.org/bsp-keys.html</ulink>
- and give the name of the BSP and your e-mail address in the web form.
- </para>
-
- COMMENT: This link is not implemented at this point.
-
- <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
- you gave and you can use them by specifying BSPKEY_&lt;keydomain&gt;
- environment variables when building the image:
- </para>
-
- <programlisting>
- $ BSPKEY_&lt;keydomain&gt;=&lt;key&gt; bitbake poky-image-sato
- </programlisting>
-
- <para>
- These steps 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
- <filename>local.conf</filename> file.
- </para>
-
- <para>
- The &lt;keydomain&gt; component of the
- BSPKEY_&lt;keydomain&gt; is required because there
- might be multiple licenses in effect for a given BSP.
- In such cases, a given &lt;keydomain&gt; corresponds to
- a particular license. In order for an encumbered
- BSP that encompasses multiple key domains to be built
- successfully, a &lt;keydomain&gt; entry for each
- applicable license must be present in <filename>local.conf</filename> or
- supplied on the command-line.
- </para>
- </listitem>
- <listitem>
- <para>
- 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 <filename>poky/build/downloads</filename>).
- 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.
- </para>
- </listitem>
- <listitem>
- <para>
- Get a full-featured BSP recipe rather than a key.
- You can do this by visiting the applicable BSP download page from the Yocto
- Project website at
- <ulink url='http://yoctoproject.org/download/board-support-package-bsp-downloads'></ulink>.
- BSP tarballs that have proprietary information can be downloaded after agreeing
- to licensing requirements as part of the download process.
- Obtaining the code this way allows you to build an encumbered image with
- no changes at all as compared to the normal build.
- </para>
- </listitem>
- </orderedlist>
- <para>
- 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 from the Yocto Project website.
- </para>
- </section>
-
-</chapter>
diff --git a/documentation/bsp-guide/figures/bsp-title.png b/documentation/bsp-guide/figures/bsp-title.png
deleted file mode 100644
index ee383141f0..0000000000
--- a/documentation/bsp-guide/figures/bsp-title.png
+++ /dev/null
Binary files differ
diff --git a/documentation/bsp-guide/figures/poky-ref-manual.png b/documentation/bsp-guide/figures/poky-ref-manual.png
deleted file mode 100644
index 333442e0d6..0000000000
--- a/documentation/bsp-guide/figures/poky-ref-manual.png
+++ /dev/null
Binary files differ
diff --git a/documentation/bsp-guide/style.css b/documentation/bsp-guide/style.css
deleted file mode 100644
index 9d068a0f56..0000000000
--- a/documentation/bsp-guide/style.css
+++ /dev/null
@@ -1,958 +0,0 @@
-/*
- Generic XHTML / DocBook XHTML CSS Stylesheet.
-
- Browser wrangling and typographic design by
- Oyvind Kolas / pippin@gimp.org
-
- Customised for Poky by
- Matthew Allum / mallum@o-hand.com
-
- Thanks to:
- Liam R. E. Quin
- William Skaggs
- Jakub Steiner
-
- Structure
- ---------
-
- The stylesheet is divided into the following sections:
-
- Positioning
- Margins, paddings, width, font-size, clearing.
- Decorations
- Borders, style
- Colors
- Colors
- Graphics
- Graphical backgrounds
- Nasty IE tweaks
- Workarounds needed to make it work in internet explorer,
- currently makes the stylesheet non validating, but up until
- this point it is validating.
- Mozilla extensions
- Transparency for footer
- Rounded corners on boxes
-
-*/
-
-
- /*************** /
- / Positioning /
-/ ***************/
-
-body {
- font-family: Verdana, Sans, sans-serif;
-
- min-width: 640px;
- width: 80%;
- margin: 0em auto;
- padding: 2em 5em 5em 5em;
- color: #333;
-}
-
-.reviewer {
- color: red;
-}
-
-h1,h2,h3,h4,h5,h6,h7 {
- font-family: Arial, Sans;
- color: #00557D;
- clear: both;
-}
-
-h1 {
- font-size: 2em;
- text-align: left;
- padding: 0em 0em 0em 0em;
- margin: 2em 0em 0em 0em;
-}
-
-h2.subtitle {
- margin: 0.10em 0em 3.0em 0em;
- padding: 0em 0em 0em 0em;
- font-size: 1.8em;
- padding-left: 20%;
- font-weight: normal;
- font-style: italic;
-}
-
-h2 {
- margin: 2em 0em 0.66em 0em;
- padding: 0.5em 0em 0em 0em;
- font-size: 1.5em;
- font-weight: bold;
-}
-
-h3.subtitle {
- margin: 0em 0em 1em 0em;
- padding: 0em 0em 0em 0em;
- font-size: 142.14%;
- text-align: right;
-}
-
-h3 {
- margin: 1em 0em 0.5em 0em;
- padding: 1em 0em 0em 0em;
- font-size: 140%;
- font-weight: bold;
-}
-
-h4 {
- margin: 1em 0em 0.5em 0em;
- padding: 1em 0em 0em 0em;
- font-size: 120%;
- font-weight: bold;
-}
-
-h5 {
- margin: 1em 0em 0.5em 0em;
- padding: 1em 0em 0em 0em;
- font-size: 110%;
- font-weight: bold;
-}
-
-h6 {
- margin: 1em 0em 0em 0em;
- padding: 1em 0em 0em 0em;
- font-size: 80%;
- font-weight: bold;
-}
-
-.authorgroup {
- background-color: transparent;
- background-repeat: no-repeat;
- padding-top: 256px;
- background-image: url("figures/bsp-title.png");
- background-position: left top;
- margin-top: -256px;
- padding-right: 50px;
- margin-left: 0px;
- text-align: right;
- width: 740px;
-}
-
-h3.author {
- margin: 0em 0me 0em 0em;
- padding: 0em 0em 0em 0em;
- font-weight: normal;
- font-size: 100%;
- color: #333;
- clear: both;
-}
-
-.author tt.email {
- font-size: 66%;
-}
-
-.titlepage hr {
- width: 0em;
- clear: both;
-}
-
-.revhistory {
- padding-top: 2em;
- clear: both;
-}
-
-.toc,
-.list-of-tables,
-.list-of-examples,
-.list-of-figures {
- padding: 1.33em 0em 2.5em 0em;
- color: #00557D;
-}
-
-.toc p,
-.list-of-tables p,
-.list-of-figures p,
-.list-of-examples p {
- padding: 0em 0em 0em 0em;
- padding: 0em 0em 0.3em;
- margin: 1.5em 0em 0em 0em;
-}
-
-.toc p b,
-.list-of-tables p b,
-.list-of-figures p b,
-.list-of-examples p b{
- font-size: 100.0%;
- font-weight: bold;
-}
-
-.toc dl,
-.list-of-tables dl,
-.list-of-figures dl,
-.list-of-examples dl {
- margin: 0em 0em 0.5em 0em;
- padding: 0em 0em 0em 0em;
-}
-
-.toc dt {
- margin: 0em 0em 0em 0em;
- padding: 0em 0em 0em 0em;
-}
-
-.toc dd {
- margin: 0em 0em 0em 2.6em;
- padding: 0em 0em 0em 0em;
-}
-
-div.glossary dl,
-div.variablelist dl {
-}
-
-.glossary dl dt,
-.variablelist dl dt,
-.variablelist dl dt span.term {
- font-weight: normal;
- width: 20em;
- text-align: right;
-}
-
-.variablelist dl dt {
- margin-top: 0.5em;
-}
-
-.glossary dl dd,
-.variablelist dl dd {
- margin-top: -1em;
- margin-left: 25.5em;
-}
-
-.glossary dd p,
-.variablelist dd p {
- margin-top: 0em;
- margin-bottom: 1em;
-}
-
-
-div.calloutlist table td {
- padding: 0em 0em 0em 0em;
- margin: 0em 0em 0em 0em;
-}
-
-div.calloutlist table td p {
- margin-top: 0em;
- margin-bottom: 1em;
-}
-
-div p.copyright {
- text-align: left;
-}
-
-div.legalnotice p.legalnotice-title {
- margin-bottom: 0em;
-}
-
-p {
- line-height: 1.5em;
- margin-top: 0em;
-
-}
-
-dl {
- padding-top: 0em;
-}
-
-hr {
- border: solid 1px;
-}
-
-
-.mediaobject,
-.mediaobjectco {
- text-align: center;
-}
-
-img {
- border: none;
-}
-
-ul {
- padding: 0em 0em 0em 1.5em;
-}
-
-ul li {
- padding: 0em 0em 0em 0em;
-}
-
-ul li p {
- text-align: left;
-}
-
-table {
- width :100%;
-}
-
-th {
- padding: 0.25em;
- text-align: left;
- font-weight: normal;
- vertical-align: top;
-}
-
-td {
- padding: 0.25em;
- vertical-align: top;
-}
-
-p a[id] {
- margin: 0px;
- padding: 0px;
- display: inline;
- background-image: none;
-}
-
-a {
- text-decoration: underline;
- color: #444;
-}
-
-pre {
- overflow: auto;
-}
-
-a:hover {
- text-decoration: underline;
- /*font-weight: bold;*/
-}
-
-
-div.informalfigure,
-div.informalexample,
-div.informaltable,
-div.figure,
-div.table,
-div.example {
- margin: 1em 0em;
- padding: 1em;
- page-break-inside: avoid;
-}
-
-
-div.informalfigure p.title b,
-div.informalexample p.title b,
-div.informaltable p.title b,
-div.figure p.title b,
-div.example p.title b,
-div.table p.title b{
- padding-top: 0em;
- margin-top: 0em;
- font-size: 100%;
- font-weight: normal;
-}
-
-.mediaobject .caption,
-.mediaobject .caption p {
- text-align: center;
- font-size: 80%;
- padding-top: 0.5em;
- padding-bottom: 0.5em;
-}
-
-.epigraph {
- padding-left: 55%;
- margin-bottom: 1em;
-}
-
-.epigraph p {
- text-align: left;
-}
-
-.epigraph .quote {
- font-style: italic;
-}
-.epigraph .attribution {
- font-style: normal;
- text-align: right;
-}
-
-span.application {
- font-style: italic;
-}
-
-.programlisting {
- font-family: monospace;
- font-size: 80%;
- white-space: pre;
- margin: 1.33em 0em;
- padding: 1.33em;
-}
-
-.tip,
-.warning,
-.caution,
-.note {
- margin-top: 1em;
- margin-bottom: 1em;
-
-}
-
-/* force full width of table within div */
-.tip table,
-.warning table,
-.caution table,
-.note table {
- border: none;
- width: 100%;
-}
-
-
-.tip table th,
-.warning table th,
-.caution table th,
-.note table th {
- padding: 0.8em 0.0em 0.0em 0.0em;
- margin : 0em 0em 0em 0em;
-}
-
-.tip p,
-.warning p,
-.caution p,
-.note p {
- margin-top: 0.5em;
- margin-bottom: 0.5em;
- padding-right: 1em;
- text-align: left;
-}
-
-.acronym {
- text-transform: uppercase;
-}
-
-b.keycap,
-.keycap {
- padding: 0.09em 0.3em;
- margin: 0em;
-}
-
-.itemizedlist li {
- clear: none;
-}
-
-.filename {
- font-size: medium;
- font-family: Courier, monospace;
-}
-
-
-div.navheader, div.heading{
- position: absolute;
- left: 0em;
- top: 0em;
- width: 100%;
- background-color: #cdf;
- width: 100%;
-}
-
-div.navfooter, div.footing{
- position: fixed;
- left: 0em;
- bottom: 0em;
- background-color: #eee;
- width: 100%;
-}
-
-
-div.navheader td,
-div.navfooter td {
- font-size: 66%;
-}
-
-div.navheader table th {
- /*font-family: Georgia, Times, serif;*/
- /*font-size: x-large;*/
- font-size: 80%;
-}
-
-div.navheader table {
- border-left: 0em;
- border-right: 0em;
- border-top: 0em;
- width: 100%;
-}
-
-div.navfooter table {
- border-left: 0em;
- border-right: 0em;
- border-bottom: 0em;
- width: 100%;
-}
-
-div.navheader table td a,
-div.navfooter table td a {
- color: #777;
- text-decoration: none;
-}
-
-/* normal text in the footer */
-div.navfooter table td {
- color: black;
-}
-
-div.navheader table td a:visited,
-div.navfooter table td a:visited {
- color: #444;
-}
-
-
-/* links in header and footer */
-div.navheader table td a:hover,
-div.navfooter table td a:hover {
- text-decoration: underline;
- background-color: transparent;
- color: #33a;
-}
-
-div.navheader hr,
-div.navfooter hr {
- display: none;
-}
-
-
-.qandaset tr.question td p {
- margin: 0em 0em 1em 0em;
- padding: 0em 0em 0em 0em;
-}
-
-.qandaset tr.answer td p {
- margin: 0em 0em 1em 0em;
- padding: 0em 0em 0em 0em;
-}
-.answer td {
- padding-bottom: 1.5em;
-}
-
-.emphasis {
- font-weight: bold;
-}
-
-
- /************* /
- / decorations /
-/ *************/
-
-.titlepage {
-}
-
-.part .title {
-}
-
-.subtitle {
- border: none;
-}
-
-/*
-h1 {
- border: none;
-}
-
-h2 {
- border-top: solid 0.2em;
- border-bottom: solid 0.06em;
-}
-
-h3 {
- border-top: 0em;
- border-bottom: solid 0.06em;
-}
-
-h4 {
- border: 0em;
- border-bottom: solid 0.06em;
-}
-
-h5 {
- border: 0em;
-}
-*/
-
-.programlisting {
- border: solid 1px;
-}
-
-div.figure,
-div.table,
-div.informalfigure,
-div.informaltable,
-div.informalexample,
-div.example {
- border: 1px solid;
-}
-
-
-
-.tip,
-.warning,
-.caution,
-.note {
- border: 1px solid;
-}
-
-.tip table th,
-.warning table th,
-.caution table th,
-.note table th {
- border-bottom: 1px solid;
-}
-
-.question td {
- border-top: 1px solid black;
-}
-
-.answer {
-}
-
-
-b.keycap,
-.keycap {
- border: 1px solid;
-}
-
-
-div.navheader, div.heading{
- border-bottom: 1px solid;
-}
-
-
-div.navfooter, div.footing{
- border-top: 1px solid;
-}
-
- /********* /
- / colors /
-/ *********/
-
-body {
- color: #333;
- background: white;
-}
-
-a {
- background: transparent;
-}
-
-a:hover {
- background-color: #dedede;
-}
-
-
-h1,
-h2,
-h3,
-h4,
-h5,
-h6,
-h7,
-h8 {
- background-color: transparent;
-}
-
-hr {
- border-color: #aaa;
-}
-
-
-.tip, .warning, .caution, .note {
- border-color: #aaa;
-}
-
-
-.tip table th,
-.warning table th,
-.caution table th,
-.note table th {
- border-bottom-color: #aaa;
-}
-
-
-.warning {
- background-color: #fea;
-}
-
-.caution {
- background-color: #fea;
-}
-
-.tip {
- background-color: #eff;
-}
-
-.note {
- background-color: #dfc;
-}
-
-.glossary dl dt,
-.variablelist dl dt,
-.variablelist dl dt span.term {
- color: #044;
-}
-
-div.figure,
-div.table,
-div.example,
-div.informalfigure,
-div.informaltable,
-div.informalexample {
- border-color: #aaa;
-}
-
-pre.programlisting {
- color: black;
- background-color: #fff;
- border-color: #aaa;
- border-width: 2px;
-}
-
-.guimenu,
-.guilabel,
-.guimenuitem {
- background-color: #eee;
-}
-
-
-b.keycap,
-.keycap {
- background-color: #eee;
- border-color: #999;
-}
-
-
-div.navheader {
- border-color: black;
-}
-
-
-div.navfooter {
- border-color: black;
-}
-
-
- /*********** /
- / graphics /
-/ ***********/
-
-/*
-body {
- background-image: url("images/body_bg.jpg");
- background-attachment: fixed;
-}
-
-.navheader,
-.note,
-.tip {
- background-image: url("images/note_bg.jpg");
- background-attachment: fixed;
-}
-
-.warning,
-.caution {
- background-image: url("images/warning_bg.jpg");
- background-attachment: fixed;
-}
-
-.figure,
-.informalfigure,
-.example,
-.informalexample,
-.table,
-.informaltable {
- background-image: url("images/figure_bg.jpg");
- background-attachment: fixed;
-}
-
-*/
-h1,
-h2,
-h3,
-h4,
-h5,
-h6,
-h7{
-}
-
-div.preface .titlepage .title,
-div.colophon .title,
-div.chapter .titlepage .title {
- background-image: url("images/title-bg.png");
- background-position: bottom;
- background-repeat: repeat-x;
-}
-
-div.section div.section .titlepage .title,
-div.sect2 .titlepage .title {
- background: none;
-}
-
-
-h1.title {
- background-color: transparent;
- background-image: url("poky-ref-manual.png");
- background-repeat: no-repeat;
- height: 256px;
- text-indent: -9000px;
- overflow:hidden;
-}
-
-h2.subtitle {
- background-color: transparent;
- text-indent: -9000px;
- overflow:hidden;
- width: 0px;
- display: none;
-}
-
- /*************************************** /
- / pippin.gimp.org specific alterations /
-/ ***************************************/
-
-/*
-div.heading, div.navheader {
- color: #777;
- font-size: 80%;
- padding: 0;
- margin: 0;
- text-align: left;
- position: absolute;
- top: 0px;
- left: 0px;
- width: 100%;
- height: 50px;
- background: url('/gfx/heading_bg.png') transparent;
- background-repeat: repeat-x;
- background-attachment: fixed;
- border: none;
-}
-
-div.heading a {
- color: #444;
-}
-
-div.footing, div.navfooter {
- border: none;
- color: #ddd;
- font-size: 80%;
- text-align:right;
-
- width: 100%;
- padding-top: 10px;
- position: absolute;
- bottom: 0px;
- left: 0px;
-
- background: url('/gfx/footing_bg.png') transparent;
-}
-*/
-
-
-
- /****************** /
- / nasty ie tweaks /
-/ ******************/
-
-/*
-div.heading, div.navheader {
- width:expression(document.body.clientWidth + "px");
-}
-
-div.footing, div.navfooter {
- width:expression(document.body.clientWidth + "px");
- margin-left:expression("-5em");
-}
-body {
- padding:expression("4em 5em 0em 5em");
-}
-*/
-
- /**************************************** /
- / mozilla vendor specific css extensions /
-/ ****************************************/
-/*
-div.navfooter, div.footing{
- -moz-opacity: 0.8em;
-}
-
-div.figure,
-div.table,
-div.informalfigure,
-div.informaltable,
-div.informalexample,
-div.example,
-.tip,
-.warning,
-.caution,
-.note {
- -moz-border-radius: 0.5em;
-}
-
-b.keycap,
-.keycap {
- -moz-border-radius: 0.3em;
-}
-*/
-
-table tr td table tr td {
- display: none;
-}
-
-
-hr {
- display: none;
-}
-
-table {
- border: 0em;
-}
-
- .photo {
- float: right;
- margin-left: 1.5em;
- margin-bottom: 1.5em;
- margin-top: 0em;
- max-width: 17em;
- border: 1px solid gray;
- padding: 3px;
- background: white;
-}
- .seperator {
- padding-top: 2em;
- clear: both;
- }
-
- #validators {
- margin-top: 5em;
- text-align: right;
- color: #777;
- }
- @media print {
- body {
- font-size: 8pt;
- }
- .noprint {
- display: none;
- }
- }
-
-
-.tip,
-.note {
- background: #666666;
- color: #fff;
- padding: 20px;
- margin: 20px;
-}
-
-.tip h3,
-.note h3 {
- padding: 0em;
- margin: 0em;
- font-size: 2em;
- font-weight: bold;
- color: #fff;
-}
-
-.tip a,
-.note a {
- color: #fff;
- text-decoration: underline;
-}