INSTALL

   1 MADWIFI: Multimode Atheros Driver for WiFi on Linux (VAP branch)
   2 ================================================================
   3
   4 * Copyright (c) 2002-2005 Sam Leffler.  All rights reserved.
   5
   6 Read the file COPYRIGHT for the complete copyright.
   7
   8
   9 Requirements
  10 ------------
  11
  12 - Configured kernel sources of the target kernel.  Some Linux
  13   distributions provide headers, makefiles and configuration data - it
  14   should suffice.
  15
  16 - Wireless Extensions support (14 or later, 17 preferred) - option
  17   CONFIG_NET_RADIO in kernel .config file.
  18
  19 - Sysctl support - option CONFIG_SYSCTL in kernel .config file.
  20
  21 - Crypto API support - option CONFIG_CRYPTO in kernel .config file (AES
  22   support is used if present, otherwise the AES-CCMP cipher module falls
  23   back to a private implementation).
  24
  25 - gcc of same version that was used to compile the kernel.  At least
  26   make sure that the first two version numbers or the compiler are the
  27   same (e.g. it's OK to use gcc 3.4.6 to compile MadWifi if the kernel
  28   was compiled by gcc 3.4.2).  Ignoring this rule will cause "Invalid
  29   module format" errors during module load.
  30
  31 Linux 2.4.x kernels starting with 2.4.22 and 2.6 kernels should work
  32 without problems.  Due to quick pace of Linux development, there is no
  33 way compatibility with the future 2.6 kernels can be ensured.  However,
  34 the latest 2.6 kernel at the time of the release should be expected to
  35 work.
  36
  37 Automatic module loading support (CONFIG_KMOD) is recommended; otherwise,
  38 care will have to be taken to manually load needed modules.
  39
  40 Building the driver
  41 -------------------
  42
  43 The driver is built using the Linux kernel build mechanism.  This means
  44 you must have some part of the kernel source distribution installed on
  45 the machine where you want to build the driver.  In particular, the
  46 kernel include files, makefiles, build scripts and configuration must be
  47 available.
  48
  49 This will be present if you built your kernel from source.  Otherwise
  50 you may need to install an additional kernel development package from
  51 your distribution that would match your kernel.  For example, the
  52 development package for the default kernel is called linux-headers on
  53 Debian and kernel-devel on Fedora Core.  Installing a package with full
  54 kernel sources should not be generally necessary.
  55
  56 Note: in the following examples "$" stands for your system prompt;
  57 you're not expected to type that as part of the actual command.  "#"
  58 stands for the command prompt when the commands must be executed by
  59 root.
  60
  61 Most people can just type:
  62
  63   $ make
  64
  65 in the top-level MadWifi source directory to build all the modules for
  66 the currently running system.
  67
  68 You MUST do a "make clean" before compiling for a different version of
  69 Linux, e.g. building for 2.6 after building for 2.4.
  70
  71 If you want to compile MadWifi for a different kernel, you need to
  72 specify the location of the kernel build tree, e.g.:
  73
  74   $ make KERNELPATH=/usr/src/linux-2.6.3
  75
  76 Note that you can also specify this path by setting an environment
  77 variable; e.g.
  78
  79   $ export KERNELPATH=/usr/src/linux-2.6.3
  80   $ make
  81
  82 If the kernel was built outside the source directory, KERNELPATH should
  83 point to the output directory where .config is located, not to the
  84 sources.
  85
  86 MadWifi currently provides four different rate control algorithms,
  87 ONOE, AMRR, SAMPLE and MINSTREL.  SAMPLE and MINSTREL are both very
  88 advanced, but MINSTREL is quite new.  Consequently, SAMPLE is used by
  89 default.  In order to make MadWifi use e.g. AMRR instead, you have to
  90 specify that as the module parameter e.g.
  91
  92   # modprobe ath_pci ratectl=amrr
  93
  94 NOTE: Changing the rate control is only required (and recommended) for
  95       users who want to setup an access point using MadWifi in difficult
  96       (e.g. lossy) environments and who know what they are doing.
  97
  98 This distribution includes support for a variety of target platforms.
  99 Because of the binary nature of the HAL not all platforms are supported
 100 (the list grows as time permits).  The supported target platforms can be
 101 found with:
 102
 103   $ ls hal/public/*.inc
 104
 105 A target specifies the CPU architecture, byte order (unless implied by
 106 the CPU), and the ABI/file format.  For most popular platforms, the
 107 build system will find the appropriate files.  When cross-compiling or
 108 compiling for less common platforms, the target platform may need to be
 109 specified using the TARGET variable, e.g:
 110
 111   $ make TARGET=armv4-le-elf
 112
 113 Consult the contents of the .inc file to find out what the target
 114 platform is and what toolchain was used to build the HAL object module.
 115 Beware of mixing toolchains; some target platforms require that the HAL
 116 and driver be built with the same toolchain (i.e. compiler, assembler,
 117 and linker) and the same compiler flags.  If you get warnings about
 118 incompatible compiler flags, chances are that you are compiling for a
 119 wrong target or using an incompatible compiler.
 120
 121
 122 Cross-compiling
 123 ---------------
 124
 125 The build system is designed to support cross-compiling without any
 126 modification to the distribution files.  It should be sufficient to
 127 specify any parameters on the make command line.
 128
 129 In most cases, only KERNELPATH and CROSS_COMPILE need to be defined.
 130 CROSS_COMPILE is the prefix for cross-compiling tools.  For instance, if
 131 the cross compiler is called arm-linux-gcc, set CROSS_COMPILE to
 132 "arm-linux-":
 133
 134   $ make KERNELPATH=/usr/src/linux-arm CROSS_COMPILE=arm-linux-
 135
 136 The build system determines ARCH and TARGET based on the .config file in
 137 the Linux build tree.  TARGET still may need to be provided on the
 138 command line some uncommon systems.  If ARCH is determined incorrectly,
 139 please report it.
 140
 141 If the compiler needs additional flags to compile userspace binaries,
 142 you can redefine CC to include those flags.
 143
 144 When installing MadWifi, set DESTDIR to the root of the target
 145 filesystem, so that the cross-compiled binaries don't overwrite the
 146 native ones.
 147
 148
 149 Loading the modules
 150 -------------------
 151
 152 Building the software will generate numerous loadable modules:
 153
 154   ath_pci               Atheros driver for PCI/Cardbus devices
 155   ath_hal               Atheros HAL
 156   wlan                  802.11 support layer
 157   wlan_wep              WEP cipher support
 158   wlan_tkip             TKIP cipher support
 159   wlan_ccmp             AES-CCMP cipher support
 160   wlan_xauth            external authenticator
 161   wlan_acl              MAC ACL support for AP operation
 162   wlan_scan_ap          AP scanning support
 163   wlan_scan_sta         station scanning support
 164   ath_rate_onoe         ONOE rate control
 165   ath_rate_amrr         AMRR rate control
 166   ath_rate_sample       SAMPLE rate control
 167
 168 The ath_pci module must be loaded either manually or by the system, e.g.
 169 through the hotplug or card manager support.  The remaining modules are
 170 loaded automatically as needed, so after doing a "make install" you only
 171 need to run following:
 172
 173   # modprobe ath_pci
 174
 175 For automatic module loading you may need to modify your system's
 176 configuration files so the necessary modules are loaded when an Atheros
 177 device is recognized.  The exact procedure varies from system to system.
 178
 179 There are module parameters available to fit your needs, e.g. you can
 180 set the countrycode manually if your card's EEPROM does not contain the
 181 correct one for your location.  See
 182 http://www.unicode.org/onlinedat/countries.html to find your code.
 183
 184 To activate German frequencies you would specify:
 185
 186   # modprobe ath_pci countrycode=276
 187
 188 To see all available module parameters type:
 189
 190   $ modinfo ath_pci
 191
 192
 193 Integrating into the kernel sources
 194 -----------------------------------
 195
 196 It is also possible to patch Linux kernel sources to integrate MadWifi
 197 directly into the kernel tree.  This allows building MadWifi as part of
 198 the kernel.  This could be useful for embedded systems that don't
 199 support loadable modules.  Please refer to patch-kernel/README for
 200 details.
 201
 202
 203 Further information
 204 -------------------
 205
 206 Further information on how to work with the driver can be found in the
 207 file README.  In addition, the project's wiki has a lot of valuable
 208 information:
 209
 210 http://madwifi.org/