Motorola LA-51XX Driver Programmer's Manual

Brand: Motorola

Model: LA-51XX

Type: Driver Programmer's Manual



LA-51XX Compact Flash Adapter

Driver Programmer’s Guide

MOTOROLA and the Stylized M Logo are registered in the US Patent & Trademark Office. Symbol is a registered

trademark of Symbol Technologies, Inc. All other product or service names are the property of their respective owners.

Contents

Chapter 1: Introduction

1.1 Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

1.2 Definitions Acronyms and Abbreviation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

1.3 System Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2

Chapter 2: SHoC Driver Design

2.1 Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

2.1.1 WRM file format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

2.1.2 Upload Helper Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2

2.1.3 Tasks Performed by the Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3

2.1.4 Overview of Firmware Upload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3

2.1.5 Firmware Upload Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4

2.2 Management Path. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5

2.2.1 PIMFOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5

2.2.2 Getoid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6

2.2.3 Setoid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8

2.3 Data Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10

2.3.1 Tx Data Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10

2.3.2 Rx Data Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11

2.4 Important Data Structures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12

2.4.1 Data Path Structures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12

2.4.2 Management Path Structures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14

2.5 Driver API Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16

2.5.1 Data Path APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16

2.5.2 Management Path APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17

Chapter 3: Applications

3.1 setoid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

3.2 getoid. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2

Chapter 4: Source Tree Description

4.1 Source Tree Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1

TOC-2 LA-51XX Compact Flash Adapter Driver Programmer’s Guide

Introduction

1.1 Purpose

The purpose of this document is to describe the APIs implemented on the Linux based LA-51XX Compact

Flash Adapter driver to communicate with an 802.11 device running with SHoC (Self Hosted Client) firmware.

1.2 Definitions Acronyms and Abbreviation

• AHB - AMBA Advance High Speed Bus.

• AP - Access Point

• API - Application Programming Interface

• FullMac - FullMAC architecture is best suited for embedded systems where host memory and MIPS are

constraints. FullMAC is a complete firmware that runs on NIC and provides 802.11 functionality. FullMAC

firmware runs from Internal Memory only and supports wireless client mode functionality only.

• LAN - Local Area Network

• Linux - Linux Operating System

• MAC - Medium Access Control

• NIC - Network Interface Controller

• OID - Object Identifier

• OS - Operating System

• PCMCIA - Personal Computer Memory Card International Association (16 Bit)

• PIMFOR - Proprietary Integrated Mechanism For Object Relay

• RAM - Random Access Memory

• ROM - Read Only Memory

• SHOC - Self Hosted Client: It is the complete firmware that runs on NIC and provides 802.11 functionality.

SHoC firmware can run from both internal and external memory. Firmware running in SHoC mode can

work in both client and AP mode.

• SRAM - Static Read Only Random Access

• STA - Station

• SSID - Sevice Set Identifier

• Vendor ID - Vendor Identification Number

1-2 LA-51XX Compact Flash Adapter Driver Programmer’s Guide

• WLAN - Wireless LAN.

• WRM - The file format containing the firmware

1.3 System Architecture

The following figure depicts the system architecture comprising the SHoC firmware, SHoC driver and

applications that interact with driver to configure SHoC firmware:

SHoC Driver: The SHoC driver provides an interface between the firmware running on the device and the

operating system running on the host. The SHoC driver is responsible for obtaining data frames and requests

from the upper layers and converting them into a format understood by the firmware running on the WLAN

device. It is also responsible for obtaining data frames, response, and traps from the device.

Driver API: The Driver APIs abstract details of the WLAN device to the higher layers.

SHoC Firmware: The Firmware provides 802.11functionality. It receives 802.3 data packets from the driver

on host, converts them into 802.11 data packets and sends them to the wireless media. Similarly, it receives

802.11 packets from wireless media, converts them to 802.3 packet and passes them to the driver on host.

The SHoC architecture implements majority of the 802.11 functionality on the WLAN device. In some MAC

