source: rtems/c/src/lib/libbsp/powerpc/beatnik/network/porting/README @ b7a6d23a

Templates to help porting freebsd networking drivers
to rtems (focus on i386 and powerpc) using a 'quick and dirty'
approach.
This is not an elegant piece of software -- be warned.

/* Copyright: Till Straumann <strauman@slac.stanford.edu>, 2005;
 * License:   see LICENSE file.
 */

Release info: $Name$

Usage:

  A obtain the freebsd driver source. It usually is made
    up of a
     if_XXX.c       --  core driver
     if_XXXreg.h    --  core header
     if_XXXvar.h    --  some have it, some don't
     if_XXX_<bus>.c --  glue to integrate the core
                        driver with different environments
                        (such as pccard, pci, ...). There
                        are several of these.

        Note that you might have to get an older version
        as some structures and interfaces may have undergone
        significant changes since the bsd/networking version that
        was ported to rtems.

  B Copy the Makefile and rtemscompat_defs.h templates to the
    driver source dir and edit them.

  C Edit if_XXXreg.h and comment all unneeded fields from the
    'softc' structure declaration with

    #ifndef __rtems__
    #endif

    In particular, the bushandle field (as defined in rtemscompat_defs.h)
    above, see comments in the template) must be re-declared:

    #ifndef __rtems__
        bus_space_handle_t  XXX_bhandle;
        #else
        unsigned                        XXX_bhandle;
        unsigned char           irq_no;
        unsigned char           b,d,f;  /* PCI tuple; needed for PCI only */
        rtems_id                        tid;    /* driver task id */
        #endif

    Later, the compilation attempts will help identifying
    fields that need to be removed.

        I like the #ifdef __rtems__  construct as it minimizes changes
    to the source thus making merging updated driver versions easier.

  D Edit if_XXX.c; at the very top, include the lines

    #ifdef __rtems__
    #include <rtemscompat.h>
        #endif

        use the #ifndef __rtems__ #endif construct to comment 
    unneeded / unsupported inclusion of headers and code pieces.

    - inclusion of net/if_media.h must usually be mapped to 
                   libchip/if_media.h
   
    comment all vm, machine, bus, mii etc. related headers.

    - replace inclusion of if_XXXreg.h by

     #include "if_XXXreg.h" 
     #include <rtemscompat1.h>

    - work through the if_XXX.c and if_XXXreg.h files commenting
    stuff until if_XXX.c compiles. This might involve hacking
    the helper headers.

    - pay attention to endian issues; things may need to be fixed!

    - at the top where the freebsd 'methods' and the like are
    commented, add a definition of the driver methods for RTEMS:

    #ifdef __rtems__
        net_drv_tbl_t METHODS = {
                n_probe  : XXX_probe,
                n_attach : XXX_attach,
                n_detach : XXX_detach,  /* optional; */
                n_intr   : XXX_intr,    /* freebsd ISR; executed from daemon under RTEMS */
        };
    #endif

        - make sure all the if_xxx methods are set; in particular,
      set
                sc->if_output = ether_output;

        - on input:
                you can use DO_ETHER_INPUT_SKIPPING_ETHER_HEADER() macro
                -- if you don't MAKE SURE THE RECEIVING INTERFACE IS SET
                in the mbuf packet header!!!

  E create 'rtems_<chip>_setup()' to probe for devices and
    set the softc struct's base address, interrupt line and
    bus/dev/fun triple (PCI only).
    For PCI devices, a generic setup routine already comes with
    porting/if_xxx_rtems.c -> nothing needs to be written!