notes/porting_drivers.txt

   1 $DragonFly: doc/notes/porting_drivers.txt,v 1.1 2006/12/03 20:49:59 dillon Exp $
   2
   3                     PORTING FREEBSD DRIVERS TO DRAGONFLY
   4
   5 * Copy the driver code to the appropriate DragonFly directory.  For example,
   6   a disk driver /usr/src/sys/dev/blah in FreeBSD would likely be
   7   /usr/src/sys/dev/disk/blah in DragonFly.
   8
   9 * Edit all source files and move the FBSDID declaration into a comment
  10   (removing the declaration but leave the CVS id in the comment).  Remove
  11   the #include <sys/cdefs.h> as well.
  12
  13 * Driver local #include's probably use a <dev/blah/blah.h> path.  These
  14   need to be changed to "blah.h".   '.' is not included in the #include
  15   path in FreeBSD builds, but it is in DragonFly builds.
  16
  17 * Other #include's may reference things in <dev/...> which in DragonFly
  18   reside in <bus/...>.  In particular, dev/pccard becomes bus/pccard.
  19   Note that defines in FreeBSD's pccard_cis.h reside in DragonFly's
  20   pccardreg.h .
  21
  22 * MUTEX conversion - mutexes are generally replaced by spinlocks.  However,
  23   DragonFly spinlocks are more restriction then FreeBSD mutexes so a
  24   direct replacement is not necessarily appropriate in all cases.  A lockmgr
  25   lock should be used when a direct replacement is not appropriate.
  26   In particular, DragonFly does not allow recursive exclusive spinlocks
  27   and does not allow multiple exclusive spinlocks to be held by any given
  28   thread.
  29
  30   Instances of <sys/mutex.h> should be replaced with <sys/spinlock.h>.
  31
  32   When replacing mutexes with spinlocks it is a good idea to rename
  33   the structural field (typically 'mtx') to something else (typically 'spin').
  34
  35   The &Giant mutex is typically converted to get_mplock() and rel_mplock().
  36   However, there are places where FreeBSD unlocks giant around some code and
  37   then relocks giant... those should simply be removed.
  38
  39   FreeBSD has weird callout + mutex functions.  DragonFly does not integrate
  40   the two.  Instead, the driver in DragonFly must obtain the spinlocks
  41   in question in the callback routine.
  42
  43 * UMA conversion - generally speaking UMA should be converted to a stanard
  44   malloc.
  45
  46   Note however that in FreeBSD M_NOWAIT is often used in cases where, in fact,
  47   the malloc cannot fail without blowing something up or causing a fatal
  48   (and very unexpected) I/O error.  M_INTWAIT should be used for these cases.
  49
  50 * CDEVSW conversion - see other devices.  Generally speaking a major number
  51   is needed and a function map needs to be specified more explicitly.
  52
  53   Most calls passing struct cdev pointers are dev_t's in DragonFly.
  54
  55   All device vectors in DragonFly pass a dev_<name>_args structure pointer
  56   instead of explicit arguments.
  57
  58   Strategy calls - we pass BIO's and a lot of BUF fields are in the BIO
  59   in FreeBSD, but left in the BUF in DragonFly.  FreeBSD for some reason
  60   names its struct bio pointers 'bp', its a good idea to rename them to 'bio'
  61   to avoid confusion and have a struct buf *bp = bio->bio_buf; pointer to
  62   access the buf.
  63
  64 * TSLEEP conversion.  The DragonFly tsleep does not have 'PRI' priorities.
  65   0 should be used.
  66
  67
  68 * BUS_* FUNCTIONS
  69
  70   bus_setup_intr() - replace INTR_TYPE_* flags with 0.  There is an extra
  71   argument for an interrupt interlock using the sys/serializer.h interface.
  72   This can either be left NULL or you can convert the genera spinlock(s) for
  73   the driver into serializer locks and integrate the interrupt service
  74   routine with a serializer.
  75