[ECOS] eCos Device Driver reorganization

[ECOS] eCos Device Driver reorganization

[Hugo Tyson]

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

Re: [ECOS] eCos Device Driver reorganization

[Jesper Skov]

To followup on Hugo's mail with some specific details for the
watchdog/wallclock drivers:

>The situation currently is that we have
>-------------------------------------------------------------------
>    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)

So we clearly need a reorg. I have a suggestion below, but I'm a bit
in two minds over where to put the common stuff and emulated devices.

Problem being that neither wallclock or watchdog really do any IO (so
putting them in the io/ hierarchy seems wrong). On the other hand, for
consistency's sake, I think the common parts and APIs belong in the
io/ hierarchy and the drivers (real and emulated) in the devs/
hierarchy. 

So:
-------------------------------------------------------------------
    io/wallclock/current/...
    io/watchdog/current/...
                          # Public APIs, common code, and tests.

    devs/wallclock/emulated/src/wallclock.cxx
    devs/wallclock/ARCH/PLATFORM/current/src/PLATFORM_wallclock.cxx
    devs/watchdog/emulated/src/watchdig.cxx
    devs/watchdog/ARCH/PLATFORM/current/src/PLATFORM_watchdog.cxx
                           # all separate components, GOOD
-------------------------------------------------------------------


The conversion of these drivers should also happen within a couple of
weeks.

Jesper

Re: [ECOS] eCos Device Driver reorganization

[Bart Veer]

>>>>> "Jesper" == Jesper Skov <jskov@redhat.com> writes:

    Jesper> To followup on Hugo's mail with some specific details for the
    Jesper> watchdog/wallclock drivers:

    >> The situation currently is that we have
    >> -------------------------------------------------------------------
    >> 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)

    Jesper> So we clearly need a reorg. I have a suggestion below, but
    Jesper> I'm a bit in two minds over where to put the common stuff
    Jesper> and emulated devices.

    Jesper> Problem being that neither wallclock or watchdog really do
    Jesper> any IO (so putting them in the io/ hierarchy seems wrong).
    Jesper> On the other hand, for consistency's sake, I think the
    Jesper> common parts and APIs belong in the io/ hierarchy and the
    Jesper> drivers (real and emulated) in the devs/ hierarchy.

    Jesper> So:
    Jesper> -------------------------------------------------------------------
    Jesper>     io/wallclock/current/...
    Jesper>     io/watchdog/current/...
    Jesper>                           # Public APIs, common code, and tests.

    Jesper>     devs/wallclock/emulated/src/wallclock.cxx
    Jesper>     devs/wallclock/ARCH/PLATFORM/current/src/PLATFORM_wallclock.cxx
    Jesper>     devs/watchdog/emulated/src/watchdig.cxx
    Jesper>     devs/watchdog/ARCH/PLATFORM/current/src/PLATFORM_watchdog.cxx
    Jesper>                            # all separate components, GOOD
    Jesper> -------------------------------------------------------------------

    Jesper> The conversion of these drivers should also happen within
    Jesper> a couple of weeks.

One issue here: I am not quite sure why you want to put the emulation
code into a separate package. A common device package can serve some
or all of the following purposes:

1) define the interface provided by the various implementations, i.e.
   export a header file. This means a hardware-specific device package
   need not export any header files (although it can still do so in
   order to provide additional information). Having a per-class header
   file like this should simplify application and test case
   development.

2) provide test cases which should be passed by all implementations.
   Again hardware-specific packages may add additional test cases.

3) provide support code, e.g. buffer management, tty support for
   serial lines, ... Some classes of device will not have any such
   code.

4) provide a default implementation, typically a software emulation.
   This only makes sense for some devices, not all. It is hard to
   provide a default implementation for an ethernet interface, but a
   wallclock or watchdog can be emulated.

I do not think putting the emulation code into a separate package
actually gains you anything. Even if the target board provides a
suitable device, application developers may still decide that the eCos
device driver should not use it: the application may have its own uses
for the device. The emulated version could still be useful in such
circumstances. Hence the target specification in ecos.db would still
want to load both the common package and the emulation, you might as
well stick them into the same package.

Bart

Re: [ECOS] eCos Device Driver reorganization

[Hugo 'NOx' Tyson]

Hugo Tyson <hmt@cygnus.co.uk> (I, myself, me) writes:
> 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.

And it's all true.  Apart from this bit, where I lied: 

> Package names will be of the form:

>         (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...)

We were always going to keep the _internal_ options with their "old" names
for compatibility, (these sorts of options:
	CYGDAT_IO_SERIAL_ARM_EBSA285_SERIAL_NAME "/dev/ser1"
	CYGNUM_IO_SERIAL_ARM_EBSA285_SERIAL_BAUD 38400
	CYGNUM_IO_SERIAL_ARM_EBSA285_SERIAL_BUFSIZE 128
are unchanged) but it turns out to be a PITA to change the top-level
package names.  So these will retain their old name, but they will be
separate packages rather than mere components.

         (parent is CYGPKG_IO_SERIAL for these...)
         CYGPKG_IO_SERIAL_ARM_AEB
         CYGPKG_IO_SERIAL_ARM_CMA230
         CYGPKG_IO_SERIAL_ARM_EDB7XXX
         CYGPKG_IO_SERIAL_ARM_PID
         CYGPKG_IO_SERIAL_MIPS_TX3904
         CYGPKG_IO_SERIAL_MIPS_...
         CYGPKG_IO_SERIAL_....

