acx-mac80211 INSTALL   
====================

I. Introduction
---------------
This document describes the steps required to build and install the
acx driver in a Linux system.

Two alternative methods are described, referred to as out-of-tree
(chapter II) and in-tree (chapter IV).

The recommended way, because of its simplicity, is the out-of-tree
installation described in chapter II), although it requires an
installed set of kernel include headers in the system.

Alternatively you may also consider a DKMS installation, see chapter
III) below.

The acx hardware required firmware in order to operate. Chapter V)
described the firmware image installation in more detail.

For hx4700 or rx1950 chapter VI) is describing building and
installation of driver and platform modules.

II. As a module, outside the kernel tree
----------------------------------------
This is the recommended and most straight forward method for end-users
for using the driver.

1) Install the sources, e.g. from a tar-ball or a git repository:
---
tar -zxf acx-source.tar.gz

git clone git:[repro]
git checkout [branch] -b [branch]
---

2) Build the module: 

The result will be the acx-mac80211.ko kernel module. The default
build config will include pci and usb support.

Make sure your kernel headers are installed and that the corresponding
'build' sym-link is set in '/lib/modules/[kernel]/build'.

A simple make should compile the driver in 10secs.
---
make
---

3) Install the module:

You can basically install the module a) fully in your kernels
/lib/modules installation or b) keep just keep it locally and do the
loading individually.

3a) 
---
make install
depmod
---

3b) ... or just use it in place. See usage below.

4) Usage:

The acx-mac80211 driver depends on the mac80211 module. So it should
be loaded before.

4.1.a) Following a 3a) installation:

Module dependency for mac80211 should have been updated by depmod, so
a simple modprobe will load the driver:
---
modprobe acx-mac80211
---

4.1.b) Following a 3b) installation:
---
modprobe mac80211
insmod ./acx-mac80211.ko
--- 

4.2) Firmware installation:

If the firmware file is not yet installed, you will find following
message in 'dmesg':
---
---
=> See the README and wiki for more information on firmware installation.

Install the corresponding firmware file [tiacx] into '/lib/firmware'
and reload the driver:
---
rmmod acx-mac80211
modprobe acx-mac80211 ... or ... insmod ./acx-mac80211.ko
---

5) That's it. A 'dmesg' should show the driver having probed devices. 

Using 'iwconfig' you should see the corresponding the wlan[0-9]
(depending on how many wifi cards you have ;) interface now.

A basic smoke test is performing a scan or two:
---
ifconfig wlan[0-9] up
iwlist wlan[0-9] scan
---

6) Advanced build

In case you need to specify configuration options other than the
default PCI build (e.g. you need to build the USB driver, or you want
to build against a special kernel version), you will first need to
have a look at the Makefile in order to understand it.

You will see that there is an EXTRA_KCONFIG variable, which you can
modify directly on the file or define it on the command-line to suit
your needs:

   export EXTRA_KCONFIG="CONFIG_ACX_MAC80211=m CONFIG_ACX_MAC80211_USB=y" && make

If you use this method (CLI), do not forget to either unset ('unset
EXTRA_KCONFIG') or explicitly define EXTRA_KCONFIG for subsequent
builds!

You can also define the KERNELDIR variable in order to specify a
different kernel directory other than that of the the currently
running one.

Note that you can also execute make with 'make V=1' in order to get
verbose information during the build.


III. DKMS installation
----------------------

For a DKMS installation, do the following

1) Install the acx-mac80211 source into /usr/src in a directory with
following form
---
/usr/src/acx-mac80211-[version]
---

Where [version] can e.g. also be "1git", if it's the git repository
[version] must start with a digit
---
/usr/src/acx-mac80211-1git
---

2) Then add the "acx-mac80211" driver module, and in this example
version "1git", to DKMS
---
dkms add -m acx-mac80211 -v 1git 
---

3) And build and install the module like this:
---
dkms build -m acx-mac80211 -v 1git 
dkms install -m acx-mac80211 -v 1git 
---

4) Then the driver module can be loaded / unloaded with the usual means:
---
modprobe acx-mac80211
rmmod acx-mac80211
---

5) To uninstall the driver from DKMS use the following
---
dkms uninstall -m acx-mac80211 -v 1git 
dkms remove -m acx-mac80211 -v 1git --all 
---


