Atheros HAL API

The Atheros HAL API is, as its name suggests, a “hardware abstraction layer” designed to hide the hardware specific building blocks from the ath(4) driver. It also provides a set of methods to extract statistics, configure optional behaviours of the hardware and get a list of hardware capabilities.

There is also support for pluggable RF modules for the various external radios supported by the Atheros chipset family. Starting with the AR9280 the radios are built-in rather than external but the framework lives on.

The HAL is broken up into a few areas:

• Regulatory information
• EEPROM decoding
• RF programming
• Everything else

There are a few design choices in the HAL code that are worth noting.

The HAL code is / was designed to be platform independent - ie, it should compile and be useful on a variety of differing operating systems and architectures. Although right now this HAL primarily targets *BSD (and FreeBSD in particular), a design aim is to keep this as a reference to be useful by other operating system projects (eg OpenSolaris, Haiku, ReactOS, etc.)

The HAL code supports multiple operating modes - ie, there is supposed to be one HAL for both station and access-point operation. In the past there was an AP-centric and STA-centric HAL.

The HAL layer assumes the driver layer is responsible for all locking and concurrency. There are no locks and no atomic operations in the HAL. Any kind of locking that is needed must be done by the driver.

The API is documented in ath_hal/ah.h . The debugging information is in ath_hal/ah_debug.h. The diagnostic API codes are in ath_hal/ah_diagcodes.h .

The HAL exposes two methods to do hardware probe and attach. These aren't registered with the main HAL structure; they instead are generally located in the xxxx_attach.c function in the chip directory; using the AH_CHIP() macro.

Similarly, the RF backends are registered through a call to the AH_RF() macro.

The “ath_hal” struct in ath_hal/ah.h contains the basic public facing state and method function pointers that are setup during device attach.

The “ath_hal_private” struct in ath_hal/ah_private.h contains the HAL-facing state which isn't directly exposed to the rest of the ath(4) driver layer. The first entry in ath_hal_private is an ath_hal struct.

Each HAL chipset will define its structure by declaring an ath_hal_private struct at the beginning.

The attach routine will then allocate a chipset specific struct (eg ath_hal_5212) from the operating system and fill that out. Because of the above, this allocation will include both ath_hal and ath_hal_private.

With this in mind, the order of the HAL state structure will look like this in memory:

• ath_hal
• ath_hal_private
• (chipset-specific HAL state)

Various macros are then used to get to the right state:

• AH_PRIVATE(ah) returns a pointer to the start of the private state;
• AHchip(ah) (eg AH5212(ah) ) will return a pointer to the start of the chip state.