Library support functions

Detailed Description

These functions manage the library in general. They concern initalizing the library, downloading firmware to the WiFi chip and handling events from the library.

For this example we assume that the application is running stand-alone without an operating system.

Before the library can do anything it needs to start up the WiFi hardware by downloading a firmware image. The firmware image is relatively big (around 144kB) and is not included in the library since it is only needed once. It is up to the application to decide where to store the firmware image and how to read it into the wl_api library.

Step one is to write a function of the type wl_fw_download_cb_t that wl_api will call to retrive the firmware image. Assuming that you have some spare RAM on your platform you can simply include the firmware image from the fw.h header file and write a firmware read function like this

static void fw_download_cb(uint32_t addr, uint8_t** buf, uint32_t* len)
{
        *buf = (uint8_t*) fw_buf;
        *len = fw_len;
}

If the firmware image is stored in ROM this function may have to read it back block by block instead.

If the host platform is connected to the WiFi hardware using SDIO which supports interrupt driven I/O then no configuration flags should be passed to the init call. The wl_api library is then initialized like this

if ( wl_init(fw_download_cb, 0) != WL_SUCCESS ) {
        app_error("Init failed");
        return 0;
}

The library startup process will now require wl_poll() to be called a number of times before it can complete. In addition, if the application needs to know when the startup process has completed so that it can, for example, start up an IP stack it will have to register a WiFi event handler and start polling the wl_api library.

The event callback will only be executed during a call to wl_poll() or another wl_api function. This simplifies the implementation since no internal locking is required and the wl_api library becomes OS-independent.

static void event_cb(struct wl_event_t event, void* ctx) {
       switch(event.id) {
              case WL_EVENT_INIT_COMPLETE:
                     init_ip_stack();
                     break;
       }
}

Registering the event callback is straightforward :

if (wl_register_event_cb(event_cb, NULL) != WL_SUCCESS) {
       app_error("Failed to register event handler");
       return 0;
}

The wl_poll() function takes a free running "tick" counter with millisecond resolution as an argument so that it can trigger internal timers when necessary. Assuming that such a tick counter is provided by the macro GET_MS_TICK() the wl_api execution loop becomes

while (TRUE) {
       wl_poll(GET_MS_TICK());
}

In a stand-alone application this loop would usually be the main application loop and include application specific calls as well.

After some number of main loop iterations the WL_EVENT_INIT_COMPLETE event is posted and the application can initialize its IP stack.

Functions

wl_err_t wl_register_event_cb (wl_event_cb_t cb, void *ctx)

Register an event handler.

wl_err_t wl_init (wl_fw_download_cb_t cb, uint32_t flags)

Initialize the wl_api library.

void wl_poll (uint32_t tick)

WiFi driver forward progress function.

Typedefs

typedef void(* wl_event_cb_t )(struct wl_event_t event, void *ctx)

WiFi event callback.

typedef void(* wl_rx_event_cb_t )(struct wl_rx_event_t event, void *ctx)

WiFi event callback.

typedef void(* wl_fw_download_cb_t )(uint32_t addr, uint8_t **buf, uint32_t *len)

Firmware access function.

Enumerations

enum wl_err_t {
  WL_FAILURE = -1, WL_SUCCESS = 1, WL_OOM, WL_INVALID_LENGTH,
  WL_NOT_SUPPORTED, WL_ABSORBED, WL_RESOURCES, WL_BUSY,
  WL_RETRY, WL_INVALID_ARGS, WL_AVAIL
}

Function Documentation

wl_err_t wl_init	(	wl_fw_download_cb_t	cb,
		uint32_t	flags
	)

Initialize the wl_api library.

Note that wl_poll() must be called for this function to progress towards complete init

The startup process will proceed asynchronously and will raise a WL_EVENT_INIT_COMPLETE event when completed.

Parameters:

	cb	callback function to invoke during firmware download.
	flags	Configuration flags. Valid flag bits are WL_FLAG_POLL : The transport layer is polled (whenver the wl_poll() function is called).

Returns:

WL_SUCCESS
WL_FAILURE

void wl_poll ( uint32_t tick )

WiFi driver forward progress function.

This function must be called in stand-alone environments to ensure forward progress. The registered rx callback will be called from this function when data packets have been received. Periodic timers are triggered from this function so it should be called as often as possible if precision timing is required (traffic timeouts, authentication timeouts etc).

Parameters:

tick

A tick count in us. This is used to expire timers in the driver.

wl_err_t wl_register_event_cb	(	wl_event_cb_t	cb,
		void *	ctx
	)

Register an event handler.

Register an event handler with the driver. This event handler will be called whenever a event listed in wl_event_id_t occurs. See wl_event_cb_t and wl_event_id_t for more details.

Parameters:

	cb	Event callback function to register.
	ctx	Opaque context pointer that will be passed to the callback when it is invoked. This parameter is never accessed by the API.

Returns:: WL_SUCCESS

Typedef Documentation

typedef void(* wl_event_cb_t)(struct wl_event_t event, void *ctx)

WiFi event callback.

This function receives WiFi events that the application wants notification of. This function is supplied by the user of the API.

Parameters:

	event	Struct describing the type of event and, for some events, additional information regarding the status of the event. See wl_event_t for additional information.
	ctx	A context handle. This handle is passed untouched to the callback and has the same value as the context registered with the callback in wl_register_event_cb().

typedef void(* wl_fw_download_cb_t)(uint32_t addr, uint8_t **buf, uint32_t *len)

Firmware access function.

Reads the WiFi firmware image. This function is supplied by the user of this API since storage for the firmware image is managed by the application.

This function should read a number of bytes of the firmware image, starting at offset addr, into buf, and put the number of bytes read into len. This function will be called until it returns len value 0.

Parameters:

	addr	Offset from the start of the firmware image. This is where the function should start to read.
	buf	Output buffer.
	len	Number of bytes read.

typedef void(* wl_rx_event_cb_t)(struct wl_rx_event_t event, void *ctx)

WiFi event callback.

This function receives WiFi data path events that the API user wants notification of. This function is supplied by the user of the API. See wl_rx_event_t for details.

This function is typically used only by the TCP/IP stack driver.

Parameters:

	event	Struct describing the type of event and, for some events, additional information regarding the status of the event. See wl_event_t for additional information.
	ctx	A context handle. This handle is passed untouched to the callback and has the same value as the context registered with the callback in wl_register_event_cb().

Enumeration Type Documentation

enum wl_err_t

API Error codes

Enumerator:

WL_RETRY

Retry the operation later. The driver is busy resolving an operation that conflicts with the request.


Functions
wl_err_t	wl_register_event_cb (wl_event_cb_t cb, void *ctx)
	Register an event handler.
wl_err_t	wl_init (wl_fw_download_cb_t cb, uint32_t flags)
	Initialize the wl_api library.
void	wl_poll (uint32_t tick)
	WiFi driver forward progress function.
Typedefs
typedef void(*	wl_event_cb_t )(struct wl_event_t event, void *ctx)
	WiFi event callback.
typedef void(*	wl_rx_event_cb_t )(struct wl_rx_event_t event, void *ctx)
	WiFi event callback.
typedef void(*	wl_fw_download_cb_t )(uint32_t addr, uint8_t *buf, uint32_t len)
	Firmware access function.
Enumerations
enum	wl_err_t { WL_FAILURE = -1, WL_SUCCESS = 1, WL_OOM, WL_INVALID_LENGTH, WL_NOT_SUPPORTED, WL_ABSORBED, WL_RESOURCES, WL_BUSY, WL_RETRY, WL_INVALID_ARGS, WL_AVAIL }