| Revision History | |
|---|---|
| Revision 0.3 | 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 on 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 that 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 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 on 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 subarchitectures 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 necessary 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 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.
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 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 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.
The host platform on which the toolchain is able to run must always be specified. 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 at least on version of the toolchain 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.), conformance with this level is also met.
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 the kernel version against which the driver was last tested.
The out-of-tree driver has to compile with -Wall without warnings.
A. Glossary and Abbreviations
- Vanilla Kernel
This is the "official" mainline version of the Linux kernel maintained by Linus Torvalds. It is the base for all distributions and for all kernel development activities. The vanilla kernel can be downloaded from http://www.kernel.org/.
- Upstream
Open Source projects make it possible for everyone to modify the code, but there usually is an official version of the code which is 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 for them to be integrated in future versions of the official code.
- Patch
A patch contains the instructions to convert a file from one revision to another. It is intended for automatic modification of source files and normally used to fix or extend a collection of source files. To be accepted by the project maintainers, a patch must meet specific criteria. These criteria may vary from project to project.
- Diff
The terms "diff" and "patch" are used synonymously.
- BSP
BSP is the abbreviation for Board Support Package. A BSP contains a set of files to support a specific hardware such as a computer board. Optimally, a BSP covers the entire functionality of a given hardware through drivers and similar system components. In consequence, the enduser can access this functionality completely from user level using system calls. There is no defined form for the BSP, its content and its mode of delivery.
- BSP Provider
Provides the enduser with a Board Support Package for a specific hardware. Normally, the hardware manufacturer is also the BSP provider.
- Tainted
If any kind of system code such as a device driver that is not covered by the GPL is inserted into a running Linux kernel, then this kernel is called "tainted".
