Programming the GPIO in Spear Board

September 2008 Rev 2 1/62

UM0479User Manual

SPEAr® Plus Linux SDK, kernel and device APIs

IntroductionThis 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.

www.st.com

http://www.st.com

Contents UM0479

2/62

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

UM0479 Contents

3/62

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

List of tables UM0479

4/62

List of tables

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

UM0479 List of figures

5/62

List of figures

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

Reference documentation UM0479

6/62

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.

UM0479 Introduction

7/62

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.

Introduction UM0479

8/62

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

UM0479 Introduction

9/62

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

Table 1. Acronyms (continued)

Acronym Explanation

Kernel overview UM0479

10/62

3 Kernel overview

3.1 Device runtime architectureAn 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

Ethernet Driver

GPIO Driver

I2C Driver

RTC Driver

DMA Driver

UART Driver

Host Stack

USBD Driver

IP Stack

GPIO KAPI

GPIO UAPI

I2C UAPI

I2C KAPI

RTC UAPI

UART UAPI

DMA KAPI

ETH UAPI

MSC UAPI

USBD KAPI

USBHKAPI

Sockets /proc/net /dev/gpio /dev/i2c /dev/rtc

/dev/ttyS0 /dev/ttyS1 Filesystem

VFAT

MSC Driver

USBH UAPI

USBFS

/proc/bus/usb

USBH Driver

Device Stack

Gadget Zero

KernelSpace

UserSpace

SoC Hardware

Ethernet Controller

Ethernet PHY

Dev.Board

GPIOs

LEDs SW3 Switch J19 Conn.

I2C Controller

EEPROM

RJ45

RTC

Battery

DMA Controller

UARTs (2)

RJ11 J16 Conn.

USBD Ctrl+PHY

USBD Conn.

USBD Ctrl+ PHY

USBD Ctrl+ PHY

USBH Conn.

USBH Conn.

kernel console

UM0479 Kernel overview

11/62

3.2 RebuildingThe 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:


$ build.sh all

In order to build a debugging kernel version, the following commands need to be used:


$ 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


12/62

3.3 Handling modulesAs 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 macrosMODULE_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 bootingA 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.

UM0479 Kernel overview

13/62

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_ethThis 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_uartU-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.


14/62

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.

UM0479 User-space APIs

15/62

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 EthernetThe 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:

User-space APIs UM0479

16/62

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:

:

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:

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.

Table 3. Open sockets

Column Description

sl The number of the line in the output listing.

local_address

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 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.

rem_addressThe remote IP address and port number for the socket. Encoding is the same as for the local_address.

st The socket status.

tx_queue The size of the transmit queue.

rx_queue The size of the receive queue.

trIndicates whether a timer is active for this socket. A value of zero indicates the timer is not active.

tm->when Indicates the time remaining (in jiffies) before timeout occurs.

retrnsmt Unused.

uidThe ID of the user that owns the socket. This is the same ID found in the /etc/passwd file.

timeout Unused.

inode A cryptic-looking number that identifies the socket to the Linux virtual filesystem.


17/62

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

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

Table 4. ARP mapping

Column Description

IP address The IP address.

FlagsSee definitions under Linux sources, in the header file:

linux-2.6.19.2/include/linux/if_arp.h

HW type

See definitions under Linux sources, in the header file:

linux-2.6.19.2/include/linux/if_arp.h

The 0x1 value indicates Ethernet hardware (ARP is used also for other network technologies).

HW address The MAC address.

MaskTypically shown as ‘*’.

Used when advertising a promiscuous ARP entry for an IP network or subnetwork.

Device Device name: eth0

Table 5. IP routing

Column Description

IfaceThe network interface that datagrams matching this route will leave. For a SPEAr Plus board, this may be eth0 or lo.

DestinationIn combination with the Mask field, specifies which datagrams will match this route.

GatewayThe IP address of the host that will act as a router for datagrams matching this route.

Flags

An indicator of various route attributes.

