| Revision History | |
|---|---|
| Revision 20080522-1 | 2008-05-22 |
| functionality clarification added. | |
| Revision 20080302-1 | 2008-03-02 |
| Marked files with the filename tag. Added more glossary terms. Out-of-tree nomenclature fixed. | |
| Revision 0.2 | 2007-06-16 |
| Major rewriting including comments from the mailing list discussion | |
| Revision 0.1 | 2006-07-04 |
| Draft | |
Table of Contents
Board Support Packages (BSPs) provide a base for Embedded Linux projects. They adapt the generic Linux kernel (http://www.kernel.org) to the vendor specific hardware platform, implementing the board-specific initializations and configurations required to run Linux on that platform.
Linux's Open Source nature allows industrial end users to adapt the kernel to their specific project needs; this work may either be done by the end user or by an Embedded Linux support or consulting company. The goal of this specification is to provide quality criteria of a BSP, closely adapting best practice rules from the kernel community. Following these rules makes it possible for different parties to interchangeably work on a particular BSP during the product life cycle.
As most BSP providers have invented their own patch handling mechanisms, it is not the aim of this specification to force them into another mechanism. As some of the mechanisms offer advantages over others, this specification defines several levels of conformance, making it easier for industrial end users to decide about a BSP. The OSADL Test Lab offers a BSP certification service and rates the BSPs into one of the categories specified below.
The Vanilla Kernel does not offer support for all kinds of industrial mainboards or modules by default. There are different hardware form factors available today, ranging from x86 mainboards, following standard PC layouts, down to deeply embedded systems based on non-x86 System-on-Chip CPUs. For non-standard platforms there is usually the need to extend the Vanilla Linux Kernel to support the specific vendor hardware, in order to enable the hardware to fulfill the specific needs of an industrial project.
These modifications are being done by BSP providers. Necessary modifications include
Driver Development. Industrial projects usually have several hardware components not supported by standard Linux drivers, so these components have to be developed. Drivers consist of the driver code itself and the integration of the device in the Driver Model.
Kernel Architecture Modifications, necessary to enable features not present in the current in-kernel code for the used architecture (x86, ARM, PowerPC, MIPS, ...).
Kernel Infrastructure Modifications. In some rare cases it is necessary to modify generic kernel code, for example if an architecture has features not supported by standard abstractions of the generic code.
The BSP provider hands over the BSP, consisting of a vanilla kernel plus necessary modifications, to the end customer. The standard method to transfer modifications is a patch in the unified diff format.
This results in the following patch flow:
- kernel.org ---> BSP Provider ---> Board Vendor ---> End Customer
BSP BSP
OSADL explicitly encourages BSP providers and board vendors to submit their patches upstream; the high quality of the Linux kernel is mainly the result of the peer review mechanism which cannot take place if the patches are not submitted upstream.
Details instructions how to provide a patch for upstream can be
found in Documentation/SubmittingPatches in the
Linux kernel.
The following general rules apply to all conformance levels except "OBSPS Patch Level 0" (see below).
Each BSP must consist of a patch or a patch series against a final vanilla kernel version. A "final" release version is either the original release (such as 2.6.21) or a follow-up release (such as 2.6.21.3). The version of the vanilla kernel the BSP is based on has to be specified explicitly. If the kernel has to be prepatched with one of the other officially released kernel patches, such as Andrew Morton's (-mm) or Ingo Molnar's (-rt) patch, these patches must be part of the BSP supplied patch stack.
It is up to the BSP provider to hand out standard patches or a custom mechanism which wraps standard patches with additional information. In any case, it must be easily possible to extract a patch in the "canonical patch format" as being defined by the kernel documentation. If the BSP provider does not offer the patches in the canonical patch format by default, a description must be provided how to convert the patches into the canonical patch format.
Patches have to be separated "by topic". That means that one patch has to address one issue at a time and must be documented in a way that makes it clear what issue the patch is addressing. The canonical patch format should be used to make it easier to merge patches upstream. The patches of a BSP may not be merged into a single all-in-one patch as the only patch format.
Patches are never allowed to delete parts of the kernel tree simply because these parts are not needed for a particular hardware, especially not components of other architectures. Files already existing in the vanilla kernel tree are not allowed to be replaced by a file with the same name but a completely different content or functionality.
If there are two or more patches, it must be clearly defined in which order the patches have to be applied. This may be done by providing a quilt patch series, or any other adequate mechanism.
Patches must have a documented originator. In order to follow the standard rule for merging patches upstream, all patches should have a "Signed-off-by:" line, following the canonical patch format.
If patches by third parties are being included by a BSP, the originator has to be specified, usually by adding a "Signed-off-by:" line and by providing a hint to the original source in the patch documentation.
Patches should not prevent elements of other architectures or sub architectures from being built. The Linux kernel offers a clear abstraction mechanism of generic vs. platform vs. BSP code that has to be used.
In rare cases, it may be needed to break other platform code due to project reasons; patches which do so have to be explicitly marked as "not for upstream", followed by a detailed documentation.
Patches do conform to one of the following OSADL Board Support Package Conformance Specification Levels (OBSPS Patch Level). Usually, not the entire BSP will conform to the same level; thus, the OSADL Test Lab documents the conformance level on a per-patch basis. The BSP provider has to specify the proposed OBSPS Patch Level of every patch.
Assignment and publication of a particular OBSPS level require that all defined and tested board features pass an obvious function test such as ICMP echo replies of an Ethernet network controller or a copy procedure to and from a storage device. If any of these tests fail, the OBSPS level is void. However, these function tests are by no means intended as an exhaustive test of the entire board functionality and are, in particular, not certified.
The BSP does boot on the target architecture but doesn't follow any particular rule of this specification. The patches are neither intended for upstream, nor do they follow the quality standards of this specification. This is the default conformance level of every BSP, even if it did not undergo the OSADL test procedure.
The BSP only adds board specific code components and usually
does not touch generic files, like source files in the
kernel/, lib/ or
mm/ directory. The only case where generic files
are being touched is to provide generic patches for bugs or
extensions.
In addition to the level 1 requirements, the patches follow the kernel patch rules and the coding style. The BSP can be compiled with sparse check without warnings. The patches may or may not be reviewed by upstream parties.
In addition to the level 2 requirements, the patches are continuously integrated with the mainline kernel (at least once per week). The continuous integration has to be documented by automatic protocols which show that the patches do apply to the upstream GIT trees; breakages have to be fixed as they do appear. Patches are actively code reviewed by the Linux community with regard to quality, realtime or security issues.
The documented functionality of all components of the hardware platform is supported by a particular version and revision (or higher) of a released mainline kernel.
In cases where the documented functionality cannot be completely deployed without additional components which are not available as Open Source software (example: proprietary kernel driver for advanced graphic boards or communication protocols), this must be clearly marked with a "T" (tainted), such as "OBSPS Patch Level 0T".
One important characteristic of a BSP is the toolchain used to compile the kernel, which may also be provided by the BSP provider.
It always has to be specified on which host platform the toolchain is able to run. This information is also part of the documentation of the OSADL certification process.
Toolchains may run on platforms other than Linux; however, the OSADL BSP Certificate requires that there is at least one version of the toolchain that can be run on a standard x86 Linux system.
There are two levels of toolchain conformance, specified as OBSPS Toolchain Levels:
The BSP provider offers a script to build the toolchain from the original sources plus necessary patches; the script must enable the end user to re-build the toolchain from the original sources. If it is possible to build the BSP with a standard toolchain supplied by one of the major distributions (SuSE, RedHat, Debian etc.), this also does conform to this level.
Drivers not intended for upstream may be written using the kernel standard mechanism for out-of-tree drivers.
Out-of-tree drivers need a mechanism to find out where the according kernel sources can be found.
They must include information about which kernel version the driver was last tested against.
The out-of-tree driver has to compile with -Wall without warnings.
A. Glossary and Abbreviations
- Vanilla Kernel
The generally accepted main version of the Linux kernel is being maintained by Linus Torvalds. It is the base for all distributions, is the most widespread version and the base for all kernel development activities. The vanilla kernel can be downloaded from http://www.kernel.org/.
- Upstream
Open Source projects make it possible that everyone modifies the code, but there usually is an official version of the code, being released by the project maintainer. The maintainer is responsible for the project and releases official versions. Normally, it is the aim of a local development to push the modifications to the so called "upstream" maintainer, to have them integrated in future versions of the official code.
- Patch
A patch contains the instructions what to do to get a file from revision 1 into revision 2. Its intended for automatic modification of source files. In the Open Source world patches are used to fix or extend source packages. To be accepted by the project maintainers, a patch must meet specific criteria. These criteria may vary from project to project.
- Diff
A diff describes the changes in a file. It can be useful to discover what is changed. Most of the time diff and patch are used for the same kind of file.
- BSP
BSP is the abbreviation for Board Support Package. This description means a set of files to support a specific hardware and its features. A BSP should free an enduser from doing any kind of software adaption by its own. It should improve enduser's development cycle and speed. There is no fixed form for the BSP, its content and its delivery.
- BSP Provider
Provides the enduser with a Board Support Package for a specific hardware. Most of the time the hardware manufacturer is also the BSP provider.
- Tainted
If any kind of code not covered by the GPL is part of the Linux kernel this kernel is called "tainted". Tainting for example happens when some propritary kernel module is inserted.
