sys/netproto/802_11/README.DRAGONFLY

   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
   8 STEP 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
  14 STEP 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
  22 modevent        search for DECLARE_MODULE and MOD_LOAD and friends.
  23
  24 sysctl          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
  31 eventhandler    search for EVENTHANDLER_REGISTER.
  32
  33 taskq           search for TASK_INIT.
  34
  35                 All taskq callback procedures should be renamed to
  36                 "<blah>_task".
  37
  38 callout         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
  46 ifnet           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
  54 devmethod       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
  60 interrupt       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
  66 ieee80211_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 tsleep          Low level drivers sometimes call tsleep() to wait for
  75                 an interrupt driven event to wake them up.  In these
  76                 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
  81 firmware        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
  87 Low 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.