See definitions under Linux sources, in the header file:linux-2.6.19.2/include/linux/route.h

RefCnt Unused.

Use Unused.

MetricThe metric value associated with the route. This is used to indicate the cost or priority of a route.

MaskIn combination with the Destination field, this specifies which datagrams will match this route.

MTUSpecifies the largest TCP segment (in bytes) that will be built for transmission via this route.

WindowSpecifies the TCP window (in bytes) that will be advertised for TCP connections made via this route.

IRTTSpecifies the Initial Round Trip time (in milliseconds) that will be used for TCP connections established via this route.


18/62

(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:

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;

Table 6. GPIO assignment

SoC subsystem Block Line Dev.board

Application GPIO 0 0 Switch SW3 – 1 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


19/62

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.


20/62

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 blockinfo.PinMask = GPIO_PIN0 + GPIO_PIN1; // select 2 pins in the maskinfo.PinInfo.PinDir = IN; // set to inputresult = 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 blockinfo.PinMask = GPIO_PIN0 + GPIO_PIN1; // select 2 pins in the maskresult = 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;


21/62

t_GPIOError result;dev = open("/dev/gpio",O_RDWR);info.GPIOId = GPIO0; // specify blockresult = 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 blockinfo.PinMask = GPIO_PIN0 + GPIO_PIN1; // select 2 pins in the maskinfo.PinInfo.PinVal = RESET; // set pins to zeroresult = 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 blockinfo.PinMask = GPIO_PIN0 + GPIO_PIN1; // select 2 pins in the maskresult = read(dev,&info,sizeof(info));if (result != GPIO_OK) { printf("Error"); }else { info.PinInfo.PinVal = RESET; // set pins to zeroif ((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);


22/62

4.4 DisplayA 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 EEPROMI2C 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


23/62

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 devicedev = open("/dev/i2c",O_RDWR);// configure I2C for access to EEPROMcfg.SlaveAddress = 0x50; // EEPROM slave addresscfg.slave_offset = 0x08; // location = ninth cellcfg.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 8data_out[0] = 0xA5;n = write(dev,data_out,1);if (n!=1) { /* error handling */ }// read back 1 byte from EEPROM location 8n = read(dev,data_in,1);if (n!=1) { /* error handling */ }// close I2C controller deviceclose(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.


24/62

4.7 JPEG codecA 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:00info.tm_mday = 26;info.tm_mon = 11info.tm_year = 64;info.tm_hour = 15;info.tm_min = 9;info.tm_sec = 0;


25/62

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 controlA 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.


26/62

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


27/62

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.


28/62

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

USBDEVFS_BULK

Issues a bulk read or write request to the opened device. Request details are specified in the argument. The ep field specifies a bulk endpoint number (1-15), masked with USB_DIR_IN in case of input endpoints (reading from the device). The “len” field specifies the size of the block to be transferred. Timeout is specified in ms. The “data” field is a pointer to the input or output buffer.

Request details, a pointer to following structure:

struct usbdevfs_bulktransfer {

unsigned int ep;

unsigned int len;

unsigned int timeout;

void *data;

};

USBDEVFS_

CLAIMINTERFACE

Forces to claim a specific interface, not previously been claimed by usbfs or any other kernel driver. The input argument is an integer specifying the interface number.

Interface number:

unsigned int


29/62

USBDEVFS_CLEAR_HALT

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 input endpoints. This call must 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.

Endpoint number:

unsigned int

USBDEVFS_CONNECT

Connect to opened device. None (ignored)

USBDEVFS_CONNECTINFO

Check if the opened device is Low Speed (1.5Mbps). If not, it could be Full or High speed but this can not be detected by this call. The argument specifies a device number “devnum” (DDD value of device filename) as input. The result is returned in the “slow” field.

A pointer to following structure:

struct usbdevfs_connectinfo {

unsigned int devnum;

unsigned char slow;

};

USBDEVFS_CONTROL

Issues a control request to the opened device. The “bRequestType” is the contents of the SETUP packet to be sent to the device. The “bRequestType” field is composed by combining a USB_TYPE_* value, a USB_DIR_* value, and a USB_RECIP_* value (as defined in <linux/usb.h>). The “wLength” field specifies the size of the block to be transferred. The maximum transfer size is 4 KB. Timeout is specified in ms. The “data” field is a pointer to the input or output buffer.


struct usbdevfs_ctrltransfer {

__u8 bRequestType;

__u8 bRequest;

__u16 wValue;

__u16 wIndex;

__u16 wLength;

__u32 timeout;

void __user *data;

};

USBDEVFS_DISCONNECT

Disconnect from opened device. None (ignored)

Table 7. USB filesystem ioctl requests (continued)



30/62

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.

USBDEVFS_GETDRIVER

Returns the name (string) of the kernel driver bound to the specified interface.


struct usbdevfs_getdriver {

unsigned int interface;

char driver

[USBDEVFS_MAXDRIVERNAME+1];

};

USBDEVFS_IOCTL

Sends a request from user-space to a kernel driver that has an ioctl entry in the struct usb_driver it registered.

The “ifno” field is the selected interface number. The “ioctl_code” contains the ioctl request. The “data” field is a pointer to the ioctl argument.


struct usbdevfs_ioctl {

int ifno;

int ioctl_code;

void *data;

};

USBDEVFS_RELEASEINTERFACE

Releases a claimed interface, whose number specified by the argument.

Interface number:unsigned int

USBDEVFS_RESET

Resets the opened USB device. After the reset, this call rebinds all device interfaces. Linux documentation currently discourages the use of this call.

None (ignored)

USBDEVFS_RESETEP

Resets the data toggle value for a bulk or interrupt endpoint to DATA0. The endpoint number (1-5 with USB_DIR_IN mask added for input endpoints) is specified by the input argument. . Linux documentation currently discourages the use of this call.

Endpoint number:unsigned int

USBDEVFS_SETCONFIGURATION

Sets the configuration for the opened device. Linux documentation currently discourages the use of this call.

Configuration number: unsigned int

USBDEVFS_SETINTERFACE

Sets the alternate setting for a specified interface.


struct usbdevfs_setinterface {

unsigned int interface;

unsigned int altsetting;

};

Table 7. USB filesystem ioctl requests (continued)


UM0479 Kernel-space APIs

31/62

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

Kernel-space APIs UM0479

32/62

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_SetConfigDevicet_DMADeviceId DeviceId,t_DMAAccessWidth AccessWidth,t_DMABurstSize MaxBurstSize,t_DMAProtection Protection, t_bool CanBeFlowController)

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


