[ag-automation] [RFC] OSADL Board Support Package Specification, Revision 0.1

[Robert Schwebel]

Wolfgang, 

thanks for your comments.

On Wed, Sep 13, 2006 at 01:42:01PM +0200, Wolfgang Denk wrote:
> * BSP Definition:
> 
>   IMHO the most obvious reason for creating a BSP does not get
>   mentioned: implementing all the  board-specific initializations and
>   configurations to get Linux running on a specific hardware.

Agreed, I've added that to the first paragraph.
 
>   I tend to disagree with your statement that it "is usually the need
>   to extend the Vanilla Linux Kernel"; this is not our experience. In
>   most cases just hardware-specific configuration to the kernel is
>   needed. Extensions only come in to play as far as driver support is
>   required.

"configurations" sounds more like changing things in .config. Board
Support Packages usually do more than that, especially on non-PCI
platforms. For example on most ARM cpus you have chip specific hardware,
module specific hardware and often also baseboard specific hardware.
Usually a BSP for that kind of boards has something like
arch/arm/mach-pxa/mymodule.c and mymodule-somebaseboard.c, containing
driver model registration and specific stuff for these ressources. 

>   Also I think it would be a good idea to clearly differentiate
>   between the requirements we want to impose to enable easy maitenance
>   of a BSP and the requirements that arise from the GPL: normally, the
>   end user expects a ready-to-use source tree, and this is IMHO what
>   is required by the GPL. The fact that we (additionally) require
>   patches against a clearly identifyable version of a standard kernel
>   tree is a different, new thing.

Which is definitely something I want to have in the spec.

Although it is common and convenient to give a complete source tree to a
customer, it is IMHO much more important that the BSP is structured in a
reviewable and manageble way and that the patch flow is clear,
documented and reproducable. 

