[ECOS] eCos Device Driver reorganization

[Hugo Tyson <hmt at cygnus dot co dot uk>]

Folks, we're about to embark on a bit of a rearrangement of the
eCos device driver tree, including serial devices, ethernet devices
and the wallclock and watchdog.

This will be done in the trunk of eCos development, and so it will
show up in anoncvs soon after it's committed.  We expect that to be
within the next couple of weeks.

The purpose of this message is twofold:

 o To warn folks out there who are porting - including writing
   serial device drivers - against the ongoing anoncvs sources, so
   that you can wait, if you like, and fit with the new scheme
   before you release or contribute your work back to Red Hat.

 o To solicit comments, naturally, in case our plan omits anything
   or fails to accommodate possible future needs.

The purpose of the reorganization is to separate individual device
drivers into proper eCos packages, so that they may be separately
distributed.  For historical reasons and resource pressure, the
overall device structure is currently somewhat ad hoc.  We also
have the OpenBSD network stack going anoncvs real soon now and we
want its ethernet device drivers to have the same useful property.

These changes will *not* rapidly be applied to 1.3.1 or maintenance
releases from there.  Anoncvs only for the immediate future.  We
*do* intend to re-release the OpenBSD network stack in the new
organization; what's out there currently has Beta status only.


The situation currently is that we have
-------------------------------------------------------------------
    net/tcpip
    net/drivers/eth/common
    net/drivers/eth/PLATFORM        # separate packages, good
    
    io/common
    io/pci                          # pci is OK, all from HALs
    
    io/serial/current/src/ARCH/PLATFORM_serial.c
                                    # all one dir, BAD, >14 variants
    
    devs/wallclock/current/include/common_stuff...
    devs/wallclock/current/src/PLATFORMY_STUFF
                                    # all one dir, BAD
    devs/watchdog/current/include/common_stuff...
    devs/watchdog/current/src/PLATFORMY_STUFF
                                     # all one dir, BAD
-------------------------------------------------------------------
Here's how we assign more meaning to the english names of the dirs:

    net: network, common stuff.  Not the drivers.
    io: io, common stuff, not the drivers.
        Including common PCI and serial stuff.
    devs: device drivers (in the crufty bit twiddling sense)

That way, we get to re-organize as follows:
-------------------------------------------------------------------
    net/tcpip                       # the stack
    net/drivers/eth/common/current/ # the eth common part
    net/drivers/HYPOTHETICAL/common/curr...
                                    # PPP, SLIP, econet...

and
    io/common/current/              # all OK
    io/pci/current/                 # pci is OK, all from HALs
    io/serial/current/              # common serial stuff

and
    devs/eth/ARCH/PLATFORM/current/
    devs/serial/ARCH/PLATFORM/current/src/PLATFORM_serial.c
                                    # all separate components, GOOD
    devs/wallclock/....
    devs/watchdog/....
-------------------------------------------------------------------

This is descriptive of the devices we have right now, arch and
platform are separate levels just to make it easier to navigate in
the filesystem and similar to the HAL structure in the filesystem.

It is *not* prescriptive of future work; for example, the mythical
common highly-portable 16550 serial driver which works on many
targets would be called "devs/serial/s16550/current", or a serial
device for a particular board (cogent springs to mind) that can
work with different CPUs fitted is "devs/serial/cogent/current".


Package names will be of the form:

        (these 4 unchanged)
        CYGPKG_IO
        CYGPKG_IO_SERIAL
        CYGPKG_NET
        CYGPKG_NET_ETH_DRIVERS

        (new packages in the devs directory heirarchy)
        (parent is CYGPKG_NET_ETH_DRIVERS for these...)
        CYGPKG_DEVS_ETH_ARM_EDB7XXX     
        CYGPKG_DEVS_ETH_QUICC
        CYGPKG_DEVS_ETH_...

        (parent is CYGPKG_IO_SERIAL for these...)
        CYGPKG_DEVS_SERIAL_ARM_AEB
        CYGPKG_DEVS_SERIAL_ARM_CMA230
        CYGPKG_DEVS_SERIAL_ARM_EDB7XXX
        CYGPKG_DEVS_SERIAL_ARM_PID
        CYGPKG_DEVS_SERIAL_MIPS_TX3904
        CYGPKG_DEVS_SERIAL_MIPS_...
        CYGPKG_DEVS_SERIAL_....

(and so on...)

The definitions of targets will change to include all relevent
drivers, for example, the arm edb7xxx target will include
  packages {  CYGPKG_HAL_ARM
              CYGPKG_HAL_ARM_EDB7XXX
              CYGPKG_DEVS_SERIAL_ARM_EDB7XXX
              CYGPKG_DEVS_ETH_ARM_EDB7XXX      }

The general principle is:

 o A target selection brings in all platform-specific packages -
   this includes all device drivers (net, serial, walldog &c)

 o A template selection brings in all packages required for your
   intended use (or a good place to start, anyway).

This means that all templates which include LIBC must also contain
CYGPKG_IO_SERIAL as well as CYGPKG_HAL CYGPKG_IO CYGPKG_INFRA
CYGPKG_ERROR and so on, but that's fine.  (This is a widespread
change; currently (almost) all *targets* include CYGPKG_IO_SERIAL
to get libc's stdio channels to work).

The problem arises when you have a template which does not include
the common serial IO stuff, CYGPKG_IO_SERIAL and CYGPKG_IO.  The
target selection will bring in serial device drivers, who want a
parent, which naturally is CYGPKG_IO_SERIAL.

Those serial (or net or whatever) device drivers will be orphaned,
which (in current releases of the config tool, though this too is
set to change) leaves them enabled by default.  The solution is
that the individual driver packages will say in their CDL package
definition:

        parent          CYGPKG_IO_SERIAL
        active_if       CYGPKG_IO_SERIAL
        active_if       CYGPKG_HAL_arch_platform
or:
        parent          CYGPKG_NET_ETH_DRIVERS
        active_if       CYGPKG_NET_ETH_DRIVERS
        active_if       CYGPKG_HAL_arch_platform

or whatever depending on driver type; that way the orphaned package
is inactive and harmless.  If this turns out to cause problems with
the config tool, be assured that we'll fix them PDQ.

Comments are welcome, to this list, please, I do read it
frequently.

Yours,
        - Huge