xref: /dragonfly/doc/porting_drivers.txt (revision ac392440)

		    PORTING FREEBSD DRIVERS TO DRAGONFLY

* Copy the driver code to the appropriate DragonFly directory.  For example,
  a disk driver /usr/src/sys/dev/blah in FreeBSD would likely be
  /usr/src/sys/dev/disk/blah in DragonFly.

* Keep all the SVN IDs in the files as a future reference point. dports' SVN
  will do that by default. When using the FreeBSD git repo, please note the
  files' IDs manually, either in the files themselves or in the commit message.
  The general idea is that it must not get lost.

* Driver local #include's probably use a <dev/blah/blah.h> path.  These
  need to be changed to "blah.h".   '.' is not included in the #include
  path in FreeBSD builds, but it is in DragonFly builds.

* Other #include's may reference things in <dev/...> which in DragonFly
  reside in <bus/...>.  In particular, dev/pccard becomes bus/pccard.
  Note that defines in FreeBSD's pccard_cis.h reside in DragonFly's
  pccardreg.h .

* The following kernel functions have been renamed in DragonFly:

  malloc(), free() etc.	->	kmalloc(), kfree() etc.
  printf() etc.		->	kprintf() etc.
  psignal()		->	ksignal()
  random()		->	krandom()

* MUTEX conversion - mutexes are generally replaced by spinlocks.  However,
  DragonFly spinlocks are more restrictive than FreeBSD mutexes so a
  direct replacement is not necessarily appropriate in all cases.  A lockmgr
  lock should be used when a direct replacement is not appropriate.
  In particular, DragonFly does not allow recursive exclusive spinlocks
  and does not allow multiple exclusive spinlocks to be held by any given
  thread.

  Instances of <sys/mutex.h> should be replaced with <sys/spinlock.h>.

  When replacing mutexes with spinlocks it is a good idea to rename
  the structural field (typically 'mtx') to something else (typically 'spin').

  The &Giant mutex is typically converted to get_mplock() and rel_mplock().
  However, there are places where FreeBSD unlocks giant around some code and
  then relocks giant... those should simply be removed.

  FreeBSD has weird callout + mutex functions.  DragonFly does not integrate
  the two.  Instead, the driver in DragonFly must obtain the spinlocks
  in question in the callback routine.

  As a rule of thumb, MTX_DEF mutexes should be replaced with exclusive,
  recursive lockmgr locks.

  So, suppose the original code is using
	struct mtx my_mtx;
  you'd normally rename it to
	struct lock my_lock;

  and change the initialization from something like
	mtx_init(&my_mtx, "mymtx", "whatever", MTX_DEF);
  to
	lockinit(&my_lock, "mylock", 0, LK_CANRECURSE);

  Destroying it is trivial,
	mtx_destroy(&my_mtx);
  becomes
	lockuninit(&my_lock);

  You use the same function for locking and unlocking a lockmgr lock,
  so exchange
	mtx_lock(&my_mtx);
  with
	lockmgr(&my_lock, LK_EXCLUSIVE);
  and
	mtx_unlock(&my_mtx);
  with
	lockmgr(&my_lock, LK_RELEASE);

  For testing the lock status, one would use
	lockstatus(&my_lock, curthread);
  in place of
	mtx_owned(&my_mtx);

  An
	mtx_trylock(&my_mtx);
  call is replaced with
	lockmgr_try(&my_lock, LK_EXCLUSIVE);

  As for mtx_assert() calls, translate them like this:

	mtx_assert(&my_mtx, MA_OWNED) -> KKASSERT(lockstatus(&my_lock, curthread) != 0)
	mtx_assert(&my_mtx, MA_NOTOWNED) -> KKASSERT(lockstatus(&my_lock, curthread) == 0)

  In DragonFly, lockstatus() does not return information about whether there have been
  recursive lock acquisitions, so there is no generic way to emulate the

	mtx_assert(&my_mtx, MA_OWNED|MA_RECURSED);
	mtx_assert(&my_mtx, MA_OWNED|MA_NOTRECURSED);

  calls.

* rwlock conversion: Use lockmgr locks

* UMA conversion - generally speaking UMA should be converted to a standard
  kmalloc.

  Note however that in FreeBSD M_NOWAIT is often used in cases where, in fact,
  the kmalloc cannot fail without blowing something up or causing a fatal
  (and very unexpected) I/O error.  M_INTWAIT should be used for these cases.