33/62

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);


34/62

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; // sourcet_DMADeviceId DestDeviceId; // destinationuint SrcAddress; // source addressuint DestAddress; // destination addressuint TransferSize; // size in bytes of transfert_DMAFlowCtrl FlowController; // flow typet_DMATransferPriority Priority;// priority of DMA transfert_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,


35/62

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.


Function: t_DMAError SPEAr_DMA_AbortTransfer(t_DMAChannelId ChannelId, t_bool DataCanBeLost);

Description: Aborts ongoing transfer on specified DMA channel.



36/62

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.


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);


37/62

Description: Sets the value or one or more pins for the specified block.


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.


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.


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,


38/62

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.


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.


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.


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


39/62

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.


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.


5.4 I2C busThe 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.


40/62

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:


41/62

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;};


Table 8. Gadget driver structure fields

Field Description

function String describing the gadget's function.

speed Highest speed the driver handles.

bind

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 initialized, and ep_list holds the currently-available endpoints. Called in a context that permits sleeping.

unbindPointer to custom callback function invoked when the driver is unbound from a gadget, usually from rmmod (after a disconnect is reported). Called in a context that permits sleeping.

setup

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. 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.

disconnect

Pointer to custom callback function invoked after all transfers have been stopped, when the host is disconnected. May be called in_interrupt; this may not sleep. Some devices can't detect disconnect, so this might not be called except as part of controller shutdown.

