Documentation/admin-guide/wimax/wimax.rst

   1 .. include:: <isonum.txt>
   2
   3 ========================
   4 Linux kernel WiMAX stack
   5 ========================
   6
   7 :Copyright: |copy| 2008 Intel Corporation < linux-wimax@intel.com >
   8
   9    This provides a basic Linux kernel WiMAX stack to provide a common
  10    control API for WiMAX devices, usable from kernel and user space.
  11
  12 1. Design
  13 =========
  14
  15    The WiMAX stack is designed to provide for common WiMAX control
  16    services to current and future WiMAX devices from any vendor.
  17
  18    Because currently there is only one and we don't know what would be the
  19    common services, the APIs it currently provides are very minimal.
  20    However, it is done in such a way that it is easily extensible to
  21    accommodate future requirements.
  22
  23    The stack works by embedding a struct wimax_dev in your device's
  24    control structures. This provides a set of callbacks that the WiMAX
  25    stack will call in order to implement control operations requested by
  26    the user. As well, the stack provides API functions that the driver
  27    calls to notify about changes of state in the device.
  28
  29    The stack exports the API calls needed to control the device to user
  30    space using generic netlink as a marshalling mechanism. You can access
  31    them using your own code or use the wrappers provided for your
  32    convenience in libwimax (in the wimax-tools package).
  33
  34    For detailed information on the stack, please see
  35    include/linux/wimax.h.
  36
  37 2. Usage
  38 ========
  39
  40    For usage in a driver (registration, API, etc) please refer to the
  41    instructions in the header file include/linux/wimax.h.
  42
  43    When a device is registered with the WiMAX stack, a set of debugfs
  44    files will appear in /sys/kernel/debug/wimax:wmxX can tweak for
  45    control.
  46
  47 2.1. Obtaining debug information: debugfs entries
  48 -------------------------------------------------
  49
  50    The WiMAX stack is compiled, by default, with debug messages that can
  51    be used to diagnose issues. By default, said messages are disabled.
  52
  53    The drivers will register debugfs entries that allow the user to tweak
  54    debug settings.
  55
  56    Each driver, when registering with the stack, will cause a debugfs
  57    directory named wimax:DEVICENAME to be created; optionally, it might
  58    create more subentries below it.
  59
  60 2.1.1. Increasing debug output
  61 ------------------------------
  62
  63    The files named *dl_* indicate knobs for controlling the debug output
  64    of different submodules of the WiMAX stack::
  65
  66         # find /sys/kernel/debug/wimax\:wmx0 -name \*dl_\*
  67         /sys/kernel/debug/wimax:wmx0/wimax_dl_stack
  68         /sys/kernel/debug/wimax:wmx0/wimax_dl_op_rfkill
  69         /sys/kernel/debug/wimax:wmx0/wimax_dl_op_reset
  70         /sys/kernel/debug/wimax:wmx0/wimax_dl_op_msg
  71         /sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
  72         /sys/kernel/debug/wimax:wmx0/wimax_dl_debugfs
  73         /sys/kernel/debug/wimax:wmx0/.... # other driver specific files
  74
  75    NOTE:
  76        Of course, if debugfs is mounted in a directory other than
  77        /sys/kernel/debug, those paths will change.
  78
  79    By reading the file you can obtain the current value of said debug
  80    level; by writing to it, you can set it.
  81
  82    To increase the debug level of, for example, the id-table submodule,
  83    just write:
  84
  85         $ echo 3 > /sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
  86
  87    Increasing numbers yield increasing debug information; for details of
  88    what is printed and the available levels, check the source. The code
  89    uses 0 for disabled and increasing values until 8.