✎ wirelessboot:drivers - Etherboot/gPXE Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Writing wireless card device drivers ======

===== Basic stuff =====
gPXE implements wireless support using a wrapper around a
''net_device'', following much the same concept as the Infiniband
subsystem. Since 802.11 uses Ethernet-style addressing, it is not
necessary to devise a separate means for handling "IP over 802.11";
there only needs to be an association between a generic ''net_device''
for a particular wireless card and the ''net80211_device''
representing its 802.11-specific attributes. For simplicity of design
I chose to have the ''net_device'' wrap the ''net80211_device'',
instead of vice versa; that way we don't have to worry about queueing
packets or tracking TX completions ourselves.

As much as possible, I have tried to keep the wireless API analogous to
that for wired NICs except where additional functionality in the
wireless realm forces differences. Because a wireless device is
encapsulated in a ''net_device'', though, almost all gPXE code need
know nothing about wireless. Calling wireless-specific functions is
necessary only for wireless drivers and perhaps in the future some
wireless-specific code in other areas. Such calls should generally be
avoided, because they introduce a link-time dependency on the rather
large 802.11 stack; when the file introducing them can be compiled in
or out due to a configuration option, the ''REQUIRE_OBJECT()'' calls
should be placed in ''net/80211/config_80211.c'' instead of
''core/config.c'' to avoid ever pulling in the objects without a
wireless stack present to make them useful.

When a wireless network card's driver ''probe()'' function is called,
it acts much the same as a wired NIC, setting up device fundamentals and
registering itself with the network stack. An 802.11 device is
allocated using ''net80211_alloc()'' and registered using
''net80211_register()''; the driver must additionally pass some
hardware-specific information about the wireless capabilities of the
device it is registering. A wrapping ''net_device'' is created and
registered behind the scenes in this call, and it can later be
accessed by the ''netdev'' field in the ''net80211_device'' structure
in use.

In all of the following, ''netdev'' denotes a pointer to a
''net_device'' structure and ''dev'' denotes a pointer to a
''net80211_device'' structure.

===== Use in a wireless driver =====

In general, in an 802.11 driver, ''net80211_device'' simply takes the
place of ''net_device''. Some of the fields in ''net_device'' must
continue to be accessed through the ''dev->netdev'' wrapper structure
pointer, while others have analogues in the ''net80211_device''
structure directly. Specifically:
  * For a wired NIC, the proper MAC address to use is always
    ''netdev->ll_addr''. For a wireless NIC, there are two available:
    ''dev->netdev->ll_addr'' is the MAC address most recently
    configured by the user, and ''dev->hw->hwaddr'' is the MAC address
    burned into the card. Usually (e.g. for setting the RX filter) the
    former should be used.
  * Any access to ''netdev->name'' and ''netdev->ll_protocol'' should
    continue to use the wrapping ''net_device''.
  * The ''netdev->state'' field retains its validity, but for wireless
    it does not provide much status detail. The ''netdev->link_rc''
    field is useful for presenting a user-visible error, and it keeps
    its value until a different error or a success. For programmatic
    status information, ''dev->state'' contains the most recent 802.11
    status code and several bits indicating how network association is
    progressing.
  * The ''netdev->priv'' now points to the wrapped ''net80211_device''
    structure. Driver-private data must be accessed using
    ''dev->priv'' (the ''priv'' field in the ''net80211_device'' itself).

There are also //many// more fields in ''net80211_device'' than in
''net_device'', owing to the significant added complexity of
wireless. Those that a driver writer needs to know about are:
  * ''dev->hw'' contains a pointer to the ''net80211_hw_info''
    structure passed to ''net80211_register()''.
  * ''dev->channels'' is a list of 802.11 channels that might be used,
    each identified by a structure indicating center frequency,
    standard channel number, transmission power, etc.
    ''dev->nr_channels'' contains a count of channels, and
    ''dev->channel'' is the index of the channel currently in use.
  * In the same vein, ''dev->rates'' is an array of transmission rates
    counted by ''dev->nr_rates'' and indexed by ''dev->rate''. For
    simplicity, rates are not represented using a structure, but
    instead simply as an integral multiple of 100,000 bits per second.
  * ''dev->rtscts_rate'' is the index of the rate that should be used
    for RTS and CTS (request-to-send and clear-to-send) frames, if
    their use is necessary.
  * ''dev->bssid'' is the MAC address of the Access Point with which
    the card is associated; generally this is used in setting the RX
    filter.
  * ''dev->phy_flags'' is a bitmask of physical-layer flags (whether
    or not to use short preamble, short slot time, or CTS protection)
    that the driver must communicate appropriately to the card.

To manage these additional wireless-specific issues, a new API
function is added to ''net80211_device_operations'': ''config()'',
passed a pointer to the device and a bitmask of what (from the set of
channel, TX rate, association, and PHY parameters) has changed. In all
cases the changes are not passed directly; the changed parameters are
updated in the ''net80211_device'' structure before the call, and the
driver is expected to update the card's understanding to match them.
It is possible for a bit to be set in the ''changed'' argument without
the underlying parameter having actually changed, but this is expected
to be rare.

The operations structure is otherwise perfectly analogous to
''net_device_operations'', with the obvious substitution of
''net80211_device'' structures for ''net_device'' structures in
arguments.

The creation and registration process for an 802.11 device is fairly
similar to that for a regular network device: ''net80211_alloc()''
passing the size of a driver-private data area to allocate, followed
by field-filling and ''net80211_register()''. Differences lie in the
fact that ''net80211_register()'' expects both the device operations
structure and an 802.11-specific hardware information structure. There
is no analogue to ''netdev_init()''; initialisation is performed by
either the allocation or the registration function as
appropriate. Before freeing an 802.11 device, it must be unregistered
using ''net80211_unregister()''. 802.11 devices are not
reference-counted, so they should be freed using ''net80211_free()''
rather than a combination of nullify and put.

As in the wired case, drivers must supply notification to the network
layer of received and transmitted packets:

    void net80211_rx ( struct net80211_device *dev, struct io_buffer *iob,
                       int signal, u16 rate );

Called with a received packet in ''iob'', which the network layer
takes ownership of. In ''signal'', pass a hardware-level signal
strength indication; it will be interpreted according to the
information specified in the hardware info structure passed to
''net80211_register''. In ''rate'', pass the bitrate used to receive
the packet, as usual in units of 100 kbps. This information is used
to adaptively set the best TX rate.

    void net80211_rx_err ( struct net80211_device *dev,
                           struct io_buffer *iob, int rc );

Called when it is known that reception of a packet failed (e.g. due to
a reported CRC error). If ''iob'' is non-NULL, it is freed, and an
error of type ''rc'' is recorded in the ''net_device'' rx statistics.

    void net80211_tx_complete ( struct net80211_device *dev,
                                struct io_buffer *iob, int retries, int rc );

Called when a transmission completes, whether successfully or
no. (There is no separate net80211_tx_complete_err() function for
error conditions.) ''rc'' must be set to 0 if the transmission was
ultimately successful, or an error code if it failed. If the
transmission had to be retried before it succeeded, this should be
reflected in a nonzero ''retries'' value, measuring the number of
failed transmissions before the successful one.
Trace: • derekpryor • san_transfer • under_construction • revised_timeline • memsearch
Navigation

Search

Toolbox

QR Code