architectures, the 802.11 MAC is partitioned such that most of the 802.11 functionality is performed on the

host and only time critical functions are performed on the WLAN device.

Applications:

• setoid()/getoid() are required to configure and read the values configured on wireless NIC firmware as

and when required.

• Port Access Entity Daemon (PAED) is used for all security/authentication on the AP viz. ACL/WPA/WPA2

etc and normally runs as a daemon.

PAED is a server process that handles authentication and security for wireless access points. It supports

following security modes:

• Open system

• WEP (40 and 104)

• Legacy 802.1x with WEP

Introduction 1-3

• SSN/WPA, with AES and TKIP ciphers, and EAP and PSK authentication

• RSN/WPA2, with AES and TKIP ciphers, and EAP and PSK authentication.

1-4 LA-51XX Compact Flash Adapter Driver Programmer’s Guide

SHoC Driver Design

The SHoC driver is designed for embedded systems. It works with the SHoC firmware running on an 802.11

device. The following sections describe the functionalities and components of the driver.

2.1 Initialization

After the device has been powered up, the driver is responsible for writing a firmware image into the device's

internal memory. Only after this firmware image has been loaded and started, subsequent communication

can take place.

For the driver, only the AHB-RAM memory is directly accessible, which has a size of 64KB. Since firmware

file is larger, it cannot be uploaded in a single step. It is therefore necessary to split the firmware into a

number of smaller blocks, and to have a simple program on the device, which accepts and disposes these

firmware blocks. The former is solved by the WRM file format; the latter is solved by the Upload Helper.

2.1.1 WRM file format

The WRM format is an array of n blocks, which must be parsed by the driver. Each block is uploaded

separately, and a simple set of rules are defined on how the driver should behave after a single block has

been uploaded. A common block consists of a header (blue) containing information for the driver, and a block

of data (white) opaque to the driver. The driver shall only upload the opaque data. The following illustration

shows a WRM block:

2-2 LA-51XX Compact Flash Adapter Driver Programmer’s Guide

The B-bit is the most significant bit of the 32-bit (little endian) MAX_WAIT field. When set, B-bit tells the

driver to issue a RAM-Boot after the corresponding block has been uploaded. A RAM-boot causes the ARM

to reset and start executing code from the start of SRAM. The SIZE field specifies how many bytes of (white)

payload follow the WRM block header.

The (white) blocks of data are disposed of by the Upload Helper (UH) binary on the device. The driver and the

UH use a PCI interrupt as handshake signal to tell each other that they are ready for the next block. The driver

shall wait for at least MAX_WAIT microseconds for UH’s sign of readiness before it may conclude that the

upload failed for some reason.

2.1.2 Upload Helper Function

The UH forms the content of the first WRM block, and the Boot flag tells the driver to RAM-boot after the

block is uploaded. This effectively boots the UH, which installs itself at address 0 (ITCM) and starts

communicating with the driver through the software-defined READY interrupt (mask 0x2000) as the

handshake signal. UH implements a simple loop through the following steps:

1. Wait for a READY interrupt from the host/driver.

2. Clear the host’s READY interrupt.

3. If no-copy (NC) bit is not set, it copies Size bytes of binary data to its destination specified by Destination.

4. Set the READY interrupt to the host/driver.

5. If no-jump (NJ) bit is not set, it jumps to the Jump address.

The UH then waits for the driver to upload the next block, copies it to its destination and signals its

readiness.

SHoC Driver Design 2-3

NOTE: The UH expects all uploaded blocks start with a well-formatted header. This header defines the

Destination where the binary data (red) inside the block should be copied. If no-copy (NC) flag (L) is set,

UH should skip copying the binary data. Size defines how many bytes of binary data there are. Jump

contains the address the UH should jump to (by means of a branch instruction) when it is done with the

block at hand. If no-jump (NJ) flag (LSB) is set, the UH shall skip the jump instruction.

2.1.3 Tasks Performed by the Driver

The driver parses the WRM file and uploads the firmware blocks based on the information to different WRM

