Atheros HAL: Overview

Introduction

The Atheros HAL is an abstraction layer which attempts to hide much of the card specific configuration from the rest of the atheros wireless driver.

The HAL takes care of the MAC, baseband and radio. It exports a set of routines which allow the atheros wireless driver to do certain tasks (set channel, configure TX queue, queue TX packet, queue RX buffer, setup interrupts, do calibration, set/get TX power, configure beacon parameters, enter power saving/sleep mode, etc.)

The HAL doesn't keep any kind of state about individual wireless stations; it doesn't handle 802.11 protocol negotiation such as station association or authentication.

It is structured in a way to make it easy to port to another operating system. A minimum set of operating system specific routines are kept in ah_osdep.[ch] in the ath driver directory. These are used by the HAL to do all platform specific tasks such as register/memory manipulation and debugging output.

Projects/Notes

Directory layout

sys/dev/ath/ath_hal/ - HAL includes, EEPROM routines, support routines, PCI device ids, debugging, etc
sys/dev/ath/ath_hal/ah_regdomain/ - HAL regulatory domain support
sys/dev/ath/ath_hal/ar5210/ - AR5210 MAC/radio support (11a only)
sys/dev/ath/ath_hal/ar5211/ - AR5211 MAC/radio support
sys/dev/ath/ath_hal/ar5212/ - AR5212 and related MAC/radio support
sys/dev/ath/ath_hal/ar5416/ - AR5416 (802.11n) and later support
sys/dev/ath/ath_hal/ar9001/ - AR9001 specific routines - AR9130, AR9160
sys/dev/ath/ath_hal/ar9002/ - AR9002 specific routines - AR9220, AR9280, AR9285, AR9287
sys/contrib/dev/ath/ath_hal/ar9300/ - Qualcomm Atheros AR9300 and later HAL

Chipset? MAC? Baseband? Radio? Huh?

This obviously needs a lot more detail, but a very quick overview should help clear things up.

Atheros wireless solutions traditionally are made up of a variety of modules. You can determine this information from the publicly available HAL source code.

MAC - controls packet scheduling, DMA, 802.11 state engine (timers, etc)
Baseband/PHY - handles the 802.11 radio encoding/decoding
Radio - handles the 2.4ghz/5ghz bit

In particular, the AR5212 and later can have different physical radios attached which implement different frequencies. Check out the ar5212Attach() routine in sys/dev/ath/ath_hal/ar5212/ar5212_attach.c for more background.

Later chips (began integrating the radio into the same physical silicon as the MAC/PHY. But the code still exists to support different radio frontends.

EEPROM handling

The Atheros wireless NICs come with EEPROMs which contain various device settings and calibration information. This includes (but isn't limited to):

regulatory information (which country the card was tested/sold for);
information about the chipset options to enable or disable;
maximum TX power settings for each channel;
TX rate and calibration.

The EEPROM layouts are documented in sys/dev/ath/ath_hal/ah_eeprom_{v1,v14,v4k,9287}.h.

The EEPROM API provides a consistent API for code to use without needing to know about the version or layout of the underlying EEPROM. This isn't always used - the AR5416 and later chipsets assume a specific EEPROM layout and hard-code access to it.

HAL Capability API

In order for the atheros wireless driver to function with a variety of underlying cards, the various options and configurations of the underlying card need to be somehow available to it in a consistent API that does not depend upon the underlying chipset or code.

The HAL capability API provides this. Each driver determines the set of hardware and software capabilities the specific card has available. The atheros driver then calls the HAL through the capabilities API to determine which features to enable.

Diagnostic API

(TODO)

API layout

HAL API Overview