[[PageOutline(2-5)]]

= HAL =

This term is short for "Hardware Abstraction Layer". In context of !MadWifi it refers to a piece of software that all direct access to the Atheros hardware is routed through. Please note that the [http://www.freedesktop.org/wiki/Software/hal HAL] promoted by freedesktop.org.

Unlike many other wireless devices Atheros chipsets can use a wide range of frequencies and the host software can control many aspects of the radio. Regulatory agencies all over the world have laws which restrict the use of the wireless spectrum to certain frequency bands under specific transmission power levels. These laws drive wireless manufacturers to come up with solutions to enforce compliance with the wide array of regulatory agencies.

The original !MadWifi author, Sam Leffler, and Atheros agreed on the concept of using a proprietary HAL as wrapper around the hardware registers. The HAL is distributed in binary form only, so that unauthorized users can not easily modify it. It ensures that non-compliant settings are not applied to the radio, while allowing the open source part of the driver to interact with the chipset in a permissive manner. It's a compromise that tries to meet the requirements of both, the open source community and the regulatory agencies.

== Frequently Asked Questions ==

In the following we would like to answer some of the most often asked questions about the binary HAL.

=== Is the HAL some kind of firmware? ===

Not exactly. The HAL performs tasks similar to that of a firmware, such as implementing an API to present the hardware to the driver in a nice, uniform fashion. But the term 'firmware' generally refers to code executed by an onboard microcontroller or DSP on the controlled device, while the HAL is executed on the host CPU. 

=== Why is the HAL closed source? ===

As explained above, the Atheros chipsets can tune to a wide range of frequencies, part of them being outside the bands that are permitted for unlicensed use (ISM-bands). Non-ISM-frequencies are licensed by various regulatory agencies for different purposes, such as military or civil radar use, military communications, wireless local loop installations, and so on. Furthermore, there may be regulations on the allowed transmission power on different frequencies, and on conditions such as indoor or outdoor use.

The Atheros chipsets are capable of operating on frequencies outside those that are licensed, or legal to use without a license, and can vary the transmission power on these frequencies. So there must be some mechanism for enforcing the frequencies that are used. The limitations in regards to legal frequencies and transmission power change depending on the given region (such as Japan, UK, USA, etc), thus the HAL changes its behaviour depending on the regulatory domain and country code.

At least the USA Federal Communications Commission (FCC) requires that any manufactured products have a mechanism for limiting transmission power and frequencies, and that these mechanisms are not easily modifiable by the consumer. If you are in a region that limits the number of frequencies, say, Japan, it is illegal to broadcast out of those assigned channels, even though the chip is capable of operating outside of the limited frequency band assigned by Japan.

=== Isn't binary-only code EVIL? ===

The Free Software and Open Source (FOSS) movements have good reasons for their philosophies and ideologies and you can read about them on their websites. However, due to regulations by regulatory authorities for the airwaves, Atheros sees itself unable to release open specifications and/or code to set frequencies and transmission powers.

On the other hand, the binary HAL forces developers to deal with a black box that they can neither fix nor fully understand. The fact that Atheros and Sam Leffler have shown a lot of commitment to the Linux platform mitigates that a bit fortunately.

As far as the !MadWifi team is concerned: we did support the HAL approach as long as no acceptable alternative existed, but decided to take a different road. The binary HAL is not evil per se, but we see alternative ways to achieve the same goal with fewer negative side effects.

=== What happens if Atheros goes out of business? ===

The HAL will always be available, as long as you have a copy of it. But it might well be that it won't be developed further in this case, but that's the same problem you'll face with virtually any other vendor. I.e. if Prism were to go out of business the firmware for their cards would no longer be actively developed, but would still be available on the net.

=== What about licensing issues? ===

If you want to see Linus' view on firmware vs binary drivers, [http://www.win.tue.nl/~aeb/linux/lk/COPYING-modules.txt here's] a collection of his e-mail on the subject. Interestingly, Linus says: You just can't make a binary module for Linux, and claim that that module isn't derived from the kernel. Because it generally is - the binary module not only included header files, but more importantly it clearly is _not_ a stand-alone work any more. So even if you made your own prototypes and tried hard to avoid kernel headers, it would _still_ be connected and dependent on the kernel.

!MadWifi gets around this by applying orthogonality to the problem. Rather than use a single precompiled binary module, the HAL module is split into two sections: the precompiled binary and ah_os.o (which comprises of [source:trunk/ath_hal/ah_os.c ah_os.c], [source:trunk/ath_hal/ah_os.h ah_os.h] and [source:trunk/ath_hal/ah_osdep.h ah_osdep.h]) that acts as an intermediary between the kernel and the binary HAL. The two sections are linked, and together they become the loadable kernel module ath_hal.o.

This design orthogonality means that the HAL binary is able to work without modification on any version of the Linux kernel, as well as the BSDs, and a few other embedded projects. All that needs modifying is the ah_osdep.c, which must map HAL and kernel function calls to one another.

So, to conclude, hal.o (the binary module) is not a derived work of the linux (or any other) kernel, however {{{ath_hal.o}}} (the fully built and linked module) is, because the file ah_osdep.o does all of the OS specific mapping.

=== What kind of access does the HAL have to my system's internals? ===

Because the HAL is a kernel module it runs in kernel space. It can therefore do anything it wants to any of the system's internals. However, all access to and from the HAL is done through the OS dependent wrapper, at least, as far is verifiable. Standard problems with pointers and memory access in low-level languages remain.

=== Are there alternatives to the binary HAL? ===

In terms of functionality there is not yet an equivalent alternative to the Atheros HAL, but [wiki:About/OpenHAL we're working on it].