1
2			    README.DRAGONFLY
3
4    All ABI entry points into the wlan infrastructure must acquire the
5    wlan_global_serializer.  Normally all wireless base drivers also
6    use this serializer to avoid deadlocks.
7
8STEP 1:
9
10    When porting a new wireless low level device be sure to remove all
11    *LOCK* (upper case) macro calls because the whole point of this is
12    to redo the locking with our own.
13
14STEP 2:
15
16    All border crossings (module loader, sysctl, eventhandlers, tasks,
17    callouts, ifnet, devmethod, and interrupt handlers) must be properly
18    wrapped with wlan_serialize_enter() and wlan_serialize_exit().  Pay
19    careful attention to any early return()s that might break your locks.
20
21
22modevent	search for DECLARE_MODULE and MOD_LOAD and friends.
23
24sysctl		search for SYSCTL_HANDLER_ARGS.
25
26		Generally speaking sysctls should be rewritten to use
27		a flow-through model (see ath for an example) as most
28		of them currently use a badly designed early-termination
29		model.
30
31eventhandler	search for EVENTHANDLER_REGISTER.
32
33taskq		search for TASK_INIT.
34
35		All taskq callback procedures should be renamed to
36		"<blah>_task".
37
38callout		search for callout_reset.
39
40		search for callout_stop to deal with potential deadlock
41		issues.
42
43		All callout callback procedures should be renamed to
44		"<blah>_callout"
45
46ifnet		wlan/ieee80211.c
47
48		This is handled by ieee80211_ifattach() where we set
49		the serializer to &wlan_global_serializer when we
50		call ether_ifattach().  The low level drivers should
51		just be calling ieee80211_ifattach() so no additional
52		work should be needed here.
53
54devmethod	Search for DEVMETHOD (low level drivers).  Typically
55		this is in the *_pci.c file.  The attach function might
56		present an issue where you may wish to release the
57		serializer across the main DMA area allocations.
58		see ath.
59
60interrupt	Search for bus_setup_intr().
61
62		Typically we pass the &wlan_global_serializer to
63		bus_setup_intr().  The interrupt callback is thus
64		serialized automatically.
65
66ieee80211_ioctl()
67		This is called directly from the wlan's ifp->if_ioctl and
68		also from various wireless drivers.  This function expects
69		the serializer to already be acquired.
70
71		The kernel will acquire if_serializer when making
72		ifp->if_ioctl() calls.
73
74{t,lk}sleep		Low level drivers sometimes call {t,lk}sleep() to
75		wait for an interrupt driven event to wake them up.  In
76		these cases the interrupt will be blocked on the wlan
77		serializer and the tsleep will timeout.  To fix the
78		problem use zsleep() to release the &wlan_global_serializer
79		across the sleep operation.
80
81firmware	The firmware loader uses a taskq to defer certain
82		operations which can then deadlock against the wlan
83		serializer.  Thus it is usually a good idea to
84		release the serializer (wlan_serialize_exit/enter)
85		around the call to firmware_get().
86
87Low level device drivers
88		Don't forget that low level device drivers such as ath
89		have callouts, taskq, sysctl, and other elements also!
90
91		Look for old calls to ifnet_serialize*() and remove,
92		in addition to the various LOCK macros.
93