suspendPointer to custom callback function invoked on USB suspend. May be called in_interrupt.

resumePointer to custom callback function invoked on USB resume. May be called in_interrupt.

driver Driver model state for this driver.


42/62

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).


Table 9. Gadget structure fields

Field Description

ops Function pointers used to access hardware-specific operations.

ep0Endpoint zero, used when reading or writing responses to driver setup() requests.

ep_list List of other endpoints supported by the device.

speed Speed of current connection to USB host.

dualspeedTrue if the controller supports both high and full speed operation. If it does, the gadget driver must also support both.

is_otgTrue if the USB device port uses a Mini-AB jack, so that the gadget driver must provide a USB OTG descriptor.

is_a_peripheralFalse unless is_otg, the A end of a USB cable is in the Mini-AB jack, and 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.

a_hnp_supportOTG device feature flag, indicating that the A-Host supports HNP at this port.

a_alt_hnp_supportOTG device feature flag, indicating that the A-Host only supports HNP on a different root port.

nameIdentifies the controller hardware type. Used in diagnostics and sometimes configuration.

dev Driver model state for this abstract device.


43/62

Function: int usb_gadget_connect(struct usb_gadget *gadget);

Description: Connects to USB host.


Function: int usb_gadget_disconnect(struct usb_gadget *gadget);

Description: Disconnects from USB host.


Function: int usb_gadget_set_selfpowered(struct usb_gadget *gadget);

Description: Sets the device self-powered feature.


Function: int usb_gadget_clear_selfpowered(struct usb_gadget *gadget);

Description: Clears the device self-powered feature.


Function: int usb_gadget_vbus_connect(struct usb_gadget *gadget);

Description: Notifies device controller that VBUS is powered.


Function: int usb_gadget_vbus_disconnect(struct usb_gadget *gadget);

Description: Notifies controller about VBUS end session.



44/62

Function: int usb_gadget_vbus_draw(struct usb_gadget *gadget, unsigned mA);

Description: Constrains controller's VBUS power usage.


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.


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;};


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

Table 10. Endpoint structure fields

Field Description

driver_dataFor use by the gadget driver, all other fields are read-only to gadget drivers.

name Identifier for the endpoint, such as ep-a or ep9in-bulk”

ops Function pointers used to access hardware-specific operations.

ep_listThe gadget's ep_list holds all of its endpoints. all the general purpose 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.

maxpacketThe maximum packet size used on this endpoint. The initial value can sometimes be reduced (hardware allowing), according to the endpoint descriptor used to configure the endpoint.


45/62

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.


Function: void usb_ep_fifo_flush(struct usb_ep *ep);

Description: Flushes the FIFO of specified endpoint.


Function: int usb_ep_fifo_status(struct usb_ep *ep);

Description: Queries the status of the FIFO of specified endpoint.


Function: int usb_ep_set_halt(struct usb_ep *ep);

Description: Sets the halt feature of specified endpoint.


Function: int usb_ep_clear_halt(struct usb_ep *ep);

Description: Clear the halt feature of specified endpoint.


46/62


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.


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.


req (in):Pointer to request structure.


47/62

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.




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.



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.


len (in):Buffer length.

dma (out):DMA address.



48/62

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.


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.


49/62

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.


50/62

5.8 USB hostsAs 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;};


Table 11. USB driver structure fields

Field Description

nameDriver name, should be unique among USB host drivers and should normally be the same as the module name.

probe

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 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.

disconnectPointer to custom callback function invoked when the interface is no longer accessible, usually because its device has been (or is being) disconnected or the driver module is being unloaded.

ioctl

Pointer to custom callback function used for drivers that want to talk to userspace through the usbfs filesystem. This lets devices provide ways to expose information to user space regardless of where they do (or don't) show up otherwise in the filesystem.


51/62

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;};


suspendPointer to custom callback function called when the device is going to be suspended by the system.

resumePointer to custom callback function called when the device is being resumed by the system.

