INSTALL

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