They will still live within the IO_SERIAL heirarchy in configtool world,
but sources will be in packages/devs/serial/arm/ebsa285 as described in my
earlier message.

Thanks for your time,

	- Huge

-- 
The 20th Century brought unprecedented increases in worldwide numeracy and
literacy and incredible advances in technology, science and mathematics.
It was also the only century in the past or in any reasonable predictable
future apparently to contain only 99 years.

Re: [ECOS] eCos Device Driver reorganization

[Jesper Skov]

>>>>> "Bart" == Bart Veer <bartv@redhat.com> writes:

Bart> One issue here: I am not quite sure why you want to put the
Bart> emulation code into a separate package. A common device package
Bart> can serve some or all of the following purposes:

Bart> 1) define the interface provided by the various implementations,
Bart> i.e.  export a header file. This means a hardware-specific
Bart> device package need not export any header files (although it can
Bart> still do so in order to provide additional information). Having
Bart> a per-class header file like this should simplify application
Bart> and test case development.

Bart> 2) provide test cases which should be passed by all
Bart> implementations.  Again hardware-specific packages may add
Bart> additional test cases.

Bart> 3) provide support code, e.g. buffer management, tty support for
Bart> serial lines, ... Some classes of device will not have any such
Bart> code.

Bart> 4) provide a default implementation, typically a software
Bart> emulation.  This only makes sense for some devices, not all. It
Bart> is hard to provide a default implementation for an ethernet
Bart> interface, but a wallclock or watchdog can be emulated.

Anyone looking at the next CVS snapshot will see that I'm (as always!)
a good little boy and adopted the layout suggested by Bart :0)

The wallclock has been moved. Watchdog still has to be done (next
week, hopefully).

Jesper

Re: [ECOS] eCos Device Driver reorganization

[Hugo 'NOx' Tyson]

Hugo Tyson <hmt@cygnus.co.uk> (me, that is) writes:
> 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 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.

That work is now largely complete and committed in our internal eCos
development trunk.  We weren't forced to deviate from the plan other than
as described in my 2nd message, so it'll be much as described.

It will be visible externally when next the anoncvs tree is updated.

	- Huge

-- 
The 20th Century brought unprecedented increases in worldwide numeracy and
literacy and incredible advances in technology, science and mathematics.
It was also the only century in the past or in any reasonable predictable
future apparently to contain only 99 years.

Re: [ECOS] eCos Device Driver reorganization

[Hugo 'NOx' Tyson]

Hugo Tyson <hmt@cygnus.co.uk> (I, myself, me) writes:
> 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.

And it's all true.  Apart from this bit, where I lied: 

> Package names will be of the form:

>         (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...)

We were always going to keep the _internal_ options with their "old" names
for compatibility, (these sorts of options:
	CYGDAT_IO_SERIAL_ARM_EBSA285_SERIAL_NAME "/dev/ser1"
	CYGNUM_IO_SERIAL_ARM_EBSA285_SERIAL_BAUD 38400
	CYGNUM_IO_SERIAL_ARM_EBSA285_SERIAL_BUFSIZE 128
are unchanged) but it turns out to be a PITA to change the top-level
package names.  So these will retain their old name, but they will be
separate packages rather than mere components.

         (parent is CYGPKG_IO_SERIAL for these...)
         CYGPKG_IO_SERIAL_ARM_AEB
         CYGPKG_IO_SERIAL_ARM_CMA230
         CYGPKG_IO_SERIAL_ARM_EDB7XXX
         CYGPKG_IO_SERIAL_ARM_PID
         CYGPKG_IO_SERIAL_MIPS_TX3904
         CYGPKG_IO_SERIAL_MIPS_...
         CYGPKG_IO_SERIAL_....

They will still live within the IO_SERIAL heirarchy in configtool world,
but sources will be in packages/devs/serial/arm/ebsa285 as described in my
earlier message.

Thanks for your time,

	- Huge

-- 
The 20th Century brought unprecedented increases in worldwide numeracy and
literacy and incredible advances in technology, science and mathematics.
It was also the only century in the past or in any reasonable predictable
future apparently to contain only 99 years.

Re: [ECOS] eCos Device Driver reorganization

[Hugo 'NOx' Tyson]

Hugo Tyson <hmt@cygnus.co.uk> (me, that is) writes:
> 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 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.

That work is now largely complete and committed in our internal eCos
development trunk.  We weren't forced to deviate from the plan other than
as described in my 2nd message, so it'll be much as described.

It will be visible externally when next the anoncvs tree is updated.

	- Huge

-- 
The 20th Century brought unprecedented increases in worldwide numeracy and
literacy and incredible advances in technology, science and mathematics.
It was also the only century in the past or in any reasonable predictable
future apparently to contain only 99 years.