Revision 6

Authors

SANA-II IEEE 802.11 wireless API by Neil Cafferkey

Overview

Several new commands have been added to the SANA-II API to facilitate use of IEEE 802.11 wireless network devices in client and ad-hoc modes. The new commands are split into two overlapping sets. One set needs to be implemented by drivers for Soft-MAC wireless devices, while the other is implemented for Hard-MAC devices.

Soft-MAC commands
S2_SETOPTIONS
S2_SETKEY
S2_WRITEMGMT
S2_READMGMT

Hard-MAC commands
S2_SETOPTIONS
S2_SETKEY
S2_GETNETWORKS
S2_GETNETWORKINFO
S2_GETSIGNALQUALITY

New constant and structure definitions

See new sana2wireless.h file below.

Description of new commands

S2_SETOPTIONS

/****** sana2.device/S2_SETOPTIONS *****************************************
*
*   NAME
*	S2_SETOPTIONS -- Set network options.
*
*   FUNCTION
*	Set various parameters for the network interface. This command
*	should be called before going online to set any essential parameters
*	not covered elsewhere. The S2INFO_#? tags used are defined in the
*	devices/sana2wireless.h include file.
*
*   INPUTS
*	ios2_Data - Pointer to a taglist that specifies parameters to use.
*
*   RESULTS
*	io_Error - Zero if successful; non-zero otherwise.
*	ios2_WireError - More specific error code.
*
****************************************************************************
*
*/

S2_SETKEY

/****** sana2.device/S2_SETKEY *********************************************
*
*   NAME
*	S2_SETKEY -- Set an encryption key.
*
*   FUNCTION
*	Sets one of the encryption keys for the device. Note that
*	ios2_StatData, if used, points to a byte array representing the RX
*	RX counter value.
*
*   INPUTS
*	ios2_WireError - Key index.
*	ios2_PacketType - Encryption type (e.g. S2ENC_WEP).
*	ios2_DataLength - Key length.
*	ios2_Data - Key.
*	ios2_StatData - RX counter number (NULL if unused).
*
*   RESULTS
*	io_Error - Zero if successful; non-zero otherwise.
*	ios2_WireError - More specific error code.
*
****************************************************************************
*
*/

S2_WRITEMGMT

/****** sana2.device/S2_WRITEMGMT ******************************************
*
*   NAME
*	S2_WRITEMGMT -- Write a management frame.
*
*   FUNCTION
*	Writes a raw IEEE 802.11 management frame to the device. The buffer
*	management mechanism used is simpler than that used for data
*	packets (e.g. with CMD_WRITE): a buffer pointer and a length value
*	are passed to the device.
*
*   INPUTS
*	ios2_DataLength - full frame length.
*	ios2_Data - pointer to a complete IEEE 802.11 management frame.
*
*   RESULTS
*	io_Error - Zero if successful; non-zero otherwise.
*	ios2_WireError - More specific error code.
*
****************************************************************************
*
*/

S2_READMGMT

/****** sana2.device/S2_READMGMT *******************************************
*
*   NAME
*	S2_READMGMT -- Read a management frame.
*
*   FUNCTION
*	Reads a raw IEEE 802.11 management frame from the device. The buffer
*	management mechanism used is simpler than that used for data
*	packets (e.g. with CMD_READ): a buffer pointer and a length value
*	are passed to the device.
*
*	As with CMDREAD/S2_READORPHAN, multiple S2_READMGMT requests can
*	(and should) be queued concurrently to ensure no incoming frames are
*	missed.
*
*   INPUTS
*	ios2_DataLength - size of frame buffer.
*	ios2_Data - pointer to a frame buffer.
*
*   RESULTS
*	io_Error - Zero if successful; non-zero otherwise.
*	ios2_WireError - More specific error code.
*	ios2_DataLength - actual size of received frame.
*	ios2_Data - pointer to the filled frame buffer.
*
****************************************************************************
*
*/

S2_GETSIGNALQUALITY

/****** prism2.device/S2_GETSIGNALQUALITY **********************************
*
*   NAME
*	S2_GETSIGNALQUALITY -- Get signal quality statistics.
*
*   FUNCTION
*	This command fills in the supplied Sana2SignalQuality structure with
*	current signal and noise levels. The unit for these figures is dBm.
*	Typically, they are negative values.
*
*   INPUTS
*	ios2_StatData - Pointer to Sana2SignalQuality structure.
*
*   RESULTS
*	io_Error - Zero if successful; non-zero otherwise.
*	ios2_WireError - More specific error code.
*	ios2_StatData - Pointer to filled Sana2SignalQuality structure.
*
****************************************************************************
*
*/