pre_resetPointer to custom callback function called by usb_reset_composite_device() when the device is about to be reset.

post_resetPointer to custom callback function called by usb_reset_composite_device() after the device has been reset.

id_tableID table to support hotplugging. Export this with MODULE_DEVICE_TABLE(usb,...). This must be set or your driver's probe function will never get called.

dynidsUsed internally to hold the list of dynamically added device ids for this driver.

drvwrap Driver-model core structure wrapper.

no_dynamic_idif set to 1, the USB core will not allow dynamic ids to be added to this driver by preventing the sysfs file from being created.

supports_autosuspendif set to 0, the USB core will not allow autosuspend for interfaces bound to this driver.

Table 12. USB interface structure fields

Field Description

altsettingArray of interface structures, one for each alternate setting that may be 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.

Table 11. USB driver structure fields

Field Description


52/62

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).


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).


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.

minor

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 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().

conditionBinding state of the interface: not bound, binding (in probe()), bound to a driver, or unbinding (in disconnect()).

is_active Flag set when the interface is bound and not suspended.

needs_remote_wakeupFlag set when the driver requires remote-wakeup capability during autosuspend.

dev Driver model's view of this device.

class_device Driver model's class view of this device.

pm_usage_cntPower management usage counter for this interface; autosuspend is not allowed unless the counter is 0.

Table 12. USB interface structure fields (continued)

Field Description

UM0479 Source files for built-in drivers

53/62

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

DMA X

drivers/char/spr_dma_pl080.h drivers/char/spr_dma_pl080_config_device.h drivers/char/spr_dma_pl080.c drivers/char/spr_dma_pl080_hal.h drivers/char/spr_dma_pl080_hal.c

EthernetX

drivers/net/arm/spr_eth_syn.h drivers/net/arm/spr_eth_syn.c drivers/net/arm/spr_eth_syn_hal.c

GPIO X X

drivers/char/spr_gpio_pl061.h drivers/char/spr_gpio_pl061.c drivers/char/spr_gpio_pl061_hal.h drivers/char/spr_gpio_pl061_hal.c

I2C Bus / EEPROM X X

drivers/i2c/busses/spr_i2c_syn.h drivers/i2c/busses/spr_i2c_syn.c drivers/i2c/busses/spr_i2c_syn_hal.h drivers/i2c/busses/spr_i2c_syn_hal.c drivers/i2c/chips/spr_m24cxx.c

Real-Time Clock (RTC) Xdrivers/rtc/spr_rtc_st.c drivers/rtc/spr_rtc_st_hal.h drivers/rtc/spr_rtc_st_hal.c

UARTs X

drivers/serial/spr_uart_pl011.h drivers/serial/spr_uart_pl011.c drivers/serial/spr_uart_pl011_hal.hdrivers/serial/spr_uart_pl011_hal.c

USB Device Controller Xdrivers/usb/gadget/spr_udc_syn.h drivers/usb/gadget/spr_udc_syn.c

USB Host Controllers Xdrivers/usb/host/spr_hcd.h drivers/usb/host/spr_ehci_syn.c drivers/usb/host/spr_ohci_syn.c

Default kernel configuration UM0479

54/62

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=yCONFIG_MMU=yCONFIG_GENERIC_HARDIRQS=yCONFIG_TRACE_IRQFLAGS_SUPPORT=yCONFIG_HARDIRQS_SW_RESEND=yCONFIG_GENERIC_IRQ_PROBE=yCONFIG_RWSEM_GENERIC_SPINLOCK=yCONFIG_GENERIC_HWEIGHT=yCONFIG_GENERIC_CALIBRATE_DELAY=yCONFIG_VECTORS_BASE=0xffff0000CONFIG_DEFCONFIG_LIST="/lib/modules/$UNAME_RELEASE/.config"

## Code maturity level options#CONFIG_BROKEN_ON_SMP=yCONFIG_INIT_ENV_ARG_LIMIT=32

