1
2			    README.DRAGONFLY
3
4		Porting low level drivers from FreeBSD
5
6    * Fixup #include lines.
7
8      <dev/pci/blah.h>  -> <bus/pci/blah.h>
9      <dev/blah/blah.h> -> <dev/netif/blah/blah.h>
10      <net80211/blah.h> -> <netproto/802_11/blah.h>
11
12      remove <machine/bus.h>
13      remove <machine/resource.h>
14      add    <sys/stdbool.h>
15      add    <net/ifq_var.h>
16
17    * Simple API changes
18
19      malloc	   -> kmalloc
20      free	   -> kfree
21      printf	   -> kprintf
22      pci_find_cap -> pci_find_extcap
23
24      In kmalloc calls, M_NOWAIT -> M_INTWAIT
25
26    * mbuf related calls
27
28      m_collapse(m, M_NOWAIT, blah)	->	m_defrag(m, M_NOWAIT)
29
30      bus_dmamap_load_mbuf_sg(dmat, map, m, segs, &nsegs, BUS_DMA_NOWAIT) ->
31	bus_dmamap_load_mbuf_segment(dmat, map, m, segs, maxscatter,
32					&nsegs, BUS_DMA_NOWAIT);
33
34	The maxscatter argument depends on the driver, '1' if you do not
35	know.
36
37    * netif interface
38
39      IFQ_SET_MAXLEN(), ifp->if_snd.ifq_drv_maxlen = blah, IFQ_SET_READY() ->
40	ifq_set_maxlen(&ifp->if_snd, blah)
41
42      if_start() and if_ioctl() have an additional argument.
43
44	  void blah_start(struct ifnet *, struct ifaltq_subque *);
45	  int  blah_ioctl(struct ifnet *, u_long, caddr_t, struct ucred *);
46
47	  In this situation the additional argument can usually be ignored.
48
49      if_inc_counter(ifp, BLAH, 1)		->  ++ifp->if_blah
50      if_inc_counter(ifp, IFCOUNTER_OERRORS, 1) -> ++ifp->if_oerrors;
51
52      if_drv_flags used with IFF_DRV_RUNNING   ->
53      if_flags used used with IFF_RUNNING
54
55      if_drv_flags used with IFF_DRV_OACTIVE  ->
56      ifq_is_oactive(), ifq_set_oactive(), ifq_clr_oactive() as appropriate.
57
58      Be very careful here, review your patches to make sure you aren't
59      testing the wrong field against the IFF_* macro.  All OACTIVE chanages
60      must use our API calls and not test the flag(s) directly.
61
62    * Change all struct mtx and related locking api calls and macros
63      to use struct lock (lockmgr locks).
64
65      struct mtx	->	struct lock
66
67      lockmgr(lk, LK_EXCUSIVE)
68      lockmgr(lk, LK_RELEASE)
69      lockinit(lk, wmesg, flags)		(typcally 0 or LK_CANRECURSE)
70      KKASSERT(lockstatus(lk) == LK_EXCUSIVE)	(asserting held)
71      KKASSERT(lockstatus(lk) != LK_EXCUSIVE)	(asserting not held)
72
73    * msleep() calls typically have to become lksleep() calls.  However,
74      in these situations the wlan_global_serializer might also be held
75      and must be released, so it is best to wrap it in your own blahsleep()
76      function which does this in addition to the lksleep():
77
78	blah_sleep(struct blah_softc *sc, void *wchan,
79		   int flags, const char *wmsg, int timo)
80	{
81		int iws;
82		int error;
83
84		iws = wlan_is_serialized()
85		if (iws)
86			wlan_serialize_exit();
87		error = lksleep(wchan, appropriatelock, flags, wmsg, timo);
88		if (iws)
89			wlan_serialize_enter();
90		return error;
91	}
92
93    * Firmware loading and/or the general network init function may have
94      to release wlan_global_serializer similarly to how the blah_sleep()
95      releases it for the duration of the init function and firmware load.
96
97    * You may need a modevent infrastructure for module loading.  See the
98      original driver for code or one of the drivers already ported, like
99      netif/ath or netif/iwn
100
101    * SYSCTL macros in FreeBSD may have a CTLFLAG_RWTUN which for us is
102      just CTLFLAG_RW plus an additional TUNABLE* macro (see netif/ath
103      for examples).
104
105    * taskq_start_threads() API is slightly different.
106
107      taskqueue_start_threads(tq, 1, 0, name) ->
108      taskqueue_start_threads(tq, 1, TDPRI_KERN_DAEMON, -1, name)
109
110    * bus_setup_intr() is different.
111
112      bus_setup_intr(dev, irq, INTR_TYPE_NET | INTR_MPSAFE,
113			NULL, intrfunc, sc, &handle)		->
114      bus_setup_intr(dev, irq, INTR_MPSAFE,
115			intrfunc, sc, &handle, &wlan_global_serializer)
116
117    * callout API.  callout_init_mtx() is already macrod to
118      callout_init_lk().
119
120      callout_stop()	-> callout_stop_sync()
121      callout_sched()	-> must be converted to the proper callout_reset(...)
122			   call (function must be re-provided).
123
124    * bus_dma_tag_create() API is dfferent.
125
126      bus_dma_tag_create(tag, alignment,
127			 0,
128			 BUS_SPACE_MAXADDR_32BIT,
129			 BUS_SPACE_MAXADDR,
130			 NULL, NULL,
131			 size, 1, size,
132			 BUS_DMA_NOWAIT,
133			 NULL, NULL,
134			 &dma->tag)			-> to
135
136      bus_dma_tag_create(tag, alignment,
137			 0,
138			 BUS_SPACE_MAXADDR_32BIT,
139			 BUS_SPACE_MAXADDR,
140			 NULL, NULL,
141			 size, 1, size,
142			 BUS_DMA_NOWAIT, &dma->tag);
143
144    * device_printf() may be used with "%6D".  This is a FreeBSD specific
145      conversion specifier that was removed from DragonFly.  There is a
146      generic kether_ntoa() helper function that can be used for printing
147      MAC addresses. ath(4) also has an ath_hal_ether_sprintf() for this
148      purpose and the wlan stack has an ether_sprintf(). Simply removing
149      the __printflike() to silence the warning is wrong since that will
150      still not print the MAC address correctly (due to removed support
151      in the kprintf() functions).
152