UM0479

User Manual

SPEAr® Plus Linux SDK, kernel and device APIs

Introduction
This document provides information about the Linux kernel and the device drivers provided
by the SPEAr Plus Linux SDK. The Linux kernel is the core component of an overall Linux-
based software solution.
This SDK version supports Linux kernel 2.6.19.2. A predefined Linux kernel is provided as
pre-stored on NOR Flash memory for SPEAr Plus development boards. Such kernel may be
immediately used for both initial assessment and application development.

September 2008 Rev 2 1/62

www.st.com
Contents UM0479

Contents

1 Reference documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

2 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.1 Acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

3 Kernel overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.1 Device runtime architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.2 Rebuilding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.3 Handling modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.4 Flashing and booting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

4 User-space APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.1 A/D converter (ADC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.2 Ethernet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.3 General-purpose input/output (GPIO) . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.4 Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
4.5 I2C bus and EEPROM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
4.6 Inter-processor communication (IPC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
4.7 JPEG codec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
4.8 Real-time clock (RTC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
4.9 Slave CPU control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.10 Synchronous serial ports (SSPs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.11 Asynchronous serial ports (UARTs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.12 USB device (gadget filesystem) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
4.13 USB hosts (mass storage and USB filesystem) . . . . . . . . . . . . . . . . . . . . 27
4.14 Watchdog timer (WDT) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

5 Kernel-space APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
5.1 A/D converter (ADC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
5.2 Direct memory access (DMA) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
5.3 General-purpose input/output (GPIO) . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
5.4 I2C bus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

2/62
UM0479 Contents

5.5 Inter-processor communication (IPC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

5.6 Synchronous serial ports (SSPs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
5.7 USB device (gadget framework) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
5.7.1 Gadget driver management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
5.7.2 Endpoint management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
5.7.3 Endpoint I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
5.8 USB hosts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
5.9 Watchdog timer (WDT) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Appendix A Source files for built-in drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Appendix B Default kernel configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

6 Revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

3/62
List of tables UM0479

List of tables

Table 1. Acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Table 2. Network interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Table 3. Open sockets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Table 4. ARP mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Table 5. IP routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Table 6. GPIO assignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Table 7. USB filesystem ioctl requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Table 8. Gadget driver structure fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Table 9. Gadget structure fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Table 10. Endpoint structure fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Table 11. USB driver structure fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Table 12. USB interface structure fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Table 13. SDK 1.1 driver summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Table 14. Document revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

4/62
UM0479 List of figures

List of figures

Figure 1. Device runtime architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

5/62
Reference documentation UM0479

1 Reference documentation

1. STMicroelectronics, SPEAr Plus – Linux SDK, getting started, SW Ver. 1.1

2. STMicroelectronics, SPEAr Plus – Linux SDK, kernel and device APIs, SW Ver. 1.1
3. STMicroelectronics, SPEAr Plus – Linux SDK, embedded root filesystem, SW Ver. 1.1
4. STMicroelectronics, SPEAr Plus development board, user manual
5. STMicroelectronics, SPEAr Head600 datasheet, http://www.st.com
6. STMicroelectronics, SPEAr Plus600 datasheet, http://www.st.com
7. BusyBox, http://www.busybox.net
8. Free Software Foundation, The GNU C Library Reference Manual, Edition 0.11,
December 2006, Ver 2.6, http://www.gnu.org/software/libc/manual/
9. Denx Software Engineering, ELDK 4.1, http://www.denx.de
10. O’Reilly, Understanding the Linux kernel, 3rd Edition, 2006.

6/62
UM0479 Introduction

2 Introduction

This document provides information about the Linux kernel and the device drivers provided
by the SPEAr Plus Linux SDK (referred as just “SDK” in the following). The Linux kernel is
the core component of an overall Linux-based software solution.
A detailed description of Linux kernel is out of the scope of this document. For a good
reference book on this subject see [10]. Anyway, the main functionality provided by the
kernel can be summarized as follows:
● Task scheduling
● Memory management
● Inter-process communication and synchronization
● Virtual filesystem
● Interrupt / exception handling
● I/O devices integration framework
● Built-in filesystems
● Built-in protocol stacks (e.g. IP, Bluetooth, USB)
● Dynamic extension through modules
This SDK version supports Linux kernel 2.6.19.2. A predefined Linux kernel is provided as
pre-stored on NOR Flash memory for SPEAr Plus development boards. Such kernel may be
immediately used for both initial assessment and application development.
Changing the kernel is mostly performed at platform software development stage, in
particular when writing and testing specific additional device drivers or assessing different
configurations. At this stage, since updates are very frequent, the U-Boot resident monitor
may be configured to automatically download the specified kernel through Ethernet from a
host PC at each target reset.
When kernel configuration and contents become more stable along a project, the kernel
may be kept as resident in flash memory and only user-space software (in the so-called root
filesystem [3], a component that is separated from the kernel) is dynamically modified on-
demand. Persistent storage of kernel on flash is also required in order to make a stand-
alone self-booting system (and, of course, in the final product). Finally, rewriting the kernel
on flash is required if the flash area allocated to the kernel has been erased or damaged for
any reason.
An additional mechanism is made available by the Linux architecture. Besides static linking
with the kernel binary image, kernel extensions may be also compiled as “modules” (also
known as LKM, Loadable Kernel Modules). Such modules are stored outside the kernel
image, namely inside the root filesystem. Modules are then dynamically loaded (and
potentially unloaded) on demand by user-space software. However, modules maintain the
same properties of code that is statically linked with the kernel. More specifically, modules
operate in kernel (physical) address space and may directly access to any exposed kernel
function or data structure.
In order to minimize flash memory occupation, as well as to make downloads faster, it is
recommended to operate with a compressed kernel binary image. Usually about 50% size
reduction may be obtained using the GZ algorithm. Compression is a post-processing step
applied when rebuilding the kernel and is also part of the build procedure predefined by the
SDK. Decompression is performed on the fly by U-Boot when loading the kernel to system
RAM for execution.

7/62
Introduction UM0479

In next sections, the procedures to rebuild and use the kernel and LKM modules are first
discussed. The device APIs of the default kernel are then described.
Interactive commands are shown in courier bold font. The “#” prompt is assumed for the
Linux shell on the target board. The “$” prompt is assumed for the Linux shell on the PC
host. The “spearplus>” prompt is assumed for interaction with the resident
bootloader/monitor (U-Boot).
Finally, in this entire document, it is assumed that the SDK 1.1 package has been installed
on a Linux PC host under the recommended path:
/opt/splus_linux_sdk_1_1/

2.1 Acronyms
Table 1. Acronyms
Acronym Explanation

ADC A/D converter

API Application programming interface
ARP Address resolution protocol
CRAMFS Compressed ROM file system
CRC Cyclic redundancy check
DMA Direct memory access
EHCI Enhanced host controller interface
ELDK Embedded linux development kit
FAT File allocation table
GPIO General purpose I/O
GPL General public license (GNU)
HAL Hardware abstraction layer
HW Hardware
I2C Inter-integrated circuit bus
IP Internet protocol
IPC Inter-process communication
ISR Interrupt service routine
LKM Loadable kernel module
LAN Local area network
MAC Media access control
MTD Memory technology device
NFS Network file system
OHCI Open host controller interface
OS Operating system

8/62
UM0479 Introduction

Table 1. Acronyms (continued)

Acronym Explanation

RAM Random access memory

RTC Real-time clock
RTOS Real time operating system
SDK Software development kit
SoC System on chip
SPEAr Structured processor enhanced architecture
SSP Synchronous serial port
SW Software
TFTP Trivial file transfer protocol
UART Universal asynchronous receiver-transmitter
USB Universal serial bus
VIC Vectored interrupt controller
WDT Watchdog timer

9/62
Kernel overview UM0479

3 Kernel overview

3.1 Device runtime architecture

An overview of the devices supported in SDK 1.1 and their runtime architecture is depicted
in Figure 1. Software interfaces to each device are described in detail in next chapters.
User-space APIs (labeled UAPI in the diagram) are intended to be used from application
software and middleware executing in some user address space and invoking system calls
to interact with device drivers and other kernel layers. Kernel-space APIs (labeled KAPI in
the diagram) are intended to be used from components executing in kernel address space
and directly invoking function calls.

Figure 1. Device runtime architecture

User
Space
Sockets /dev/ttyS0
/proc/net /dev/gpio /dev/i2c /dev/rtc /dev/ttyS1 /proc/bus/usb Filesystem

ETH GPIO I2C RTC UART USBH MSC

UAPI UAPI UAPI UAPI UAPI UAPI UAPI

Gadget
Zero USBFS VFAT

DMA GPIO I2C USBD USBH MSC

KAPI KAPI KAPI KAPI KAPI Driver

kernel
console
IP Device Host
Stack Stack Stack

DMA Ethernet GPIO I2C RTC UART USBD USBH Kernel

Driver Driver Driver Driver Driver Driver Driver Driver Space

DMA Ethernet GPIOs I2C RTC UARTs USBD USBD USBD SoC
Controller Controller Controller (2) Ctrl+PHY Ctrl+ Ctrl+ Hardware
PHY PHY

Dev.
Ethernet LEDs EEPROM Battery RJ11 J16 USBD USBH USBH Board
PHY SW3 Switch Conn. Conn. Conn. Conn.
J19 Conn.

RJ45

10/62
UM0479 Kernel overview

3.2 Rebuilding
The Linux kernel, provided in source code inside the SDK, needs to be rebuilt in the
following typical cases:
● the source code of a new device driver is added or an existing driver source has been
modified
● the value of some kernel configuration options must be changed (e.g. to enable the use
of an additional protocol stack or filesystem)
The kernel contents are modified by directly adding files and/or editing existing files in the
kernel source tree. When new files are added, some Makefile and Kconfig files have
usually to be adapted as well.
It is important to remark that custom extensions or modifications that are statically linked to
the kernel are constrained by the GPL licensing policy. In other terms, any statically linked
extension is considered as a kernel derivative work and must be licensed as a GPL
component. On the other hand, for kernel extensions implemented as dynamically loaded
modules, no GPL policy automatically applies.
The SDK provides two default kernel configuration files, located under path:
/opt/splus_linux_sdk_1_1/src/linux-2.6.19.2/arch/arm/configs
The spearplus_defconfig file contains the standard configuration to be used. For
debugging purposes, an alternative configuration is also available, named
spearplus_dbg_defconfig. The latter file provides the same functionality as the former
one, but the kernel will be compiled with debugging options.
The kernel (as well as any module specified in the selected configuration file) may be rebuilt
with the configuration defined in spearplus_defconfig using the following commands:
$ cd /opt/splus_linux_sdk_1_1
$ build.sh linux
The output of this operation is a compressed kernel binary image located under:
/opt/splus_linux_sdk_1_1/flash/linux.uimg
This file is already in the proper format to be used by U-Boot for flashing or loading on-
demand through TFTP. The following commands also rebuild everything including the kernel
from standard configuration file:
$ cd /opt/splus_linux_sdk_1_1
$ build.sh all
In order to build a debugging kernel version, the following commands need to be used:
$ cd /opt/splus_linux_sdk_1_1
$ build.sh linux_dbg
The output of this operation is a compressed kernel binary image located under:
/opt/splus_linux_sdk_1_1/flash/linux_dbg.uimg

11/62
Kernel overview UM0479

3.3 Handling modules

As already anticipated, loadable kernel modules (LKM) are dynamically loaded and linked
on demand by user-space software while maintaining the same properties of code that is
statically linked with the kernel. Hence, modules operate in physical address space and may
directly access to any exposed kernel function or data structure.
Modules are single ELF object files identified by the.ko extension. Modules are
automatically recompiled when rebuilding the kernel. Some components of the Linux kernel
have the option of being rebuilt as modules instead of statically linked with the kernel image.
This option may be enabled with the “=M” assignment (instead of “=Y”) inside the kernel
configuration file.
Moreover, custom modules may be developed. An online guide to develop custom modules
for the Linux 2.6 series of kernels can be found at address:
http://www.tldp.org/LDP/lkmpg/2.6/html/index.html
Modules have to be developed according to special requirements. As an example, the
following is the simplest module that can be designed. Special macros are shown in
courier bold font.
// simplest.c
#include <linux/module.h>// needed by all modules
#include <linux/kernel.h>// needed for KERN_INFO
#include <linux/init.h> // needed for macros
MODULE_AUTHOR("ST Microelectronics");
MODULE_DESCRIPTION("Simplest module");
MODULE_LICENSE("GPL");
static int __init simplest_init(void)
{
printk(KERN_INFO "Loading simplest module\n");
return 0; // a non-zero return value will prevent module loading
}
static void __exit simplest_exit(void)
{
printk(KERN_INFO "Unloading simplest module\n");
}
module_init(simplest_init);
module_exit(simplest_exit);

3.4 Flashing and booting

A NOR Flash memory update is required to use a custom flashed kernel or when a new
version of the default kernel is delivered by ST.
On the NOR Flash, sector range 5-47 is reserved to the kernel partition. Since each sector
is 64 Kbyte, the maximum size of the kernel image is 2752 Kbyte.
It is very important to assure that the Linux kernel partition is restored to write-protected
mode after any flash update. Any unexpected writing access to the kernel partition will
usually lead to a system bootstrap failure. In fact, besides software updates, there is no
other case where writing to this partition is required. Write-protection, anyway, is already
performed by ST-provided scripts as discussed below.

12/62
UM0479 Kernel overview

An Ethernet host-target link is the fastest way to support flash updating. A predefined U-
Boot script called flash_linux_eth has been made available as predefined on the
development boards to minimize manual steps. In order to update the kernel partition with a
new Linux binary image using Ethernet, the following procedure has to be performed:
1. Connect the target board to a PC using both a null-modem serial cable (the UART0
DB9 connector must be used) and an Ethernet cross cable or an Ethernet hub/switch.
2. Assure that the TFTP server is running on the PC host and copy the linux.uimg file
(or linux_dbg.uimg for the debugging version) to the default TFTP server directory.
3. Launch a terminal emulator (HyperTerminal, minicom, etc.) on the PC. The PC serial
port must be set to 115200 bps, 8-N-1 mode, no flow control.
4. Switch on or just reset the target board and enter the U-Boot monitor interactive mode.
5. From U-Boot prompt, execute the following command:
spearplus> run flash_linux_eth
This will first start the transfer of the file from PC to the board over Ethernet. After the
transfer, the command will automatically proceed by completing all required steps for
flashing and verification.
An alternative to Ethernet for flash updating is the use of a serial link and the Kermit
protocol. This approach is slower but still helpful when an Ethernet link is not available. A
predefined U-Boot script called flash_linux_uart has been made available as
predefined on the development boards to minimize manual steps. In order to update the
kernel partition with a new Linux binary image using the serial link, the following procedure
has to be performed:

1. Connect the target board to a PC using a null-modem serial cable (the UART0 DB9
connector must be used).
2. Launch a terminal emulator with Kermit support (HyperTerminal, minicom, etc.) on the
PC. The PC serial port must be set to 115200 bps, 8-N-1 mode, no flow control.
3. Switch on or just reset the target board and enter the U-Boot monitor interactive mode.
4. From U-Boot prompt, execute the following command:
spearplus> run flash_linux_uart
U-Boot is now waiting for a Kermit file transfer from the PC terminal. The linux.uimg
file must be selected from a PC directory (or linux_dbg.uimg for the debugging
version). After the transfer is started on the PC, the command will go on by transferring
(using Kermit) the file over serial cable and completing all required steps for flashing
and verification.

System bootstrap with the flashed Linux kernel is normally performed with the following U-
Boot environment setting:
bootcmd=bootm 0xf8050000
When the Linux kernel is often changed, it may be useful to boot it directly from a host PC
instead of updating the NOR Flash everytime. This approach may be followed by just
changing the U-Boot environment variable as follows:
spearplus> setenv bootcmd tftpboot 0xF8050000 linux${dbg}.uimg
In this way, the kernel will be downloaded from a TFTP server at each board reset and then
executed.

13/62
Kernel overview UM0479

In order to use the alternative debugging version of the kernel, the dbg variable must be set
to “_dbg” as follows:
spearplus> setenv dbg _dbg
Consult appendix A of document [1] to fully restore default U-Boot settings in case of any
damage to them.

14/62
UM0479 User-space APIs

4 User-space APIs

The APIs to access SPEAr Plus devices from user-space software are described in the
following sections. Access is always performed internally through system calls, since there
is no static or dynamic linking of the relevant device drivers with application software.
It should be noted that user-space APIs are exposed only for devices that actually require
this access level. For instance, there is no need to expose a user-space API for DMA.
Standard Linux APIs are exploited wherever applicable (e.g. Ethernet, RTC, UARTs, USB
mass storage). In all other cases an ST-specific API has been defined for each kind of
device, while still based on standard I/O function calls.

4.1 A/D converter (ADC)

A device driver for the SPEAr Plus A/D Converter (ADC) and the relevant user-space API
shall be provided in future SDK releases.

4.2 Ethernet
The Ethernet port is usually accessed by user-space applications indirectly, by means of the
standard Linux Sockets API, available in the C runtime library [8], on top of the IP protocol
stack integrated in the kernel.
In addition, information about the Ethernet device is accessible to user-space through the
/proc/net pseudo file tree. These logical files may be directly accessed by user-space
commands and applications using standard library functions like for real files.
The /proc/net/dev file contains information about the configured network interfaces.
There is one text line for each logical network interface known to the kernel. For a SPEAr
board connected to a PC or to a LAN, there will be two interfaces named: eth0 and lo
(loopback). In each line you are given the interface name followed by two sets of nearly
identical statistics, receive and transmit, for that interface. The meanings of each of the
columns are:

15/62
User-space APIs UM0479

Table 2. Network interfaces

Column Description

bytes The total number of bytes of data transmitted or received by the interface.
packets The total number of packets of data transmitted or received by the interface.
errs The total number of transmit or receive errors detected by the device driver.
drop The total number of packets dropped by the device driver.
fifo The number of FIFO buffer errors.
frame The number of packet framing errors.
colls The number of collisions detected on the interface.
compressed The number of compressed packets transmitted or received by the device driver.
carrier The number of carrier losses detected by the device driver.
multicast The number of multicast frames transmitted or received by the device driver.

The /proc/net/tcp, /proc/net/udp and /proc/net/raw files contain information

about currently open sockets (if any), for TCP, UDP and raw mode respectively. All three files
have the same tabular format with columns defined as follows:
:

Table 3. Open sockets

Column Description

sl The number of the line in the output listing.

The local IP address and port number for the socket. The IP address is displayed
as a little-endian four-byte hexadecimal number; that is, the least significant byte
local_address
is listed first, so you'll need to reverse the order of the bytes to convert it to an IP
address. The port number is a simple two-byte hexadecimal number.
The remote IP address and port number for the socket. Encoding is the same as
rem_address
for the local_address.
st The socket status.
tx_queue The size of the transmit queue.
rx_queue The size of the receive queue.
Indicates whether a timer is active for this socket. A value of zero indicates the
tr
timer is not active.
tm->when Indicates the time remaining (in jiffies) before timeout occurs.
retrnsmt Unused.
The ID of the user that owns the socket. This is the same ID found in the
uid
/etc/passwd file.
timeout Unused.
inode A cryptic-looking number that identifies the socket to the Linux virtual filesystem.

The /proc/net/arp file contain the ARP table. ARP is the low-level protocol used by Ethernet
networks to enable a mapping from IP addresses (layer 3) to MAC addresses (layer 2). The
columns have the following meaning:

16/62
UM0479 User-space APIs

Table 4. ARP mapping

Column Description

IP address The IP address.

See definitions under Linux sources, in the header file:
Flags
linux-2.6.19.2/include/linux/if_arp.h
See definitions under Linux sources, in the header file:
linux-2.6.19.2/include/linux/if_arp.h
HW type
The 0x1 value indicates Ethernet hardware (ARP is used also for other network
technologies).
HW address The MAC address.
Typically shown as ‘*’.
Mask Used when advertising a promiscuous ARP entry for an IP network or
subnetwork.
Device Device name: eth0

The /proc/net/route file contain the IP routing table. The columns have the following
meaning:

Table 5. IP routing
Column Description

The network interface that datagrams matching this route will leave. For a SPEAr
Iface
Plus board, this may be eth0 or lo.
In combination with the Mask field, specifies which datagrams will match this
Destination
route.
The IP address of the host that will act as a router for datagrams matching this
Gateway
route.
An indicator of various route attributes.
Flags See definitions under Linux sources, in the header file:
linux-2.6.19.2/include/linux/route.h
RefCnt Unused.
Use Unused.
The metric value associated with the route. This is used to indicate the cost or
Metric
priority of a route.
In combination with the Destination field, this specifies which datagrams will match
Mask
this route.
Specifies the largest TCP segment (in bytes) that will be built for transmission via
MTU
this route.
Specifies the TCP window (in bytes) that will be advertised for TCP connections
Window
made via this route.
Specifies the Initial Round Trip time (in milliseconds) that will be used for TCP
IRTT
connections established via this route.

The /proc/net/snmp file exports protocol statistics. It may be used for performance
analysis purposes or by a SNMP (Simple Network Management Protocol) daemon program

17/62
User-space APIs UM0479

(not provided with SDK). It reports summary statistics for each of the IP, ICMP, TCP, and
UDP protocols.
Very detailed access to networking information may be finally achieved using the
/proc/sys/net subtree.

4.3 General-purpose input/output (GPIO)

The SPEAr Plus chip has internally 3 General-Purpose I/O (GPIO) digital blocks, each of
them provided with 8 lines, for a total of 24 lines. However, only 10 GPIO lines are made
available by the chip as external pins: four of them are connected to a dip switch (SW3) on
the development board, so that they may be easily read from software for any custom
purpose; other two of them are controlling corresponding yellow and green LEDs. Finally, all
of the 10 exposed lines are also available on the J19 (GPIO) connector.
The following table provides a summary of available GPIO lines:

Table 6. GPIO assignment

SoC subsystem Block Line Dev.board

Application GPIO 0 0 Switch SW3 – 1 and J19 connector

Application GPIO 0 1 Switch SW3 – 2 and J19 connector
Application GPIO 0 2 Switch SW3 – 3 and J19 connector
Application GPIO 0 3 Switch SW3 – 4 and J19 connector
Application GPIO 0 4 Yellow LED (D5) and J19 connector
Application GPIO 0 5 Green LED (D6) and J19 connector
Application GPIO 0 6 J19 connector
Application GPIO 0 7 J19 connector
Basic GPIO 1 0 J19 connector
Basic GPIO 1 1 J19 connector

GPIO pins are accessed by user-space applications by means of a character device named:
/dev/gpio
A single GPIO device driver supporting all blocks is implemented.
As a general consideration, accessing GPIOs from user-space has some intrinsic
limitations. Interrupts may not be configured or intercepted and operations on GPIOs are
slower than from kernel-space due to system call overhead. Therefore, the GPIO user-
space API is usually exploited only for non speed-critical tasks (such as turning on/off a LED
or reading a dip switch configuration).
User-space applications must include the drivers/char/spr_gpio_pl061.h header
file.
In addition to the standard and generic open() and close() routines, the GPIO user-
space API provides the interfaces described in the following.
Each block is identified by a specific enumeration constant:
typedef enum { GPIO0, GPIO1, GPIO2, GPIO_NONE } t_GPIOId;

18/62
UM0479 User-space APIs

The eight pins inside a block are identified through bit masks:
#define GPIO_PIN00x00000001
#define GPIO_PIN10x00000002
#define GPIO_PIN20x00000004
#define GPIO_PIN30x00000008
#define GPIO_PIN40x00000010
#define GPIO_PIN50x00000020
#define GPIO_PIN60x00000040
#define GPIO_PIN70x00000080
#define GPIO_ALLPINS0x000000FF
As anticipated, only GPIO0 and GPIO1 blocks are actually exposed by the SoC and the
development board. In addition, only GPIO_PIN0 and GPIO_PIN1 are available for the
GPIO1 block.
Binary values for pins are defined as follows:
typedef enum { RESET, SET } t_GPIOValue;
The direction (input or output) of a pin is defined as follows:
typedef enum { IN, OUT } t_GPIODir;
Given the definitions above, the interaction with GPIOs is performed through the following
data structure type:
typedef struct {
union {
t_GPIOValue PinVal; // SET, RESET
t_GPIODir PinDir; // IN, OUT
} PinInfo;
t_GPIOId GPIOId; // GPIO0, GPIO1, GPIO2
uint PinMask; // see bitmasks above
} t_GPIOPinInfo;
Error handling for all API calls is performed through predefined values returned by the
functions and defined as follows:
typedef enum {
GPIO_OK = 0,
GPIO_INVALID_ID,
GPIO_INVALID_PIN_DIRECTION,
GPIO_INVALID_PIN_ID,
GPIO_INVALID_PIN_VALUE,
GPIO_INVALID_INTERRUPT_TYPE, // not used in user-space
GPIO_NOT_AN_OUTPUT_PIN,
GPIO_NOT_AN_INPUT_PIN,
GPIO_INVALID_PARAMETER,
GPIO_PIN_NOT_AN_INTERRUPT_LINE, // not used in user-space
GPIO_PIN_NO_INT_HANDLER_REGISTERED, // not used in user-space
GPIO_INVALID_INTERRUPT_HANDLER, // not used in user-space
GPIO_PIN_NOT_IN_SOFTWARE_MODE, // not used in user-space
GPIO_UNKNOWN_ERROR
} t_GPIOError;
In order to configure pins, the ioctl() system call is used.

19/62
User-space APIs UM0479

In order to configure the direction of one or more pin for a specified block, the ioctl() call
is invoked with a GPIOIOC_DIRSET request parameter and a pointer to a
t_GPIOPinInfo structure initialized with block, pin mask of pins to be changed and
chosen direction.
Example:
int dev;
t_GPIOPinInfo info;
t_GPIOError result;
dev = open("/dev/gpio ",O_RDWR);
info.GPIOId = GPIO0; // specify block
info.PinMask = GPIO_PIN0 + GPIO_PIN1; // select 2 pins in the mask
info.PinInfo.PinDir = IN; // set to input
result = ioctl(dev,GPIOIOC_DIRSET,&info);
if (result != GPIO_OK) { printf("Error\n"); }
close(dev);
In order to query the current direction of one or more pin for a specified block, the ioctl()
call is used with a GPIOIOC_DIRGET request parameter and a pointer to a
t_GPIOPinInfo structure initialized with block identifier and pin mask of pins to be
queried.
Example:
int dev;
t_GPIOPinInfo info;
t_GPIOError result;
dev = open("/dev/gpio",O_RDWR);
info.GPIOId = GPIO0; // specify block
info.PinMask = GPIO_PIN0 + GPIO_PIN1; // select 2 pins in the mask
result = ioctl(dev,GPIOIOC_DIRGET,&info);
if (result != GPIO_OK)
{
printf("Error");
}
else
{
if ((info.PinInfo.PinDir & GPIO_PIN0)==IN)
{ printf("Block 0, Pin 0 direction is input\n"); }
else
{ printf("Block 0, Pin 0 direction is output\n"); }
if ((info.PinInfo.PinDir & GPIO_PIN1)==IN)
{ printf("Block 0, Pin 1 direction is input\n"); }
else
{ printf("Block 0, Pin 1 direction is output\n"); }
}
close(dev);
It is also possible to restore all pins of a specified block to default settings using the
ioctl() call with a GPIOIOC_CONFIGDEFAULT request.
Example:
int dev;
t_GPIOPinInfo info;

20/62
UM0479 User-space APIs

t_GPIOError result;
dev = open("/dev/gpio",O_RDWR);
info.GPIOId = GPIO0; // specify block
result = ioctl(dev,GPIOIOC_CONFIGDEFAULT,&info);
if (result != GPIO_OK) { printf("Error"); }
close(dev);
With default settings, all pins have input direction and interrupts are edge-triggered and
disabled.
In order to change the value of one or more GPIO pins for a specified block, the write()
system call is used. The passed structure specifies the operation (RESET or SET).
Example:
int dev;
t_GPIOPinInfo info;
t_GPIOError result;
dev = open("/dev/gpio",O_RDWR);
info.GPIOId = GPIO0; // specify block
info.PinMask = GPIO_PIN0 + GPIO_PIN1; // select 2 pins in the mask
info.PinInfo.PinVal = RESET; // set pins to zero
result = write(dev,&info,sizeof(info));
if (result != GPIO_OK) { printf("Error"); }
close(dev);
In order to read the value of one or more GPIO pins for a specified block, the read() system
call is used. On call return, the values for the specified pins are stored as bit pattern in the
PinVal field.
Example:
int dev;
t_GPIOPinInfo info;
t_GPIOError result;
dev = open("/dev/gpio",O_RDWR);
info.GPIOId = GPIO0; // specify block
info.PinMask = GPIO_PIN0 + GPIO_PIN1; // select 2 pins in the mask
result = read(dev,&info,sizeof(info));
if (result != GPIO_OK)
{
printf("Error");
}
else
{
info.PinInfo.PinVal = RESET; // set pins to zero
if ((info.PinInfo.PinVal & GPIO_PIN0)==RESET)
{ printf("Block 0, Pin 0 value is zero\n"); }
else
{ printf("Block 0, Pin 0 value is one\n"); }
if ((info.PinInfo.PinVal & GPIO_PIN1)== RESET)
{ printf("Block 0, Pin 1 value is zero\n"); }
else
{ printf("Block 0, Pin 1 value is one\n"); }
}
close(dev);

21/62
User-space APIs UM0479

4.4 Display
A device driver for the SPEAr Plus graphics display controller (CLCDC) and the relevant
user-space API shall be provided in future SDK releases. Such API shall be compatible with
the Linux frame buffer standard.

4.5 I2C bus and EEPROM

I2C is a serial, 2-wire, master-slave protocol for inter-device hardware interface. The SPEAr
Plus I2C bus controller is accessed by user-space applications by means of a device
named:
/dev/i2c
Current implementation only works in master mode and using a polling scheme.
User-space applications must include the drivers/i2c/busses/spr_i2c_syn.h
header file.
In addition to the standard and generic open() and close() routines, the I2C user-space
API provides the interfaces described in the following.
Error handling is performed according to the following definition:
typedef enum {
I2C_OK = 0,
I2C_FAIL,
I2C_INVALID_ADDRESS,
I2C_RX_BUFFER_NULL,
I2C_NO_RX_DATA,
I2C_TX_BUFFER_NULL,
I2C_NO_TX_DATA,
I2C_OFFSET_ERROR,
I2C_TX_FIFO_NOT_EMPTY
} t_I2CError;
The configuration to interface a specific slave device is performed
by a ioctl() call like:
t_I2C_Configure cfg;
...
result = ioctl(dev,I2CIOC_CONFIG,&cfg);
where the following definitions are assumed from the header file:
typedef enum {
SEVEN_BIT_ADDRESSING,// 7-bit addresses (the most common)
TEN_BIT_ADDRESSING// 10-bit addresses
} t_I2C_addressing_mode;
typedef enum {
IC_SPEED_MODE_STANDARD,// 100 Kbps
IC_SPEED_MODE_FAST,// 400 Kbps (the most common)
IC_MAX_SPEED// 3.4 Mbps
} t_I2C_speed;
typedef struct {
u32 SlaveAddress;// address of slave
u32 slave_offset;// offset

22/62
UM0479 User-space APIs

t_I2C_control_mode mode; // must be I2C_MASTER_MODE

t_I2C_addressing_mode operation; // 7 or 10 bit addresses
t_I2C_tar_update tar_update;// currently unused
t_I2C_command FirstByte;// currently unused
t_I2C_transfer_mode TransferMode;// currently unused
t_I2C_speedSpeed;
} t_I2C_Configure;
Data may be written to the slave device according to current configuration, set by ioctl()
as described above, by using a standard write() call. Data may be read from the slave
device according to current configuration, set by ioctl() as described above, by using a
standard read() call.
The specific byte-level protocol to be used in read() and write() calls is slave-dependent.
One common use of I2C bus interface is to access EEPROM memory devices.
The SPEAr Plus development board includes an EEPROM memory at I2C slave address
0x50. The following example shows how to access the I2C controller and then how to write
and read back a specific byte location on the EEPROM:
Example:
int dev;
t_I2C_Configure cfg;
t_I2CError result;
char data_out[1];
char data_in[1];
int n;
// open I2C controller device
dev = open("/dev/i2c",O_RDWR);
// configure I2C for access to EEPROM
cfg.SlaveAddress = 0x50; // EEPROM slave address
cfg.slave_offset = 0x08; // location = ninth cell
cfg.mode = I2C_MASTER_MODE;
cfg.operation = SEVEN_BIT_ADDRESSING;
cfg.Speed = IC_SPEED_MODE_FAST;
result = ioctl(dev,I2CIOC_CONFIG,&cfg);
if (result != I2C_OK) { /* error handling */ }
// write 1 byte to EEPROM location 8
data_out[0] = 0xA5;
n = write(dev,data_out,1);
if (n!=1) { /* error handling */ }
// read back 1 byte from EEPROM location 8
n = read(dev,data_in,1);
if (n!=1) { /* error handling */ }
// close I2C controller device
close(dev);

4.6 Inter-processor communication (IPC)

A device driver for managing communication between the main CPU (running Linux) and the
slave CPU (for dual-core scenarios) as well as the relevant user-space API shall be
provided in future SDK releases.

23/62
User-space APIs UM0479

4.7 JPEG codec

A device driver for the SPEAr Plus JPEG hardware codec and the relevant user-space API
shall be provided in future SDK releases.

4.8 Real-time clock (RTC)

The Real-Time Clock (RTC) device maintains “wall-clock” date and time information and is
intended to be provided with a battery backup so that date/time is kept even when the
system is switched off and automatically restored by the Linux kernel at each bootstrap.
Note: on some early SPEAr Plus development boards, battery backup may be not available; in this
case, wall clock time will be preserved in case of reset but not in case of power off.
The hwclock command utility may be invoked from the shell console in order to change the
RTC settings from current system time or update system time from current RTC value.
The RTC is accessed by user-space applications by means of a character device named:
/dev/rtc
User-space applications must include the linux/rtc.h header file.
In addition to the standard and generic open() and close() routines, the RTC user-space
API provides the ioctl() operations as described in the following.
Successful calls return 0. A negative value is returned in case of errors.
Common definitions are:
struct rtc_time {
int tm_sec;// seconds (0-59)
int tm_min;// minutes (0-59)
int tm_hour;// hours (0-23)
int tm_mday;// day of month (0-30)
int tm_mon;// month (0-11)
int tm_year;// year, 0-based, since 1900
int tm_wday;// not used
int tm_yday; // not used
int tm_isdst; // not used
};
The current RTC date and time may be changed with RTC_SET_TIME ioctl() request as
in the following example:
Example:
int dev;
struct rtc_time info;
dev = open("/dev/rtc",O_RDWR);
// set date and time to December 27, 1964 15:09:00
info.tm_mday = 26;
info.tm_mon = 11
info.tm_year = 64;
info.tm_hour = 15;
info.tm_min = 9;
info.tm_sec = 0;

24/62
UM0479 User-space APIs

result = ioctl(dev,RTC_SET_TIME,&info);
if (result) { printf("Error"); }
close(dev);
The current RTC date and time may be read with RTC_RD_TIME ioctl()
request as in the following example:
Example:
int dev;
struct rtc_time info;
dev = open("/dev/rtc",O_RDWR);
result = ioctl(dev,RTC_RD_TIME,&info);
if (result)
{
printf("Error");
}
else
{
printf("%02d/%02d/%04d %02d:%02d:%02d\n",
info.tm_mday+1,info.tm_mon+1,1900+info.tm_year,
info.tm_hour,info.tm_min,info.tm_sec);
close(dev);
The read() and write() functions are not used.

4.9 Slave CPU control

A device driver for booting a software image on the slave CPU and starting/halting its
execution, as well as the relevant user-space API, shall be provided in future SDK releases.

4.10 Synchronous serial ports (SSPs)

A device driver for the three SPEAr Plus synchronous serial ports (SSP) and the relevant
user-space API shall be provided in future SDK releases.

4.11 Asynchronous serial ports (UARTs)

Two UART ports are available on SPEAr Plus development board. UART0 is accessible
through a standard DB9 connector. UART1 is accessible only through an auxiliary connector
requiring a different cabling.
Both UARTs are accessed from user-space applications through character devices named,
respectively:
/dev/ttyS0
/dev/ttyS1
SPEAr UARTs only provide 2 wires. There are no hardware flow control lines or modem-
specific support. Software flow control (XON/XOFF) support will be provided in future
releases.
The UART driver works in interrupt mode and exploits hardware FIFO queues. The default
configuration is 115200 bps, 8 data bits, 2 stop bits, even parity and no software flow control.

25/62
User-space APIs UM0479

User-space applications have to include only standard I/O header files.

All the standard open(), close(), read() and write() functions may be invoked in
the usual way.
Port configuration is performed using a standard Linux structure equivalent to the following
definition:
struct termios {
unsigned short c_iflag;/* input mode flags */
unsigned short c_oflag;/* output mode flags */
unsigned short c_cflag;/* control mode flags */
unsigned short c_lflag;/* local mode flags */
unsigned char c_line;/* line discipline */
unsigned char c_cc[NCC]; /* control characters */
};
The most important field is c_cflag.
Usually only the bitrate needs to be specified. Macros for common bitrates supported by the
driver are as follows:
B1200, B2400, B4800, B9600, B19200, B38400, B57600, B115200,
B230400, B460800
Since SPEAr UARTs are mainly used for development and testing purposes, the other
subfields are usually set to 8 data bits (CS8 macro), 1 stop bit, no parity.
It is usually recommended to retrieve first current settings using the tcgetattr() function
and then change only required fields using the tcsetattr() function as shown below:
Example:
int dev;
int result;
int n;
char buffer[10];
struct termios config;
dev = open("ttyS1",O_RDWR);
if (dev == -1) { /* error handling */ }

// get default settings

result = tcgetattr(dev,&config);
if (result < 0) { /* error handling */ }
// reconfigure for 57600 bps, 8 data bits, 1 stop bit, no parity
config.c_cflag = B57600 | CS8;
result = tcsetattr(dev,TCSANOW,&config);
// write 4 bytes
n = write(dev, "test",4);
if (n < 0) { /* error handling */ }
// read 2 bytes
n = read(dev,buffer,2);
if (n < 0) { /* error handling */ }
close(dev);

26/62
UM0479 User-space APIs

4.12 USB device (gadget filesystem)

The exploitation of SPEAr Plus development boards as USB devices is strongly application-
dependent. For instance, the board’s software may be designed to operate as a USB-
controllable printer, scanner, fax, gateway, mass storage, etc. While custom USB device
components (so-called gadgets) are more often integrated as kernel-space extensions with
no user-space API, future SDK releases will also support the development of user-space
gadgets through the so-called USB gadget filesystem (gadgetfs) according to the following
approach:
● the on-chip USB device controller is exposed to user space as a virtual file under
/dev/gadget
● standard open(), close(), read() and write() calls are used
● events from remote host to a user-space USB device (setup, disconnect, suspend, etc.)
are delivered on the ep0 file descriptor
● commands to be sent to an endpoint of the USB device controller (e.g. FIFO flushing)
are implemented by ioctl() calls

4.13 USB hosts (mass storage and USB filesystem)

SPEAr Plus has two USB host controllers. The USB host protocol stack is already provided
by standard Linux kernel. The specific Host Controller Driver (HCD) is a thin layer mainly
linking the kernel USB stack to SPEAr compatible hardware (EHCI/OHCI).
As for the USB device scenario, the exploitation of SPEAr Plus development boards as USB
hosts is strongly application-dependent. For instance, the board’s software may be designed
to access external USB peripherals like printers, scanners, keyboards, card readers,
modems, digital still cameras, pendrives, etc.
In order to provide access to standard mass storage devices such as USB pendrives, USB
card readers and some USB digital still cameras, SDK 1.1 supports manual mounting and
unmounting of a VFAT filesystem on top of a selected USB host port. Hot plug detection
shall be delivered in future SDK releases.
After proper mounting, files on the device become accessible using the standard user-space
filesystem API. Examples of user commands for mounting USB storage devices are
described in [3].
Up to 4 USB mass storage devices are exposed through the following devices:
/dev/sda (also accessible as /dev/sda1)
/dev/sdb (also accessible as /dev/sdb1)
/dev/sdc (also accessible as /dev/sdc1)
/dev/sdd (also accessible as /dev/sdd1)
It should be noted that, since only 2 USB host connectors are available, the use of up to 4
devices will require an external USB hub.
Of course, the USB mass storage driver included by the SDK in the default kernel
configuration is just an example of class driver that can be added to manage a specific kind
of USB peripheral. Other predefined class drivers may be found inside the Linux kernel
source tree, while not enabled by default. Each class driver will provide its own user-space
API.

27/62
User-space APIs UM0479

Finally, custom class drivers could be developed in user-space. In this case, the class driver
will directly interface with the USB host protocol stack through a user-space API based on
the so-called USB filesystem (usbfs). A possible application of this scenario is to implement,
in user-space, the USB Still Imaging Class and the corresponding PTP (Picture Transfer
Protocol) protocol.
Similar to the /proc/net pseudo file tree supported for Ethernet, there is a
/proc/bus/usb logical subtree for USB. On SPEAr Plus boards, the
/proc/bus/usb/devices logical file reports information about four USB host controllers:
Bus 01USB Host Port 1 (EHCI, USB 2.0)
Bus 02USB Host Port 2 (EHCI, USB 2.0)
Bus 03USB Host Port 1 (OHCI, USB 1.1)
Bus 04USB Host Port 2 (OHCI, USB 1.1)
In order to mount usbfs, the following command would need to be issued:
# mount -t usbfs none /proc/bus/usb
However, for user convenience, this command is already included in the initialization script
/etc/rc as described in [3].
The generic user-space API for USB host controllers is defined in the
include/linux/usbdevice_fs.h header file and is based on ioctl() calls. A specific
plugged USB device must be opened with open() before using such calls and closed with
close() after usage. The read() and write() system calls are not used.

Table 7. USB filesystem ioctl requests

IOCTL request Description Argument

Issues a bulk read or write

request to the opened device.
Request details are specified in
Request details, a pointer to following
the argument. The ep field
structure:
specifies a bulk endpoint
number (1-15), masked with struct usbdevfs_bulktransfer {
USB_DIR_IN in case of input unsigned int ep;
USBDEVFS_BULK
endpoints (reading from the unsigned int len;
device). The “len” field specifies unsigned int timeout;
the size of the block to be void *data;
transferred. Timeout is specified
};
in ms. The “data” field is a
pointer to the input or output
buffer.
Forces to claim a specific
interface, not previously been
USBDEVFS_ claimed by usbfs or any other Interface number:
CLAIMINTERFACE kernel driver. The input unsigned int
argument is an integer
specifying the interface number.

28/62
UM0479 User-space APIs

Table 7. USB filesystem ioctl requests (continued)

IOCTL request Description Argument

Clears endpoint halt (stall) and

resets the endpoint toggle (only
meaningful for bulk or interrupt
endpoints). The input argument
is an integer specifying the
endpoint number (1-15), masked
with USB_DIR_IN in case of
USBDEVFS_ Endpoint number:
input endpoints. This call must
CLEAR_HALT unsigned int
be used on bulk or interrupt
endpoints which have stalled,
returning -EPIPE status to a
data transfer request. Do not
issue the control request directly,
since that could invalidate the
host's record of the data toggle.
USBDEVFS_
Connect to opened device. None (ignored)
CONNECT
Check if the opened device is
Low Speed (1.5Mbps). If not, it
could be Full or High speed but A pointer to following structure:
this can not be detected by this struct usbdevfs_connectinfo {
USBDEVFS_
call. The argument specifies a unsigned int devnum;
CONNECTINFO
device number “devnum” (DDD unsigned char slow;
value of device filename) as };
input. The result is returned in
the “slow” field.
Issues a control request to the
opened device. The
“bRequestType” is the contents
of the SETUP packet to be sent A pointer to following structure:
to the device. The struct usbdevfs_ctrltransfer {
“bRequestType” field is __u8 bRequestType;
composed by combining a __u8 bRequest;
USB_TYPE_* value, a
USBDEVFS_ __u16 wValue;
USB_DIR_* value, and a
CONTROL __u16 wIndex;
USB_RECIP_* value (as defined
in <linux/usb.h>). The “wLength” __u16 wLength;
field specifies the size of the __u32 timeout;
block to be transferred. The void __user *data;
maximum transfer size is 4 KB. };
Timeout is specified in ms. The
“data” field is a pointer to the
input or output buffer.
USBDEVFS_
Disconnect from opened device. None (ignored)
DISCONNECT

29/62
User-space APIs UM0479

Table 7. USB filesystem ioctl requests (continued)

IOCTL request Description Argument

A pointer to following structure:

struct usbdevfs_getdriver {
Returns the name (string) of the
USBDEVFS_ unsigned int interface;
kernel driver bound to the
GETDRIVER char driver
specified interface.
[USBDEVFS_MAXDRIVERNAME+1];
};
Sends a request from user-
space to a kernel driver that has A pointer to following structure:
an ioctl entry in the struct struct usbdevfs_ioctl {
usb_driver it registered.
int ifno;
USBDEVFS_IOCTL The “ifno” field is the selected
int ioctl_code;
interface number. The
“ioctl_code” contains the ioctl void *data;
request. The “data” field is a };
pointer to the ioctl argument.
Releases a claimed interface, Interface number:
USBDEVFS_
whose number specified by the
RELEASEINTERFACE unsigned int
argument.
Resets the opened USB device.
After the reset, this call rebinds
USBDEVFS_RESET all device interfaces. Linux None (ignored)
documentation currently
discourages the use of this call.
Resets the data toggle value for
a bulk or interrupt endpoint to
DATA0. The endpoint number (1-
USBDEVFS_ 5 with USB_DIR_IN mask added Endpoint number:
RESETEP for input endpoints) is specified unsigned int
by the input argument. . Linux
documentation currently
discourages the use of this call.
Sets the configuration for the
USBDEVFS_ opened device. Linux Configuration number:
SETCONFIGURATION documentation currently unsigned int
discourages the use of this call.
A pointer to following structure:
struct usbdevfs_setinterface {
USBDEVFS_ Sets the alternate setting for a
unsigned int interface;
SETINTERFACE specified interface.
unsigned int altsetting;
};

4.14 Watchdog timer (WDT)

A device driver for the SPEAr Plus hardware watchdog timer (WDT) and the relevant user-
space API shall be provided in future SDK releases.

30/62
UM0479 Kernel-space APIs

5 Kernel-space APIs

The APIs to access SPEAr Plus devices from kernel-space software are described in the
following sections. Direct function calls are made in this case, since static or dynamic linking
of the relevant device drivers with client software is assumed.
A standard Linux API is exploited wherever applicable (USB host and device frameworks).
In all other cases an ST-specific API has been defined.
It should be noted that kernel-space APIs are exposed only for devices that actually require
this access level. For instance, there is no need to expose a kernel-space API for graphics
display, JPEG codec, real-time clock and slave CPU control.
Moreover, the Ethernet driver is designed to be integrated in the Linux networking
framework. Therefore, it only exposes interfaces to that framework and not to other kernel-
space subsystems (most driver functions are static, hence private). Likewise, the UART
driver is designed to be integrated in the Linux serial port framework. Therefore, it only
exposes interfaces to that framework and not to other kernel-space subsystems. For this
reason, no specific kernel APIs for Ethernet and UARTs are documented in this section.

5.1 A/D converter (ADC)

A device driver for the SPEAr Plus A/D Converter (ADC) and the relevant kernel-space API
shall be provided in future SDK releases.

5.2 Direct memory access (DMA)

DMA is a hardware mechanism to automatically and efficiently perform data transfers on a
bus without involving the CPU. Sources and sinks of a transfer may be peripherals as well
as memory devices.
DMA is typically used in the implementation of some drivers in kernel-space. Therefore, no
user-space API is made available.
The SPEAr Plus devices supporting DMA through the general-purpose DMA controller are
referenced through the following enumeration:
typedef enum {
MEMORY_DMA_DEVICE,
SPI_2_IN_DMA_DEVICE,// SPI not supported in SDK 1.1
SPI_2_OUT_DMA_DEVICE, // SPI not supported in SDK 1.1
UART_1_IN_DMA_DEVICE,// UART only supported in interrupt mode in SDK 1.1
UART_1_OUT_DMA_DEVICE,// UART only supported in interrupt mode in SDK 1.1
UART_2_IN_DMA_DEVICE,// UART only supported in interrupt mode in SDK 1.1
UART_2_OUT_DMA_DEVICE,// UART only supported in interrupt mode in SDK 1.1
SPI_3_IN_DMA_DEVICE, // SPI not supported in SDK 1.1
SPI_3_OUT_DMA_DEVICE, // SPI not supported in SDK 1.1
SPI_1_IN_DMA_DEVICE, // SPI not supported in SDK 1.1
SPI_1_OUT_DMA_DEVICE, // SPI not supported in SDK 1.1
I2C_IN_DMA_DEVICE, // I2C only supported in polling mode in SDK 1.1
I2C_OUT_DMA_DEVICE, // I2C only supported in polling mode in SDK 1.1
IRDA_DMA_DEVICE, // IRDA not supported in SDK 1.1
JPEG_IN_DMA_DEVICE, // JPEG not supported in SDK 1.1
JPEG_OUT_DMA_DEVICE, // JPEG not supported in SDK 1.1

31/62
Kernel-space APIs UM0479

LAST_DMA_DEVICE
} t_DMADeviceId;
It should be pointed out that some on-chip peripherals such as Ethernet and USB use their
own dedicated DMA support. In addition, the MEMORY_DMA_DEVICE value may be used for
generic transfer including peripherals since they are memory-mapped.
Error handling is managed by API functions through return values according to the following
definition:
typedef enum {
DMA_OK, // successful call
DMA_INVALID_BURST_SIZE,
DMA_INVALID_ACCESS_WIDTH,
DMA_INVALID_PROTECTION,
DMA_INVALID_CHANNEL_ID,
DMA_INVALID_INT_HANDLER,
DMA_INCORRECT_FLOW_CONTROLLER,
DMA_INVALID_DEVICE_ID,
DMA_INVALID_PRIORITY,
DMA_INVALID_PARAMETER,
DMA_INCOMPATIBLE_DMA_DEVICE,
DMA_NO_MORE_LLIS_AVAILABLE,
DMA_NO_MORE_HW_CHANNELS_AVAILABLE,
DMA_NO_INT_ACTIVE,
DMA_TRANSFER_OVER,
DMA_TRANSFER_ONGOING,
DMA_INCOMPATIBLE_TRANSFER_SIZE,
DMA_INCOMPATIBLE_BUFFER_SIZE,
DMA_DEVICE_CANT_BE_FLOWCTRL,
DMA_INVALID_FLOW_CONTROLLER,
DMA_CONTROLLER_NOT_INITIALIZED,
DMA_NULL_POINTER,
DMA_MISALLIGNED_ADDRESS,
DMA_ERROR
} t_DMAError;
The DMA Kernel API functions are listed in the following. Basically, the DMA controller must
be first initialized. Specific source or destination devices may be also configured. Then data
transfers may be started with optional user-defined callback routines to be invoked when the
each transfer is terminated. If required, DMA transfers may be also suspended, resumed or
aborted before normal completion.
It is important to remind that DMA operates with physical rather than virtual addresses.

Function: t_DMAError SPEAr_DMA_SetConfigDevice

t_DMADeviceId DeviceId,
t_DMAAccessWidth AccessWidth,
t_DMABurstSize MaxBurstSize,
t_DMAProtection Protection,
t_bool CanBeFlowController)
Description: Sets the configuration of a DMA-capable device.

32/62
UM0479 Kernel-space APIs

Arguments: DeviceId (in):

Device to be configured.

AccessWidth (in):
Access width of device according to following definition:

typedef enum {
BYTE_WIDTH = 1,
HALFWORD_WIDTH = 2,
WORD_WIDTH = 4
} t_DMAAccessWidth;

MaxBurstSize (in):
Maximum burst size of device according to following definition:

typedef enum {
BURST_SIZE_1,
BURST_SIZE_4,
BURST_SIZE_8,
BURST_SIZE_16,
BURST_SIZE_32,
BURST_SIZE_64,
BURST_SIZE_128,
BURST_SIZE_256
} t_DMABurstSize;

Protection (in):
Protection information of device according to following definition:

typedef enum {
PROT_RESET,
USER_BUFFERABLE_CACHEABLE,
USER_NOT_BUFFERABLE_CACHEABLE,
USER_BUFFERABLE_NOT_CACHEABLE,
USER_NOT_BUFFERABLE_NOT_CACHEABLE,
PRIV_BUFFERABLE_CACHEABLE,
PRIV_NOT_BUFFERABLE_CACHEABLE,
PRIV_BUFFERABLE_NOT_CACHEABLE,
PRIV_NOT_BUFFERABLE_NOT_CACHEABLE
} t_DMAProtection;

CanBeFlowController (in): If true, the device may be the flow controller.

Function: t_DMAError SPEAr_DMA_GetConfigDevice(

t_DMADeviceId DeviceId,
t_DMAAccessWidth *AccessWidth,
t_DMABurstSize *MaxBurstSize,
t_DMAProtection *Protection,
t_bool *CanBeFlowController);

33/62
Kernel-space APIs UM0479

Description: Gets the configuration of a DMA-capable device.

Arguments: DeviceId (in):
Device for which configuration is obtained.

AccessWidth (out):
Access width of device (see SPEAr_DMA_SetConfigDevice for values).

MaxBurstSize (out):
Maximum burst size of device (see SPEAr_DMA_SetConfigDevice for values).

Protection (out):
Protection information of device (see SPEAr_DMA_SetConfigDevice for values).

CanBeFlowController (out): If true, the device may be the flow controller.

Function: t_DMAError SPEAr_DMA_Transfer

t_DMATransferDesc TransferDesc,
t_DMAChannelId *ChannelId);

Description: Transfers data from source to destination. The selected DMA channel for the transfer
is returned.
Arguments: TransferDesc (in):
Defines the details of the requested transfer using the following data structure:

typedef struct {
t_DMADeviceId SrcDeviceId; // source
t_DMADeviceId DestDeviceId; // destination
uint SrcAddress; // source address
uint DestAddress; // destination address
uint TransferSize; // size in bytes of transfer
t_DMAFlowCtrl FlowController; // flow type
t_DMATransferPriority Priority;// priority of DMA transfer
t_bool IsIntReqAfterEachPacketTransfer; // interrupt required
// after each LLI transfer ?
t_DMAIntHandler HandlerPtr; // interrupt handler for
// end of transfer
} t_DMATransferDesc;

The available flow types are defined as follows:

typedef enum {
DMA_MEMORY_TO_MEMORY,
DMA_MEMORY_TO_PERIPHERAL,
DMA_PERIPHERAL_TO_MEMORY,
DMA_PERIPHERAL_TO_PERIPHERAL,
DEST_PERIPHERAL_TO_PERIPHERAL,
DEST_MEMORY_TO_PERIPHERAL,
SRC_PERIPHERAL_TO_MEMORY,

34/62
UM0479 Kernel-space APIs

SRC_PERIPHERAL_TO_PERIPHERAL
} t_DMAFlowCtrl;

The available priorities are defined as follows:

typedef enum {
LOW_PRIORITY,
NORMAL_PRIORITY,
HIGH_PRIORITY,
UNDEFINED_PRIORITY
} t_DMATransferPriority;

Interrupt handlers, if used, must be specified as follows:

typedef void (* t_DMAIntHandler)(

t_bool IsTransferOver, t_DMAIntType IntType);

where t_DMAIntType is defined as:

typedef enum { INT_TC, INT_ERROR } t_DMAIntType;

ChannelID (out):
Returns the selected DMA channel for further reference .

Function: t_DMAError SPEAr_DMA_HaltTransfer(t_DMAChannelId ChannelId);

Description: Suspends a transfer on specified DMA channel.
Arguments: ChannelId (in):
Target channel number as obtained when starting the transfer.

Function: t_DMAError SPEAr_DMA_ResumeTransfer(t_DMAChannelId ChannelId);

Description: Resumes a suspended transfer on specified DMA channel.
Arguments: ChannelId (in):
Target channel number as obtained when starting the transfer.

Function: t_DMAError SPEAr_DMA_AbortTransfer(

t_DMAChannelId ChannelId,
t_bool DataCanBeLost);
Description: Aborts ongoing transfer on specified DMA channel.
Arguments: ChannelId (in):
Target channel number as obtained when starting the transfer.

35/62
Kernel-space APIs UM0479

DataCanBeLost (in):
If true, the channel is directly disabled and any data in the DMA FIFO is lost.

5.3 General-purpose input/output (GPIO)

The advantages of interfacing GPIOs in kernel-space are higher performance and the
capability of handling interrupts. Type definitions and returned codes are the same as
described for GPIO User API.

Function: t_GPIOError SPEAr_GPIO_DirSet(

t_GPIOId GPIOId,
t_GPIODir Dir,
uint Mask);
Description: Sets the direction or one or more pins for the specified block.
Arguments: GPIOId (in):
Block index.

Dir (in):
Direction.

Mask (in):
Bitmask defining the pins for which the direction must be changed.

Function: t_GPIOError SPEAr_GPIO_DirGet(

t_GPIOId GPIOId,
t_GPIODir* Dir,
uint Mask);
Description: Gets the direction or one or more pins for the specified block.
Arguments: GPIOId (in):
Block index.

Dir (out):
Direction.

Mask (in):
Bitmask defining the pins for which the direction is obtained.

Function: t_GPIOError SPEAr_GPIO_ValSet(

t_GPIOId GPIOId,
t_GPIOValue Val,
uint Mask);

36/62
UM0479 Kernel-space APIs

Description: Sets the value or one or more pins for the specified block.
Arguments: GPIOId (in):
Block index.

Val (in):
Value.

Mask (in):
Bitmask defining the pins for which the value must be changed.

Function: t_GPIOError SPEAr_GPIO_ValGet(

t_GPIOId GPIOId,
t_GPIOValue* Val,
uint Mask);
Description: Gets the value or one or more pins for the specified block.
Arguments: GPIOId (in):
Block index.

Val (out):
Value.

Mask (in):
Bitmask defining the pins for which the value must be obtained.

Function: t_GPIOError SPEAr_GPIO_EdgeConfig(

t_GPIOId GPIOId,
t_GPIOIntEdgeConfig IntEdge,
t_GPIOIntSingleEdgeConfig IntSingleEdge,
uint Mask);
Description: Configures the interrupt triggering mode of one or more pins for the specified block.
Arguments: GPIOId (in):
Block index.

IntEdge (in):
Single or both edge according to following definition:

typedef enum { SINGLE_EDGE, BOTH_EDGE} t_GPIOIntEdgeConfig;

IntSingleEdge (in):
Single edge type according to following definition:

typedef enum {
FALLING_EDGE,
RISING_EDGE,

37/62
Kernel-space APIs UM0479

NONE
} t_GPIOIntSingleEdgeConfig;

Mask (in):
Bitmask defining the pins for to be configured.

Function: t_GPIOError SPEAr_GPIO_LevelConfig(

t_GPIOId GPIOId,
t_GPIOIntLevelConfig IntLevel,
uint Mask);
Description: Configures the interrupt triggering level mode of one or more pins for the specified
block.
Arguments: GPIOId (in):
Block index.

IntLevel (in):
Level according to following definition:

typedef enum { LOW_LEVEL, HIGH_LEVEL} t_GPIOIntLevelConfig;

Mask (in):
Bitmask defining the pins for to be configured.

Function: t_GPIOError SPEAr_GPIO_IntEnable(t_GPIOId GPIOId, uint Mask);

Description: Enables interrupts for one or more pins for the specified block.
Arguments: GPIOId (in):
Block index.

Mask (in):
Bitmask defining the pins for which interrupts must be enabled.

Function: t_GPIOError SPEAr_GPIO_IntDisable(t_GPIOId GPIOId, uint Mask);

Description: Disables interrupts for one or more pins for the specified block.
Arguments: GPIOId (in):
Block index.

Mask (in):
Bitmask defining the pins for which interrupts must be disabled.

38/62
UM0479 Kernel-space APIs

Function: t_GPIOError SPEAr_GPIO_BindIntHandler(

t_GPIOId GPIOId,
uint Mask,
t_GPIOIntHandler Handler);
Description: Installs an interrupt handler for one or more pins for the specified block.
Arguments: GPIOId (in):
Block index.

Mask (in):
Bitmask defining the pins for which interrupts must be disabled.

Handler (in):
Pointer to user-defined callback function to be invoked on interrupt occurrence. Such
handler must be defined according to following signature:

typedef void (*t_GPIOIntHandler)(void);

Function: t_GPIOError SPEAr_GPIO_ConfigDefault(t_GPIOId GPIOId);

Description: Restore default configuration for the specified block.
Arguments: GPIOId (in):
Block index.

5.4 I2C bus

The I2C kernel-space API reflects the same operations provided through
ioctl(I2CIOC_CONFIG), read() and write() by the user-space API.

Function: SPEAR_I2C_ConfigureUpdate(t_I2C_Configure *config)

Description: Configure I2C controller according to a specific slave device to be interfaced.
Arguments: config (in):
Structure defining the required configuration (see user-space API for details).

Function: SPEAR_I2C_Receive(char *RxBuffer, unsigned long NoOfBytes)

Description: Read the specified number of bytes from the current I2C slave device previously set
in the configuration.
Arguments: RxBuffer (out):
Destination buffer for the received data.

39/62
Kernel-space APIs UM0479

Function: SPEAR_I2C_Transmit(char *TxBuffer, unsigned long NoOfBytes)

Description: Write the specified number of bytes to the current I2C slave device previously set in
the configuration.
Arguments: TxBuffer (in):
Source buffer for the transmitted data.

5.5 Inter-processor communication (IPC)

A device driver for managing communication between the main CPU (running Linux) and the
slave CPU (for dual-core scenarios) as well as the relevant kernel-space API shall be
provided in future SDK releases.

5.6 Synchronous serial ports (SSPs)

A device driver for the three SPEAr Plus synchronous serial ports (SSP) and the relevant
kernel-space API shall be provided in future SDK releases.

5.7 USB device (gadget framework)

A standardized API is defined by Linux for kernel-space access to the USB device stack.
This software interface is known as “gadget framework” and is defined inside the
include/linux/usb_gadget.h header file. A gadget driver is an handler for the USB
device port performing some specific function.
An example of simple and generic gadget driver is provided by the so-called “Gadget Zero”
that can be found under path:
splus_linux_sdk_1_1\linux-2.6.19.2\drivers\usb\gadget\zero.c

5.7.1 Gadget driver management

A gadget driver has to be defined through the following data structure:
struct usb_gadget_driver {
char* function;
enum usb_device_speed speed;
int (*bind)(struct usb_gadget *);
void (*unbind)(struct usb_gadget *);
int (*setup)(struct usb_gadget*,const struct usb_ctrlrequest *);
void (*disconnect)(struct usb_gadget *);
void (*suspend)(struct usb_gadget *);
void (*resume)(struct usb_gadget *);
struct device_driver driver;
};
where the fields have the following meanings:

40/62
UM0479 Kernel-space APIs

Table 8. Gadget driver structure fields

Field Description

function String describing the gadget's function.

speed Highest speed the driver handles.
Pointer to custom callback function invoked when the driver is bound to a
gadget, usually after registering the driver. At that point, ep0 is fully
bind
initialized, and ep_list holds the currently-available endpoints. Called in a
context that permits sleeping.
Pointer to custom callback function invoked when the driver is unbound
unbind from a gadget, usually from rmmod (after a disconnect is reported). Called
in a context that permits sleeping.
Pointer to custom callback function invoked for ep0 control requests that
aren't handled by the hardware level driver. Most calls must be handled by
the gadget driver, including descriptor and configuration management.
setup
The 16 bit members of the setup data are in USB byte order. Called
in_interrupt; this may not sleep. Driver queues a response to ep0, or
returns negative to stall.
Pointer to custom callback function invoked after all transfers have been
stopped, when the host is disconnected. May be called in_interrupt; this
disconnect
may not sleep. Some devices can't detect disconnect, so this might not be
called except as part of controller shutdown.
Pointer to custom callback function invoked on USB suspend. May be
suspend
called in_interrupt.
Pointer to custom callback function invoked on USB resume. May be called
resume
in_interrupt.
driver Driver model state for this driver.

All callbacks receive a standard argument defined as a pointer to the following structure:
struct usb_gadget {
const struct usb_gadget_ops *ops;
struct usb_ep *ep0;
struct list_head ep_list;
enum usb_device_speed speed;
unsigned is_dualspeed:1;
unsigned is_otg:1;
unsigned is_a_peripheral:1;
unsigned b_hnp_enable:1;
unsigned a_hnp_support:1;
unsigned a_alt_hnp_support:1;
const char *name;
struct device dev;
};
where the fields have the following meanings:

41/62
Kernel-space APIs UM0479

Table 9. Gadget structure fields

Field Description

ops Function pointers used to access hardware-specific operations.

Endpoint zero, used when reading or writing responses to driver setup()
ep0
requests.
ep_list List of other endpoints supported by the device.
speed Speed of current connection to USB host.
True if the controller supports both high and full speed operation. If it
dualspeed
does, the gadget driver must also support both.
True if the USB device port uses a Mini-AB jack, so that the gadget driver
is_otg
must provide a USB OTG descriptor.
False unless is_otg, the A end of a USB cable is in the Mini-AB jack, and
is_a_peripheral HNP has been used to switch roles so that the A device currently acts as
A-Peripheral, not A-Host.
b_hnp_enable OTG device feature flag, indicating that the A-Host enabled HNP support.
OTG device feature flag, indicating that the A-Host supports HNP at this
a_hnp_support
port.
OTG device feature flag, indicating that the A-Host only supports HNP on
a_alt_hnp_support
a different root port.
Identifies the controller hardware type. Used in diagnostics and
name
sometimes configuration.
dev Driver model state for this abstract device.

The kernel API functions available for gadget driver management are as follows:

Function: int usb_gadget_register_driver(struct usb_gadget_driver

*driver);
Description: Registers a driver with the USB device stack. This is usually invoked in a module
initialization function (defined by module_init macro).
Arguments: driver (in):
Pointer to the driver structure.

Function: int usb_gadget_unregister_driver(struct usb_gadget_driver

*driver);
Description: Unregisters a driver from the USB device stack. This is usually invoked in a module
termination function (defined by module_exit macro).
Arguments: driver (in):
Pointer to the driver structure.

42/62
UM0479 Kernel-space APIs

Function: int usb_gadget_connect(struct usb_gadget *gadget);

Description: Connects to USB host.
Arguments: driver (in):
Pointer to the driver structure.

Function: int usb_gadget_disconnect(struct usb_gadget *gadget);

Description: Disconnects from USB host.
Arguments: driver (in):
Pointer to the driver structure.

Function: int usb_gadget_set_selfpowered(struct usb_gadget *gadget);

Description: Sets the device self-powered feature.
Arguments: driver (in):
Pointer to the driver structure.

Function: int usb_gadget_clear_selfpowered(struct usb_gadget *gadget);

Description: Clears the device self-powered feature.
Arguments: driver (in):
Pointer to the driver structure.

Function: int usb_gadget_vbus_connect(struct usb_gadget *gadget);

Description: Notifies device controller that VBUS is powered.
Arguments: driver (in):
Pointer to the driver structure.

Function: int usb_gadget_vbus_disconnect(struct usb_gadget *gadget);

Description: Notifies controller about VBUS end session.
Arguments: driver (in):
Pointer to the driver structure.

43/62
Kernel-space APIs UM0479

Function: int usb_gadget_vbus_draw(struct usb_gadget *gadget, unsigned

mA);
Description: Constrains controller's VBUS power usage.
Arguments: driver (in):
Pointer to the driver structure.

mA (in):
Current to draw, in milliAmperes.

Function: int usb_gadget_wakeup(struct usb_gadget *gadget);

Description: Tries to wake up the host connected to this gadget.
Arguments: driver (in):
Pointer to the driver structure.

5.7.2 Endpoint management

The second and third fields (ep0 and ep_list) of the USB_gadget structure are the
representation of USB device endpoints. The relevant structure includes the following fields:
struct usb_ep {
void *driver_data;
const char *name;
const struct usb_ep_ops *ops;
struct list_head ep_list;
unsigned maxpacket:16;
};
where the fields have the following meanings:

Table 10. Endpoint structure fields

Field Description

For use by the gadget driver, all other fields are read-only to gadget
driver_data
drivers.
name Identifier for the endpoint, such as ep-a or ep9in-bulk”
ops Function pointers used to access hardware-specific operations.
The gadget's ep_list holds all of its endpoints. all the general purpose
ep_list endpoints in gadget->ep_list. The control endpoint (gadget->ep0) is not in
that list, and is accessed only in response to a driver setup() callback.
The maximum packet size used on this endpoint. The initial value can
maxpacket sometimes be reduced (hardware allowing), according to the endpoint
descriptor used to configure the endpoint.

A wide set of functions is available to manage endpoints, all of them getting as first
argument a pointer to the specified endpoint structure:

44/62
UM0479 Kernel-space APIs

Function: int usb_ep_enable(

struct usb_ep *ep,
const struct usb_endpoint_descriptor *desc);
Description: Enables specified endpoint, passing a descriptor.
Arguments: ep (in):
Pointer to endpoint structure.

desc (in):
Pointer to endpoint descriptor.

Function: int usb_ep_disable(struct usb_ep *ep);

Description: Disables specified endpoint.
Arguments: ep (in):
Pointer to endpoint structure.

Function: void usb_ep_fifo_flush(struct usb_ep *ep);

Description: Flushes the FIFO of specified endpoint.
Arguments: ep (in):
Pointer to endpoint structure.

Function: int usb_ep_fifo_status(struct usb_ep *ep);

Description: Queries the status of the FIFO of specified endpoint.
Arguments: ep (in):
Pointer to endpoint structure.

Function: int usb_ep_set_halt(struct usb_ep *ep);

Description: Sets the halt feature of specified endpoint.
Arguments: ep (in):
Pointer to endpoint structure.

Function: int usb_ep_clear_halt(struct usb_ep *ep);

Description: Clear the halt feature of specified endpoint.

45/62
Kernel-space APIs UM0479

Arguments: ep (in):
Pointer to endpoint structure.

5.7.3 Endpoint I/O

An I/O request is represented by the following data structure:
struct usb_request {
void *buf;
unsigned length;
dma_addr_t dma;
unsigned no_interrupt:1;
unsigned zero:1;
unsigned short_not_ok:1;
void (*complete)(struct usb_ep *ep,struct usb_request
*req);
void *context;
struct list_headlist;
int status;
unsigned actual;
};
The following functions are available for preparing and transmitting requests to endpoints.
The GFP flags are defined in the include/linux/gfp.h header file. Typical values used
in this context are GFP_ATOMIC and GFP_KERNEL.

Function: struct usb_request *usb_ep_alloc_request(

struct usb_ep *ep,
gfp_t gfp_flags);
Description: Allocates an I/O request data structure.
Arguments: ep (in):
Pointer to endpoint structure.

gfp_flags (in):
GFP flags.

Function: void usb_ep_free_request(

struct usb_ep *ep,
struct usb_request *req);
Description: Deallocates an I/O request data structure.
Arguments: ep (in):
Pointer to endpoint structure.

req (in):
Pointer to request structure.

46/62
UM0479 Kernel-space APIs

Function: int usb_ep_queue(

struct usb_ep *ep,
struct usb_request *req,
gfp_t gfp_flags);
Description: Sends an I/O request to the transmission queue.
Arguments: ep (in):
Pointer to endpoint structure.

req (in):
Pointer to request structure.

gfp_flags (in):
GFP flags.

Function: int usb_ep_dequeue(

struct usb_ep *ep,
struct usb_request *req);
Description: Cancels the transmission of an I/O request to the transmission queue.
Arguments: ep (in):
Pointer to endpoint structure.

req (in):
Pointer to request structure.

Function: void *usb_ep_alloc_buffer(

struct usb_ep *ep,
unsigned len,
dma_addr_t *dma,
gfp_t gfp_flags);
Description: Allocates a buffer to be used in I/O requests.
Arguments: ep (in):
Pointer to endpoint structure.

len (in):
Buffer length.

dma (out):
DMA address.

gfp_flags (in):
GFP flags.

47/62
Kernel-space APIs UM0479

Function: void usb_ep_free_buffer(

struct usb_ep *ep,
void *buf,
dma_addr_t dma,
unsigned len);
Description: Deallocates a buffer used in I/O requests.
Arguments: ep (in):
Pointer to endpoint structure.

buf (in):
Pointer to buffer.

dma (in):
DMA address.

len (in):
Buffer length.
Finally, the following utility functions are available:

Function: int usb_gadget_config_buf(

const struct usb_config_descriptor *config,
void *buf,
unsigned buflen,
const struct usb_descriptor_header **desc);
Description: Fills a buffer from a configuration descriptor.
Arguments: config (in):
Descriptor configuration.

buf (out):
Buffer to be filled.

buflen (in):
Buffer length.

desc (in):
Pointer to descriptor header.

Function: int usb_descriptor_fillbuf(

void * buf,
unsigned buflen,
const struct usb_descriptor_header **src);
Description: Fills a descriptor buffer.

48/62
UM0479 Kernel-space APIs

Arguments: buf (out):

Buffer to be filled.

buflen (in):
Buffer length.

src (in):
Pointer to descriptor header.

Function: int usb_gadget_get_string(

struct usb_gadget_strings *table,
int id,
u8 *buf);
Description: Performs lookup in a strings table (typically for internationalization purposes).
Arguments: table (in):
Pointer to strings table.

id (in):
String identifier.

buf (out):
Pointer to buffer for returned string.

Function: struct usb_ep* usb_ep_autoconfig(

struct usb_gadget *gadget,
struct usb_endpoint_descriptor *desc
);
Description: Autoconfiguration of endpoints. Return pointer to configured endpoint.
Arguments: gadget (in):
Pointer to gadget driver.

desc (in):
Pointer to endpoint descriptor.

Function: void usb_ep_autoconfig_reset(struct usb_gadget *);

Description: Resets the autoconfiguration of a gadget.
Arguments: gadget (in):
Pointer to gadget driver.

49/62
Kernel-space APIs UM0479

5.8 USB hosts

As discussed for the USB host user-space API, there are many off-the-shelf host class
drivers made available in the Linux kernel source tree. One of them (mass storage) has
been integrated in the default kernel configuration delivered in this SDK. Other class drivers
may be added to the configuration, each of them exposing its own specific interfaces to
applications. Anyway, all such drivers are compliant to a USB host stack framework
standardized by Linux and defined inside the include/linux/usb.h header file.
Understanding such kernel-space framework is only required when a custom USB host
class driver must be developed as kernel extension. An example could be a PictBridge class
driver for a printer.
Each USB class driver has to be defined through the following data structure:
struct usb_driver {
const char *name;
int (*probe) (struct usb_interface *intf,const struct
usb_device_id *id);
void (*disconnect) (struct usb_interface *intf);
int (*ioctl) (struct usb_interface *intf, unsigned int
code,void *buf);
int (*suspend) (struct usb_interface *intf, pm_message_t
message);
int (*resume) (struct usb_interface *intf);
void (*pre_reset) (struct usb_interface *intf);
void (*post_reset) (struct usb_interface *intf);
const struct usb_device_id *id_table;
struct usb_dynids dynids;
struct usbdrv_wrap drvwrap;
unsigned int no_dynamic_id:1;
unsigned int supports_autosuspend:1;
};
where the fields have the following meanings:

Table 11. USB driver structure fields

Field Description

Driver name, should be unique among USB host drivers and should
name
normally be the same as the module name.
Pointer to custom callback function invoked to see if the driver is willing to
manage a particular interface on a device. If it is, probe returns zero and
probe uses dev_set_drvdata() to associate driver-specific data with the interface.
It may also use usb_set_interface() to specify the appropriate altsetting. If
unwilling to manage the interface, return a negative errno value.
Pointer to custom callback function invoked when the interface is no longer
disconnect accessible, usually because its device has been (or is being) disconnected
or the driver module is being unloaded.
Pointer to custom callback function used for drivers that want to talk to
userspace through the usbfs filesystem. This lets devices provide ways to
ioctl
expose information to user space regardless of where they do (or don't)
show up otherwise in the filesystem.

50/62
UM0479 Kernel-space APIs

Table 11. USB driver structure fields

Field Description

Pointer to custom callback function called when the device is going to be

suspend
suspended by the system.
Pointer to custom callback function called when the device is being
resume
resumed by the system.
Pointer to custom callback function called by
pre_reset
usb_reset_composite_device() when the device is about to be reset.
Pointer to custom callback function called by
post_reset
usb_reset_composite_device() after the device has been reset.
ID table to support hotplugging. Export this with
id_table MODULE_DEVICE_TABLE(usb,...). This must be set or your driver's
probe function will never get called.
Used internally to hold the list of dynamically added device ids for this
dynids
driver.
drvwrap Driver-model core structure wrapper.
if set to 1, the USB core will not allow dynamic ids to be added to this driver
no_dynamic_id
by preventing the sysfs file from being created.
if set to 0, the USB core will not allow autosuspend for interfaces bound to
supports_autosuspend
this driver.

All callbacks receive a standard argument defined as a pointer to the following structure:
struct usb_interface {
struct usb_host_interface *altsetting;
struct usb_host_interface *cur_altsetting;
unsigned num_altsetting;
int minor;
enum usb_interface_condition condition;
unsigned is_active:1;
unsigned needs_remote_wakeup:1;
struct device dev;
struct class_device *class_dev;
int pm_usage_cnt;
};
where the fields have the following meanings:

Table 12. USB interface structure fields

Field Description

Array of interface structures, one for each alternate setting that may be
altsetting selected. Each one includes a set of endpoint configurations. They will be
in no particular order.
cur_altsetting The current altsetting.
num_altsetting Number of altsettings defined.

51/62
Kernel-space APIs UM0479

Table 12. USB interface structure fields (continued)

Field Description

The minor number assigned to this interface, if this interface is bound to a

driver that uses the USB major number. If this interface does not use the
minor USB major, this field should be unused. The driver should set this value in
the probe() function of the driver, after it has been assigned a minor
number from the USB core by calling usb_register_dev().
Binding state of the interface: not bound, binding (in probe()), bound to a
condition
driver, or unbinding (in disconnect()).
is_active Flag set when the interface is bound and not suspended.
Flag set when the driver requires remote-wakeup capability during
needs_remote_wakeup
autosuspend.
dev Driver model's view of this device.
class_device Driver model's class view of this device.
Power management usage counter for this interface; autosuspend is not
pm_usage_cnt
allowed unless the counter is 0.

The main kernel API functions available for class driver management are as follows:

Function: int usb_register(struct usb_driver *driver);

Description: Registers a driver with the USB host stack. This is usually invoked in a module
initialization function (defined by module_init macro).
Arguments: driver (in):
Pointer to the driver structure.

Function: void usb_deregister(struct usb_driver *driver);

Description: Unregisters a driver from the USB host stack. This is usually invoked in a module
termination function (defined by module_exit macro).
Arguments: driver (in):
Pointer to the driver structure.
The rest of kernel-space USB host API is quite complex and can not be entirely documented
here. It is recommended to look at the include/linux/usb.h header file as well as an
example of skeleton driver provided inside the kernel source tree at path:
/opt/splus_linux_sdk_1_1/src/linux-2.6.19.2/drivers/usb/usb-
skeleton.c

5.9 Watchdog timer (WDT)

A device driver for the SPEAr Plus hardware watchdog timer (WDT) and the relevant kernel-
space API shall be provided in future SDK releases.

52/62
UM0479 Source files for built-in drivers

Appendix A Source files for built-in drivers

A reference to source files implementing the SPEAr Plus device drivers provided with SDK
1.1 is reported in the following table. All paths are relative to Linux kernel top directory.
The availability of user-space and/or kernel-space API for each device is also reported.
A standard naming convention is adopted. All source files have a fixed “spr_” prefix,
followed by a general device identifier (dma, eth, gpio, etc.) and a cell-specific identifier
(pl080, syn, pl061, etc.). The “_hal” suffix, where applied, refers to source files
directly accessing hardware registers (Hardware Abstraction Layer).

Table 13. SDK 1.1 driver summary

Device User API Kernel API Driver source files

drivers/char/spr_dma_pl080.h
drivers/char/spr_dma_pl080_config_device.h
DMA X drivers/char/spr_dma_pl080.c
drivers/char/spr_dma_pl080_hal.h
drivers/char/spr_dma_pl080_hal.c
drivers/net/arm/spr_eth_syn.h
Ethernet
X drivers/net/arm/spr_eth_syn.c
drivers/net/arm/spr_eth_syn_hal.c
drivers/char/spr_gpio_pl061.h
drivers/char/spr_gpio_pl061.c
GPIO X X
drivers/char/spr_gpio_pl061_hal.h
drivers/char/spr_gpio_pl061_hal.c
drivers/i2c/busses/spr_i2c_syn.h
drivers/i2c/busses/spr_i2c_syn.c
I2C Bus / EEPROM X X drivers/i2c/busses/spr_i2c_syn_hal.h
drivers/i2c/busses/spr_i2c_syn_hal.c
drivers/i2c/chips/spr_m24cxx.c
drivers/rtc/spr_rtc_st.c
Real-Time Clock (RTC) X drivers/rtc/spr_rtc_st_hal.h
drivers/rtc/spr_rtc_st_hal.c
drivers/serial/spr_uart_pl011.h
drivers/serial/spr_uart_pl011.c
UARTs X
drivers/serial/spr_uart_pl011_hal.hdrivers/serial
/spr_uart_pl011_hal.c
drivers/usb/gadget/spr_udc_syn.h
USB Device Controller X
drivers/usb/gadget/spr_udc_syn.c
drivers/usb/host/spr_hcd.h
USB Host Controllers X drivers/usb/host/spr_ehci_syn.c
drivers/usb/host/spr_ohci_syn.c

53/62
Default kernel configuration UM0479

Appendix B Default kernel configuration

This section provides the contents of the default kernel configuration file
(spearplus_defconfig). For the sake of better readability, unused sections and
commented lines have been omitted.
CONFIG_ARM=y
CONFIG_MMU=y
CONFIG_GENERIC_HARDIRQS=y
CONFIG_TRACE_IRQFLAGS_SUPPORT=y
CONFIG_HARDIRQS_SW_RESEND=y
CONFIG_GENERIC_IRQ_PROBE=y
CONFIG_RWSEM_GENERIC_SPINLOCK=y
CONFIG_GENERIC_HWEIGHT=y
CONFIG_GENERIC_CALIBRATE_DELAY=y
CONFIG_VECTORS_BASE=0xffff0000
CONFIG_DEFCONFIG_LIST="/lib/modules/$UNAME_RELEASE/.config"

#
# Code maturity level options
#
CONFIG_BROKEN_ON_SMP=y
CONFIG_INIT_ENV_ARG_LIMIT=32

#
# General setup
#
CONFIG_LOCALVERSION=""
CONFIG_LOCALVERSION_AUTO=y
CONFIG_SWAP=y
CONFIG_SYSVIPC=y
CONFIG_INITRAMFS_SOURCE=""
CONFIG_SYSCTL=y
CONFIG_EMBEDDED=y
CONFIG_UID16=y
CONFIG_TINY_SHMEM=y
CONFIG_BASE_SMALL=1
CONFIG_SLOB=y

#
# Loadable module support
#
CONFIG_MODULES=y
CONFIG_MODULE_UNLOAD=y
CONFIG_KMOD=y

#
# Block layer
#
CONFIG_BLOCK=y

54/62
UM0479 Default kernel configuration

#
# IO Schedulers
#
CONFIG_IOSCHED_NOOP=y
CONFIG_IOSCHED_AS=y
CONFIG_IOSCHED_DEADLINE=y
CONFIG_IOSCHED_CFQ=y
CONFIG_DEFAULT_CFQ=y
CONFIG_DEFAULT_IOSCHED="cfq"

#
# System Type
#
CONFIG_ARCH_SPEARPLUS=y

#
# SPEAR platform options
#
CONFIG_SPEAR_MISC_CONFIG=y
CONFIG_SPEAR_LOCK=y

#
# Processor Type
#
CONFIG_CPU_32=y
CONFIG_CPU_ARM926T=y
CONFIG_CPU_32v5=y
CONFIG_CPU_ABRT_EV5TJ=y
CONFIG_CPU_CACHE_VIVT=y
CONFIG_CPU_COPY_V4WB=y
CONFIG_CPU_TLB_V4WBI=y
CONFIG_CPU_CP15=y
CONFIG_CPU_CP15_MMU=y

#
# Processor Features
#
CONFIG_ARM_THUMB=y

#
# Kernel Features
#
CONFIG_HZ=100
CONFIG_FLATMEM=y
CONFIG_FLAT_NODE_MEM_MAP=y
CONFIG_SPLIT_PTLOCK_CPUS=4096
CONFIG_ALIGNMENT_TRAP=y

#
# Boot options
#
CONFIG_ZBOOT_ROM_TEXT=0x0

55/62
Default kernel configuration UM0479

CONFIG_ZBOOT_ROM_BSS=0x0

CONFIG_CMDLINE="console=ttyS0 quiet mem=64M root=/dev/mtdblock3

#
# Floating point emulation
#
CONFIG_FPE_NWFPE=y

#
# Userspace binary formats
#
CONFIG_BINFMT_ELF=y

#
# Networking
#
CONFIG_NET=y

#
# Networking options
#
CONFIG_PACKET=y
CONFIG_PACKET_MMAP=y
CONFIG_UNIX=y
CONFIG_XFRM=y
CONFIG_INET=y
CONFIG_IP_FIB_HASH=y
CONFIG_IP_PNP=y
CONFIG_INET_XFRM_MODE_TRANSPORT=y
CONFIG_INET_XFRM_MODE_TUNNEL=y
CONFIG_INET_XFRM_MODE_BEET=y
CONFIG_INET_DIAG=y
CONFIG_INET_TCP_DIAG=y
CONFIG_TCP_CONG_CUBIC=y
CONFIG_DEFAULT_TCP_CONG="cubic"

#
# Generic Driver Options
#
CONFIG_STANDALONE=y
CONFIG_PREVENT_FIRMWARE_BUILD=y

#
# Memory Technology Devices (MTD)
#
CONFIG_MTD=y
CONFIG_MTD_CONCAT=y
CONFIG_MTD_PARTITIONS=y

56/62
UM0479 Default kernel configuration

# User Modules And Translation Layers

#
CONFIG_MTD_CHAR=y
CONFIG_MTD_BLOCK=y

#
# RAM/ROM/Flash chip drivers
#
CONFIG_MTD_MAP_BANK_WIDTH_1=y
CONFIG_MTD_MAP_BANK_WIDTH_2=y
CONFIG_MTD_MAP_BANK_WIDTH_4=y
CONFIG_MTD_CFI_I1=y
CONFIG_MTD_CFI_I2=y

#
# Self-contained MTD device drivers
#
CONFIG_SPEAR_MTD_NOR=y
CONFIG_MTD_STATIC_MEMORY_BANKS=y
CONFIG_MTD_STATIC_PARTITIONING=y

#
# SCSI device support
#
CONFIG_SCSI=y
CONFIG_SCSI_NETLINK=y
CONFIG_SCSI_PROC_FS=y

#
# SCSI support type (disk, tape, CD-ROM)
#
CONFIG_BLK_DEV_SD=y
CONFIG_CHR_DEV_ST=y
CONFIG_CHR_DEV_OSST=y
CONFIG_BLK_DEV_SR=y
CONFIG_BLK_DEV_SR_VENDOR=y

#
# Some SCSI devices (e.g. CD jukebox) support multiple LUNs
#
CONFIG_SCSI_MULTI_LUN=y
CONFIG_SCSI_CONSTANTS=y
CONFIG_SCSI_LOGGING=y

#
# SCSI Transports
#
CONFIG_SCSI_FC_ATTRS=y

#
# Network device support
#

57/62
Default kernel configuration UM0479

CONFIG_NETDEVICES=y
CONFIG_ETH_SPEAR_SYN=y

#
# Ethernet (10 or 100Mbit)
#
CONFIG_NET_ETHERNET=y
CONFIG_MII=y

#
# Non-8250 serial port support
#
CONFIG_SERIAL_CORE=y
CONFIG_SERIAL_CORE_CONSOLE=y
CONFIG_SPEAR_UART_pl011=y
CONFIG_SPEAR_UART_CONSOLE_pl011=y
CONFIG_UNIX98_PTYS=y
CONFIG_LEGACY_PTYS=y
CONFIG_LEGACY_PTY_COUNT=256

#
# Ftape, the floppy tape device driver
#
CONFIG_SPEAR_GPIO_pl061=y
CONFIG_SPEAR_DMA_pl080=y

#
# I2C support
#
CONFIG_I2C=y

#
# I2C Hardware Bus support
#
CONFIG_SPEAR_I2C_Syn=y

#
# Miscellaneous I2C Chip support
#
CONFIG_SPEAR_M24CXX=y

#
# USB support
#
CONFIG_USB_ARCH_HAS_HCD=y
CONFIG_USB_ARCH_HAS_OHCI=y
CONFIG_USB=y

#
# Miscellaneous USB options
#
CONFIG_USB_DEVICEFS=y

58/62
UM0479 Default kernel configuration

#
# USB Host Controller Drivers
#
CONFIG_USB_EHCI_HCD=y
CONFIG_USB_OHCI_HCD=y
CONFIG_USB_OHCI_LITTLE_ENDIAN=y

#
# NOTE: USB_STORAGE enables SCSI, and 'SCSI disk support'
# may also be needed; see USB_STORAGE Help for more information
#
CONFIG_USB_STORAGE=y

#
# USB Gadget Support
#
CONFIG_USB_GADGET=y
CONFIG_USB_GADGET_SELECTED=y
CONFIG_USB_GADGET_SPEAR_SYN=y
CONFIG_USB_SPEAR_SYN=y
CONFIG_USB_GADGET_DUALSPEED=y
CONFIG_USB_ZERO=y

#
# Real Time Clock
#
CONFIG_RTC_LIB=y
CONFIG_SPEAR_RTC_ST=y

#
# DOS/FAT/NT Filesystems
#
CONFIG_FAT_FS=y
CONFIG_VFAT_FS=y
CONFIG_FAT_DEFAULT_CODEPAGE=437
CONFIG_FAT_DEFAULT_IOCHARSET="iso8859-1"

#
# Pseudo filesystems
#
CONFIG_PROC_FS=y
CONFIG_PROC_SYSCTL=y
CONFIG_SYSFS=y
CONFIG_TMPFS=y
CONFIG_RAMFS=y

#
# Miscellaneous filesystems
#
CONFIG_CRAMFS=y

59/62
Default kernel configuration UM0479

#
# Network File Systems
#
CONFIG_NFS_FS=y
CONFIG_ROOT_NFS=y
CONFIG_LOCKD=y
CONFIG_NFS_COMMON=y
CONFIG_SUNRPC=y

#
# Partition Types
#
CONFIG_MSDOS_PARTITION=y

#
# Native Language Support
#
CONFIG_NLS=y
CONFIG_NLS_DEFAULT="iso8859-1"
CONFIG_NLS_CODEPAGE_437=y
CONFIG_NLS_CODEPAGE_850=y
CONFIG_NLS_ASCII=y
CONFIG_NLS_ISO8859_1=y
CONFIG_NLS_UTF8=y

#
# Kernel hacking
#
CONFIG_ENABLE_MUST_CHECK=y
CONFIG_LOG_BUF_SHIFT=14
CONFIG_FRAME_POINTER=y

#
# Library routines
#
CONFIG_CRC_CCITT=y
CONFIG_CRC32=y
CONFIG_ZLIB_INFLATE=y

60/62
UM0479 Revision history

6 Revision history

Table 14. Document revision history

Date Revision Changes

14-Nov-2007 1 Initial release.

Minor package upgrade, mainly extending DDR clock to
17-Sep-2008 2
266 MHz and supporting Gigabit Ethernet.

61/62
 UM0479

Please Read Carefully:

Information in this document is provided solely in connection with ST products. STMicroelectronics NV and its subsidiaries (“ST”) reserve the
right to make changes, corrections, modifications or improvements, to this document, and the products and services described herein at any
time, without notice.
All ST products are sold pursuant to ST’s terms and conditions of sale.
Purchasers are solely responsible for the choice, selection and use of the ST products and services described herein, and ST assumes no
liability whatsoever relating to the choice, selection or use of the ST products and services described herein.
No license, express or implied, by estoppel or otherwise, to any intellectual property rights is granted under this document. If any part of this
document refers to any third party products or services it shall not be deemed a license grant by ST for the use of such third party products
or services, or any intellectual property contained therein or considered as a warranty covering the use in any manner whatsoever of such
third party products or services or any intellectual property contained therein.

UNLESS OTHERWISE SET FORTH IN ST’S TERMS AND CONDITIONS OF SALE ST DISCLAIMS ANY EXPRESS OR IMPLIED
WARRANTY WITH RESPECT TO THE USE AND/OR SALE OF ST PRODUCTS INCLUDING WITHOUT LIMITATION IMPLIED
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE (AND THEIR EQUIVALENTS UNDER THE LAWS
OF ANY JURISDICTION), OR INFRINGEMENT OF ANY PATENT, COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT.
UNLESS EXPRESSLY APPROVED IN WRITING BY AN AUTHORIZE REPRESENTATIVE OF ST, ST PRODUCTS ARE NOT DESIGNED,
AUTHORIZED OR WARRANTED FOR USE IN MILITARY, AIR CRAFT, SPACE, LIFE SAVING, OR LIFE SUSTAINING APPLICATIONS,
NOR IN PRODUCTS OR SYSTEMS, WHERE FAILURE OR MALFUNCTION MAY RESULT IN PERSONAL INJURY, DEATH, OR
SEVERE PROPERTY OR ENVIRONMENTAL DAMAGE.

Resale of ST products with provisions different from the statements and/or technical features set forth in this document shall immediately void
any warranty granted by ST for the ST product or service described herein and shall not create or extend in any manner whatsoever, any
liability of ST.

ST and the ST logo are trademarks or registered trademarks of ST in various countries.

Information in this document supersedes and replaces all information previously supplied.

The ST logo is a registered trademark of STMicroelectronics. All other names are the property of their respective owners.

© 2008 STMicroelectronics - All rights reserved

STMicroelectronics group of companies

Australia - Belgium - Brazil - Canada - China - Czech Republic - Finland - France - Germany - Hong Kong - India - Israel - Italy - Japan -
Malaysia - Malta - Morocco - Singapore - Spain - Sweden - Switzerland - United Kingdom - United States of America
www.st.com

62/62