## General setup#CONFIG_LOCALVERSION=""CONFIG_LOCALVERSION_AUTO=yCONFIG_SWAP=yCONFIG_SYSVIPC=yCONFIG_INITRAMFS_SOURCE=""CONFIG_SYSCTL=yCONFIG_EMBEDDED=yCONFIG_UID16=yCONFIG_TINY_SHMEM=yCONFIG_BASE_SMALL=1CONFIG_SLOB=y

## Loadable module support#CONFIG_MODULES=yCONFIG_MODULE_UNLOAD=yCONFIG_KMOD=y

## Block layer#CONFIG_BLOCK=y

UM0479 Default kernel configuration

55/62

## IO Schedulers#CONFIG_IOSCHED_NOOP=yCONFIG_IOSCHED_AS=yCONFIG_IOSCHED_DEADLINE=yCONFIG_IOSCHED_CFQ=yCONFIG_DEFAULT_CFQ=yCONFIG_DEFAULT_IOSCHED="cfq"

## System Type#CONFIG_ARCH_SPEARPLUS=y

## SPEAR platform options#CONFIG_SPEAR_MISC_CONFIG=yCONFIG_SPEAR_LOCK=y

## Processor Type#CONFIG_CPU_32=yCONFIG_CPU_ARM926T=yCONFIG_CPU_32v5=yCONFIG_CPU_ABRT_EV5TJ=yCONFIG_CPU_CACHE_VIVT=yCONFIG_CPU_COPY_V4WB=yCONFIG_CPU_TLB_V4WBI=yCONFIG_CPU_CP15=yCONFIG_CPU_CP15_MMU=y

## Processor Features#CONFIG_ARM_THUMB=y

## Kernel Features#CONFIG_HZ=100CONFIG_FLATMEM=yCONFIG_FLAT_NODE_MEM_MAP=yCONFIG_SPLIT_PTLOCK_CPUS=4096CONFIG_ALIGNMENT_TRAP=y

## Boot options#CONFIG_ZBOOT_ROM_TEXT=0x0


56/62

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=yCONFIG_PACKET_MMAP=yCONFIG_UNIX=yCONFIG_XFRM=yCONFIG_INET=yCONFIG_IP_FIB_HASH=yCONFIG_IP_PNP=yCONFIG_INET_XFRM_MODE_TRANSPORT=yCONFIG_INET_XFRM_MODE_TUNNEL=yCONFIG_INET_XFRM_MODE_BEET=yCONFIG_INET_DIAG=yCONFIG_INET_TCP_DIAG=yCONFIG_TCP_CONG_CUBIC=yCONFIG_DEFAULT_TCP_CONG="cubic"

## Generic Driver Options#CONFIG_STANDALONE=yCONFIG_PREVENT_FIRMWARE_BUILD=y

## Memory Technology Devices (MTD)#CONFIG_MTD=yCONFIG_MTD_CONCAT=yCONFIG_MTD_PARTITIONS=y

#


57/62

# User Modules And Translation Layers#CONFIG_MTD_CHAR=yCONFIG_MTD_BLOCK=y

## RAM/ROM/Flash chip drivers#CONFIG_MTD_MAP_BANK_WIDTH_1=yCONFIG_MTD_MAP_BANK_WIDTH_2=yCONFIG_MTD_MAP_BANK_WIDTH_4=yCONFIG_MTD_CFI_I1=yCONFIG_MTD_CFI_I2=y

## Self-contained MTD device drivers#CONFIG_SPEAR_MTD_NOR=yCONFIG_MTD_STATIC_MEMORY_BANKS=yCONFIG_MTD_STATIC_PARTITIONING=y

## SCSI device support#CONFIG_SCSI=yCONFIG_SCSI_NETLINK=yCONFIG_SCSI_PROC_FS=y

## SCSI support type (disk, tape, CD-ROM)#CONFIG_BLK_DEV_SD=yCONFIG_CHR_DEV_ST=yCONFIG_CHR_DEV_OSST=yCONFIG_BLK_DEV_SR=yCONFIG_BLK_DEV_SR_VENDOR=y

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

