Annotation of doc/notes/porting_drivers.txt, revision 1.1
1.1 ! dillon 1: $DragonFly$
! 3: PORTING FREEBSD DRIVERS TO DRAGONFLY
! 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.
! 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.
! 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.
! 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 .
! 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.
! 30: Instances of <sys/mutex.h> should be replaced with <sys/spinlock.h>.
! 32: When replacing mutexes with spinlocks it is a good idea to rename
! 33: the structural field (typically 'mtx') to something else (typically 'spin').
! 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.
! 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.
! 43: * UMA conversion - generally speaking UMA should be converted to a stanard
! 44: malloc.
! 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.
! 50: * CDEVSW conversion - see other devices. Generally speaking a major number
! 51: is needed and a function map needs to be specified more explicitly.
! 53: Most calls passing struct cdev pointers are dev_t's in DragonFly.
! 55: All device vectors in DragonFly pass a dev_<name>_args structure pointer
! 56: instead of explicit arguments.
! 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.
! 64: * TSLEEP conversion. The DragonFly tsleep does not have 'PRI' priorities.
! 65: 0 should be used.
! 68: * BUS_* FUNCTIONS
! 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.