Ethernet-WiFi Device Driver Data Structures

There are two distinct modes in which the EtherSmart/WiFi Wildcard can be used in web-enabled instrumentation applications. One mode is to use the Wildcard to replace the serial port on the controller, enabling command line interaction via Ethernet or WiFi instead of via RS-232. This is called "revectored serial via TCP/IP". The other mode is to configure the EtherSmart/WiFi Wildcard to provide communications services including serial tunneling, outgoing email, and web service. These two modes use different data structures as described in the following subsections.

Revectored serial via TCP/IP is conceptually very simple: the three fundamental serial primitives Key, AskKey, and Emit are "revectored" so that they use the Ethernet or WiFi Wildcard port instead of the serial port on the controller. The simplest approach to revectoring is to store the correct modulenum into the global variable named ether_revector_module, and then to call Ether_Serial_Revector. This runs the default (startup) task through the specified EtherSmart/WiFi Wildcard with no additional data structures needed. Setting up a separate Ethernet task for revectoring is possible but not required.

Most users will want to configure the EtherSmart Wildcard to provide communications services including serial tunneling, outgoing email, and web service. This requires more sophisticated data structures and a dedicated task to run the services. The pre-coded driver functions automate the required interactions between the application program and the Ethernet task.

As explained in the User Guide for your Mosaic controller board, a "task" is an environment that is capable of running a program. The task contains a user area, stacks, and buffers that enable a program to run independently of other tasks. The operating system switches between tasks using cooperative multitasking mediated by the Pause routine, and using the timeslice multitasker to force periodic task switches. Each of the tasks typically manages a defined set of services, and the tasks interact by means of shared variables or mailboxes.

A "mailbox" is a 32-bit variable in common memory that conveys a message from one task to another. A mailbox must be cleared before a new message may be sent; this helps to synchronize the tasks and ensures that no messages are discarded or written over without being read by the receiving task. A mailbox may be read and cleared by a "blocking" function that waits until the mailbox contains a message (that is, until it contains a non-zero value) and then reads out, reports, and zeros the mailbox. It may also be checked by a "non-blocking" function that reads and reports the contents of the mailbox and, if it contains a non-zero value, clears it. Non-blocking mailbox reads are often preferred because they avoid tying up one task while waiting for another task to send a message.

The EtherSmart/WiFi driver code uses mailboxes to coordinate the provision of communications services by the Ethernet task to the programmer’s main application task. This is all done transparently, so you don’t have to be an expert on inter-task communications to use the EtherSmart/WiFi Wildcard. Three 32-bit mailboxes named ether_command, ether_response, and ether_gui_message are allocated in common RAM when the initialization routine executes. For example, when the application program invokes a command such as Ether_Send_Email, a message is dispatched via the ether_command mailbox to the Ethernet task. Consequently, the Ethernet task opens a connection to the specified remote computer, sends the email, and closes the connection. The Ethernet task then sends a result error code in the ether_response mailbox. This mailbox must be cleared by the application program using either the blocking function Ether_Await_Response, or the non-blocking function Ether_Check_Response. The main loop of your program’s application task should periodically call one of these two functions to manage the interactions with the Ethernet task. See the Email and Serial Tunneling sections (and the corresponding functions in the demo program) for examples of use.

In addition to the mailboxes, there are two variables declared in the driver code named ether_revector_module and ether_service_module. As mentioned above, ether_revector_module specifies which module (if any) is being used for revectored serial via TCP/IP (Ethernet or WiFi). The ether_service_module variable is set by the initialization functions Ether_Init or WiFi_Init and their calling functions (Ether_Setup, Ether_Setup_Default, and Ether_Task_Setup, or WiFi_Setup, WiFi_Setup_Default, and WiFi_Task_Setup). The ether_service_module variable specifies which Wildcard module is accessed by the Ether_Service_Loop routine running in the Ethernet control task. Because each of these variables is automatically initialized by higher level functions, you typically don’t have to worry about them. It is easy to install two EtherSmart and/or WiFi Wildcards, one for revectored serial, and the other providing communications services including serial tunneling, email, and web service.

If you need more than one Wildcard providing TCP/IP communications services, consult the section below titled "Initializing Multiple EtherSmart/WiFi Wildcards".

Most of the LAN (Local Area Network) control data for the EtherSmart/WiFi Wildcard is contained in a structure whose extended 32-bit base xaddress is returned by the Ether_Info function. There is one of these structures for each initialized EtherSmart/WiFi Wildcard providing communications services. This structure contains error results, flags to enable the web server and serial tunneling services, buffer sizes, pointers to the mailboxes and buffers, web service form parsing pointers, configuration data, and security parameters. The configuration data includes local and gateway IP addresses for the Lantronix XPort or WiPort devices, ports and netmasks, timeout parameters, and pointers to strings used by the email routine. The structure also stores the input parameters passed to each service request function until the Ethernet task can extract the parameters and perform the requested action.

