[Bug 1601] New: USB stack port from FreeBSD 8.0

[bugzilla-daemon at rtems.org]

https://www.rtems.org/bugzilla/show_bug.cgi?id=1601

           Summary: USB stack port from FreeBSD 8.0
           Product: RTEMS
           Version: 4.10
          Platform: All
        OS/Version: RTEMS
            Status: NEW
          Severity: enhancement
          Priority: P3
         Component: misc
        AssignedTo: joel.sherrill at oarcorp.com
        ReportedBy: sebastian.huber at embedded-brains.de


This is a port of parts of the FreeBSD USB stack released with version 8.0.
The code is based on trunk revision 209644.

HOWTO USE IT WITH YOUR BSP:

1. Update to RTEMS 4.10 or CVS HEAD.

2. Verify that a supported BSP works with you local installation
(ARM/lpc24xx_ncs_ram):
  2.1. Install the ARM/lpc24xx_ncs_ram BSP:
    ${RTEMS_SOURCE}/configure --target=arm-rtems4.10
--enable-rtemsbsp=lpc24xx_ncs_ram --enable-posix
  2.2. Install the media library (attached):
    cd libmedia && make clean install
  2.3. Install the USB library (attached):
    cd libusb && make clean install
  2.4. Build the demo application (attached):
    cd usb-demo && make clean all
  2.5. If you have problems with the steps above please report the errors.

3. Build the demo application with your BSP:
  3.1. Install the media library (attached):
    cd libmedia && make clean install
  3.2. Install the USB library (attached):
    cd libusb && make clean install
  3.3. If you have problems with steps 3.1 or 3.2 please report the errors.
  3.4. Build the demo application (attached):
    cd usb-demo && make clean all
  3.5. You will likely encounter errors from the linker.  Your BSP must support
    the following linker set:
      .rodata : {
        __start_set_modmetadata_set = .;
        *(set_modmetadata_set);
        __stop_set_modmetadata_set = .;
      }
    Your BSP must implement the interrupt server API:
     
http://www.rtems.org/onlinedocs/doxygen/cpukit/html/group__rtems__interrupt__extension.html
    Support files:
      c/src/lib/libbsp/shared/include/irq-generic.h
      c/src/lib/libbsp/shared/include/irq-info.h
      c/src/lib/libbsp/shared/src/irq-generic.c
      c/src/lib/libbsp/shared/src/irq-info.c
      c/src/lib/libbsp/shared/src/irq-legacy.c
      c/src/lib/libbsp/shared/src/irq-server.c
      c/src/lib/libbsp/shared/src/irq-shell.c

4. Add support for your USB controller
  Examples:
    libusb/rtems/freebsd/dev/usb/controller/ehci_mpc83xx.c
    libusb/rtems/freebsd/dev/usb/controller/ohci_lpc24xx.c
    libusb/rtems/freebsd/dev/usb/controller/ohci_lpc32xx.c

IMPLEMENTATION NOTES:

There are different ways to port subsystems from FreeBSD to RTEMS.  You can
replace locking and synchronization primitives from FreeBSD with dummy
functionality or provide a mapping to the RTEMS directives.

The current FreeBSD is capable to run on a SMP machine.  If you run the FreeBSD
kernel within different RTEMS tasks this is like running FreeBSD on a SMP
machine.  Thus if you provide a proper mapping of the locking and
synchronization primitives of FreeBSD to RTEMS you can use FreeBSD code without
much modification.  The current TCP/IP port uses a different approach.  It
introduces a giant lock outside the FreeBSD kernel and ensures that the FreeBSD
kernel will be executed through defined entry and exit points which are
protected by this giant lock (this is not the Giant lock, it is the network
semaphore).

With the current SMP aware FreeBSD system it is possible to avoid the
introduction of external giant locks and use only the native FreeBSD locking
and synchronization means.  This requires that RTEMS provides some core APIs
from FreeBSD.  The work with the USB stack from current FreeBSD showed that the
following APIs are important.  You can obtain a man page for each API at

http://www.freebsd.org/cgi/man.cgi?query=signal&apropos=0&sektion=9&manpath=FreeBSD+8-current&format=html

Each name matches the man page entry.  A proposed implementation with RTEMS
directives is given.

sx (Shared/exclusive locks):
    Binary semaphores (this neglects the ability to allow shared access).

mutex (Mutual exclusion):
    Binary semaphores (not recursive mutexes are not supported this way).

condvar (Condition variables):
    POSIX condition variables with modifications (hack).

callout (Timer functions):
    Timer server.

kthread, kproc (Tasks):
    Tasks.

devfs (Device file system):
    Dummy, IMFS or new implementation (currently dummy).

psignal (Signals):
    TBD.  Seems to be not needed.

poll, select:
    TBD.  Seems to be not needed.

rman (Resource management):
    TBD.  Seems to be not needed.

devclass, device, driver, make_dev (Device management):
    Use FreeBSD implementation as far as possible.  FreeBSD has a nice API
    for dynamic device handling.  It may be interesting for RTEMS to use
    this API internally in the future.

bus_space, bus_dma (Bus and DMA access):
    Likely BSP dependent.  A default implementation for memory mapped
    linear access is easy to provide.  The current heap implementation
    supports all properties demanded by bus_dma (including the boundary
    constraint).

Interrupt handlers can use some kind of blocking calls in FreeBSD.  We can use
an interrupt handler server for this purpose.

All files for the USB port are generated through a Python script from modified
FreeBSD sources.  The generated files are placed into an own directory
hierarchy.  The script changes include paths and adds a special RTEMS
configuration include file to the top of the include list.  The header guards
are also modfied.  The modifications done by the script are reversible.  All
modifications of the original FreeBSD sources are within preprocessor sections
guarded by the __rtems__ define.  So you can update with a low chance for
conflicts.  This is useful for synchronization with the FreeBSD development.
Suppose we used revision X for our USB port and want to synchronize with
revision Y.  We can do this in the following steps:

1. Check-out FreeBSD at revision X.
2. Make the changes done for revision X (through a script).
3. Update to revision Y.
4. Resolve conflicts.
5. Use script to generate USB port.

The FreeBSD kernel is not designed to be a library.  It is incorporated as a
bunch of object files.  The linker generates so called linker sets of special
objects (the BSP linker command file must support this).  At runtime these sets
are evaluated for example to do the system startup.  We cannot use this method
instead we have to use for example an explicit table instead of the linker set
to resolve all dependencies.

TODO:

o Tests for FreeBSD API implementations.
o Proper bus space implementation.
o More robust unmount().  This requires thorough file system changes.

-- 
Configure bugmail: https://www.rtems.org/bugzilla/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are watching all bug changes.