sys/netproto/802_11/README.DRAGONFLY

   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                          NULL, NULL,
 140                          size, 1, size,
 141                          BUS_DMA_NOWAIT, &dma->tag);
 142
 143     * device_printf() may be used with "%6D".  This is a FreeBSD specific
 144       conversion specifier that was removed from DragonFly.  There is a
 145       generic kether_ntoa() helper function that can be used for printing
 146       MAC addresses. ath(4) also has an ath_hal_ether_sprintf() for this
 147       purpose and the wlan stack has an ether_sprintf(). Simply removing
 148       the __printflike() to silence the warning is wrong since that will
 149       still not print the MAC address correctly (due to removed support
 150       in the kprintf() functions).