[OSADL-svn-commits] r107 - trunks/fddi-trunk/doc
OSADL repository commits
osadl-svn-commits at lists.osadl.org
Tue Oct 2 11:48:06 CEST 2007
Author: robert
Date: Wed Aug 22 21:00:41 2007
New Revision: 107
Log:
start of documentation, wip
Added:
trunks/fddi-trunk/doc/GNUmakefile.am
trunks/fddi-trunk/doc/OSADL-FieldbusFramework-20070809-1.docbook
Added: trunks/fddi-trunk/doc/GNUmakefile.am
==============================================================================
--- (empty file)
+++ trunks/fddi-trunk/doc/GNUmakefile.am Wed Aug 22 21:00:41 2007
@@ -0,0 +1,29 @@
+DOCBOOKFILES = $(wildcard *.docbook)
+HTMLFILES = $(patsubst %.docbook,%.html,$(DOCBOOKFILES))
+TXTFILES = $(patsubst %.docbook,%.txt,$(DOCBOOKFILES))
+HTMLXSL = /usr/share/xml/docbook/stylesheet/nwalsh/html/docbook.xsl
+XMLTO = xmlto
+
+all: $(HTMLFILES) $(TXTFILES)
+
+%.html: %.docbook
+ # $(XMLTO) -x $(HTMLXSL) html $<
+ # mv $(subst .docbook,.proc,$<) $(subst .docbook,.html,$<)
+ xsltproc --output $(subst .docbook,.html,$<) --stringparam section.autolabel 1 $(HTMLXSL) $<
+ touch *.wml
+
+%.txt: %.html
+ lynx -dump $< > $@
+ #recode utf8..latin1 $@
+
+clean:
+ rm -f $(HTMLFILES) $(TXTFILES) osadl-*.html
+
+osadl-fieldbus-framework.html: OSADL-Fieldbus-Framework-20070809-1.html
+
+EXTRA_DIST = \
+ OSADL-Fieldbus-Framework-20070809-1.docbook
+
+MAINTAINERCLEANFILES = \
+ GNUmakefile.in
+
Added: trunks/fddi-trunk/doc/OSADL-FieldbusFramework-20070809-1.docbook
==============================================================================
--- (empty file)
+++ trunks/fddi-trunk/doc/OSADL-FieldbusFramework-20070809-1.docbook Wed Aug 22 21:00:41 2007
@@ -0,0 +1,376 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+ "http://docbook.org/xml/4.1.2/docbookx.dtd" []>
+
+<article lang="en">
+
+ <articleinfo>
+
+ <authorgroup>
+ <author><firstname>Robert</firstname><surname>Schwebel</surname></author>
+ <!-- <collab><collabname>Fridolin Tux</collabname></collab> -->
+ </authorgroup>
+
+ <title>
+ OSADL Fieldbus Framework
+ </title>
+
+ <revhistory>
+ <revision>
+ <revnumber>0.1</revnumber>
+ <date>2007-08-09</date>
+ <revremark>Draft</revremark>
+ </revision>
+ </revhistory>
+
+ </articleinfo>
+
+
+
+<!-- ==================================================================== -->
+<sect1 id="rationale"><title>Rationale</title>
+<!-- ==================================================================== -->
+
+ <para> Industrial I/O components are the central interface between today's
+ automation systems and our physical environment. As Linux is becoming
+ more and more the first-class choice for embedded controllers, measurement
+ devices, soft PLCs and other control equipment throughout the industry,
+ there is still no commonly accepted way to connect I/O devices to a POSIX
+ operating system. </para>
+
+ <para> Although modern embedded controllers use more and more
+ decentralized infrastructure and although there is a huge variety of
+ fieldbus topologies available today, we are still far away from the
+ situation we have in the IT business: today's server infrastructure
+ is completely based on open standards. It simply does not matter if
+ you buy a network card from vendor A or vendor B: nobody would ever
+ try to start changing lowlevel hardware access code inside of the
+ apache web server just in case of a hardware change. But that's exactly
+ how industral I/O works today. There is no generally accepted interface
+ for accessing fieldbusses and local I/O on the market. </para>
+
+ <para> OSADL, being an organization who's members are machine building
+ companies, software specialists and embedded Linux experts, has the
+ declared aim to join market forces in order to make such a unified
+ framework possible. This document outlines the ideas and concepts behind
+ the OSADL Fieldbus Framework. </para>
+
+</sect1>
+
+<!-- ==================================================================== -->
+<sect1 id="bsp-definition"><title>BSP Definition</title>
+<!-- ==================================================================== -->
+
+ <para> 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. </para>
+
+ <para> These modifications are being done by BSP Providers. Necessary
+ modifications include </para>
+
+ <itemizedlist>
+
+ <listitem><para> 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. </para></listitem>
+
+ <listitem><para> Kernel Architecture Modifications, necessary to
+ enable features not present in the current in-kernel code for the
+ used architecture (x86, ARM, PowerPC, MIPS, ...). </para></listitem>
+
+ <listitem><para> 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. </para></listitem>
+
+ </itemizedlist>
+
+ <para> 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. </para>
+
+ <para> This results in the following patch flow: </para>
+
+ <literallayout>
+ - kernel.org ---> BSP Provider ---> Board Vendor ---> End Customer
+ BSP BSP
+ </literallayout>
+
+ <para> OSADL explicitly encourages BSP providers and board vendors to
+ submit their patches upstream; note that the high quality of the Linux
+ kernel is mainly a result of the peer review mechanism which cannot
+ take place if the patches are not submitted upstream. </para>
+
+ <para> Details instructions how to provide a patch for upstream can be
+ found in Documentation/SubmittingPatches in the Linux kernel. </para>
+
+</sect1>
+
+<!-- ==================================================================== -->
+<sect1 id="kernel-modifications"><title>Kernel Modifications Rules</title>
+<!-- ==================================================================== -->
+
+ <para> Each BSP must consist of a patch or a patch series against a
+ vanilla kernel version. The version of the vanilla kernel the BSP is
+ based on has to be specified explicitly. </para>
+
+ <para> 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 provicer does not offer his patches in the
+ canonical patch format by default, he has to provide a description
+ how to convert his patch format into canonical patches. </para>
+
+ <para> 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. One-big-patch is not allowed to be the only form of
+ delivery of a kernel patch in a BSP. </para>
+
+ <para> Patches are never allowed to delete parts of the tree,
+ especially not other architectures. Files already existing in the
+ vanilla kernel tree are not allowed to be replaced by a file with the
+ same name but other contention. </para>
+
+ <para> If there is more than one patch 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.
+ </para>
+
+ <para> 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.
+ </para>
+
+ <para> 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 adding a hint to the original source to the patch
+ documentation. </para>
+
+ <para> Patches should not destroy other architectures or sub
+ archtectures. The Linux kernel offers a clear abstraction of generic
+ vs. platform vs. BSP code, which has to be used. </para>
+
+ <para> In rare cases there may be a need to break other platform code
+ due to project reasons; patches which do so have to be explicitly
+ marked as "uggly hack". </para>
+
+</sect1>
+
+<!-- ==================================================================== -->
+<sect1 id="conformance-levels"><title>Levels of Conformance</title>
+<!-- ==================================================================== -->
+
+ <para> Patches do conform to one of the following OSADL Boardsupport
+ Conformance Specification Levels (OBSPS-Patch-Level). Usually not the
+ whole BSP will conform to the same level, so the OSADL Testlab
+ documents the conformance to the levels on a per-patch base. The BSP
+ provider has to specify for each patch the proposed OBSPS-Patch-Level.
+ </para>
+
+ <para> The OSADL Testlab BSP Spec Certificate documents a statistics
+ of the patches of a BSP and their according OBCS level. </para>
+
+ <sect2><title>OBSPS-Patch-Level-0</title>
+
+ <para> 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. </para>
+
+ </sect2>
+
+ <sect2><title>OBSPS-Patch-Level-1</title>
+
+ <para> The BSP only adds board specific code components and usually
+ does not touch generic files. The only case where generic files are
+ being touched is to provide generic patches for bugs or extensions.
+ </para>
+
+ </sect2>
+
+ <sect2><title>OBSPS-Patch-Level-2</title>
+
+ <para> 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. </para>
+
+ </sect2>
+
+ <sect2><title>OBSPS-Patch-Level-3</title>
+
+ <para> 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. </para>
+
+ </sect2>
+
+</sect1>
+
+<!-- ==================================================================== -->
+<sect1 id="toolchains"><title>Toolchains</title>
+<!-- ==================================================================== -->
+
+ <para> One important part of a BSP is the toolchain used to compile
+ the kernel, which usually is also provided by the BSP provider.
+ </para>
+
+ <para> There are two levels of toolchain conformance, specified as
+ OBSPS-Toochain-Levels: </para>
+
+ <para> 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. </para>
+
+ <para> Toolchains may run on other platforms than Linux; however, in
+ order to get the OSADL BSP Certificate there needs to be at least a
+ version of the toolchain which is able to run on standard x86 Linux.
+ </para>
+
+ <sect2><title>OBSPS-Toolchain-Level 0</title>
+
+ <para> The BSP Provider offers a binary toolchain packet. </para>
+
+ </sect2>
+
+ <sect2><title>OBSPS-Toolchain-Level 1</title>
+
+ <para> 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), this also
+ does conform to this level. </para>
+
+ </sect2>
+
+</sect1>
+
+<!-- ==================================================================== -->
+<sect1 id="offtree-drivers"><title>Off Tree Drivers</title>
+<!-- ==================================================================== -->
+
+ <para> Drivers not intended for upstream may be written using the
+ kernel standard mechanism for off-tree drivers. </para>
+
+ <para> Off-tree drivers need a mechanism to find out where the
+ according kernel sources can be found. </para>
+
+ <para> They must include information about which kernel version the
+ driver was last tested against. </para>
+
+ <para> The off-tree driver has to compile with -Wall without warnings.
+ </para>
+
+</sect1>
+
+<!-- ==================================================================== -->
+<appendix label="A"><title>Glossary and Abbreviations</title>
+<!-- ==================================================================== -->
+
+<glosslist>
+
+ <glossentry>
+ <glossterm>Vanilla Kernel</glossterm>
+ <glossdef>
+
+ <para> 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 whidespread version and the base for
+ all kernel development activities. The vanilla kernel can be
+ downloaded from <ulink
+ url="http://www.kernel.org/">http://www.kernel.org/</ulink>.
+ </para>
+
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Upstream</glossterm>
+ <glossdef>
+
+ <para> 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. Often
+ it is an aim of local devleopment to push the modifications to the
+ "upstream" maintainer, to have them integrated in future versions
+ of the official code. </para>
+
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Patch</glossterm>
+ <glossdef>
+
+ <para></para>
+
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Diff</glossterm>
+ <glossdef>
+
+ <para></para>
+
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>BSP</glossterm>
+ <glossdef>
+
+ <para></para>
+
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>BSP Provider</glossterm>
+ <glossdef>
+
+ <para></para>
+
+ </glossdef>
+ </glossentry>
+
+</glosslist>
+
+</appendix>
+
+<!-- ==================================================================== -->
+
+<appendix label="B"><title>Authors</title>
+
+<para>
+ <literallayout>
+Robert Schwebel
+Pengutronix
+Hannoversche Straße 2
+31134 Hildesheim
+Tel. +49-5121-206917-0
+Fax: +49-5121-206917-9
+e-Mail: r.schwebel at pengutronix.de
+URI: http://www.pengutronix.de
+ </literallayout>
+</para>
+
+</appendix>
+
+</article>
More information about the OSADL-svn-commits
mailing list