Return to porting_drivers.txt CVS log

Up to [DragonFly] / doc / notes

Annotation of doc/notes/porting_drivers.txt, revision 1.1

1.1     ! dillon      1: $DragonFly$
        !             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: