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    <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 *, ulong, 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).