* CDEVSW conversion - see other devices.  Generally speaking a major number
  is needed and a function map needs to be specified more explicitly.

  Most calls passing struct cdev pointers are dev_t's in DragonFly.

  All device vectors in DragonFly pass a dev_<name>_args structure pointer
  instead of explicit arguments.

  Strategy calls - we pass BIO's and a lot of BUF fields are in the BIO
  in FreeBSD, but left in the BUF in DragonFly.  FreeBSD for some reason
  names its struct bio pointers 'bp', its a good idea to rename them to 'bio'
  to avoid confusion and have a struct buf *bp = bio->bio_buf; pointer to
  access the buf.

* MSLEEP/TSLEEP conversion.  The DragonFly msleep/tsleep do not have 'PRI'
  priorities.  0 should be used.

* BUS_* FUNCTIONS

  bus_setup_intr() - replace INTR_TYPE_* flags with 0.  There is an extra
  argument for an interrupt interlock using the sys/serializer.h interface.
  This can either be left NULL or you can convert the spinlock(s) for
  the driver into serializer locks and integrate the interrupt service
  routine with a serializer.

* CAM CODE - cam_simq* code refcounts, so shared device queues (raid and
  multi-channel devices) are not freed before all references have gone
  away.

* UNRHDR functions - DragonFly uses a more generic idr(9) subsystem
  compatible with the Linux API of the same name

  This LWN article describes it in details: http://lwn.net/Articles/103209/

  A typical conversion looks like this:

  #include <sys/idr.h>

  free_unr() has to be replaced by idr_remove()

  alloc_unr() has to be replaced by a code sequence using idr_pre_get and
  idr_get_new such as this one:

  retry:
	if (idr_pre_get(xxx) ==0) {
	kprintf("Memory allocation error\n");
	    return error;
	}
	spin_lock(xxx);
	ret = idr_get_new(xxx);
	spin_unlock(xxx);
	if (ret == EAGAIN)
	    goto retry;

* MPASS macro - Replace it with KKASSERT


* PROC_LOCK / PROC_UNLOCK: to be determined on a case-by-case basis

  Some of the time these macros can be removed entirely

  In some cases, some locking must be done; lwkt_gettoken(&proc_token)
  and the corresponding lwkt_reltoken() call should be good replacements

  It is not a good idea to blindly implement these macros globally, some
  particular proc subsystem locking semantics differ enough between FreeBSD
  and DragonFly that this would cause problems

* In DragonFly 5.1 format specifier %b was replaced by args safe "%pb%i" version
  that only needs argument swapping. Replacement functions where not added.

	kvcprintf("reg=%pb%i\n", "\10\2BITTWO\1BITONE\n", 3);

* In DragonFly 5.1 format specifier %r was removed from kprintf. As a
  replacement function makedev_unit_b32() was added.

  - Unit suffix encoded as base32 for make_dev() device creation:

	char tbuf[MAKEDEV_MINNBUF];

	kbd->kb_dev = make_dev(&kbd_ops, kbd->kb_index,
				UID_ROOT, GID_WHEEL, 0600, "kbd%s",
				makedev_unit_b32(tbuf, kbd->kb_index));

  - For single character case the hex2ascii() can be used to avoid buffers:

	kprintf("%c\n", hex2ascii(n % base));

* In DragonFly 3.3 format specifier %D was removed from kprintf. As a
  replacement functions kether_ntoa() and hexncpy() were added.

  - Ethernet address (MAC) to its hexadecimal form:

	char ethstr[ETHER_ADDRSTRLEN + 1];
	u_char hwaddr[6];

	kprintf("MAC address %s\n", kether_ntoa(hwaddr, ethstr)

  - Generic conversion (block of bytes to hexadecimal form):

	char hexstr[18];
	u_char mydata[6] = {1, 2, 3, 4, 5 ,6};

	/*
	 * Below statement would print:
	 *
	 * 01-02-03-04-05-06
	 */
	kprintf("%s\n", hexncpy(mydata, 6, hexstr, HEX_NCPYLEN(6), "-"));

* TAILQ_XXX_SAFE

  Use TAILQ_XXX_MUTABLE; the macros have the same effect, only the name is
  different

* kern_yield()

  Replace by lwkt_yield()

* vm_page_lock() and vm_page_unlock()

  Not needed on DragonFly, remove these calls

* vm_pager_get_pages()

  Removed, use vm_pager_get_page() instead

* VPO_BUSY

  Replace by PG_BUSY

* kern_psignal()

  Replace by ksignal()