block headers. The driver also runs in a loop implementing the following steps:

1. Copy SIZE bytes of opaque data to the “0x1ffe0000” location of SRAM.

2. Issue a READY interrupt to the wireless NIC.

3. Issue a RAM-Boot if the Boot-bit of the corresponding WRM block is set.

4. Wait for a READY interrupt from the wireless NIC.

5. Clear the READY interrupt when detected.

6. Timeout and fail the upload after MAX_WAIT microseconds.

After receiving READY interrupt for the last block in WRM file, the driver shall expect that the regular

firmware boot process has started, and it may continue with the regular PCI protocol initialization. Please

refer [1] for PCI protocol initialization procedure.

2.1.4 Overview of Firmware Upload

The firmware upload process entails the following:

1. The driver copies UH into device AHB-RAM memory.

2. The driver issue a RAM-Boot to boot the UH.

3. On booting UH installs itself at address 0 (ITCM) and starts communicating with the driver using PCI

interrupt (Software defined READY interrupt) as handshake signal to tell the other that they are ready for

the next block.

4. The driver copies next block in device memory and UH copies it from AHB-RAM to its destination address.

This step gets repeated till last WRM block gets transferred from host driver to device.

5. In last WRM block NJ bit is not set and code jumps to the Jump address. This is the address from where

firmware starts its execution.

6. The device informs driver its readiness by setting ‘Initialized’ bit in ‘Host Interrupt’ register.

2.1.4.1 RAMBoot

The device boots from Boot ROM by default. In this case, Boot ROM reads the Manufacturing ID, initializes

the CLK, device internal memory etc. After the firmware downloads, it gets initialized by issuing RAMBoot

from the Host. The Boot Process starts from the first instruction of the firmware.

The driver issues RAM-Boot using the following sequence of operations on the Control/Status register.

1. Clear the Reset bit.

2. Set the RAMBoot bit.

3. Set the Reset bit.

4. Clear the Reset bit.

2-4 LA-51XX Compact Flash Adapter Driver Programmer’s Guide

2.1.5 Firmware Upload Flow

This diagram depicts the complete initialization flow of the 802.11 SHoC device and shows the information

flow between various procedures called during the initialization process.

SHoC Driver Design 2-5

2.2 Management Path

This topic discusses programming interface between the device and the host. The management information

is encapsulated by means of the ‘Proprietary Integrated Mechanism For Object Relay’ (PIMFOR) and

conveyed between the host and device.

2.2.1 PIMFOR

Management information is modeled as a set of variables (or managed objects) residing in an internal

management information base (MIB). These objects can be queried for their value and/or can be set. Each

managed object is uniquely identified by an Object Identifier (OID). Each variable has an associated type that

has specific syntax and semantics with respect to the values it can take. For PIMFOR, however, these values

are opaque. PIMFOR simply conveys the value of the variable as an octet string; it doesn’t convey type

information. It is the responsibility of senders and receivers of PIMFOR packets to know the type of a

variable, how to encode this type in an octet string, and syntactical and/or semantic constraints (if any) of

the variable when performing operations on it. The protocol purely acts as a transport of management

information. PIMFOR peers may assume correctly formatted packets and mutual understanding of the MIB.

This design decision is justified by the assumption that PIMFOR is meant to be a management interface

internal to a product (for example, between host driver and firmware). It is not meant to be used by third-

party applications directly. The generic packet interface of PIMFOR makes it suitable for a variety of other

situations where a simple form of management and control is desired.

2.2.1.1 PIMFOR Packet Format

Proprietary Integrated Mechanism For Object Relay (PIMFOR) was devised to fill the need for simple

management and configuration of NIC firmware through host driver.

The MAC implements a wealth of configurable objects, which are accessed by sm_conf() function to

configure the MAC. PIMFOR is also used by sm_trap() which is used for sending async traps from the MAC

to the driver. To access these objects from the host, the PIMFOR frame format is used over Mgmt queues of

the PCI protocol. In case of a get operation, the driver waits for the firmware to respond for the value and

