source: arduino-1-6-7/trunk/fuentes/arduino-ide-amd64/hardware/arduino/avr/firmwares/wifishield/wifiHD/src/SOFTWARE_FRAMEWORK/COMPONENTS/WIFI/HD/wl_api.h @ 4837

Last change on this file since 4837 was 4837, checked in by daduve, 2 years ago

Adding new version

File size: 60.4 KB
Line 
1/*
2 *  Programming interface for wl_api.
3 *  Copyright (C) 2010 HD Wireless AB
4 *
5 *  You should have received a copy of the license along with this library.
6 */
7
8/*! \file wl_api.h *************************************************************
9 *
10 * \brief Basic WiFi API
11 *
12 * This file provides the wl_api interface.
13 *
14 * - Compiler:           GNU GCC for AVR32
15 * - Supported devices: 
16 *  \li SPB104 + EVK1100
17 *  \li SPB104 + EVK1101
18 *  \li SPB104 + EVK1104
19 *  \li SPB104 + EVK1105 (SPI)
20 *  \li SPB104 + EVK1105 (SPI + irq)
21 *  \li SPB105 + EVK1105 (SPI)
22 * - AppNote:
23 *
24 * \author               H&D Wireless AB: \n
25 *
26 *****************************************************************************
27 *
28 * \section intro Introduction
29 * This is the documentation for the generic WiFi Driver API \a wl_api.
30 *
31 * \section files Main Files
32 * - wl_api.h : WiFi driver interface.
33 * - lib_ucr*_hd_wifi_standalone_v*.*.a - Driver library.
34 *
35 */
36/** \mainpage wl_api Reference Manual
37
38\image html images/wl_api_block_diagram_small.png "wl_api Architecture"
39
40(o)WL API © is a programming interface for WiFi (802.11). It aims
41to be a complete interface for embedded applications wanting to use
42wireless as a communications interface. (o)WL API © is shortened
43"wl_api" in this document.
44
45wl_api has been designed to meet the following goals :
46 \li Simple : The API is as simple as is practicable
47   to make it easy to use.
48 \li Minimal size : The API is usable on very resource constrained
49   platforms.
50 \li Portable : The API is deployable on any platform with a standards
51   compliant C compiler.
52 \li OS independent : The API is deployable on systems using a real time
53   operating system as well as with applications running on the
54   "bare metal" of a hardware platform (that is without an operating system).
55
56As a consequence of these design goals wl_api does not allow very fine
57grained control of most parameters relating to 802.11 networks. That
58would increase the flexibility of the API while also increasing
59complexity and code size. When the underlying WiFi hardware can
60support a richer feature set the extra features can be offered as a
61add-on library if required.
62
63The wl_api is implemented by two libraries. The core library is
64compiled for a hardware platform and is independent of operating
65system or IP stack.  The core library contains all WiFi
66functionality. The core library is supported by a suite of transport
67libraries. The transport libraries implements the hardware
68communication layer and are specific to the type of hardware interface
69used to connect the host platform to the WiFi hardware. For example,
70there are transport libraries for SPI and for SDIO. Only the core
71library has a public interface (wl_api.h) but applications will need
72to link with both the core library and a transport library matching
73the hardware configuration.
74
75\section wl_api_princ Operation Principles
76
77There are three important properties of wl_api to keep in mind when
78programming with it.
79
80The first is that wl_api is \b asynchronous. For instance, when the
81\a wl_connect() function is called to attempt connection with an access
82point it will trigger a sequence of packets being exchanged with the
83access point after which, if everything is okay, a connection has been
84established. The \a wl_connect() call is asynchronous (or non-blocking)
85which means that you don't know if the connection attempt has
86succeeded after the call returns. You only know if the sequence was
87successfully started or not. To find out if, and when, the connection
88attempt was successful you must register an event handler using the
89function \a wl_register_event_cb(). This is true of a number of API calls
90(which is indicated in their documentation).
91
92The second important property is that wl_api is \b polled.  wl_api
93never executes "by itself", since it would then have to support
94interrupts, timers, locks and other operating system dependent
95features.  Instead all asynchronous processes proceed when wl_api is
96polled by calling the \a wl_tick() function. When \a wl_tick() is called
97wl_api reacts to any received management frames, expires any internal timers and
98performs any other tasks necessary for forward progress. After
99\a wl_tick() returns nothing will happen unless it or some other wl_api
100function is called again. Also, to send and receive data, the \a wl_process_rx()
101and \a wl_process_tx() must be invoked upon reception and transmission of data.
102
103The third important property is that wl_api is \b not \b thread \b safe.
104All wl_api calls must execute in the same context since the
105library has no knowledge of the locking mechanisms available (if any).
106
107\section wl_api_code_examples A note on the code examples
108
109The code examples illustrate how to call the different wl_api functions.
110They do not constitute a complete program. Functions with the prefix "app_"
111in the code examples are application specific calls that illustrate a
112particular action. These functions are not part of the API and will have
113to be implemented if needed. For a complete working code example see
114one of the H&D Wireless software reference designs, such as the WiFi HTTP
115server demo code in the Atmel Software Framework.
116
117The API is structured into these functional groups:
118
119\li \ref wl_api
120\li \ref wl_wifi
121\li \ref wl_data
122\li \ref wl_transport
123\li \ref wl_custom
124
125Also documented here is the transport layers for SPI and SDIO.
126There interfaces are only necessary when porting the library to
127a new hardware platform.
128
129\li \ref wl_spi
130\li \ref wl_sdio
131
132 * \section contactinfo Contact Information
133 * For further information, visit
134 * <A href="http://www.hd-wireless.se/">H&D Wireless</A>.\n
135 * Support and FAQ: http://www.atmel.com/
136 */
137 
138#ifndef WL_API_H
139#define WL_API_H
140 
141#define WL_API_RELEASE_NAME "v2.7.0"
142
143/*! Maximum size of a SSID */
144#define WL_SSID_MAX_LENGTH 32
145/*! Size of a MAC-address or BSSID */
146#define WL_MAC_ADDR_LENGTH 6
147/*! Maximum length of a passphrase */
148#define WL_MAX_PASS_LEN 64
149/*! Indicates that there is no SNR information */
150#define WL_SNR_UNKNOWN -128
151
152#define SPB104 104
153#define SPB105 105
154 
155/*! \ingroup wl_api
156 * API Error codes */
157typedef enum {
158        WL_FAILURE = -1,
159        WL_SUCCESS = 1,
160        WL_NOEFFECT,
161        WL_OOM,
162        WL_INVALID_LENGTH,
163        WL_NOT_SUPPORTED,
164        WL_ABSORBED,
165        WL_RESOURCES,
166        WL_BUSY,
167        WL_RETRY, /*!< Retry the operation later. The driver is busy
168                    resolving an operation that conflicts with the
169                    request. */
170        WL_INVALID_ARGS,
171        WL_AVAIL,
172        WL_CARD_FAILURE,        /*!< Could not detect SPB device */
173        WL_FIRMWARE_INVALID,    /*!< Invalid firmware data */
174
175} wl_err_t;
176
177/*! \ingroup wl_wifi
178 * Event identifiers */
179enum wl_event_id_t {
180        WL_EVENT_MEDIA_CONNECTED = 0,
181        WL_EVENT_CONN_FAILURE,
182        WL_EVENT_MEDIA_DISCONNECTED,
183        WL_EVENT_SCAN_COMPLETE,
184        WL_EVENT_FAILURE,
185        MAX_WL_EVENT
186};
187
188/*! \ingroup wl_wifi
189 * Authentication modes */
190enum wl_auth_mode {
191        AUTH_MODE_INVALID,
192        AUTH_MODE_AUTO,
193        AUTH_MODE_OPEN_SYSTEM,
194        AUTH_MODE_SHARED_KEY,
195        AUTH_MODE_WPA,
196        AUTH_MODE_WPA2,
197        AUTH_MODE_WPA_PSK,
198        AUTH_MODE_WPA2_PSK
199};
200
201/*! \ingroup wl_wifi
202 * Encryption modes */
203enum wl_enc_type {  /* Values map to 802.11 encryption suites... */
204        ENC_TYPE_WEP  = 5,
205        ENC_TYPE_TKIP = 2,
206        ENC_TYPE_CCMP = 4,
207        /* ... except these two, 7 and 8 are reserved in 802.11-2007 */
208        ENC_TYPE_NONE = 7,
209        ENC_TYPE_AUTO = 8
210};
211
212enum wl_host_attention_mode {
213        WL_HOST_ATTENTION_SDIO = 0x1, /*!< For SDIO or polled SPI */
214        WL_HOST_ATTENTION_SPI  = 0x5a /*!< For SPI with interrupt line */
215};
216
217/*! \ingroup wl_wifi
218 * Event descriptor
219*/
220struct wl_event_t {
221        enum wl_event_id_t id;  /**< Event identifier. */
222
223};
224
225/*! \ingroup wl_wifi
226 * Infrastructure (ESS) or Ad-hoc (IBSS) connection modes.
227 */
228enum wl_conn_type_t {
229        WL_CONN_TYPE_INFRA, /*!< For infrastructure mode (default) */
230        WL_CONN_TYPE_ADHOC  /*!< For ad-hoc mode */
231};
232
233/* Note:
234 * If your environment does not have stdint.h you will have to
235 * define the fixed-width integer types specified in that file
236 * yourself, make sure that those definitions are included
237 * before any inclusions of wl_api.h, and build with the macro
238 * WITHOUT_STDINT defined. In this case the wl_api library
239 * must have been built with the same integer type definitions.
240 */
241
242#ifndef WITHOUT_STDINT
243#include <stdint.h>
244#endif
245
246/* Note:
247 * If your environment does not have stdio.h you will have to define
248 * the size_t type yourself, make sure that that definition is
249 * included before any inclusions of wl_api.h, and build with the
250 * macro WITHOUT_STDIO defined. In this case the wl_api library must
251 * have been built with the same size_t type definition.
252 */
253#ifndef WITHOUT_STDIO
254#include <stdio.h>
255#endif
256
257/*! \ingroup wl_wifi
258 *
259 * \brief SSID representation.
260 *
261 * The SSID is a binary string and cannot be treated as a
262 * C-string safely. An empty SSID is represented by a
263 * SSID struct with the len field set to 0.
264 */
265struct wl_ssid_t
266{
267        char ssid[WL_SSID_MAX_LENGTH]; /**< Octet array containing the SSID data. */
268        uint8_t len; /**< Length of valid data in ssid member.
269                      *   Cannot be longer than WL_SSID_MAX_LENGTH. */
270};
271
272/*! \ingroup wl_wifi
273 *
274 * MAC-address/BSSID representation
275 *
276 * A broadcast BSSID is one with all octets set to 0xFF.
277 */
278struct wl_mac_addr_t
279{
280        uint8_t octet[WL_MAC_ADDR_LENGTH]; /**< Octet array containing the MAC address
281                                            * data. This array is always WL_MAC_ADDR_LENGTH bytes.
282                                            */
283};
284
285/*! \ingroup wl_wifi
286 *
287 * Network representation
288 *
289 */
290struct wl_network_t
291{
292        struct wl_ssid_t ssid; /**< The SSID of the network. */
293        struct wl_mac_addr_t bssid; /**<  The BSSID of the network. */
294        uint8_t channel; /**< The wlan channel which the network uses */
295        uint32_t beacon_period; /**< Beacon period for the network */
296        uint16_t dtim_period; /**< DTIM period for the network */
297        int32_t rssi; /**< Received Signal Strength in dBm (measured on beacons) */
298        int32_t snr; /**< Received Signal to noise ratio in dBm (measured on beacons) */
299        uint8_t enc_type; /**< The encryption type used in the network. */
300   
301        enum wl_conn_type_t net_type; /**< Type of network (Infrastructure or Ad-Hoc */
302        size_t ie_len;    /**< Always 0 unless wl_api has been built with WL_CONFIG_WPA_SUPPLICANT */
303                             
304        uint8_t ie[0]; /**< Not used unless wl_api has been built with WL_CONFIG_WPA_SUPPLICANT */
305};
306
307/*! \ingroup wl_wifi
308 * Network list representation. Array of pointers to wl_network_t entries.
309 *
310 */
311struct wl_network_list_t
312{
313        struct wl_network_t **net; /**< The list of pointers to networks */
314        size_t cnt;                /**< Number of networks */
315};
316
317#define WL_RATE_1MBIT      2
318#define WL_RATE_2MBIT      4
319#define WL_RATE_5_5MBIT    11
320#define WL_RATE_6MBIT      12
321#define WL_RATE_9MBIT      18
322#define WL_RATE_11MBIT     22
323#define WL_RATE_12MBIT     24
324#define WL_RATE_18MBIT     36
325#define WL_RATE_22MBIT     44
326#define WL_RATE_24MBIT     48
327#define WL_RATE_33MBIT     66
328#define WL_RATE_36MBIT     72
329#define WL_RATE_48MBIT     96
330#define WL_RATE_54MBIT     108
331#define WL_RATE_NUM_RATES  14
332#define WL_RATE_INVALID    WL_RATE_NUM_RATES
333
334/*! \ingroup wl_wifi
335 *
336 * Rate representation
337 *
338 */
339typedef uint8_t wl_rate_t;
340   
341/** \defgroup wl_api Library support functions
342 *
343 * These functions manage the library in general. They concern initalizing
344 * the library, downloading firmware to the WiFi chip and handling events
345 * from the library.
346
347For this example we assume that the application is running stand-alone
348without an operating system.
349
350Before the library can do anything it needs to start up the WiFi
351hardware by downloading a firmware image. The firmware image is
352relatively big (around 144kB) and is therefore not included in the library
353it is only needed once. It is up to the application to decide where to
354store the firmware image and how to read it into the wl_api library.
355
356Step one is to write a function of the type \a ::wl_fw_read_cb_t
357that wl_api will call to retrive the firmware image. Assuming that you
358have some spare RAM (or whatever memory type is used for read only
359data, such as FLASH memory) on your platform you can simply include
360the firmware image from the \a wl_fw.h header file and write a
361firmware read function like this
362
363\code
364static size_t fw_read_cb(void* ctx,
365                         uint8_t** buf,
366                         size_t offset,
367                         size_t len)
368{
369        if ( NULL == buf ) {
370                return 0;
371        }
372        *buf = ((uint8_t*) fw_buf) + offset;
373        if ( len > ( fw_len - offset ) ) {
374                return fw_len - offset;
375        }
376        return len;
377}
378
379\endcode
380
381If the firmware image is stored in ROM this function may have to read
382it back block by block instead.
383
384First, firmware must be downloaded to the device
385
386\code
387if ( wl_transport_init(fw_read_cb, NULL, &mode) != WL_SUCCESS ) {
388        app_error("Firmware download failed");
389        return 0;
390}
391\endcode
392
393The wl_api library is then initialized like this
394
395\code
396if ( wl_init(NULL, init_complete_cb, mode) != WL_SUCCESS ) {
397        app_error("Init failed");
398        return 0;
399}
400\endcode
401
402The library startup process will now require \a wl_poll() to be called
403a number of times before it can complete. In addition, if the
404application needs to know when the startup process has completed so
405that it can, for example, start up an IP stack it will have to supply
406a valid callback function of the type \a ::wl_init_complete_cb_t as a parameter
407to the \a wl_init() call and start polling the wl_api library.
408
409The init complete callback will only be executed during a call to \a wl_poll()
410or another wl_api function. This simplifies the implementation since no
411internal locking is required and the wl_api library becomes OS-independent.
412
413\code
414static void init_complete_cb(void* ctx) {
415       init_ip_stack();
416}
417\endcode
418
419Registering the event callback is straightforward :
420
421\code
422if (wl_register_event_cb(event_cb, NULL) != WL_SUCCESS) {
423       app_error("Failed to register event handler");
424       return 0;
425}
426\endcode
427
428Similar to \a wl_poll(), there is also a \a wl_tick() function that takes a
429free running "tick" counter with millisecond resolution as an argument so
430that it can trigger internal timers when necessary. Assuming that such a tick
431counter is provided by the macro GET_MS_TICK() the wl_api execution loop becomes
432
433\code
434while (TRUE) {
435       wl_tick(GET_MS_TICK());
436       wl_poll();
437}
438\endcode
439
440In a stand-alone application this loop would usually be the main application
441loop and include application specific calls as well.
442
443After some number of main loop iterations the init_complete_cb will be
444invoked and the application can initialize its IP stack.
445
446 *  @{
447 */
448
449/*! \brief WiFi event callback.
450 *
451 * This function receives WiFi events that the application
452 * wants notification of. This function is supplied by the user
453 * of the API.
454 *
455 * @param event Struct describing the type of event and, for some
456 *              events, additional information regarding the
457 *              status of the event. See wl_event_t for additional
458 *              information.
459 * @param ctx   A context handle. This handle is passed
460 *              untouched to the callback and has the same value
461 *              as the context registered with the callback in
462 *              wl_register_event_cb().
463 */
464typedef void (*wl_event_cb_t) (struct wl_event_t event, void* ctx);
465
466
467/*! \brief Initialization complete callback function.
468 *
469 * Invoked when WiFi initialization is complete.
470 *
471 * @param ctx Opaque context pointer as provided to \a wl_init() that will be
472 *            passed back to the callback.
473 */
474typedef void (wl_init_complete_cb_t)(void* ctx);
475
476 
477/*! \brief Register an event handler.
478 *
479 * Register an event handler with the driver. This
480 * event handler will be called whenever a event
481 * listed in #wl_event_id_t occurs.
482 * See #wl_event_cb_t and #wl_event_id_t for more details.
483 *
484 * @param cb Event callback function to register.
485 * @param ctx Opaque context pointer that will be
486 *            passed to the callback when it is
487 *            invoked. This parameter is never
488 *            accessed by the API.
489 * @return WL_SUCCESS
490 */
491wl_err_t wl_register_event_cb(wl_event_cb_t cb, void* ctx);
492
493/*! \brief Initialize the wl_api library.
494 *
495 * Note that \a wl_poll() must be called for this function to progress
496 * towards complete init
497 *
498 * The startup process will proceed asynchronously and will inkove
499 * init_complete_cb when completed. The callback will not be invoked if any
500 * error occurs during initialization.
501 *
502 * This function should be called after firmware has been downloaded to the
503 * device.
504 *
505 * @param ctx Opaque context pointer that will be passed to the callback
506 *            when invoked. This parameter is never accessed by the API.
507 * @param init_complete_cb callback function to invoke when initialization is
508 *        complete.
509 * @param mode Indicates the host attention mode used by the device. If
510 *         \a wl_transport_init() was used to download the firmware image to the
511 *         device, the proper mode can be obtained from the mode parameter of
512 *         that function.
513 *
514 * @return
515 * - WL_SUCCESS
516 * - WL_FAILURE
517 */
518wl_err_t wl_init(void* ctx, wl_init_complete_cb_t init_complete_cb,
519                 enum wl_host_attention_mode mode);
520
521
522/*! \brief Shutdown the wl_api library and free resources.
523 *
524 * \a wl_init() must be invoked to startup the library
525 * again.
526 *
527 * @return
528 * - WL_SUCCESS on success
529 * - WL_FAILURE
530 *
531 */
532wl_err_t wl_shutdown(void);
533
534
535/*! \brief WiFi driver timer tick function
536 *
537 * Periodic timers are triggered from this function so it should be called as
538 * often as possible if precision timing is required (traffic timeouts,
539 * authentication timeouts etc).
540 *
541 * @param tick A tick count in us. This is used to expire timers
542 *  in the driver.
543 */
544void wl_tick(uint32_t tick);
545
546/*!  @} */
547
548
549/** \defgroup wl_wifi Connection Management
550 *
551 * These functions access WiFi-specific functionality such as
552 * scanning, connect/disconnect, authentication and encryption,
553 * and power save modes.
554 *
555
556\section scanning Scanning
557
558To scan all channels that are available in the current regulatory
559domain
560
561\code
562       if ( wl_scan() != WL_SUCCESS ) {
563              // May be busy scanning already, no fatal error
564              return 0;
565       }
566\endcode
567
568Since wl_scan() only starts the scanning process the application
569should add code to the event handler to catch the "scan complete" event
570and retrieve the list of seen networks from the library
571
572\code
573static void event_cb(struct wl_event_t event, void* ctx) {
574       switch(event.id) {
575              case WL_EVENT_SCAN_COMPLETE:
576                     struct wl_network_list_t *netlist;
577                     uint8_t netcnt;
578                     
579                     wl_get_network_list(&netlist);
580                     netcnt = netlist->cnt;
581                     while (--netcnt) {
582                             print_network(netlist->net[netcnt]);
583                     }
584                     break;
585       }
586}
587\endcode
588
589The function print_network() could display the network name, the SSID, in
590a user interface. It is important to keep in mind is that despite the fact
591that the SSID is usually presented as a ASCII string, it is
592in fact just a byte string and can legally contain all kinds of
593non-printable characters, including a 0-byte. This means that it is
594easy to end up with buffer overrun bugs if the SSID is ever treated
595as a normal string without precautions.
596
597\code
598void print_network(struct wl_network_t* wl_network)
599{
600        char ssid[WL_SSID_MAX_LENGTH + 1];
601        memset(ssid, 0, sizeof(ssid));
602        memcpy(ssid, wl_network->ssid.ssid, wl_network->ssid.len);
603        if (app_is_printable(ssid)) {
604                app_print("\"%s\" ", ssid);
605        }
606        else {
607                app_print("<binary SSID> ");
608        }
609        switch (wl_network->enc_type) {
610        case ENC_TYPE_WEP :
611                app_print("(WEP encryption)");
612                break;
613        case ENC_TYPE_TKIP :
614                app_print("(TKIP encryption)");
615                break;
616        case ENC_TYPE_CCMP :
617                app_print("(CCMP encryption)");
618                break;
619        }
620        app_print("\n");
621}
622\endcode
623
624\section connecting Connecting
625
626To connect to an access point (beware binary SSIDs) the connection process
627must be started
628
629\code
630         if ( wl_connect("My AP", strlen("My AP"))
631              != WL_SUCCESS ) {
632              app_error("Connection failed.\n");
633              return 0;
634         }
635\endcode
636
637and the \a WL_EVENT_MEDIA_CONNECTED and \a WL_EVENT_CONN_FAILURE events should be
638caught. To detect that a connection is terminated after it has been successfully established
639(such as when the AP goes out of range) the \a WL_EVENT_MEDIA_DISCONNECTED event
640must be also be caught
641
642
643\code
644static void event_cb(struct wl_event_t event, void* ctx) {
645       switch(event.id) {
646              case WL_EVENT_SCAN_COMPLETE:
647                     struct wl_network_list_t *netlist;
648                     uint8_t netcnt;
649                     
650                     wl_get_network_list(&netlist);
651                     netcnt = netlist->cnt;
652                     while (--netcnt) {
653                             print_network(netlist->net[netcnt]);
654                     }
655                     break;
656              case WL_EVENT_CONN_FAILURE:
657                     app_error("Connection failed\n");
658                     break;
659              case WL_EVENT_MEDIA_CONNECTED:
660                     app_print("Connected to Access Point\n");
661                     app_ip_interface_up();
662                     break;
663              case WL_EVENT_MEDIA_DISCONNECTED:
664                     app_print("Disconnected from Access Point\n");
665                     app_ip_interface_down();
666                     break;
667       }
668}
669\endcode
670
671\section security Security
672
673To use WEP a WEP key must be added before the connection is initiated.
674To set the 40-bit WEP key 0xDEADBEEF00 as default key for key index 0 do
675
676\code
677         char key[5] = { 0xDE, 0xAD, 0xBE, 0xEF, 0x00 };
678         struct wl_mac_addr_t bssid;
679
680         // This means that the bssid is a broadcast bssid and the WEP key will be a default key instead of a key-mapping key.
681         memset(&bssid.octet, 0xff, sizeof bssid.octet);
682
683         if ( wl_add_wep_key(0, sizeof key, key, &bssid)
684              != WL_SUCCESS ) {
685              app_error("Failed to add WEP key.");
686              return 0;
687         }
688\endcode
689
690To use WPA/WPA2 with a Pre-shared key a passphrase must be associated
691with the network before the connection is initiated.
692
693\code
694        struct wl_network_t net;
695        char passphrase[] = "MySecretKey";
696
697        memset(&net, 0, sizeof net);
698        memset(net.bssid.octet, 0xFF, sizeof net.bssid.octet);
699        strncpy(net.ssid.ssid, "My AP", strlen("My AP"));
700        net.ssid.len = strlen("My AP");
701        net.enc_type = ENC_TYPE_AUTO;
702        if (wl_set_passphrase(&net,
703                              passphrase,
704                              strlen(passphrase),
705                              ENC_TYPE_AUTO,
706                              AUTH_MODE_AUTO)
707            != WL_SUCCESS) {
708                app_error("Failed to add passphrase");
709        }
710\endcode
711
712The library supports several passphrase-network associations to be
713configured simultaneously. Be aware that the \a wl_connect() call
714can take up to 15 seconds longer than normal when using a pre-shared
715WPA/WPA2 key since the platform must calculate a temporal encryption
716key from the passphrase before the connection attempt can start.
717
718 *  @{
719 */
720
721   
722/*! \brief Scan all channels.
723 *
724 * Starts a scan of all WiFi channels allowed in this regulatory
725 * domain. The list of allowed channels (the domain) is adapted to the
726 * channels announced as allowed by the first AP heard.
727 *
728 * The scan will proceed asynchronously and will raise a
729 * WL_EVENT_SCAN_COMPLETE event when completed.
730 *
731 * Currently, there's a limit on the scan list size that depends on the
732 * architecture (6 networks for the AVR32 UCR1 architecture 16 networks for
733 * other architectures. If more network exist, the strongest networks are
734 * chosen. Note that the limitation on the scan list size does not limit the
735 * networks which the device can connect to. See wl_connect() for more
736 * details.
737 *
738 * @return
739 * - WL_SUCCESS
740 * - WL_FAILURE.
741 */
742wl_err_t wl_scan(void);
743
744/*! \brief Get the list of currently known networks.
745 *
746 * Retrieves the list of currently known networks from
747 * the driver. To ensure that this list is up-to-date
748 * a wl_scan() call should be issued and this function
749 * should be called upon reception of the WL_EVENT_SCAN_COMPLETE
750 * event. This function can be called at other times
751 * but the list of networks retrieved then might not
752 * correspond to the networks actually in range.
753 *
754 * Note that a successful scan does not necessarily
755 * find any networks.
756 *
757 * @param network_list Output buffer. The API call returns
758 *        a pointer to allocated memory containing the network list.
759 * @return
760 * - WL_SUCCESS
761 * - WL_FAILURE.
762 */
763wl_err_t wl_get_network_list(struct wl_network_list_t **network_list);
764
765#ifdef WFE_6_12
766/*! \brief Start a Ad-hoc network.
767 *
768 * Attempt to start a Ad-hoc (IBSS) network. If a Ad-hoc network
769 * is successfully started then a WL_EVENT_MEDIA_CONNECTED event
770 * will be raised once the first peer station connects to the Ad-hoc
771 * network (and not when the network is announced on the air).
772 *
773 * If a Ad-hoc network should be started with encryption
774 * enabled then \a wl_set_passphrase() should be called before
775 * \a wl_start_adhoc_net() to configure the security parameters.
776 * The Ad-hoc network is started with the security parameters
777 * (if any) that was configured for the specified \a ssid.
778 *
779 * @param ssid The SSID of the new network. If there's a network
780 *             already present with this SSID this call will fail.
781 * @param channel The channel to use. Valid channels are 1-14
782 * @param auth_mode The authentication mode to use. Supported
783 *        authentication modes for Ad-hoc networks are
784 *        AUTH_MODE_OPEN_SYSTEM and AUTH_MODE_SHARED_KEY.
785 *        Passing other modes will cause a WL_INVALID_ARGS return.
786 *        If AUTH_MODE_SHARED_KEY is used then a valid WEP
787 *        key must be set with a call to \a wl_add_wep_key()
788 *        and the default WEP key index must be set with a
789 *        call to \a wl_set_default_wep_key().
790 * @return
791 *        - WL_SUCCESS on success.
792 *        - WL_INVALID_ARGS if the ssid is malformed, if
793 *          the channel not valid or if the authentication mode
794 *          is invalid.
795 *        - WL_RETRY if the driver is busy resolving a conflicting
796 *          operation.  The operation should be retried after a wait
797 *          (at least one call to wl_poll() for polled implementations). 
798 *        - WL_BUSY if the driver is already connected or if a network
799 *          with the same SSID is already known.
800 *         
801 */
802wl_err_t wl_start_adhoc_net(struct wl_ssid_t ssid, 
803                            uint8_t channel,
804                            enum wl_auth_mode auth_mode);
805#endif
806/*! \brief Connect to a SSID.
807 *
808 * Attempt to connect to a given SSID. If the driver is already
809 * connected to an AP with a different SSID then this call will
810 * return WL_BUSY and wl_disconnect() should be called before
811 * trying again.
812 *
813 * The connection process will proceed asynchronously and will raise a
814 * WL_EVENT_MEDIA_CONNECTED event when completed, or a WL_EVENT_CONN_FAILURE
815 * when failed. After a WL_EVENT_MEDIA_CONNECTED event has been raised
816 * a WL_EVENT_MEDIA_DISCONNECT event will be raised if the connection is
817 * terminated. Note that this can be caused by external factors and can
818 * happen at any time.
819 *
820 * If wl_connect() is invoked with a network that is not shown in the
821 * scan list, the device will probe for that specific network and connect
822 * to it, if found. This is also the method to use in order to connect to
823 * "hidden" networks (AP's that doesn't broadcast its SSID).
824 *
825 * @param ssid Pointer to the SSID string.
826 *             Freed by caller.
827 * @param ssid_len Length of the SSID string in octets. Max value is 32.
828 * @return
829 *  - WL_SUCCESS
830 *  - WL_FAILURE if the network could not be found
831 *  - WL_BUSY if the driver is already connected
832 *  - WL_RETRY if the driver is busy resolving a conflicting operation.
833 *    The operation should be retried after a wait (at least one call to wl_poll()
834 *    for polled implementations).
835 */
836wl_err_t wl_connect(char* ssid, size_t ssid_len);
837
838/*! \brief Connect to a BSSID
839 *
840 * Attempt to connect to a given BSSID. If the driver is already
841 * connected to an AP with a different BSSID then this call will
842 * return WL_BUSY and wl_disconnect() should be called before
843 * trying again.
844 *
845 * The connection process will proceed asynchronously and will raise a
846 * WL_EVENT_MEDIA_CONNECTED event when completed, or a WL_EVENT_CONN_FAILURE
847 * when failed. After a WL_EVENT_MEDIA_CONNECTED event has been raised
848 * a WL_EVENT_MEDIA_DISCONNECT event will be raised if the connection is
849 * terminated. Note that this can be caused by external factors and can
850 * happen at any time.
851 *
852 * If wl_connect_bssid() is invoked with a network that is not shown in the
853 * scan list, the device will probe for that specific network and connect
854 * to it, if found.
855 *
856 * @param bssid Pointer to the BSSID. Freed by caller.
857 * @return
858 *  - WL_SUCCESS
859 *  - WL_FAILURE if the network could not be found
860 *  - WL_BUSY if the driver is already connected
861 *  - WL_RETRY if the driver is busy resolving a conflicting operation.
862 *    The operation should be retried after a wait (at least one call to wl_poll()
863 *    for polled implementations).
864 */
865wl_err_t wl_connect_bssid(struct wl_mac_addr_t bssid);
866
867/*! \brief Disconnect from the network
868 *
869 * Disconnect from any currently associated network.
870 *
871 * The disconnection process will proceed asynchronously and will raise a
872 * WL_EVENT_MEDIA_DISCONNECTED event when completed.
873 * @return
874 *  - WL_SUCCESS if the disconnect process was started
875 *  - WL_FAILURE if the driver was not connected
876 *  - WL_RETRY if the driver is in the process of connecting.
877 *     In this case the disconnect must be retried after
878 *     the connection attempt has completed (resulted in a
879 *     WL_EVENT_MEDIA_CONNECTED or a WL_EVENT_CONN_FAILURE event).
880 */
881wl_err_t wl_disconnect(void);
882
883/*!
884 * @brief Add a WEP encryption key to the device.
885 *
886 * Configure a key into the device. The key type (WEP-40, WEP-104)
887 * is determined by the size of the key (5 bytes for WEP-40, 13 bytes for WEP-104).
888 *
889 * @param key_idx The key index to set. Valid values are 0-3.
890 * @param key_len Length of key in bytes. Valid values are 5 and 13.
891 * @param key Key input buffer.
892 * @param bssid BSSID that the key applies to. If this is
893 *        the broadcast BSSID then the key is configured
894 *        as one of the default keys (not _the_ default key,
895 *        this must be set by calling set_default_wep_key()
896 *        after adding it). If the BSSID is a valid unicast
897 *        bssid then the key is configured as a key-mapping
898 *        key ( See 802.11-2007 8.2.1.3 ).
899 * @return
900 * - WL_SUCCESS on success.
901 * - WL_INVALID_LENGTH if the key length is bad.
902 * - WL_FAILURE on failure
903 */
904wl_err_t wl_add_wep_key(uint8_t key_idx, 
905                        size_t key_len, 
906                        const void *key, 
907                        struct wl_mac_addr_t *bssid);
908
909/*! @brief Set the default WEP key index.
910 *
911 * Select which WEP key to use for transmitted packets.
912 * For this to work correctly you must have added a WEP
913 * key with \a wl_add_wep_key() as a default key, using the
914 * same index as the one set in this call.
915 * @param key_idx Index of the key to make the default key.
916 *        Valid values are 0-3.
917 * @return WL_SUCCESS or WL_FAILURE.
918 */
919wl_err_t wl_set_default_wep_key(uint8_t key_idx);
920
921/*! \brief Delete a WEP key.
922 *
923 * Deletes a WEP key from the driver.
924 *
925 * @param key_idx The index of the key to delete. Valid values are 0-3.
926 * @param bssid BSSID that the key applies to. If this is
927 *        the broadcast BSSID then the key deleted is a default key.
928 *        If the BSSID is a valid unicast bssid then the deleted
929 *        key is a key-mapping key.
930 * @return WL_SUCCESS or WL_FAILURE
931 */
932wl_err_t wl_delete_wep_key(uint8_t key_idx, struct wl_mac_addr_t *bssid);
933
934/*! @brief Set a WPA/WPA2 passphase
935 *
936 * Associate a WPA/WPA2/RSN passphrase with a network.
937 * The number of passphrases that can be stored can
938 * vary but is always at least one. Passphrases can
939 * be added until \a wl_add_wpa_passphrase() returns
940 * WL_RESOURCES.
941 *
942 * @param net Network with which to associate the passphrase.
943 * @param passphrase Passphrase. Valid characters in a passphrase
944 *        must lie between ASCII 32-126 (decimal).
945 * @param len Length of passphrase. Valid lengths are 8-63.
946 * @param enc_type Encryption type. If this is set to ENC_TYPE_AUTO
947 *        then the most secure supported mode will be automatically
948 *        selected. Normally you only need to pass something else here
949 *        if you need to enforce picking a certain encryption mode when
950 *        the network supports several modes and you don't want to use
951 *        the best one.
952 * @param auth_mode Authentication mode. If this is set to AUTH_MODE_AUTO
953 *        then the most secure mode will be automatically selected.
954 *        Normally you only need to pass something else here if the network
955 *        announces support for both WPA and WPA2/RSN and the passphrases are
956 *        different.
957 * @return
958 *        - WL_SUCCESS
959 *        - WL_INVALID_ARGS if the passphrase length is invalid.
960 *        - WL_RESOURCES if no more passphrases can be added.
961 */
962wl_err_t wl_set_passphrase(const struct wl_network_t *net,
963                           const char *passphrase, 
964                           const size_t len,
965                           const enum wl_enc_type  enc_type,
966                           const enum wl_auth_mode auth_mode);
967
968/*! @brief Remove a WPA/WPA2 passphase
969 *
970 * Remove a WPA/WPA2/RSN passphrase associated with a network.
971 *
972 * @param net Network with which to associate the passphrase.
973 *        If net is NULL then all stored passphrases will be
974 *        cleared.
975 * @return
976 *        - WL_SUCCESS
977 *        - WL_FAILURE if no passphrase was associated with the net.
978 */
979wl_err_t wl_clear_passphrase(struct wl_network_t *net);
980
981
982/*! \brief Enable legacy power save mode
983 *
984 * Enable legacy power save mode. In legacy power save mode, the device
985 * will power down when idle. When connected, the device will wake up to
986 * receive beacon frames and any buffered data from the AP. The response
987 * time when legacy power save is enabled might therefore be as long as the
988 * AP beacon interval (mostly 100 ms). However, the throughput should not
989 * be affected.
990 *
991 * @return WL_SUCCESS or WL_FAILURE.
992 */
993wl_err_t wl_enable_ps(void);
994
995/*! \brief Disable legacy power save mode
996 *
997 * @return WL_SUCCESS or WL_FAILURE.
998 */
999wl_err_t wl_disable_ps(void);
1000
1001/*! \brief Configure power save parameters.
1002 *
1003 * @param use_ps_poll Use PS-Poll frames to retrieve buffered data. Any changes
1004 *        to this parameter will take effect upon next connect
1005 *        or when power save is enabled through wl_enable_ps().
1006 *        Note: To retrieve one buffered packet, the ps poll scheme
1007 *        needs one ps poll packet to the AP instead of two null
1008 *        packets in the power management bit scheme. Ps poll avoids
1009 *        the overhead of traffic monitoring time in active mode as
1010 *        well. But since each ps poll request can make the AP
1011 *        release only one buffered packet, it is not the optimal
1012 *        scheme for applications with heavy downlink traffic.
1013 * @param ps_traffic_timeout Timeout in [ms] to wait for more buffered data
1014 *        from AP. This setting has no effect if
1015 *        use_ps_poll is 1. Any changes to this parameter
1016 *        will take effect immediately.
1017 * @param ps_delay Power save will de delayed ps_delay [ms] after connecting to
1018 *        an AP.
1019 * @param rx_all_dtim If set to 1, then STA will wake up to listen to every
1020 *        beacon containing DTIM (delivery traffic indication messages) when
1021 *        connected. The actual DTIM interval is configured in the AP.
1022 *        If the DTIM interval, as configured in the AP, is larger than
1023 *        \a listen_interval, the STA will wakeup according to the
1024 *        \a listen_interval parameter.
1025 * @param listen_interval The Listen Interval field is used to indicate to the
1026 *        AP how often a STA in power save mode wakes to listen
1027 *        to beacon frames. The value of this parameter is expressed in units
1028 *        of Beacon Interval. An AP may use the Listen Interval information in
1029 *        determining the lifetime of frames that it buffers for a STA.
1030 *        Any changes to this parameter will take effect upon next association.
1031 *
1032 * @return WL_SUCCESS or WL_FAILURE.
1033 */
1034wl_err_t wl_conf_ps(uint8_t use_ps_poll, 
1035                    uint32_t ps_traffic_timeout,
1036                    uint32_t ps_delay,
1037                    uint8_t rx_all_dtim,
1038                    uint16_t listen_interval);
1039 
1040/*! \brief Get the interface MAC address.
1041 *
1042 * Return the 802.3 MAC address of the network interface.
1043 *
1044 * @param buf Output buffer. It must be at least WL_MAC_ADDR_LENGTH
1045 *            bytes long and only the first WL_MAC_ADDR_LENGTH bytes
1046 *            will contain valid data.
1047 * @return
1048 *         - WL_FAILURE if the interface is not up.
1049 *         - WL_SUCCESS
1050 */
1051wl_err_t wl_get_mac_addr(uint8_t* buf);
1052
1053/*! \brief Return the associated network.
1054 *
1055 * Return the description of the currently associated
1056 * network, if any.
1057 *
1058 * @return The network description, or NULL of the driver
1059 *  is unconnected.
1060 */
1061struct wl_network_t* wl_get_current_network(void);
1062/*!  @} */
1063
1064/** \defgroup wl_data Data Transfer
1065 *
1066 * \brief Packet processing interface.
1067 *
1068 * Note that the examples in this group assumes that the transport library
1069 * functions in the \a wl_transport group are being used. For more information,
1070 * See the documentation for those functions in the \a wl_transport group.
1071
1072For the IP stack integration you need to intercept received packets so
1073they can be sent up the stack and to transmit packets coming down the
1074stack.
1075
1076By default the wl_api library discards all data packets.  To receive
1077them the application must register a rx interrupt service routine (isr)
1078using the \a wl_register_rx_isr() function.
1079
1080\code
1081static void rx_isr(void* ctx) {
1082       rx_pending = TRUE;
1083}
1084\endcode
1085
1086Since the rx_isr() function is only called in interrupt context, it is not
1087safe to perform the actual read directly from rx_isr(). If an OS is used,
1088the normal case is to signal a receiver thread to invoke the ip stack
1089read function to read the pending data. In a system that runs without an OS
1090(as in the example), a flag is set to indicate that wl_rx() can be invoked
1091from the ip stack read function next time the ip stack is polled.
1092The beginning of a ip stack read function can look like this
1093
1094\code
1095static void ip_stack_rx_pkt() {
1096       char *pkt = malloc(MAX_PKT_SIZE);
1097       uint16_t len = MAX_PKT_SIZE;
1098
1099       if (p == NULL) {
1100              app_error("Out of memory.");
1101              return;
1102       }
1103       wl_rx(pkt, &len);
1104       if (0 == len) {
1105              app_error("Packet reception failed.");
1106              free(pkt);
1107              return
1108       }     
1109}
1110\endcode
1111
1112Since the ip_stack_rx_pkt() function should only be called when there is
1113actually a packet ready to read you do not have to check the return value
1114from \a wl_rx() since it only returns failure if there is no packet ready to
1115read.
1116
1117A packet arriving from the WiFi interface can be either a data
1118packet or a message from the WiFi hardware to the WiFi driver
1119(which is implemented by the wl_api library). This means that
1120wl_api must process every packet to decide if it is an internal
1121message or a data frame that
1122should be passed up to the application. Data packets are
1123prefixed with an extra header containing some administrative
1124information, and may be followed by padding bytes and so
1125wl_api also needs to strip the extra header and any padding
1126before the packet can be safely ingested by the IP stack.
1127All this happens in the function \a wl_process_rx() which \b must
1128be called on every packet received by a call to \a wl_rx().
1129
1130Continuing the ip_stack_rx_pkt() example
1131
1132\code
1133       {
1134                char*  stripped_pkt;
1135                size_t stripped_pkt_len;
1136                uint16_t vlan;
1137                int status;
1138               
1139                status = wl_process_rx(pkt,
1140                                       len,
1141                                       &stripped_pkt,
1142                                       &stripped_pkt_len,
1143                                       &vlan);
1144                if (WL_ABSORBED == status) {
1145                       // This is normal. The packet was a
1146                       // wl_api-internal message.
1147                       free(pkt);
1148                       return;   
1149                }
1150                app_ip_stack_input(stripped_pkt,
1151                                   stripped_pkt_len,
1152                                   vlan);
1153                free(pkt);
1154        }
1155}
1156\endcode
1157                               
1158If \a wl_process_rx() decides that the packet was a command it processes
1159it and returns \a WL_ABSORBED to signal that the packet should
1160not be used by anyone else. Otherwise stripped_pkt is
1161pointing to the beginning of a 802.3 Ethernet frame of length
1162stripped_pkt_len. If the IP stack supports VLAN and QoS
1163the extra VLAN tag should be passed to the IP stack
1164together with the packet. For IP stacks without this support the VLAN tag
1165contents can safely be ignored, but it must still be filled in by \a wl_process_tx().
1166
1167To register the receive isr
1168
1169\code
1170        wl_register_rx_isr(rx_isr, NULL);
1171\endcode
1172
1173Transmitting data packets happens in a similar way but does not
1174require a callback/isr since the application/IP stack knows when it has
1175packets to send.
1176
1177\code
1178int ip_stack_tx_pkt(char *pkt, size_t len, uint16_t vlan_tag) {
1179        int status;
1180        char wlan_hdr[WL_HEADER_SIZE];
1181        // The packet must have an Ethernet header
1182        if (len < ETHERNET_HEADER_SIZE) {
1183                app_error("Invalid packet length");
1184                return 0;
1185        }
1186        hdr_len = sizeof wlan_hdr;
1187        status = wl_process_tx(pkt,
1188                               ETHERNET_HEADER_SIZE,
1189                               len,
1190                               wlan_hdr,
1191                               vlan_tag,
1192                               NULL);
1193        if ( WL_SUCCESS != status ) {
1194                app_error("Packet processing failed");
1195                return 0;
1196        }
1197        // Transmit the header first
1198        if (wl_tx(wlan_hdr, hdr_len) != WL_SUCCESS) {
1199                app_error("Header transmission failed");
1200                return 0;
1201        }
1202        // Then transmit the data packet
1203        if (wl_tx(pkt, len) != WL_SUCCESS) {
1204                app_error("Packet transmission failed");
1205                return 0;
1206        }
1207}
1208\endcode
1209
1210The final piece of the puzzle in the IP stack integration is
1211the MAC address of the WiFi interface
1212
1213\code
1214        char mac_addr[WL_MAC_ADDR_LENGTH];
1215
1216        wl_get_mac_addr(mac_addr);
1217        ip_stack_set_mac_address(mac_addr);
1218\endcode
1219
1220 *  @{
1221 */
1222
1223/*! Size of the wl_api packet header */
1224#ifdef WFE_6_12
1225#define WL_HEADER_SIZE 16
1226#else
1227#define WL_HEADER_SIZE 14
1228#endif
1229   
1230/*! Maximum packet size (including wl_api headers and paddings)
1231 *
1232 * Maximum packet size is obtained with the following data:
1233 *
1234 * 1500 bytes of Ethernet payload (MTU) + 14 bytes of Ethernet header +
1235 * WL_HEADER_SIZE of wl header. This data is then size-aligned to 16.
1236 *
1237 */
1238#define WL_MAX_PKT_LEN 1536
1239
1240
1241/*!
1242 * \brief Process rx packet.
1243 *
1244 * Processes a raw rx packet by unencrypting it (if necessary)
1245 * and stripping headers so as to output a 802.3 frame.
1246 *
1247 * wl_process_rx() will strip bytes both from the head and from the tail.
1248 *
1249 * Upon return from wl_process_rx(), the pointer at stripped_pkt will
1250 * point to the start of the Ethernet header, hence adjusting the offset
1251 * by WL_HEADER_LEN bytes. Any padding (added by the wifi device) will
1252 * be removed from the tail of the packet, hence making len smaller.
1253 *
1254 * The wl_api library of the device will not perform any Ethernet padding
1255 * removal. The padding removal performed by wl_process_rx() is only for
1256 * the padding used in the protocol shared by the host and the device.
1257 * This padding is mainly there to ensure that the host does not have to
1258 * deal with rx of odd-sized data buffers (which some DMA's have problems
1259 * to handle).
1260 *
1261 * @param pkt Input buffer (raw packet)
1262 * @param pkt_len Length of the input buffer (in bytes)
1263 * @param stripped_pkt Pointer to the packet with the
1264 *  transport header stripped.
1265 * @param stripped_pkt_len Length of the stripped packet.
1266 * @param vlanid_prio VLAN ID and 802.1p priority value
1267 * using following format:
1268 * <PRE>
1269 *        1
1270 *  5|432109876543|210
1271 *  -+------------+---
1272 *  0|   VLANID   |PRI
1273 * </PRE>
1274 *
1275 * @returns
1276 *          - WL_FAILURE
1277 *          - WL_ABSORBED if the packet was an internal driver command
1278 *                      and not a proper data packet. The packet should
1279 *                      be freed and the stripped_pkt will not point
1280 *                      to a valid packet.
1281 *          - WL_SUCCESS
1282 */
1283wl_err_t wl_process_rx(char *pkt, size_t pkt_len, char **stripped_pkt, 
1284                       size_t *stripped_pkt_len, uint16_t *vlanid_prio);
1285
1286/*! \brief Process tx packet.
1287 *
1288 * Prepare tx packet for transmission.
1289 *
1290 * This function is typically used only by the TCP/IP stack driver.
1291 *
1292 * Takes a Ethernet II frame header and generates a message passing header
1293 * for it.
1294 *
1295 * The caller should ensure that any frames injected into wl_process_tx()
1296 * are proper Ethernet frames. The wl_api library or the device will not
1297 * perform any Ethernet padding if the frames are too short.
1298 *
1299 * The Ethernet header is assumed to have the following layout :
1300 * <dst addr:6><src addr:6><type:2>...
1301 * The rest of the Ethernet header buffer (if any) is ignored.
1302 *
1303 * A note on the TX packet representation :
1304 * If your TX packets are simple contiguous buffers you can ignore
1305 * the rest of this note and pass NULL in parameter \a pkt_handle.
1306 * A TX packet may have a more complex structure than a RX packet
1307 * (which must be a contiguous, flat buffer). The IP stack may
1308 * for example represent a packet as a linked list of buffers where
1309 * the Ethernet header, the IP header and other headers, are represented
1310 * by separate buffers. In some cases, such as when the driver is
1311 * running in SoftAP mode, a TX packet has to be copied and queued
1312 * internally for later processing and to support this when packets
1313 * have a complicated structure a special data access function can
1314 * be registered. See \a wl_register_pkt_read_cb() for details.
1315 * If you use \a wl_process_tx() with non-simple packets you
1316 * should pass a handle to the packet in parameter \a pkt_handle
1317 * and register an access function with \a wl_register_pkt_read_cb().
1318 *
1319 * @param eth_hdr Input buffer (Ethernet header)
1320 * @param eth_hdr_len Input buffer length (must be >= 14)
1321 *  This is usually the same as pkt_len unless e.g linked list or buffers
1322 *  chained in other ways are being used.
1323 * @param pkt_len Length of the complete data packet (in bytes)
1324 * @param hdr Pointer to the header buffer (must be
1325 * allocated by the caller). The length of the buffer
1326 * must be at least WL_HEADER_SIZE bytes.
1327 * @param vlanid_prio VLAN ID and 802.1p priority value
1328 * using following format:
1329 * <PRE>
1330 *        1
1331 *  5|432109876543|210
1332 *  -+------------+---
1333 *  0|   VLANID   |PRI
1334 * </PRE>
1335 * Ignored for legacy association (no WMM)
1336 * @param pkt_handle A handle to the complete packet. If this parameter
1337 *  is NULL then \a eth_hdr is expected to point to the whole packet
1338 *  in a single contiguous buffer (the default). If a different packet
1339 *  representation is used this parameter should be a handle to the
1340 *  complete packet and will be passed unmodified to the data
1341 *  access function that was registered with \a wl_register_pkt_read_cb().
1342 *
1343 * @returns
1344 *          - WL_FAILURE
1345 *          - WL_RESOURCES if packet can not be processed at the moment.
1346 *                       The caller must either drop the packet or try
1347 *                       retransmit it later.
1348 *          - WL_AVAIL     if network not available
1349 *          - WL_SUCCESS   if packet is ready for transmission through wl_tx().
1350 */
1351wl_err_t wl_process_tx(char *eth_hdr, 
1352                       size_t eth_hdr_len, 
1353                       size_t pkt_len, 
1354                       char *hdr,
1355                       uint16_t vlanid_prio,
1356                       void *pkt_handle);
1357
1358 
1359/*! \brief Get current TX and RX rate used for data transfer
1360 *
1361 * During transmission and reception of data, the actual rate used will depend
1362 * on the signal quality. This function can be used to get the actual rate used
1363 * for the last tx and rx data.
1364 *
1365 * @param tx will hold the tx rate upon successful return.
1366 * @param rx will hold the rx rate upon successful return.
1367 *
1368 * @return
1369 * - WL_SUCCESS on success
1370 * - WL_FAILURE on failure.
1371 */ 
1372wl_err_t wl_get_rate(wl_rate_t *tx, wl_rate_t *rx);
1373
1374
1375/*! @} */ /* End wl_data group */
1376
1377
1378/** \defgroup wl_transport Transport interface
1379 *
1380 * \brief Low level transport interface.
1381 *
1382 * These functions access the low level transport driver which makes
1383 * the application independent of the actual physical transport
1384 * layer (usually SDIO or SPI).
1385 *
1386 
1387For applications running on an real time kernel or without an
1388operating system, the provided transport library will fit right into the
1389application design. However, when running on a more complex operating system
1390(such as windows or linux) which has its own transport primitivies and
1391components (and probably its own IP stack) it might be preferred to design a
1392custom transport library for that specific environment. Therefore, these
1393transport interface functions are fully optional.
1394
1395
1396 *  @{
1397 */
1398
1399#define WL_RX_MIN_PKT_LEN    32
1400
1401
1402/*! \brief WiFi event callback.
1403 *
1404 * This function is invoked in interrupt context when there is new data
1405 * available from the mac. This function is supplied by the user
1406 * of the API.
1407 *
1408 * This function is typically used only by the TCP/IP stack driver.
1409 *
1410 * @param ctx   A context handle. This handle is passed
1411 *              untouched to the callback and has the same value
1412 *              as the context registered with the callback in
1413 *              wl_register_event_cb().
1414 */
1415typedef void (*wl_rx_isr_t) (void* ctx);
1416
1417
1418/*! \brief Firmware access function.
1419 *
1420 * Reads the WiFi firmware image. This function is supplied by
1421 * the user of this API since storage for the firmware image is
1422 * managed by the application.
1423 *
1424 * This function should read the specified number of bytes of the
1425 * firmware image starting at the specified \a offset. The number of
1426 * bytes to read is given in \a len. Upon return, \a buf should point
1427 * to a buffer which holds the read data and the number of valid bytes
1428 * in \a buf is returned from the call.
1429 *
1430 * This function will be called repeatedly until the complete firmware
1431 * image has been read.
1432 *
1433 * This function may be called again at any time while the driver is
1434 * running to download further pieces of the WiFi firmware image as
1435 * needed by the runtime requirements. This will normally only happen
1436 * when the driver switches between networks of different kinds such
1437 * as from WEP to WPA, or from ESS to IBSS for example.
1438 *
1439 * For convenience, any time a firmware chunk has been completely
1440 * downloaded this function will be called once with the \a buf
1441 * parameter set to NULL to indicate that no more data is needed right
1442 * now and that any dynamically allocated buffers which holds firmware
1443 * data can be freed without much performance impact.
1444 *
1445 * @param ctx Opaque context pointer as provided to \a wl_init() that will be
1446 *            passed back to the callback.
1447 * @param buf Should be assigned the address of the buffer holding the read
1448 *            data upon return. This parameter can be NULL which indicates
1449 *            that there are no further immediately pending accesses.
1450 * @param offset Offset in bytes from the start of the firmware image.
1451 *            Data should be copied into buf starting at \a offset.
1452 * @param len The number of bytes to copy into \a buf.
1453 * @return The number of bytes copied into buf. This may be smaller than
1454 *         \len if the implementation of the function so requires.
1455 */
1456typedef size_t (wl_fw_read_cb_t)(void *ctx, 
1457                                 const uint8_t **buf, 
1458                                 size_t offset, 
1459                                 size_t len);
1460
1461
1462/*! \brief Initialize the transport interface and download the WiFi firmware
1463 * image to the device.
1464 *
1465 * This operation will proceed synchronously until the firmware is completely
1466 * downloaded. wl_init() should be called after this function has returned to
1467 * perform device initialization.
1468 *
1469 * @param fw_read_cb callback function to invoke during firmware download.
1470 * @param ctx Opaque context pointer that will be passed to the callbacks
1471 *            when they are invoked. This parameter is never
1472 *            accessed by the API.
1473 * @param mode will hold the host attention mode used by the transport layer.
1474 *         This parameter can be passed directly to \a wl_init().
1475 *
1476 * @return
1477 *
1478 * - WL_CARD_FAILURE if the wl hardware device is not available
1479 * - WL_FIRMWARE_INVALID if the firmware obtained through fw_read_cb is
1480 *                       invalid.
1481 * - WL_OOM if the necessary memory could not be allocated.
1482 */
1483wl_err_t wl_transport_init(wl_fw_read_cb_t *fw_read_cb,
1484                           void *ctx,
1485                           enum wl_host_attention_mode *mode);
1486 
1487/*! \brief WiFi driver forward progress function
1488 *
1489 * This function must be called in polled environments to
1490 * ensure forward progress. The call can be made as often as possible from
1491 * the main application loop. However, the call will not have any effect unless
1492 * there is an interrupt pending from the hardware.
1493 *
1494 * In interrupt mode, wl_poll() must be called if no interrupt
1495 * handler is registered through wl_register_rx_isr(). When an interrupt
1496 * handler is registered, it is no longer necessary to invoke wl_poll().
1497 *
1498 * Note that this function should not be invoked from interrupt context.
1499 *
1500 */
1501void wl_poll(void);
1502
1503 
1504/*! \brief Register RX callback
1505 *
1506 * Register function to be called by the low level transport driver
1507 * when a new packet is available or when there is a state change in the
1508 * data path. When invoked, any pending data can be fetched by calling wl_rx().
1509 *
1510 * This function is typically used only by the TCP/IP stack driver.
1511 * Note, the registered function is called in interrupt context.
1512 *
1513 * @param isr rx interrup handler.
1514 * @param ctx Opaque context pointer that is passed unmodified to the
1515 * rx_cb callback when it is invoked.
1516 *
1517 * @return WL_SUCCESS
1518 */
1519wl_err_t wl_register_rx_isr(wl_rx_isr_t isr, void* ctx);
1520
1521
1522/*! \brief Read pending packet
1523 *
1524 * Read a pending packet from the low level transport driver.
1525 * The read packet must be passed to the wl_process_rx() function
1526 * for proper driver operation.
1527 *
1528 * @param buf Buffer to read the packet into. This buffer must be
1529 *            at least WL_MAX_PKT_LEN bytes long.
1530 * @param len Length of buf in bytes. Contains the length of the
1531 *            read packet in bytes on output.
1532 * @return
1533 *         - WL_FAILURE if no RX packet is pending.
1534 *         - WL_SUCCESS
1535 */
1536wl_err_t wl_rx(uint8_t* buf, uint16_t* len);
1537
1538/*! \brief Send processed tx packet
1539 *
1540 * Send a packet to the low level transport driver.
1541 * This packet has to have been successfully processed by the
1542 * wl_process_tx() function.
1543 *
1544 * @param buf Buffer to send.
1545 * @param len Length of buf in bytes.
1546 *
1547 * @return
1548 *         - WL_FAILURE if the interface is not ready to send.
1549 *         - WL_SUCCESS if the packet was successfully transmitted.
1550 */
1551wl_err_t wl_tx(const uint8_t* buf, uint16_t len);
1552
1553 
1554/*! \brief Configure data alignment
1555 *
1556 * This function can be used if the host SDIO/SPI controller has certain
1557 * requirements on the data transfer sizes that can be used on the SDIO/SPI bus.
1558 *
1559 * If the txsize parameter is non-zero, additional padding data should be added
1560 * when performing the low level transfer of data buffer of sizes that are not
1561 * a multiple of the size_align parameter. See \ref wl_sdio and \ref wl_spi for
1562 * more information.
1563 *
1564 * @param txsize will configure the size alignment for tx data.
1565 *
1566 */
1567void wl_conf_alignment(uint8_t txsize);
1568
1569
1570/*! @} */ /* End wl_transport group */
1571
1572
1573/** \defgroup wl_custom Custom environment support
1574 *
1575 * \brief Support for custom environments
1576 *
1577 * These functions should only be used in cases where the transport library is
1578 * not used at all. This usually applies to operating systems and environments
1579 * where there already exists a transport layer framework, e.g. linux or
1580 * windows.
1581 *
1582 *
1583
1584Note that the \a wl_poll() function is part of the transport library. Therefore,
1585it should not be used in custom environments. Therefore, it is necessary to
1586implement a custom polling or interrupt based scheme to ensure that any
1587incoming packets are processed by the core.
1588
1589 *  @{
1590 */
1591 
1592 /*! \brief Wakeup callback function.
1593 *
1594 * Invoked when the WiFi device should wake up from power save mode.
1595 * This function should send the proper commands to the device.
1596 *
1597 * Note that this type should only be used in custom environments, where
1598 * the transport library is not used.
1599 *
1600 * @param ctx Opaque context pointer as provided to \a wl_register_wakeup_cb()
1601 *            that will be passed back to the callback.
1602 * @param wakeup indicates whether wakeup should be set or cleared in the
1603 *               device.
1604 */
1605typedef void (wl_wakeup_cb_t)(void* ctx, uint8_t wakeup);
1606
1607/*! \brief Register wakeup callback function.
1608 *
1609 * Register a function that will be invoked when the WiFi device should wake
1610 * up from power save mode.
1611 *
1612 * Note that this function should only be used in custom environments, where
1613 * the transport library is not used.
1614 *
1615 * @param wakeup_cb Will be invoked when the device should wakeup from sleep
1616 *                 mode.
1617 * @param ctx Opaque context pointer that will be passed back to the callback.
1618 */
1619void wl_register_wakeup_cb(wl_wakeup_cb_t *wakeup_cb, void *ctx);
1620 
1621
1622/*! \brief Management tx callback function.
1623 *
1624 * Invoked when the a management message should be transmitted to the
1625 * WiFi device. This function should ensure that the message is passed through
1626 * to the device and should never fail.
1627 *
1628 * Note that this type should only be used in custom environments, where
1629 * the transport library is not used.
1630 *
1631 * @param ctx Opaque context pointer as provided to \a wl_register_mgmt_tx_cb()
1632 *            that will be passed back to the callback.
1633 * @param buf Points to the buffer which holds the management data,
1634 * @param len Size of the buffer.
1635 */
1636typedef void (wl_mgmt_tx_cb_t)(void *ctx, const uint8_t *buf, uint16_t len);
1637
1638
1639/*! \brief Register management tx callback function
1640 *
1641 * Register a function that will be invoked when a management message should
1642 * be transmitted to the device.
1643 *
1644 * Note that this function should only be used in custom environments, where
1645 * the transport library is not used.
1646 *
1647 * IMPORTANT : In a custom environment without a transport library \a
1648 *             wl_register_mgmt_tx_cb() \b must have been called
1649 *             before \a wl_fw_download() is called since \a
1650 *             wl_fw_download() depends on the \a mgmt_tx_cb() to send
1651 *             the firmware data to the WiFi chip.
1652 *
1653 * @param mgmt_tx_cb The callback function to invoke.
1654 * @param ctx Opaque context pointer that  will be passed back to the callback.
1655 */
1656void wl_register_mgmt_tx_cb(wl_mgmt_tx_cb_t *mgmt_tx_cb, void *ctx);
1657
1658
1659
1660/*! \brief Download the WiFi firmware image to the device.
1661 *
1662 * This operation will proceed synchronously until the firmware is completely
1663 * downloaded. wl_init() should be called after this function has returned to
1664 * perform device initialization. This function depends on \a
1665 * wl_register_mgmt_tx_cb(). See that function for details.
1666 *
1667 * @param ctx Opaque context pointer that will be passed to the callbacks
1668 *            when they are invoked. This parameter is never
1669 *            accessed by the API.
1670 * @param fw_read_cb callback function to invoke during firmware download.
1671 *
1672 * @return
1673 *
1674 * - WL_CARD_FAILURE if the wl hardware device is not available
1675 * - WL_FIRMWARE_INVALID if the firmware obtained through fw_read_cb is
1676 *                       invalid.
1677 * - WL_OOM if the necessary memory could not be allocated.
1678 */
1679 wl_err_t wl_fw_download(wl_fw_read_cb_t *fw_read_cb, void *ctx);
1680
1681 
1682 
1683/*! @} */ /* End wl_custom group */
1684
1685
1686
1687#endif
Note: See TracBrowser for help on using the repository browser.