I've seen so many BSPs out there where vendors have added tons of
undefined patches without any documentation (not even if a specific
patch is required for that customer's platform, or if it is just there
to make the vendor's life easier), where in the end several parties have
changed things in a random way that it should be the aim of this
specification to make sure that

	* the BSP user knows the well-known-kernel version it depends on
	* patch stacks can be applied and de-applied in a clean way.

It is also a common thing, especially done by the big vendors, to make
kernels which contain something like 400 patches all over the place; if
you give that kind of kernel to your Linux-guru-of-trust and tell him to
maintain it and port it up to 2.6.18 you are _lost_, because the first
couple of weeks you are busy with thowing out all kind of stuff not
necessary for your platform.

I don't want to make multi megabyte patch distros impossible; the
OBSPS-Patch-Levels (or however we name them) are just a hint to the end
user how maintainable a BSP is.

> * Kernel Modifications Rules
> 
>   A better definition of "vanilla  kernel  version"  is  needed.  For
>   example,  it  is  not  clear  if  "2.6.18-rc6-gbd314d97"  is such a
>   "vanilla" version, or  if  I  have  to  use  "2.6.18-rc6"  or  even
>   "2.6.17" instead.

Do you have a suggestion? IMHO any of the "well known kernel trees"
could make it, which is anything which is archived on kernel.org in a
structured way (2.6.17, 2.6.18-rc6, ...).

>   "Patches are never allowed to delete parts of the tree" - please
>   delete this. When I find I can refactor identical code used by
>   several BSP I maintain into common code I should of course be able
>   to get rid of the resulting dead files.

That's not the point here. We have seen BSPs for example for ARM where
the vendor has deleted all other arch/{powerpc,mips,...} directories and
everything else he thought nobody would need; this makes it pretty
impossible to diff the BSP against original versions and find out the
changes.

Any suggestion how we could phrase this in a way it becomes more clear?

>   "Files already existing in the vanilla kernel tree are not allowed
>   to be replaced by a file with the same name but other contention." -
>   please delte this. This is exactly what a patch does: changing the
>   content of existing files.

You modify a file, but you don't replace for example
drivers/net/some_driver.c by a file called some_driver.c which is
something completely new (for example another driver for the same
device, written by other authors and being completely different).

>   " Patches should not destroy other architectures or sub
>   archtectures." - please delete this; it is redundant to the
>   statement " Patches are never allowed to delete parts of the tree,
>   especially not other architectures." above.

It is meant differently. The paragraph above talks about removing for
example arch/powerpc in an ARM BSP.

For example, I've recently seen a BSP by a big chip vendor which
introduced a new CPU core, and because they had problems with the caches
they had added hand crufted assembler instructions for that CPU,
flushing the cache, to several random places in mm/, which is generic
code. In result that kernel could not even be configured for x86 any
more, although the kernel has all the abstractions. This method is ok
for doing a quick hack, but if a BSP product is a quick hack it should
be labled as such.

>   "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"." - I think we should not explicitely allow
>   for such exceptions. Also, "ugly  hack"  comments  is  IMHO  not  a
>   standard  way  to  mark  such  code,  at least I am not aware of it
>   generally being accepted and/or documented for kernel code.

In reality such BSPs are out there, and the spec will give the customer
a classification scheme for quality. You are right that "uggly hack" is
not seriously business compatible, so please suggest another
declaration.

> * Levels of Conformance
> 
>   I have to admit that I cannot make heads nor tails of this. I would
>   expoect  that  the  listed  4  confoirmance  levels  are   somewhat
>   hierarchical, so that for example improvements to the code could be
>   added to reach better conformance levels - however, I find that the
>   descriptions for the 4 levels are pretty unrelated.
> 
>   Also, I disagree with the "does not touch generic files"
>   requirement. For any BSP it is a standard thing to touch generic
>   files, for example you will probably always want to patch
>   arch/*/Kconfig to add a configuration option for your new board.

There may be a need to find better phrases for the levels. By the way,
we should probably rename them to something like OBSPS-Level-N.

Your example is not what I would consider to be "generic files". If you
add a new option for a $arch board, it is surely the right way to add it
to arch/$arch/Kconfig. Generic files means "generic code" here, for
example if you want to change some memory management stuff which is ARM
related, fix it in arch/arm/mm, not in mm. If you add something which is
PXA related, put it in arch/arm/mach-pxa, not somewhere else.

Any case which modifies generic (architecture, board, module inspecific)
files has to do with infrastructure improvement. We should clarify that
somehow, I agree.

I do not agree that the levels are not hierarchic. 

- IMHO the lowest level of sophistication is a BSP that "just boots" and
  doesn't follow any of the usual kernel developers' best practise.

- OBSPS-Patch-Level-1 does only follows the idea of fixing and adding
  stuff in the right places, nothing else.

- OBSPS-Patch-Level-2 adds following the coding style and taking care of
  compiler warnings and survives static code analysis.

- Level 3 adds long term maintenance & community review.

These levels surely document the priorities of the people having
participated in the meeting where we discussed this document; if you
have ideas for other classifications please go ahead and let's discuss
them here.

> * Toolchains
> 
>   "One important part of a BSP is the toolchain used to compile the
>   kernel" - I disagree. The toolchain has *nothing* to to with a BSP.
>   These should be completely orthogonal, and I would like to see an
>   explixcit requirement, that any BSP that reaches any OSADL
>   conformance level does *not* depend on any specific tool chain. On
>   controary, it should be required that any known-to-be-working
>   toolchain for this architecture and kernel version can be used.
> 
>   I suggest to remove the toolchain section from the BSP document.

I disagree with your disagreement :-)

Several points why toolchain specification is important:

- The days where there is only something like "arm-linux-gcc" are long
  over. Today we have to fight with things like hard float with FPA vs.
  IWMMXt vs. Maverick Crunch, soft float with FPA vs. VFP etc, or ARM
  OABI vs. EABI, Linuxthreads vs. NPTL, uClibc vs. glibc. Not all of
  them are kernel related, but usually one works with one specific
  toolchain for kernel and userland tasks.

- We have seen more than once that a toolchain which was proven to work
  really good for quite some time ICEd while compiling some random new
  userspace packet which we had not ported before, or userspace tools
  like Qtopia having it's own idea of floating point handling, or Java
  VMs having another idea of emitted float code than the kernel etc.

- My very personal opinion is that a vendor should supply the scripts
  used to build the toolchain, so if something goes wrong one has the
  chance to file a bugzilla entry for upstream projects. But that's
  surely a matter of what you want to achieve.

- Newer kernels have other toolchain requirements, note things like gcc3
  vs. gcc4 etc.

- Current toolchains tend to be much more specific than they have been
  in the past. Although we have long lived with an
  arm-softloat-linux-gnu toolchain, emitting soft-vfp and ARMv4 code, we
  today have to take care of things like little vs. big endian, ARMv4,
  ARMv5, ARMv6, thumb and not etc.

- It is most often the case that, for non-x86, the officially released
  toolchains (i.e. gcc-4.1.1 or gcc-3.4.5) don't even work on an
  archtecture (for example gcc-4.1.1+glibc-2.4+ports is broken for NPTL).
  So usually vendors don't use the toolchains without further patching.

I don't doubt that usually vendors give their customers a toolchain that
"just works" in compiling the kernel. IMHO the spec should make sure
that, if the vendor supplies a toolchain, the OSADL BSP Spec conformance
process either declares it to be "binary-and-we-don't-know-what-it-is"
or "this follows a well documented process". 

Anyway, suggestions for better wording are always welcome.

Robert
-- 
 Dipl.-Ing. Robert Schwebel | http://www.pengutronix.de
 Pengutronix - Linux Solutions for Science and Industry
   Handelsregister:  Amtsgericht Hildesheim, HRA 2686
     Hannoversche Str. 2, 31134 Hildesheim, Germany
   Phone: +49-5121-206917-0 |  Fax: +49-5121-206917-9