wimax-tools 1.4.4

wimax-tools Documentation

This is a simple library to control WiMAX devices through the control API exported by the Linux kernel WiMAX Stack. It provides means to execute functions exported by the stack and to receive its notifications.

Because of this, this is a callback oriented library. It is designed to be operated asynchronously and/or in an event loop. For the very simple cases, helpers that implement synchronous functionality are available.

This library is provided as a convenience and using it is not required to talk to the WiMAX kernel stack. It is possible to do so by interacting with it over generic netlink directly.

Note:
this is a very low level library. It does not provide the caller with means to scan, connect, disconnect, etc from a WiMAX network. Said capability is provided by higher level services which might be users of this library.

Conventions

Most function calls return an integer with a negative errno error code when there is an error.

General usage

The first operation to start controlling a WiMAX device is to open a handle for it:

  struct wimaxll_handle *wmx = wimaxll_open("wmx0");

With an open handle you can execute all the WiMax API operations. When done with the handle, it has to be closed:

If the device is unloaded/disconnected, the handle will be marked as invalid and any operation will fail with -ENODEV.

To reset a WiMAX device, use:

To turn a device on or off, or to query it's status, use:

  wimaxll_rfkill(wmx, WIMAX_RF_ON);

WIMAX_RF_ON and WIMAX_RF_OFF turn the radio on and off respectively, using the software switch and return the current status of both switches. WIMAX_RF_QUERY just returns the status of both the HW and SW switches.

See device management for more information.

Receiving notifications from the WiMAX kernel stack

The WiMAX kernel stack will broadcast notifications and driver-specific messages to all the user space clients connected to it over a generic netlink multicast group.

To listen to said notifications, a library client needs to block waiting for them or set callbacks and integrate into some kind of main loop using select() call to detect incoming notifications.

Simple example of mainloop integration:

 int fd = wimaxll_recv_fd(wmx);
 fd_set pipe_fds, read_fds;
 ...
 // Main loop
 FD_ZERO(&pipe_fds);
 FD_SET(fd, &pipe_fds);
 while(1) {
         read_fds = pipe_fds;
         select(FD_SETSIZE, &read_fds, NULL, NULL, NULL);
         if (FD_ISSET(fd, &read_fds))
                 wimaxll_recv(wmx);
 }

This code will call wimaxll_recv() when notifications are available for delivery. Calling said function will execute, for each notification, the callback associated to it.

To wait for a state change notification, for example:

 result = wimaxll_wait_for_state_change(wmx, &old_state, &new_state);

The same thing can be accomplished setting a callback for a state change notification with wimaxll_set_cb_state_change() and then waiting on a main loop. See state changes for more information.

To wait for a (device-specific) message from the driver, an application would use:

 void *msg;
 ...

 size = wimaxll_msg_read(wmx, &msg);

 ... <act on the message>

 wimaxll_msg_free(msg);            // done with the message

msg points to a buffer which contains the message payload as sent by the driver. When done with msg it has to be freed with wimaxll_msg_free().

As with state change notifications, a callback can be set that will be executed from a mainloop every time a message is received from a message pipe. See wimaxll_pipe_set_cb_msg_to_user().

A message can be sent to the driver with wimaxll_msg_write(). not the default message pipe.

For more details, see The message interface.

Miscellaneous

Controlling the ouput of diagnostics

libwimaxll will output messages by default to stderr. See Set of simple log helpers for changing the default destination.

Endianess conversion

The following convenience helpers are provided for endianess conversion:

Multithreading

This library is not threaded or locked. Internally it uses two different netlink handles, one for receiving and one for sending; thus the maximum level of paralellism you can do with one handle is:

Any function not covered by the in this list can be parallelizable.