Several of the functions in the driver code allow the programmer to set and read the values in the Ether_Info structure. The structure is declared and initialized by the functions Ether_Init or WiFi_Init and their calling functions (Ether_Setup, Ether_Setup_Default, and Ether_Task_Setup, or WiFi_Setup, WiFi_Setup_Default, and WiFi_Task_Setup). These functions write reasonable default values into this data structure.

Communicating via TCP/IP over Ethernet or WiFi requires the use of buffers to hold incoming and outgoing data. The input and output buffers for serial tunneling and email are called Ether_Inbuf and Ether_Outbuf, respectively. The web service input and output buffers are called HTTP_Inbuf and HTTP_Outbuf. Each of these buffers has a default maximum size that is set at initialization time. The default size of Ether_Inbuf and Ether_Outbuf is given by the constant ETHER_BUFSIZE_DEFAULT. The default size of the HTTP_Inbuf and HTTP_Outbuf are given by the constants HTTP_INBUFSIZE_DEFAULT and HTTP_OUTBUFSIZE_DEFAULT, respectively. The functions that write to the buffers typically accept the maximum buffer size as an input parameter, and ensure that they never write beyond the allowed buffer size.

If you need specify a new buffer base xaddress or size that is different from the values set at initialization time, use the functions Ether_Set_Inbuf, Ether_Set_Outbuf, HTTP_Set_Inbuf, and HTTP_Set_Outbuf.

Functions that manipulate buffers need to know the number of valid bytes stored in the buffer. A convenient place to store this information is in the buffer itself. For this reason, this driver code uses a data structure called an "LBuffer", defined as a buffer with a 16-bit count stored in the first two bytes of the buffer, with the data following. For example, a function like Ether_Send_LBuffer expects the 32-bit extended address (xaddress) of the LBuffer as an input parameter, and sends the contents on the active TCP/IP connection. This function automatically fetches the number of data bytes in the buffer (its "count") from the buffer’s first 2 bytes, and sends data starting at the specified xaddress+2. Data reception functions such as Ether_Get_Data, Ether_Get_Chars and Ether_Get_Line expect the 32-bit extended address (xaddress) of an LBuffer as an input parameter, and receive incoming data to the buffer, storing the count at the specified xaddress, and storing the data starting at xaddress+2. The glossary entry for each buffer handling function tells whether it is dealing with an uncounted buffer or an LBuffer.

Note that the maximum size of a buffer set at initialization time refers to the data portion of the buffer; the allocated size of the LBuffer is two bytes larger than the data size. For example, ETHER_BUFSIZE_DEFAULT equals 510 bytes. The resulting allocated size of Ether_Inbuf and Ether_Outbuf is 512 bytes each, with the first 2 bytes of each buffer containing the count, and the remaining 510 bytes containing the data.

The EtherSmart/WiFi Wildcard driver includes a programmable dynamic webserver. You configure the webserver by defining and posting a "handler function" for each web address that is implemented. When the browser¹⁾ requests the web address (known as a URL, or Uniform Resource Locator), the webserver automatically executes the associated handler which performs any required actions and transmits the web page to the browser. As described in a later section, versatile functions make it easy to use HTML "forms" to request particular data or stimulate particular actions from the Mosaic controller.

The "Autoserve Array" is a data structure that holds a pointer to each URL string, and the corresponding 32-bit function pointer (execution address) of the handler associated with that URL. HTTP_Autoserve_Ptr returns an address that contains the 32-bit base address of this array which is set up by the functions Ether_Init or WiFi_Init and their calling functions (Ether_Setup, Ether_Setup_Default, and Ether_Task_Setup, or WiFi_Setup, WiFi_Setup_Default, and WiFi_Task_Setup). The functions HTTP_Add_Handler and HTTP_Add_GUI_Handler post the required information into this array, so the programmer does not need to directly access the contents of this low-level data structure. The demonstration program (provided in source form and described in this document) shows the proper syntax for adding handler functions.

A number of the functions in the EtherSmart/WiFi software driver expect as input parameters the 32-bit extended address ("xaddress") of a string. An xaddress includes page information that is not available in a 16-bit address. Because by default the C compiler treats string addresses as 16-bit parameters, a conversion must be performed to generate the 32-bit xaddress. A macro called STRING_XADDR performs the required conversion. Simply invoke the STRING_XADDR macro with the string specifier as the macro argument to generate the corresponding 32-bit xaddress. It is best to use the macro right in the argument list of the function being called. For an example of use, see Listing 1-7.

See also → Ethernet-WiFi Device Driver Data Structures