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