then passes the response encapsulated in PIMFOR frame to the host.

2.2.1.2 PIMFOR Header Format

PIMFOR is a proprietary format. The PIMFOR header format is shown in below:

2-6 LA-51XX Compact Flash Adapter Driver Programmer’s Guide

PIMFOR Header Description

Version: The current PIMFOR version.

Operation: The operation is one of the following:

Get and Set are only sent by a PIMFOR sender such as application/ driver; Response, Error, and Trap are only

sent by a PIMFOR receiver i.e. firmware on device. When the operation is Get, the sender asks the receiver

to retrieve the value for the variable specified in the OID field and to send this back in a Response. When the

operation is Set, the sender instructs the receiver to set the variable specified in the OID field to the value

(encoded in an opaque octet string) in the Value field. The Value Length field indicates the length of the octet

string contained in the Value field. There is no type information involved: sender and receiver must be aware

of syntactical and semantic constraints of the OID on which they are operating.

Both Get and Set normally yield a response (Operation is set to Response). For Get, the response contains

the value of the requested OID. For Set, the response is merely an acknowledgment that the set was

successful. There is no new information in the response to a Set; it is identical to the Set, except for the

Operation field. An error is returned in response to a Get or a Set if the receiver cannot process the request

correctly (for example in the case of an unknown OID). A trap is an asynchronous notification from the

firmware on device to alert driver on host to a specific situation or change. The OID and value contained in

the Trap indicate to which variable the notification refers. Reserved is not being used and reserved for future

use.

OID: The OID is a 32-bit value uniquely representing a variable or managed object in a system. There is only

one OID involved in a PIMFOR packet.

Value Length: Value Length indicates the length of the value that follows in the Value field. For a Get, the

Value Length must be greater than or equal to the length of the value (expressed as an octet string) of the

variable that is retrieved. For example, for a variable representing a 32-bit integer, Value Length typically is

four. Value Length can be set to zero for a Get, whereupon the PIMFOR receiver shall return a PIMFOR Error.

In this case however, the PIMFOR receiver sets Value Length to indicate the number of bytes that are

necessary to retrieve the value of that variable. Another request can then be sent using a large enough buffer

to contain the number of bytes required. This can be used for arrays of unknown length or for variable-length

strings. Value: An (opaque) octet string of length Value Length that must be present in each PIMFOR packet.

For a Get, this field must also be present, but it is ignored by a PIMFOR receiver. For Set and Response, this

field contains the value of the variable represented as an octet string. Again, it is implementation-specific

as to how a value of a specific type is converted to an octet string.

2.2.2 Getoid

This section depicts the flow of management (control) information when a getoid is called from the

application running on host to fetch the information from firmware running on host.

SHoC Driver Design 2-7

2.2.2.1 Flow Description

1. When the driver receives the request from the getoid application through Netlink Interface, it frames the

request in the s_sm_conf format using sm_drv_get() function:

struct s_sm_conf

{

uint16_t flags;

uint16_t length;

uint32_t oid;

uint8_t *data;

};

2. The s_sm_conf structure is passed to sm_drv_conf(), which sets the PIMFOR Header and reads the value

of flags set and checks if the packet is for PIMFOR_OP_SET or PIMFOR_OP_GET

3. The structure is added into Tx Control queue after converting into fragment

4. Increments Driver_Current_fragment queue value. This queue pointer is used to maintain

synchronization between device and host. Driver interrupts the device for the packet in the transmit

control queue

5. The driver suspends the application until a response is received from the firmware:

a. Put on the sleep queue.

b. When response is received, need to distinguish whether it is a TRAP or a response to the GET

operation.

c. If it is a response, wake up the sleeping process.

6. Pass the response to the application.

2-8 LA-51XX Compact Flash Adapter Driver Programmer’s Guide

2.2.2.2 Flow Diagram

2.2.3 Setoid

This section depicts the flow of management (control) information when a setoid is called from the

application running on host to set the configurable parameters on the firmware running on host.