S2_GETNETWORKS

/****** prism2.device/S2_GETNETWORKS ***************************************
*
*   NAME
*	S2_GETNETWORKS -- Scan for available networks.
*
*   FUNCTION
*	This command supplies details of available networks. If the scan
*	should be limited to one specific network, the S2INFO_SSID tag
*	should specify its name.
*
*	If this command completes successfully, ios2_StatData will contain
*	an array of pointers to tag lists, each of which contains
*	information on a single network. The device will set ios2_DataLength
*	to the number of elements in this array.
*
*	The returned taglists are allocated from the supplied memory pool.
*	To discard the results of this command, the entire memory pool
*	should be destroyed.
*
*	The S2INFO_#? tags used with this command are defined in the
*	devices/sana2wireless.h include file.
*
*   INPUTS
*	ios2_Data - Pointer to an Exec memory pool.
*	ios2_StatData - Pointer to taglist that specifies parameters to use.
*
*   RESULTS
*	ios2_DataLength - Number of tag lists returned.
*	ios2_Data - Remains unchanged.
*	ios2_StatData - Pointer to an array of tag lists.
*	io_Error - Zero if successful; non-zero otherwise.
*	ios2_WireError - More specific error code.
*
****************************************************************************
*
*/

S2_GETNETWORKINFO

/****** prism2.device/S2_GETNETWORKINFO ************************************
*
*   NAME
*	S2_GETNETWORKINFO -- Get information on current network.
*
*   FUNCTION
*	This command provides information on the status of the currently
*	used network. If this command completes successfully, ios2_StatData
*	will contain a pointer to a tag list that contains information on
*	the network. The S2INFO_#? tags used are defined in the
*	devices/sana2wireless.h include file.
*
*	The returned taglist is allocated from the supplied memory pool.
*	To discard the results of this command, the entire memory pool
*	should be destroyed.
*
*   INPUTS
*	ios2_Data - Pointer to an Exec memory pool.
*
*   RESULTS
*	ios2_Data - Remains unchanged.
*	ios2_StatData - Pointer to a tag list.
*	io_Error - Zero if successful; non-zero otherwise.
*	ios2_WireError - More specific error code.
*
****************************************************************************
*
*/

sana2wireless.h

#ifndef DEVICES_SANA2WIRELESS_H
#define DEVICES_SANA2WIRELESS_H
 
#include <exec/types.h>
#include <utility/tagitem.h>
 
 
/* Constants */
/* ========= */
 
/* Tags to get and set information */
 
#define S2INFO_SSID           (TAG_USER + 0)
#define S2INFO_BSSID          (TAG_USER + 1)
#define S2INFO_AuthTypes      (TAG_USER + 2)
#define S2INFO_AssocID        (TAG_USER + 3)
#define S2INFO_Encryption     (TAG_USER + 4)
#define S2INFO_PortType       (TAG_USER + 5)
#define S2INFO_BeaconInterval (TAG_USER + 6)
#define S2INFO_Channel        (TAG_USER + 7)
#define S2INFO_Signal         (TAG_USER + 8)
#define S2INFO_Noise          (TAG_USER + 9)
#define S2INFO_Capabilities   (TAG_USER + 10)
#define S2INFO_InfoElements   (TAG_USER + 11)
#define S2INFO_WPAInfo        (TAG_USER + 12)
#define S2INFO_Band           (TAG_USER + 13)
#define S2INFO_DefaultKeyNo   (TAG_USER + 14)
 
/* Wireless Commands */
 
#define S2_GETSIGNALQUALITY 0xc010
#define S2_GETNETWORKS      0xc011
#define S2_SETOPTIONS       0xc012
#define S2_SETKEY           0xc013
#define S2_GETNETWORKINFO   0xc014
#define S2_READMGMT         0xc015
#define S2_WRITEMGMT        0xc016
#define S2_GETRADIOBANDS    0xc017
 
/* Encryption types */
 
#define S2ENC_NONE 0
#define S2ENC_WEP  1
#define S2ENC_TKIP 2
#define S2ENC_CCMP 3
 
/* Radio modes */
 
#define S2BAND_A 0
#define S2BAND_B 1
#define S2BAND_G 2
#define S2BAND_N 3
 
/* Network topologies */
 
#define S2PORT_MANAGED 7
#define S2PORT_ADHOC   8
 
 
/* Structures */
/* ========== */
 
/* Structure for returning signal quality */
 
struct Sana2SignalQuality
{
   LONG SignalLevel;   /* signal level in dBm */
   LONG NoiseLevel;   /* noise level in dBm */
};
 
#endif