VI. Inside the kernel tree 
---------------------------

1) Copy the driver sources into the kernel tree

  cd <linux-sources-path>
  cd drivers/net/wireless/
  mkdir acx
  cd acx
  cp <acx-mac80211-sources-path>/* .

2) Kernel build system preparation 

Modify the file drivers/net/wireless/Makefile by adding the following
line to it:

  obj-$(CONFIG_ACX_MAC80211)      += acx/

Modify the file drivers/net/wireless/Kconfig by adding the following
line to it:

  source "drivers/net/wireless/acx/Kconfig"

Start the kernel configuration menu as usual:

  make menuconfig

(or any similar method, e.g. with graphical interface)

Now you can simply configure the kernel in the usual way, making sure
that the CONFIG_ACX_MAC80211 option and at least one of the
CONFIG_ACX_MAC80211_PCI or CONFIG_ACX_MAC80211_USB options are set in
the .config file, as described below.

Note: you will have to first select the mac80211 stack in the kernel
configuration menu:

Networking  --->
  Wireless  --->
    {M} Improved wireless configuration API
    [*]   nl80211 new netlink interface support
    -*- Wireless extensions
     Generic IEEE 802.11 Networking Stack (mac80211)
          Rate control algorithm selection  --->
    [ ]   Enable mac80211 mesh networking (pre-802.11s) support (NEW)
    [ ]   Enable packet alignment debugging
    [ ]   Enable debugging output
    < > Generic IEEE 802.11 Networking Stack (DEPRECATED)

ACX kernel configuration (select either PCI/USB support or both)

Device Drivers  --->
  [*] Network device support  --->
    Wireless LAN  --->
      [*] Wireless LAN (IEEE 802.11)
            TI acx100/acx111 802.11b/g wireless chipsets
         [*]     TI acx100/acx111 802.11b/g PCI
         [ ]     TI acx100/acx111 802.11b/g USB (NEW)

3) Build

Issue a standard 'make' or 'make modules' command on the command line
in order to start the compilation of the kernel. Depending on the
kernel configuration you have chosen, this might take some time.

Refer to the kernel documentation for further information.

4) Installation

TODO -> description of the standard kernel module installation and the
'make modules_install' target. Refer to the kernel documentation for
now.

V) Firmware Images
------------------

The driver will try to load the following images via hotplug
(hotplug firmware directory location varies for different distros,
try /lib/firmware or /usr/lib/hotplug/firmware):

PCI driver: 'tiacxNNNcMM' (NNN=100/111, MM=radio module ID (in
uppercase hex)): combined firmware for specified chipset and radio.
Failing that, it will try to load images named 'tiacxNNN' (main
firmware for specified chipset) and 'tiacxNNNrMM' (corresponding
radio module). For example, my firmware is in file named
'tiacx111c16'. Alternatively, I may remove it and use pair of files
'tiacx111' and 'tiacx111r16' instead.

USB driver: image is named 'tiacxNNNusbcMM'

=> See also the wiki for more info

VI) hx4700 or rx1950 installation
--------------------------------

The acx-mac80211 driver includes slave-memory and platform module
support for the iPaq hx4700 and rx1950.

Here some complementary instructions for build, install and usage.

1) Select CONFIG_ACX_MAC80211_MEM and deselect CONFIG_ACX_MAC80211_PCI
and CONFIG_ACX_MAC80211_USB in the Makefile

2) Build the driver module with your tool chain (no more details,
since probably at this point corresponding cross-building know-how is
anyway present)

3) Build the platform module in the corresponding platform directory
(cd platform-(hx4700|rx1950); make)

4) Install the acx-mac80211.ko and (hx4700|rx1950)_acx.ko modules on
your machine

5) Install firmware, see above 

6) First load acx-mac80211, then the platform module

7) Driver should probe and the wlan interface appear.

-----
Copyright (C) 2008, 2010 The ACX100 Open Source Project
<acx100-devel@lists.sourceforge.net>

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 2 of the License, or (at
your option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

Original author:
	David Planella <david.planella AT gmail.com>

Updated by: 
  Oliver Winker <oliver AT oli1170.net>