SHoC Driver Design 2-9

2.2.3.1 Flow Description

1. When the driver receives the request from the setoid application, it frames the request in the s_sm_conf

format using sm_drv_set() function:

struct s_sm_conf

{

uint16_t flags;

uint16_t length;

uint32_t oid;

uint8_t *data;

};

2. The s_sm_conf structure is passed to sm_drv_conf, which sets the Pimfor Header and reads the value

of flags set and checks if the packet is for PIMFOR_OP_SET or PIMFOR_OP_GET

3. The structure is added into Tx Control queue after converting into fragment. Driver interrupts the device

for the packet in the transmit control queue

4. Increments Driver_Current_fragment queue value.

2.2.3.2 Flow Diagram

2-10 LA-51XX Compact Flash Adapter Driver Programmer’s Guide

2.3 Data Path

The Data Path provides an interface to the operating system running on host and the firmware running on

device to handle ingress and egress calls of data transfer. These packets are Ethernet 802.3 packets.

2.3.1 Tx Data Path

2.3.1.1 Flow Diagram

2.3.1.2 Flow Description

1. The Network Stack delivers an 802.3 data frame for transmission to the Wireless Card by calling the

driver transmit function. The transmit function verifies whether the data frame can be transmitted or not

by assessing the queue availability.

2. It then converts the socket buffer to be transmitted into frame format having ic_msg and s_sm_frame

header and adds it to the queue.

3. The host driver adds the frame into Tx Queue Control Block and the Driver current queue pointer is

updated.

SHoC Driver Design 2-11

4. The driver issues the Update Interrupt to the device. The device on obtaining the interrupt, will initiate

the DMA of the data buffer.

5. Once the frame is obtained by the firmware on the device, it converts the frame (802.3 format) to the

802.11 format and transmits on the air.

2.3.2 Rx Data Path

2.3.2.1 Flow Diagram

2.3.2.2 Flow Description

1. The Wireless Card receives a data frame and processes it in the firmware to convert it from 802.11 format

to 802.3 format. The driver allocates a few data frames during initialization, such that the data is returned

in one of these frames. Then it replenishes these frames periodically.

2. The device DMAs the received data frame through the PCI Bus interface to the host. Please refer [1] for

PCI host interface description.

3. The device informs the driver a frame has been placed in the receive queue by generating an Update IRQ

after updating the receive data queue device counter.

4. The driver reads the data frame from the Control Block and in case of a data frame it converts the frame

into a socket buffer and then sends it to upper layer and in case of a control frame the driver calls the

appropriate handling function.

5. The removed frame in the Control Block receive queue is filled again by a frame allocate driver function.

2-12 LA-51XX Compact Flash Adapter Driver Programmer’s Guide

2.4 Important Data Structures

These are the control block data structures which can be sub-divided into Data and Management path

structures based on their functionalities.

2.4.1 Data Path Structures

struct fragment

{

uint32_t host_address;

uint16_t size;

uint16_t flags;

};

#define CB_QCOUNT 4

#define CB_RX_DATA_QSIZE 8

#define CB_TX_DATA_QSIZE 32

#define CB_RX_CTRL_QSIZE 4

#define CB_TX_CTRL_QSIZE 4

struct control_block

{

uint32_t driver_curr_frag[CB_QCOUNT];

uint32_t device_curr_frag[CB_QCOUNT];

struct fragment rx_data[CB_RX_DATA_QSIZE];

struct fragment tx_data[CB_TX_DATA_QSIZE];

struct fragment rx_high_data[CB_RX_DATA_QSIZE];

struct fragment tx_high_data[CB_TX_DATA_QSIZE];

struct fragment rx_control[CB_RX_CTRL_QSIZE];

struct fragment tx_control[CB_TX_CTRL_QSIZE];

}

Page is loading ...

Motorola LA-51XX Driver Programmer's Manual

Motorola LA-51XX Driver Programmer's Manual

Motorola LA-51XX Driver Programmer's Manual

Related papers

Other documents