## SCSI Transports#CONFIG_SCSI_FC_ATTRS=y

## Network device support#


58/62

CONFIG_NETDEVICES=yCONFIG_ETH_SPEAR_SYN=y

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

## Non-8250 serial port support#CONFIG_SERIAL_CORE=yCONFIG_SERIAL_CORE_CONSOLE=yCONFIG_SPEAR_UART_pl011=yCONFIG_SPEAR_UART_CONSOLE_pl011=yCONFIG_UNIX98_PTYS=yCONFIG_LEGACY_PTYS=yCONFIG_LEGACY_PTY_COUNT=256

## Ftape, the floppy tape device driver#CONFIG_SPEAR_GPIO_pl061=yCONFIG_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=yCONFIG_USB_ARCH_HAS_OHCI=yCONFIG_USB=y

## Miscellaneous USB options#CONFIG_USB_DEVICEFS=y


59/62

## USB Host Controller Drivers#CONFIG_USB_EHCI_HCD=yCONFIG_USB_OHCI_HCD=yCONFIG_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=yCONFIG_USB_GADGET_SELECTED=yCONFIG_USB_GADGET_SPEAR_SYN=yCONFIG_USB_SPEAR_SYN=yCONFIG_USB_GADGET_DUALSPEED=yCONFIG_USB_ZERO=y

## Real Time Clock#CONFIG_RTC_LIB=yCONFIG_SPEAR_RTC_ST=y

## DOS/FAT/NT Filesystems#CONFIG_FAT_FS=yCONFIG_VFAT_FS=yCONFIG_FAT_DEFAULT_CODEPAGE=437CONFIG_FAT_DEFAULT_IOCHARSET="iso8859-1"

## Pseudo filesystems#CONFIG_PROC_FS=yCONFIG_PROC_SYSCTL=yCONFIG_SYSFS=yCONFIG_TMPFS=yCONFIG_RAMFS=y

## Miscellaneous filesystems#CONFIG_CRAMFS=y


60/62

## Network File Systems#CONFIG_NFS_FS=yCONFIG_ROOT_NFS=yCONFIG_LOCKD=yCONFIG_NFS_COMMON=yCONFIG_SUNRPC=y

## Partition Types#CONFIG_MSDOS_PARTITION=y

## Native Language Support#CONFIG_NLS=yCONFIG_NLS_DEFAULT="iso8859-1"CONFIG_NLS_CODEPAGE_437=yCONFIG_NLS_CODEPAGE_850=yCONFIG_NLS_ASCII=yCONFIG_NLS_ISO8859_1=yCONFIG_NLS_UTF8=y

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

## Library routines#CONFIG_CRC_CCITT=yCONFIG_CRC32=yCONFIG_ZLIB_INFLATE=y

UM0479 Revision history

61/62

6 Revision history

Table 14. Document revision history

Date Revision Changes

14-Nov-2007 1 Initial release.

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

UM0479

62/62

Please Read Carefully:

Information in this document is provided solely in connection with ST products. STMicroelectronics NV and its subsidiaries (“ST”) reserve theright to make changes, corrections, modifications or improvements, to this document, and the products and services described herein at anytime, 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 noliability 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 thisdocument 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 productsor services, or any intellectual property contained therein or considered as a warranty covering the use in any manner whatsoever of suchthird 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 IMPLIEDWARRANTY WITH RESPECT TO THE USE AND/OR SALE OF ST PRODUCTS INCLUDING WITHOUT LIMITATION IMPLIEDWARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE (AND THEIR EQUIVALENTS UNDER THE LAWSOF 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, ORSEVERE 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 voidany warranty granted by ST for the ST product or service described herein and shall not create or extend in any manner whatsoever, anyliability 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

Date post:	07-Apr-2015
Category:	Documents
Upload:	samiie30
View:	202 times
Download:	3 times

Programming the GPIO in Spear Board

Documents