UM0479 User Manual
SPEAr Plus Linux SDK, kernel and device APIs
Introduction
This document provides information about the Linux kernel and the device drivers provided by the SPEAr Plus Linux SDK. The Linux kernel is the core component of an overall Linuxbased software solution. This SDK version supports Linux kernel 2.6.19.2. A predefined Linux kernel is provided as pre-stored on NOR Flash memory for SPEAr Plus development boards. Such kernel may be immediately used for both initial assessment and application development.
September 2008
Rev 2
1/62
www.st.com
Contents
UM0479
Contents
1 2 Reference documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.1 Acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3
Kernel overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.1 3.2 3.3 3.4 Device runtime architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Rebuilding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Handling modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Flashing and booting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4
User-space APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.1 4.2 4.3 4.4 4.5 4.6 4.7 4.8 4.9 4.10 4.11 4.12 4.13 4.14 A/D converter (ADC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Ethernet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 General-pur pose input/output (GPIO) . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 I2C bus and EEPROM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Inter-processor communication (IPC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 JPEG codec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Real-time clock (RTC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Slave CPU control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Synchronous serial ports (SSPs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Asynchronous serial ports (UARTs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 USB device (gadget filesystem) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 USB hosts (mass storage and USB filesystem) . . . . . . . . . . . . . . . . . . . . 27 Watchdog timer (WDT) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
5
Kernel-space APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
5.1 5.2 5.3 5.4 A/D converter (ADC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Direct memory access (DMA) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 General-pur pose input/output (GPIO) . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 I2C bus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
2/62
UM0479
Contents
5.5 5.6 5.7
Inter-processor communication (IPC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Synchronous serial ports (SSPs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 USB device (gadget framework) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
5.7.1 5.7.2 5.7.3 Gadget driver management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Endpoint management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Endpoint I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
5.8 5.9
USB hosts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Watchdog timer (WDT) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Appendix A Source files for built-in drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Appendix B Default kernel configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 6 Revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
3/62
List of tables
UM0479
List of tables
Table 1. Table 2. Table 3. Table 4. Table 5. Table 6. Table 7. Table 8. Table 9. Table 10. Table 11. Table 12. Table 13. Table 14. Acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Network interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Open sockets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 ARP mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 IP routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 GPIO assignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 USB filesystem ioctl requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Gadget driver structure fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Gadget structure fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 Endpoint structure fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 USB driver structure fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 USB interface structure fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 SDK 1.1 driver summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Document revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
4/62
UM0479
List of figures
List of figures
Figure 1. Device runtime architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
5/62
Reference documentation
UM0479
1
Reference documentation
1. 2. 3. 4. 5. 6. 7. 8. 9. STMicroelectronics, SPEAr Plus Linux SDK, getting started, SW Ver. 1.1 STMicroelectronics, SPEAr Plus Linux SDK, kernel and device APIs, SW Ver. 1.1 STMicroelectronics, SPEAr Plus Linux SDK, embedded root filesystem, SW Ver. 1.1 STMicroelectronics, SPEAr Plus development board, user manual STMicroelectronics, SPEAr Head600 datasheet, http://www.st.com STMicroelectronics, SPEAr Plus600 datasheet, http://www.st.com BusyBox, http://www.busybox.net Free Software Foundation, The GNU C Library Reference Manual, Edition 0.11, December 2006, Ver 2.6, http://www.gnu.org/software/libc/manual/ Denx Software Engineering, ELDK 4.1, http://www.denx.de
10. O'Reilly, Understanding the Linux kernel, 3rd Edition, 2006.
6/62
UM0479
Introduction
2
Introduction
This document provides information about the Linux kernel and the device drivers provided by the SPEAr Plus Linux SDK (referred as just "SDK" in the following). The Linux kernel is the core component of an overall Linux-based software solution. A detailed description of Linux kernel is out of the scope of this document. For a good reference book on this subject see [10]. Anyway, the main functionality provided by the kernel can be summarized as follows:
Task scheduling Memory management Inter-process communication and synchronization Vir tual 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 ondemand. Persistent storage of kernel on flash is also required in order to make a standalone self-booting system (and, of course, in the final product). Finally, rewriting the kernel on flash is required if the flash area allocated to the kernel has been erased or damaged for any reason. An additional mechanism is made available by the Linux architecture. Besides static linking with the kernel binary image, kernel extensions may be also compiled as "modules" (also known as LKM, Loadable Kernel Modules). Such modules are stored outside the kernel image, namely inside the root filesystem. Modules are then dynamically loaded (and potentially unloaded) on demand by user-space software. However, modules maintain the same properties of code that is statically linked with the kernel. More specifically, modules operate in kernel (physical) address space and may directly access to any exposed kernel function or data structure. In order to minimize flash memory occupation, as well as to make downloads faster, it is recommended to operate with a compressed kernel binary image. Usually about 50% size reduction may be obtained using the GZ algorithm. Compression is a post-processing step applied when rebuilding the kernel and is also part of the build procedure predefined by the SDK. Decompression is performed on the fly by U-Boot when loading the kernel to system RAM for execution.
7/62
Introduction
UM0479
In next sections, the procedures to rebuild and use the kernel and LKM modules are first discussed. The device APIs of the default kernel are then described. Interactive commands are shown in courier bold font. The "#" prompt is assumed for the Linux shell on the target board. The "$" prompt is assumed for the Linux shell on the PC host. The "spearplus>" prompt is assumed for interaction with the resident bootloader/monitor (U-Boot). Finally, in this entire document, it is assumed that the SDK 1.1 package has been installed on a Linux PC host under the recommended path: /opt/splus_linux_sdk_1_1/
2.1
Acronyms
Table 1. Acronyms
Explanation A/D converter Application programming interface Address resolution protocol Compressed ROM file system Cyclic redundancy check Direct memory access Enhanced host controller interface Embedded linux development kit File allocation table General purpose I/O General public license (GNU) Hardware abstraction layer Hardware Inter-integrated circuit bus Internet protocol Inter-process communication Interrupt service routine Loadable kernel module Local area network Media access control Memory technology device Network file system Open host controller interface Operating system Acronym ADC API ARP CRAMFS CRC DMA EHCI ELDK FAT GPIO GPL HAL HW I2C IP IPC ISR LKM LAN MAC MTD NFS OHCI OS
8/62
UM0479 Table 1. Acronyms (continued)
Explanation Random access memory Real-time clock Real time operating system Software development kit System on chip Structured processor enhanced architecture Synchronous serial port Software Trivial file transfer protocol Universal asynchronous receiver-transmitter Universal serial bus Vectored interrupt controller Watchdog timer
Introduction
Acronym RAM RTC RTOS SDK SoC SPEAr SSP SW TFTP UART USB VIC WDT
9/62
Kernel overview
UM0479
3
3.1
Kernel overview
Device runtime architecture
An overview of the devices supported in SDK 1.1 and their runtime architecture is depicted in Figure 1. Software interfaces to each device are described in detail in next chapters. User-space APIs (labeled UAPI in the diagram) are intended to be used from application software and middleware executing in some user address space and invoking system calls to interact with device drivers and other kernel layers. Kernel-space APIs (labeled KAPI in the diagram) are intended to be used from components executing in kernel address space and directly invoking function calls.
Figure 1.
Device runtime architecture
User Space Sockets /proc/net ETH UAPI /dev/gpio GPIO UAPI /dev/i2c I2C UAPI /dev/rtc RTC UAPI /dev/ttyS0 /dev/ttyS1 UART UAPI Gadget Zero /proc/bus/usb USBH UAPI Filesystem MSC UAPI
USBFS
VFAT
DMA KAPI
GPIO KAPI
I2C KAPI kernel console
USBD KAPI
USBH KAPI
MSC Driver
IP Stack DMA Driver Etherne t Driver GPIO Driver I2C Driver RTC Driver UART Driver
Device Stack USBD Driver
Host Stack USBH Driver Kernel Space
DMA Controller
Ethernet Controller
GPIOs
I2C Controller
RTC
UARTs (2)
USBD Ctrl+PHY
USBD Ctrl+ PHY
USBD Ctrl+ PHY
SoC Hardware
Ethernet PHY RJ45
LEDs SW3 Switch J19 Conn.
EEPROM
Battery
RJ11
J16 Conn.
USBD Conn.
USBH Conn.
USBH Conn.
Dev. Board
10/62
UM0479
Kernel overview
3.2
Rebuilding
The Linux kernel, provided in source code inside the SDK, needs to be rebuilt in the following typical cases:
the source code of a new device driver is added or an existing driver source has been modified the value of some kernel configuration options must be changed (e.g. to enable the use of an additional protocol stack or filesystem)
The kernel contents are modified by directly adding files and/or editing existing files in the kernel source tree. When new files are added, some Makefile and Kconfig files have usually to be adapted as well. It is important to remark that custom extensions or modifications that are statically linked to the kernel are constrained by the GPL licensing policy. In other terms, any statically linked extension is considered as a kernel derivative work and must be licensed as a GPL component. On the other hand, for kernel extensions implemented as dynamically loaded modules, no GPL policy automatically applies. The SDK provides two default kernel configuration files, located under path: /opt/splus_linux_sdk_1_1/src/linux-2.6.19.2/arch/arm/configs The spearplus_defconfig file contains the standard configuration to be used. For debugging purposes, an alternative configuration is also available, named spearplus_dbg_defconfig. The latter file provides the same functionality as the former one, but the kernel will be compiled with debugging options. The kernel (as well as any module specified in the selected configuration file) may be rebuilt with the configuration defined in spearplus_defconfig using the following commands: $ cd /opt/splus_linux_sdk_1_1 $ build.sh linux The output of this operation is a compressed kernel binary image located under: /opt/splus_linux_sdk_1_1/flash/linux.uimg This file is already in the proper format to be used by U-Boot for flashing or loading ondemand through TFTP. The following commands also rebuild everything including the kernel from standard configuration file: $ cd /opt/splus_linux_sdk_1_1 $ build.sh all In order to build a debugging kernel version, the following commands need to be used: $ cd /opt/splus_linux_sdk_1_1 $ build.sh linux_dbg The output of this operation is a compressed kernel binary image located under: /opt/splus_linux_sdk_1_1/flash/linux_dbg.uimg
11/62
Kernel overview
UM0479
3.3
Handling modules
As already anticipated, loadable kernel modules (LKM) are dynamically loaded and linked on demand by user-space software while maintaining the same properties of code that is statically linked with the kernel. Hence, modules operate in physical address space and may directly access to any exposed kernel function or data structure. Modules are single ELF object files identified by the.ko extension. Modules are automatically recompiled when rebuilding the kernel. Some components of the Linux kernel have the option of being rebuilt as modules instead of statically linked with the kernel image. This option may be enabled with the "=M" assignment (instead of "=Y") inside the kernel configuration file. Moreover, custom modules may be developed. An online guide to develop custom modules for the Linux 2.6 series of kernels can be found at address: http://www.tldp.org/LDP/lkmpg/2.6/html/index.html Modules have to be developed according to special requirements. As an example, the following is the simplest module that can be designed. Special macros are shown in courier bold font. // simplest.c #include // needed by all modules #include // needed for KERN_INFO #include // needed for macros MODULE_AUTHOR("ST Microelectronics"); MODULE_DESCRIPTION("Simplest module"); MODULE_LICENSE("GPL"); static int __init simplest_init(void) { printk(KERN_INFO "Loading simplest module\n"); return 0; // a non-zero return value will prevent module loading } static void __exit simplest_exit(void) { printk(KERN_INFO "Unloading simplest module\n"); } module_init(simplest_init); module_exit(simplest_exit);
3.4
Flashing and booting
A NOR Flash memory update is required to use a custom flashed kernel or when a new version of the default kernel is delivered by ST. On the NOR Flash, sector range 5-47 is reserved to the kernel partition. Since each sector is 64 Kbyte, the maximum size of the kernel image is 2752 Kbyte. It is very important to assure that the Linux kernel partition is restored to write-protected mode after any flash update. Any unexpected writing access to the kernel partition will usually lead to a system bootstrap failure. In fact, besides software updates, there is no other case where writing to this partition is required. Write-protection, anyway, is already performed by ST-provided scripts as discussed below.
12/62
UM0479
Kernel overview An Ethernet host-target link is the fastest way to support flash updating. A predefined UBoot 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. 2. 3. 4. 5. 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. 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. 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. Switch on or just reset the target board and enter the U-Boot monitor interactive mode. From U-Boot prompt, execute the following command: spearplus> run flash_linux_eth This will first start the transfer of the file from PC to the board over Ethernet. After the transfer, the command will automatically proceed by completing all required steps for flashing and verification.
An alternative to Ethernet for flash updating is the use of a serial link and the Kermit protocol. This approach is slower but still helpful when an Ethernet link is not available. A predefined U-Boot script called flash_linux_uart has been made available as predefined on the development boards to minimize manual steps. In order to update the kernel partition with a new Linux binary image using the serial link, the following procedure has to be performed: 1. 2. 3. 4. Connect the target board to a PC using a null-modem serial cable (the UART0 DB9 connector must be used). 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. Switch on or just reset the target board and enter the U-Boot monitor interactive mode. From U-Boot prompt, execute the following command: spearplus> run flash_linux_uart U-Boot is now waiting for a Kermit file transfer from the PC terminal. The linux.uimg file must be selected from a PC directory (or linux_dbg.uimg for the debugging version). After the transfer is started on the PC, the command will go on by transferring (using Kermit) the file over serial cable and completing all required steps for flashing and verification.
System bootstrap with the flashed Linux kernel is normally performed with the following UBoot environment setting: bootcmd=bootm 0xf8050000 When the Linux kernel is often changed, it may be useful to boot it directly from a host PC instead of updating the NOR Flash everytime. This approach may be followed by just changing the U-Boot environment variable as follows: spearplus> setenv bootcmd tftpboot 0xF8050000 linux${dbg}.uimg In this way, the kernel will be downloaded from a TFTP server at each board reset and then executed.
13/62
Kernel overview
UM0479
In order to use the alternative debugging version of the kernel, the dbg variable must be set to "_dbg" as follows: spearplus> setenv dbg _dbg Consult appendix A of document [1] to fully restore default U-Boot settings in case of any damage to them.
14/62
UM0479
User-space APIs
4
User-space APIs
The APIs to access SPEAr Plus devices from user-space software are described in the following sections. Access is always performed internally through system calls, since there is no static or dynamic linking of the relevant device drivers with application software. It should be noted that user-space APIs are exposed only for devices that actually require this access level. For instance, there is no need to expose a user-space API for DMA. Standard Linux APIs are exploited wherever applicable (e.g. Ethernet, RTC, UARTs, USB mass storage). In all other cases an ST-specific API has been defined for each kind of device, while still based on standard I/O function calls.
4.1
A/D converter (ADC)
A device driver for the SPEAr Plus A/D Converter (ADC) and the relevant user-space API shall be provided in future SDK releases.
4.2
Ethernet
The Ethernet port is usually accessed by user-space applications indirectly, by means of the standard Linux Sockets API, available in the C runtime library [8], on top of the IP protocol stack integrated in the kernel. In addition, information about the Ethernet device is accessible to user-space through the /proc/net pseudo file tree. These logical files may be directly accessed by user-space commands and applications using standard library functions like for real files. The /proc/net/dev file contains information about the configured network interfaces. There is one text line for each logical network interface known to the kernel. For a SPEAr board connected to a PC or to a LAN, there will be two interfaces named: eth0 and lo (loopback). In each line you are given the interface name followed by two sets of nearly identical statistics, receive and transmit, for that interface. The meanings of each of the columns are:
15/62
User-space APIs Table 2.
Column bytes packets errs drop fifo frame colls compressed carrier multicast
UM0479 Network interfaces
Description The total number of bytes of data transmitted or received by the interface. The total number of packets of data transmitted or received by the interface. The total number of transmit or receive errors detected by the device driver. The total number of packets dropped by the device driver. The number of FIFO buffer errors. The number of packet framing errors. The number of collisions detected on the interface. The number of compressed packets transmitted or received by the device driver. The number of carrier losses detected by the device driver. The number of multicast frames transmitted or received by the device driver.
The /proc/net/tcp, /proc/net/udp and /proc/net/raw files contain information about currently open sockets (if any), for TCP, UDP and raw mode respectively. All three files have the same tabular format with columns defined as follows: Table 3.
:
Open sockets
Description The number of the line in the output listing. The local IP address and port number for the socket. The IP address is displayed as a little-endian four-byte hexadecimal number; that is, the least significant byte is listed first, so you'll need to reverse the order of the bytes to convert it to an IP address. The port number is a simple two-byte hexadecimal number. The remote IP address and port number for the socket. Encoding is the same as for the local_address. The socket status. The size of the transmit queue. The size of the receive queue. Indicates whether a timer is active for this socket. A value of zero indicates the timer is not active. Indicates the time remaining (in jiffies) before timeout occurs. Unused. The ID of the user that owns the socket. This is the same ID found in the /etc/passwd file. Unused. A cryptic-looking number that identifies the socket to the Linux virtual filesystem.
Column sl
local_address
rem_address st tx_queue rx_queue tr tm->when retrnsmt uid timeout inode
The /proc/net/arp file contain the ARP table. ARP is the low-level protocol used by Ethernet networks to enable a mapping from IP addresses (layer 3) to MAC addresses (layer 2). The columns have the following meaning:
16/62
UM0479 Table 4.
Column IP address Flags The IP address. See definitions under Linux sources, in the header file: linux-2.6.19.2/include/linux/if_arp.h
User-space APIs ARP mapping
Description
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). The MAC address. Typically shown as `*'. Used when advertising a promiscuous ARP entry for an IP network or subnetwork. Device name: eth0
HW address Mask Device
The /proc/net/route file contain the IP routing table. The columns have the following meaning: Table 5.
Column Iface Destination Gateway
IP routing
Description The network interface that datagrams matching this route will leave. For a SPEAr Plus board, this may be eth0 or lo. In combination with the Mask field, specifies which datagrams will match this route. The IP address of the host that will act as a router for datagrams matching this route. An indicator of various route attributes. See definitions under Linux sources, in the header file: linux-2.6.19.2/include/linux/route.h Unused. Unused. The metric value associated with the route. This is used to indicate the cost or priority of a route. In combination with the Destination field, this specifies which datagrams will match this route. Specifies the largest TCP segment (in bytes) that will be built for transmission via this route. Specifies the TCP window (in bytes) that will be advertised for TCP connections made via this route. Specifies the Initial Round Trip time (in milliseconds) that will be used for TCP connections established via this route.
Flags RefCnt Use Metric Mask MTU Window IRTT
The /proc/net/snmp file exports protocol statistics. It may be used for performance analysis purposes or by a SNMP (Simple Network Management Protocol) daemon program
17/62
User-space APIs
UM0479
(not provided with SDK). It reports summary statistics for each of the IP, ICMP, TCP, and UDP protocols. Ver y detailed access to networking information may be finally achieved using the /proc/sys/net subtree.
4.3
General-purpose input/output (GPIO)
The SPEAr Plus chip has internally 3 General-Purpose I/O (GPIO) digital blocks, each of them provided with 8 lines, for a total of 24 lines. However, only 10 GPIO lines are made available by the chip as external pins: four of them are connected to a dip switch (SW3) on the development board, so that they may be easily read from software for any custom purpose; other two of them are controlling corresponding yellow and green LEDs. Finally, all of the 10 exposed lines are also available on the J19 (GPIO) connector. The following table provides a summary of available GPIO lines: Table 6. GPIO assignment
Block GPIO 0 GPIO 0 GPIO 0 GPIO 0 GPIO 0 GPIO 0 GPIO 0 GPIO 0 GPIO 1 GPIO 1 Line 0 1 2 3 4 5 6 7 0 1 Dev.board Switch SW3 1 and J19 connector Switch SW3 2 and J19 connector Switch SW3 3 and J19 connector Switch SW3 4 and J19 connector Yellow LED (D5) and J19 connector Green LED (D6) and J19 connector J19 connector J19 connector J19 connector J19 connector
SoC subsystem Application Application Application Application Application Application Application Application Basic Basic
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 userspace 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 userspace API provides the interfaces described in the following. Each block is identified by a specific enumeration constant: typedef enum { GPIO0, GPIO1, GPIO2, GPIO_NONE } t_GPIOId;
18/62
UM0479 The eight pins inside a block are identified through bit masks: #define #define #define #define #define #define #define #define #define GPIO_PIN00x0 0 0001 GPIO_PIN10x0 0 0002 GPIO_PIN20x0 0 0004 GPIO_PIN30x0 0 0008 GPIO_PIN40x0 0 0010 GPIO_PIN50x0 0 0020 GPIO_PIN60x0 0 0040 GPIO_PIN70x0 0 0080 GPIO_ALLPINS0x0 0 00FF
User-space APIs
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; t_GPIODir PinDir; } PinInfo; t_GPIOId GPIOId; uint PinMask; } t_GPIOPinInfo;
// SET, RESET // IN, OUT // GPIO0, GPIO1, GPIO2 // see bitmasks above
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, GPIO_NOT_AN_OUTPUT_PIN, GPIO_NOT_AN_INPUT_PIN, GPIO_INVALID_PARAMETER, GPIO_PIN_NOT_AN_INTERRUPT_LINE, GPIO_PIN_NO_INT_HANDLER_REGISTERED, GPIO_INVALID_INTERRUPT_HANDLER, GPIO_PIN_NOT_IN_SOFTWARE_MODE, GPIO_UNKNOWN_ERROR } t_GPIOError;
// not used in user-space
// // // //
not not not not
used used used used
in in in in
user-space user-space user-space user-space
In order to configure pins, the ioctl() system call is used.
19/62
User-space APIs
UM0479
In order to configure the direction of one or more pin for a specified block, the ioctl() call is invoked with a GPIOIOC_DIRSET request parameter and a pointer to a t_GPIOPinInfo structure initialized with block, pin mask of pins to be changed and chosen direction. Example: int dev; t_GPIOPinInfo info; t_GPIOError result; dev = open("/dev/gpio ",O_RDWR); info.GPIOId = GPIO0; // specify block info.PinMask = GPIO_PIN0 + GPIO_PIN1; // select 2 pins in the mask info.PinInfo.PinDir = IN; // set to input result = ioctl(dev,GPIOIOC_DIRSET,&info); if (result != GPIO_OK) { printf("Error\n"); } close(dev); In order to query the current direction of one or more pin for a specified block, the ioctl() call is used with a GPIOIOC_DIRGET request parameter and a pointer to a t_GPIOPinInfo structure initialized with block identifier and pin mask of pins to be queried. Example: int dev; t_GPIOPinInfo info; t_GPIOError result; dev = open("/dev/gpio",O_RDWR); info.GPIOId = GPIO0; // specify block info.PinMask = GPIO_PIN0 + GPIO_PIN1; // select 2 pins in the mask result = ioctl(dev,GPIOIOC_DIRGET,&info); if (result != GPIO_OK) { printf("Error"); } else { if ((info.PinInfo.PinDir & GPIO_PIN0)==IN) { printf("Block 0, Pin 0 direction is input\n"); } else { printf("Block 0, Pin 0 direction is output\n"); } if ((info.PinInfo.PinDir & GPIO_PIN1)==IN) { printf("Block 0, Pin 1 direction is input\n"); } else { printf("Block 0, Pin 1 direction is output\n"); } } close(dev); It is also possible to restore all pins of a specified block to default settings using the ioctl() call with a GPIOIOC_CONFIGDEFAULT request. Example: int dev; t_GPIOPinInfo info;
20/62
UM0479 t_GPIOError result; dev = open("/dev/gpio",O_RDWR); info.GPIOId = GPIO0; // specify block result = ioctl(dev,GPIOIOC_CONFIGDEFAULT,&info); if (result != GPIO_OK) { printf("Error"); } close(dev);
User-space APIs
With default settings, all pins have input direction and interrupts are edge-triggered and disabled. In order to change the value of one or more GPIO pins for a specified block, the write() system call is used. The passed structure specifies the operation (RESET or SET). Example: int dev; t_GPIOPinInfo info; t_GPIOError result; dev = open("/dev/gpio",O_RDWR); info.GPIOId = GPIO0; // specify block info.PinMask = GPIO_PIN0 + GPIO_PIN1; // select 2 pins in the mask info.PinInfo.PinVal = RESET; // set pins to zero result = write(dev,&info,sizeof(info)); if (result != GPIO_OK) { printf("Error"); } close(dev); In order to read the value of one or more GPIO pins for a specified block, the read() system call is used. On call return, the values for the specified pins are stored as bit pattern in the PinVal field. Example: int dev; t_GPIOPinInfo info; t_GPIOError result; dev = open("/dev/gpio",O_RDWR); info.GPIOId = GPIO0; // specify block info.PinMask = GPIO_PIN0 + GPIO_PIN1; // select 2 pins in the mask result = read(dev,&info,sizeof(info)); if (result != GPIO_OK) { printf("Error"); } else { info.PinInfo.PinVal = RESET; // set pins to zero if ((info.PinInfo.PinVal & GPIO_PIN0)==RESET) { printf("Block 0, Pin 0 value is zero\n"); } else { printf("Block 0, Pin 0 value is one\n"); } if ((info.PinInfo.PinVal & GPIO_PIN1)== RESET) { printf("Block 0, Pin 1 value is zero\n"); } else { printf("Block 0, Pin 1 value is one\n"); } } close(dev);
21/62
User-space APIs
UM0479
4.4
Display
A device driver for the SPEAr Plus graphics display controller (CLCDC) and the relevant user-space API shall be provided in future SDK releases. Such API shall be compatible with the Linux frame buffer standard.
4.5
I2C bus and EEPROM
I2C is a serial, 2-wire, master-slave protocol for inter-device hardware interface. The SPEAr Plus I2C bus controller is accessed by user-space applications by means of a device named: /dev/i2c Current implementation only works in master mode and using a polling scheme. User-space applications must include the drivers/i2c/busses/spr_i2c_syn.h header file. In addition to the standard and generic open() and close() routines, the I2C user-space API provides the interfaces described in the following. Error handling is performed according to the following definition: typedef enum { I2C_OK = 0, I2C_FAIL, I2C_INVALID_ADDRESS, I2C_RX_BUFFER_NULL, I2C_NO_RX_DATA, I2C_TX_BUFFER_NULL, I2C_NO_TX_DATA, I2C_OFFSET_ERROR, I2C_TX_FIFO_NOT_EMPTY } t_I2CError; The configuration to interface a specific slave device is performed by a ioctl() call like: t_I2C_Configure cfg; ... result = ioctl(dev,I2CIOC_CONFIG,&cfg); where the following definitions are assumed from the header file: typedef enum { SEVEN_BIT_ADDRESSING,// 7-bit addresses (the most common) TEN_BIT_ADDRESSING// 10-bit addresses } t_I2C_addressing_mode; typedef enum { IC_SPEED_MODE_STANDARD,// 100 Kbps IC_SPEED_MODE_FAST,// 400 Kbps (the most common) IC_MAX_SPEED// 3.4 Mbps } t_I2C_speed; typedef struct { u32 SlaveAddress;// address of slave u32 slave_offset;// offset
22/62
UM0479
User-space APIs t_I2C_control_mode mode; // must be I2C_MASTER_MODE t_I2C_addressing_mode operation; // 7 or 10 bit addresses t_I2C_tar_update tar_update;// currently unused t_I2C_command FirstByte;// currently unused t_I2C_transfer_mode TransferMode;// currently unused t_I2C_speedSpeed; } t_I2C_Configure; Data may be written to the slave device according to current configuration, set by ioctl() as described above, by using a standard write() call. Data may be read from the slave device according to current configuration, set by ioctl() as described above, by using a standard read() call. The specific byte-level protocol to be used in read() and write() calls is slave-dependent. One common use of I2C bus interface is to access EEPROM memory devices. The SPEAr Plus development board includes an EEPROM memory at I2C slave address 0x50. The following example shows how to access the I2C controller and then how to write and read back a specific byte location on the EEPROM: Example: int dev; t_I2C_Configure cfg; t_I2CError result; char data_out[1]; char data_in[1]; int n; // open I2C controller device dev = open("/dev/i2c",O_RDWR); // configure I2C for access to EEPROM cfg.SlaveAddress = 0x50; // EEPROM slave address cfg.slave_offset = 0x08; // location = ninth cell cfg.mode = I2C_MASTER_MODE; cfg.operation = SEVEN_BIT_ADDRESSING; cfg.Speed = IC_SPEED_MODE_FAST; result = ioctl(dev,I2CIOC_CONFIG,&cfg); if (result != I2C_OK) { /* error handling */ } // write 1 byte to EEPROM location 8 data_out[0] = 0xA5; n = write(dev,data_out,1); if (n!=1) { /* error handling */ } // read back 1 byte from EEPROM location 8 n = read(dev,data_in,1); if (n!=1) { /* error handling */ } // close I2C controller device close(dev);
4.6
Inter-processor communication (IPC)
A device driver for managing communication between the main CPU (running Linux) and the slave CPU (for dual-core scenarios) as well as the relevant user-space API shall be provided in future SDK releases.
23/62
User-space APIs
UM0479
4.7
JPEG codec
A device driver for the SPEAr Plus JPEG hardware codec and the relevant user-space API shall be provided in future SDK releases.
4.8
Real-time clock (RTC)
The Real-Time Clock (RTC) device maintains "wall-clock" date and time information and is intended to be provided with a battery backup so that date/time is kept even when the system is switched off and automatically restored by the Linux kernel at each bootstrap.
Note:
on some early SPEAr Plus development boards, battery backup may be not available; in this case, wall clock time will be preserved in case of reset but not in case of power off. The hwclock command utility may be invoked from the shell console in order to change the RTC settings from current system time or update system time from current RTC value. The RTC is accessed by user-space applications by means of a character device named: /dev/rtc User-space applications must include the linux/rtc.h header file. In addition to the standard and generic open() and close() routines, the RTC user-space API provides the ioctl() operations as described in the following. Successful calls return 0. A negative value is returned in case of errors. Common definitions are: struct rtc_time { int tm_sec;// seconds (0-59) int tm_min;// minutes (0-59) int tm_hour;// hours (0-23) int tm_mday;// day of month (0-30) int tm_mon;// month (0-11) int tm_year;// year, 0-based, since 1900 int tm_wday;// not used int tm_yday; // not used int tm_isdst; // not used }; The current RTC date and time may be changed with RTC_SET_TIME ioctl() request as in the following example: Example : int dev; struct rtc_time info; dev = open("/dev/rtc",O_RDWR); // set date and time to December 27, 1964 15:09:00 info.tm_mday = 26; info.tm_mon = 11 info.tm_year = 64; info.tm_hour = 15; info.tm_min = 9; info.tm_sec = 0;
24/62
UM0479
User-space APIs result = ioctl(dev,RTC_SET_TIME,&info); if (result) { printf("Error"); } close(dev); The current RTC date and time may be read with RTC_RD_TIME ioctl() request as in the following example: Example: int dev; struct rtc_time info; dev = open("/dev/rtc",O_RDWR); result = ioctl(dev,RTC_RD_TIME,&info); if (result) { printf("Error"); } else { printf("%02d/%02d/%04d %02d:%02d:%02d\n", info.tm_mday+1,info.tm_mon+1,1900+info.tm_year, info.tm_hour,info.tm_min,info.tm_sec); close(dev); The read() and write() functions are not used.
4.9
Slave CPU control
A device driver for booting a software image on the slave CPU and starting/halting its execution, as well as the relevant user-space API, shall be provided in future SDK releases.
4.10
Synchronous serial ports (SSPs)
A device driver for the three SPEAr Plus synchronous serial ports (SSP) and the relevant user-space API shall be provided in future SDK releases.
4.11
Asynchronous serial ports (UARTs)
Two UART ports are available on SPEAr Plus development board. UART0 is accessible through a standard DB9 connector. UART1 is accessible only through an auxiliary connector requiring a different cabling. Both UARTs are accessed from user-space applications through character devices named, respectively: /dev/ttyS0 /dev/ttyS1 SPEAr UARTs only provide 2 wires. There are no hardware flow control lines or modemspecific support. Software flow control (XON/XOFF) support will be provided in future releases. The UART driver works in interrupt mode and exploits hardware FIFO queues. The default configuration is 115200 bps, 8 data bits, 2 stop bits, even parity and no software flow control.
25/62
User-space APIs User-space applications have to include only standard I/O header files.
UM0479
All the standard open(), close(), read() and write() functions may be invoked in the usual way. Por t configuration is performed using a standard Linux structure equivalent to the following definition: struct termios { unsigned short c_iflag;/* input mode flags */ unsigned short c_oflag;/* output mode flags */ unsigned short c_cflag;/* control mode flags */ unsigned short c_lflag;/* local mode flags */ unsigned char c_line;/* line discipline */ unsigned char c_cc[NCC]; /* control characters */ }; The most important field is c_cflag. Usually only the bitrate needs to be specified. Macros for common bitrates supported by the driver are as follows: B1200, B2400, B4800, B9600, B19200, B38400, B57600, B115200, B230400, B460800 Since SPEAr UARTs are mainly used for development and testing purposes, the other subfields are usually set to 8 data bits (CS8 macro), 1 stop bit, no parity. It is usually recommended to retrieve first current settings using the tcgetattr() function and then change only required fields using the tcsetattr() function as shown below: Example : int dev; int result; int n; char buffer[10]; struct termios config; dev = open("ttyS1",O_RDWR); if (dev == -1) { /* error handling */ } // get default settings result = tcgetattr(dev,&config); if (result < 0) { /* error handling */ } // reconfigure for 57600 bps, 8 data bits, 1 stop bit, no parity config.c_cflag = B57600 | CS8; result = tcsetattr(dev,TCSANOW,&config); // write 4 bytes n = write(dev, "test",4); if (n < 0) { /* error handling */ } // read 2 bytes n = read(dev,buffer,2); if (n < 0) { /* error handling */ } close(dev);
26/62
UM0479
User-space APIs
4.12
USB device (gadget filesystem)
The exploitation of SPEAr Plus development boards as USB devices is strongly applicationdependent. For instance, the board's software may be designed to operate as a USBcontrollable 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 /dev/sdb /dev/sdc /dev/sdd (also (also (also (also accessible accessible accessible accessible as as as as /dev/sda1) /dev/sdb1) /dev/sdc1) /dev/sdd1)
It should be noted that, since only 2 USB host connectors are available, the use of up to 4 devices will require an external USB hub. Of course, the USB mass storage driver included by the SDK in the default kernel configuration is just an example of class driver that can be added to manage a specific kind of USB peripheral. Other predefined class drivers may be found inside the Linux kernel source tree, while not enabled by default. Each class driver will provide its own user-space API.
27/62
User-space APIs
UM0479
Finally, custom class drivers could be developed in user-space. In this case, the class driver will directly interface with the USB host protocol stack through a user-space API based on the so-called USB filesystem (usbfs). A possible application of this scenario is to implement, in user-space, the USB Still Imaging Class and the corresponding PTP (Picture Transfer Protocol) protocol. Similar to the /proc/net pseudo file tree supported for Ethernet, there is a /proc/bus/usb logical subtree for USB. On SPEAr Plus boards, the /proc/bus/usb/devices logical file reports information about four USB host controllers: Bus Bus Bus Bus 01USB 02USB 03USB 04USB Host Host Host Host Port Port Port Port 1 2 1 2 (EHCI, (EHCI, (OHCI, (OHCI, USB USB USB USB 2.0) 2.0) 1.1) 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
Description 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. 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. Argument
IOCTL request
USBDEVFS_BULK
Request details, a pointer to following structure: struct usbdevfs_bulktransfer { unsigned int ep; unsigned int len; unsigned int timeout; void *data; };
USBDEVFS_ CLAIMINTERFACE
Interface number: unsigned int
28/62
UM0479 Table 7. USB filesystem ioctl requests (continued)
Description
User-space APIs
IOCTL request
Argument
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 Endpoint number: input endpoints. This call must unsigned int be used on bulk or interrupt endpoints which have stalled, returning -EPIPE status to a data transfer request. Do not issue the control request directly, since that could invalidate the host's record of the data toggle. Connect to opened device. 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. None (ignored)
USBDEVFS_ CONNECT
USBDEVFS_ CONNECTINFO
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 A pointer to following structure: struct usbdevfs_ctrltransfer { to the device. The "bRequestType" field is __u8 bRequestType; composed by combining a __u8 bRequest; USB_TYPE_* value, a __u16 wValue; USB_DIR_* value, and a __u16 wIndex; USB_RECIP_* value (as defined __u16 wLength; in ). The "wLength" __u32 timeout; field specifies the size of the block to be transferred. The void __user *data; maximum transfer size is 4 KB. }; Timeout is specified in ms. The "data" field is a pointer to the input or output buffer. Disconnect from opened device. None (ignored)
USBDEVFS_ DISCONNECT
29/62
User-space APIs Table 7. USB filesystem ioctl requests (continued)
Description Argument
UM0479
IOCTL request
USBDEVFS_ GETDRIVER
A pointer to following structure: struct usbdevfs_getdriver { Returns the name (string) of the unsigned int interface; kernel driver bound to the char driver specified interface. [USBDEVFS_MAXDRIVERNAME+1]; }; Sends a request from userspace to a kernel driver that has A pointer to following structure: an ioctl entry in the struct struct usbdevfs_ioctl { usb_driver it registered. int ifno; The "ifno" field is the selected int ioctl_code; interface number. The void *data; "ioctl_code" contains the ioctl }; request. The "data" field is a pointer to the ioctl argument. Interface number: unsigned int
USBDEVFS_IOCTL
Releases a claimed interface, USBDEVFS_ whose number specified by the RELEASEINTERFACE argument.
USBDEVFS_RESET
Resets the opened USB device. After the reset, this call rebinds all device interfaces. Linux None (ignored) documentation currently discourages the use of this call. Resets the data toggle value for a bulk or interrupt endpoint to DATA0. The endpoint number (15 with USB_DIR_IN mask added Endpoint number: for input endpoints) is specified unsigned int by the input argument. . Linux documentation currently discourages the use of this call. Configuration number: unsigned int A pointer to following structure: struct usbdevfs_setinterface { unsigned int interface; unsigned int altsetting; };
USBDEVFS_ RESETEP
Sets the configuration for the USBDEVFS_ opened device. Linux SETCONFIGURATION documentation currently discourages the use of this call.
USBDEVFS_ SETINTERFACE
Sets the alternate setting for a specified interface.
4.14
Watchdog timer (WDT)
A device driver for the SPEAr Plus hardware watchdog timer (WDT) and the relevant userspace API shall be provided in future SDK releases.
30/62
UM0479
Kernel-space APIs
5
Kernel-space APIs
The APIs to access SPEAr Plus devices from kernel-space software are described in the following sections. Direct function calls are made in this case, since static or dynamic linking of the relevant device drivers with client software is assumed. A standard Linux API is exploited wherever applicable (USB host and device frameworks). In all other cases an ST-specific API has been defined. It should be noted that kernel-space APIs are exposed only for devices that actually require this access level. For instance, there is no need to expose a kernel-space API for graphics display, JPEG codec, real-time clock and slave CPU control. Moreover, the Ethernet driver is designed to be integrated in the Linux networking framework. Therefore, it only exposes interfaces to that framework and not to other kernelspace subsystems (most driver functions are static, hence private). Likewise, the UART driver is designed to be integrated in the Linux serial port framework. Therefore, it only exposes interfaces to that framework and not to other kernel-space subsystems. For this reason, no specific kernel APIs for Ethernet and UARTs are documented in this section.
5.1
A/D converter (ADC)
A device driver for the SPEAr Plus A/D Converter (ADC) and the relevant kernel-space API shall be provided in future SDK releases.
5.2
Direct memory access (DMA)
DMA is a hardware mechanism to automatically and efficiently perform data transfers on a bus without involving the CPU. Sources and sinks of a transfer may be peripherals as well as memory devices. DMA is typically used in the implementation of some drivers in kernel-space. Therefore, no user-space API is made available. The SPEAr Plus devices supporting DMA through the general-purpose DMA controller are referenced through the following enumeration:
typedef enum { MEMORY_DMA_DEVICE, SPI_2_IN_DMA_DEVICE,// SPI not supported in SDK 1.1 SPI_2_OUT_DMA_DEVICE, // SPI not supported in SDK 1.1 UART_1_IN_DMA_DEVICE,// UART only supported in interrupt mode in SDK 1.1 UART_1_OUT_DMA_DEVICE,// UART only supported in interrupt mode in SDK 1.1 UART_2_IN_DMA_DEVICE,// UART only supported in interrupt mode in SDK 1.1 UART_2_OUT_DMA_DEVICE,// UART only supported in interrupt mode in SDK 1.1 SPI_3_IN_DMA_DEVICE, // SPI not supported in SDK 1.1 SPI_3_OUT_DMA_DEVICE, // SPI not supported in SDK 1.1 SPI_1_IN_DMA_DEVICE, // SPI not supported in SDK 1.1 SPI_1_OUT_DMA_DEVICE, // SPI not supported in SDK 1.1 I2C_IN_DMA_DEVICE, // I2C only supported in polling mode in SDK 1.1 I2C_OUT_DMA_DEVICE, // I2C only supported in polling mode in SDK 1.1 IRDA_DMA_DEVICE, // IRDA not supported in SDK 1.1 JPEG_IN_DMA_DEVICE, // JPEG not supported in SDK 1.1 JPEG_OUT_DMA_DEVICE, // JPEG not supported in SDK 1.1
31/62
Kernel-space APIs
LAST_DMA_DEVICE } t_DMADeviceId;
UM0479
It should be pointed out that some on-chip peripherals such as Ethernet and USB use their own dedicated DMA support. In addition, the MEMORY_DMA_DEVICE value may be used for generic transfer including peripherals since they are memory-mapped. Error handling is managed by API functions through return values according to the following definition: typedef enum { DMA_OK, // successful call DMA_INVALID_BURST_SIZE, DMA_INVALID_ACCESS_WIDTH, DMA_INVALID_PROTECTION, DMA_INVALID_CHANNEL_ID, DMA_INVALID_INT_HANDLER, DMA_INCORRECT_FLOW_CONTROLLER, DMA_INVALID_DEVICE_ID, DMA_INVALID_PRIORITY, DMA_INVALID_PARAMETER, DMA_INCOMPATIBLE_DMA_DEVICE, DMA_NO_MORE_LLIS_AVAILABLE, DMA_NO_MORE_HW_CHANNELS_AVAILABLE, DMA_NO_INT_ACTIVE, DMA_TRANSFER_OVER, DMA_TRANSFER_ONGOING, DMA_INCOMPATIBLE_TRANSFER_SIZE, DMA_INCOMPATIBLE_BUFFER_SIZE, DMA_DEVICE_CANT_BE_FLOWCTRL, DMA_INVALID_FLOW_CONTROLLER, DMA_CONTROLLER_NOT_INITIALIZED, DMA_NULL_POINTER, DMA_MISALLIGNED_ADDRESS, DMA_ERROR } t_DMAError; The DMA Kernel API functions are listed in the following. Basically, the DMA controller must be first initialized. Specific source or destination devices may be also configured. Then data transfers may be started with optional user-defined callback routines to be invoked when the each transfer is terminated. If required, DMA transfers may be also suspended, resumed or aborted before normal completion. It is important to remind that DMA operates with physical rather than virtual addresses.
Function:
t_DMAError SPEAr_DMA_SetConfigDevice t_DMADeviceId DeviceId, t_DMAAccessWidth AccessWidth, t_DMABurstSize MaxBurstSize, t_DMAProtection Protection, t_bool CanBeFlowController) Sets the configuration of a DMA-capable device.
Description:
32/62
UM0479 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;
Kernel-space APIs
CanBeFlowController (in): If true, the device may be the flow controller.
Function:
t_DMAError SPEAr_DMA_GetConfigDevice( t_DMADeviceId DeviceId, t_DMAAccessWidth *AccessWidth, t_DMABurstSize *MaxBurstSize, t_DMAProtection *Protection, t_bool *CanBeFlowController);
33/62
Kernel-space APIs Description: Arguments: Gets the configuration of a DMA-capable device. DeviceId (in): Device for which configuration is obtained. AccessWidth (out): Access width of device (see SPEAr_DMA_SetConfigDevice for values).
UM0479
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); Transfers data from source to destination. The selected DMA channel for the transfer is returned. TransferDesc (in): Defines the details of the requested transfer using the following data structure: typedef struct { t_DMADeviceId SrcDeviceId; // source t_DMADeviceId DestDeviceId; // destination uint SrcAddress; // source address uint DestAddress; // destination address uint TransferSize; // size in bytes of transfer t_DMAFlowCtrl FlowController; // flow type t_DMATransferPriority Priority;// priority of DMA transfer t_bool IsIntReqAfterEachPacketTransfer; // interrupt required // after each LLI transfer ? t_DMAIntHandler HandlerPtr; // interrupt handler for // end of transfer } t_DMATransferDesc; The available flow types are defined as follows: typedef enum { DMA_MEMORY_TO_MEMORY, DMA_MEMORY_TO_PERIPHERAL, DMA_PERIPHERAL_TO_MEMORY, DMA_PERIPHERAL_TO_PERIPHERAL, DEST_PERIPHERAL_TO_PERIPHERAL, DEST_MEMORY_TO_PERIPHERAL, SRC_PERIPHERAL_TO_MEMORY,
Description: Arguments:
34/62
UM0479 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 .
Kernel-space APIs
Function: Description: Arguments:
t_DMAError SPEAr_DMA_HaltTransfer(t_DMAChannelId ChannelId); Suspends a transfer on specified DMA channel. ChannelId (in): Target channel number as obtained when starting the transfer.
Function: Description: Arguments:
t_DMAError SPEAr_DMA_ResumeTransfer(t_DMAChannelId ChannelId); Resumes a suspended transfer on specified DMA channel. ChannelId (in): Target channel number as obtained when starting the transfer.
Function:
t_DMAError SPEAr_DMA_AbortTransfer( t_DMAChannelId ChannelId, t_bool DataCanBeLost); Abor ts ongoing transfer on specified DMA channel. ChannelId (in): Target channel number as obtained when starting the transfer.
Description: Arguments:
35/62
Kernel-space APIs DataCanBeLost (in): If true, the channel is directly disabled and any data in the DMA FIFO is lost.
UM0479
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); Sets the direction or one or more pins for the specified block. GPIOId (in): Block index. Dir (in): Direction. Mask (in): Bitmask defining the pins for which the direction must be changed.
Description: Arguments:
Function:
t_GPIOError SPEAr_GPIO_DirGet( t_GPIOId GPIOId, t_GPIODir* Dir, uint Mask); Gets the direction or one or more pins for the specified block. GPIOId (in): Block index. Dir (out): Direction. Mask (in): Bitmask defining the pins for which the direction is obtained.
Description: Arguments:
Function:
t_GPIOError SPEAr_GPIO_ValSet( t_GPIOId GPIOId, t_GPIOValue Val, uint Mask);
36/62
UM0479 Description: Arguments: Sets the value or one or more pins for the specified block. GPIOId (in): Block index. Val (in): Value. Mask (in): Bitmask defining the pins for which the value must be changed.
Kernel-space APIs
Function:
t_GPIOError SPEAr_GPIO_ValGet( t_GPIOId GPIOId, t_GPIOValue* Val, uint Mask); Gets the value or one or more pins for the specified block. GPIOId (in): Block index. Val (out): Value. Mask (in): Bitmask defining the pins for which the value must be obtained.
Description: Arguments:
Function:
t_GPIOError SPEAr_GPIO_EdgeConfig( t_GPIOId GPIOId, t_GPIOIntEdgeConfig IntEdge, t_GPIOIntSingleEdgeConfig IntSingleEdge, uint Mask); Configures the interrupt triggering mode of one or more pins for the specified block. GPIOId (in): Block index. IntEdge (in): Single or both edge according to following definition: typedef enum { SINGLE_EDGE, BOTH_EDGE} t_GPIOIntEdgeConfig; IntSingleEdge (in): Single edge type according to following definition: typedef enum { FALLING_EDGE, RISING_EDGE,
Description: Arguments:
37/62
Kernel-space APIs NONE } t_GPIOIntSingleEdgeConfig; Mask (in): Bitmask defining the pins for to be configured.
UM0479
Function:
t_GPIOError SPEAr_GPIO_LevelConfig( t_GPIOId GPIOId, t_GPIOIntLevelConfig IntLevel, uint Mask); Configures the interrupt triggering level mode of one or more pins for the specified block. GPIOId (in): Block index. IntLevel (in): Level according to following definition: typedef enum { LOW_LEVEL, HIGH_LEVEL} t_GPIOIntLevelConfig; Mask (in): Bitmask defining the pins for to be configured.
Description: Arguments:
Function: Description: Arguments:
t_GPIOError SPEAr_GPIO_IntEnable(t_GPIOId GPIOId, uint Mask); Enables interrupts for one or more pins for the specified block. GPIOId (in): Block index. Mask (in): Bitmask defining the pins for which interrupts must be enabled.
Function: Description: Arguments:
t_GPIOError SPEAr_GPIO_IntDisable(t_GPIOId GPIOId, uint Mask); Disables interrupts for one or more pins for the specified block. GPIOId (in): Block index. Mask (in): Bitmask defining the pins for which interrupts must be disabled.
38/62
UM0479 Function: t_GPIOError SPEAr_GPIO_BindIntHandler( t_GPIOId GPIOId, uint Mask, t_GPIOIntHandler Handler);
Kernel-space APIs
Description: Arguments:
Installs an interrupt handler for one or more pins for the specified block. GPIOId (in): Block index. Mask (in): Bitmask defining the pins for which interrupts must be disabled. Handler (in): Pointer to user-defined callback function to be invoked on interrupt occurrence. Such handler must be defined according to following signature: typedef void (*t_GPIOIntHandler)(void);
Function: Description: Arguments:
t_GPIOError SPEAr_GPIO_ConfigDefault(t_GPIOId GPIOId); Restore default configuration for the specified block. GPIOId (in): Block index.
5.4
I2C bus
The I2C kernel-space API reflects the same operations provided through ioctl(I2CIOC_CONFIG), read() and write() by the user-space API.
Function: Description: Arguments:
SPEAR_I2C_ConfigureUpdate(t_I2C_Configure *config) Configure I2C controller according to a specific slave device to be interfaced. config (in): Structure defining the required configuration (see user-space API for details).
Function: Description: Arguments:
SPEAR_I2C_Receive(char *RxBuffer, unsigned long NoOfBytes) Read the specified number of bytes from the current I2C slave device previously set in the configuration. RxBuffer (out): Destination buffer for the received data.
39/62
Kernel-space APIs Function: Description: Arguments:
UM0479
SPEAR_I2C_Transmit(char *TxBuffer, unsigned long NoOfBytes) Write the specified number of bytes to the current I2C slave device previously set in the configuration. TxBuffer (in): Source buffer for the transmitted data.
5.5
Inter-processor communication (IPC)
A device driver for managing communication between the main CPU (running Linux) and the slave CPU (for dual-core scenarios) as well as the relevant kernel-space API shall be provided in future SDK releases.
5.6
Synchronous serial ports (SSPs)
A device driver for the three SPEAr Plus synchronous serial ports (SSP) and the relevant kernel-space API shall be provided in future SDK releases.
5.7
USB device (gadget framework)
A standardized API is defined by Linux for kernel-space access to the USB device stack. This software interface is known as "gadget framework" and is defined inside the include/linux/usb_gadget.h header file. A gadget driver is an handler for the USB device port performing some specific function. An example of simple and generic gadget driver is provided by the so-called "Gadget Zero" that can be found under path: splus_linux_sdk_1_1\linux-2.6.19.2\drivers\usb\gadget\zero.c
5.7.1
Gadget driver management
A gadget driver has to be defined through the following data structure: struct usb_gadget_driver { char* function; enum usb_device_speed speed; int (*bind)(struct usb_gadget *); void (*unbind)(struct usb_gadget *); int (*setup)(struct usb_gadget*,const struct usb_ctrlrequest *); void (*disconnect)(struct usb_gadget *); void (*suspend)(struct usb_gadget *); void (*resume)(struct usb_gadget *); struct device_driver driver; }; where the fields have the following meanings:
40/62
UM0479 Table 8. Gadget driver structure fields
Field function speed Description String describing the gadget's function. Highest speed the driver handles.
Kernel-space APIs
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. Pointer 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. 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. 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. Pointer to custom callback function invoked on USB suspend. May be called in_interrupt. Pointer to custom callback function invoked on USB resume. May be called in_interrupt. Driver model state for this driver.
unbind
setup
disconnect
suspend resume driver
All callbacks receive a standard argument defined as a pointer to the following structure: struct usb_gadget { const struct usb_gadget_ops *ops; struct usb_ep *ep0; struct list_head ep_list; enum usb_device_speed speed; unsigned is_dualspeed:1; unsigned is_otg:1; unsigned is_a_peripheral:1; unsigned b_hnp_enable:1; unsigned a_hnp_support:1; unsigned a_alt_hnp_support:1; const char *name; struct device dev; }; where the fields have the following meanings:
41/62
Kernel-space APIs Table 9. Gadget structure fields
Field ops ep0 ep_list speed dualspeed is_otg Description Function pointers used to access hardware-specific operations.
UM0479
Endpoint zero, used when reading or writing responses to driver setup() requests. List of other endpoints supported by the device. Speed of current connection to USB host. True if the controller supports both high and full speed operation. If it does, the gadget driver must also support both. True if the USB device port uses a Mini-AB jack, so that the gadget driver must provide a USB OTG descriptor. False 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. OTG device feature flag, indicating that the A-Host enabled HNP support. OTG device feature flag, indicating that the A-Host supports HNP at this port. OTG device feature flag, indicating that the A-Host only supports HNP on a different root port. Identifies the controller hardware type. Used in diagnostics and sometimes configuration. Driver model state for this abstract device.
is_a_peripheral b_hnp_enable a_hnp_suppor t a_alt_hnp_suppor t name dev
The kernel API functions available for gadget driver management are as follows:
Function: Description: Arguments:
int usb_gadget_register_driver(struct usb_gadget_driver *driver); Registers a driver with the USB device stack. This is usually invoked in a module initialization function (defined by module_init macro). driver (in): Pointer to the driver structure.
Function: Description: Arguments:
int usb_gadget_unregister_driver(struct usb_gadget_driver *driver); Unregisters a driver from the USB device stack. This is usually invoked in a module termination function (defined by module_exit macro). driver (in): Pointer to the driver structure.
42/62
UM0479 Function: Description: Arguments:
Kernel-space APIs int usb_gadget_connect(struct usb_gadget *gadget); Connects to USB host. driver (in): Pointer to the driver structure.
Function: Description: Arguments:
int usb_gadget_disconnect(struct usb_gadget *gadget); Disconnects from USB host. driver (in): Pointer to the driver structure.
Function: Description: Arguments:
int usb_gadget_set_selfpowered(struct usb_gadget *gadget); Sets the device self-powered feature. driver (in): Pointer to the driver structure.
Function: Description: Arguments:
int usb_gadget_clear_selfpowered(struct usb_gadget *gadget); Clears the device self-powered feature. driver (in): Pointer to the driver structure.
Function: Description: Arguments:
int usb_gadget_vbus_connect(struct usb_gadget *gadget); Notifies device controller that VBUS is powered. driver (in): Pointer to the driver structure.
Function: Description: Arguments:
int usb_gadget_vbus_disconnect(struct usb_gadget *gadget); Notifies controller about VBUS end session. driver (in): Pointer to the driver structure.
43/62
Kernel-space APIs Function: Description: Arguments:
UM0479
int usb_gadget_vbus_draw(struct usb_gadget *gadget, unsigned mA); Constrains controller's VBUS power usage. driver (in): Pointer to the driver structure. mA (in): Current to draw, in milliAmperes.
Function: Description: Arguments:
int usb_gadget_wakeup(struct usb_gadget *gadget); Tries to wake up the host connected to this gadget. driver (in): Pointer to the driver structure.
5.7.2
Endpoint management
The second and third fields (ep0 and ep_list) of the USB_gadget structure are the representation of USB device endpoints. The relevant structure includes the following fields: struct usb_ep { void *driver_data; const char *name; const struct usb_ep_ops *ops; struct list_head ep_list; unsigned maxpacket:16; }; where the fields have the following meanings: Table 10. Endpoint structure fields
Description For use by the gadget driver, all other fields are read-only to gadget drivers. Identifier for the endpoint, such as ep-a or ep9in-bulk" Function pointers used to access hardware-specific operations. The 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. The 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.
Field driver_data name ops ep_list
maxpacket
A wide set of functions is available to manage endpoints, all of them getting as first argument a pointer to the specified endpoint structure:
44/62
UM0479 Function: int usb_ep_enable( struct usb_ep *ep, const struct usb_endpoint_descriptor *desc); Enables specified endpoint, passing a descriptor. ep (in): Pointer to endpoint structure. desc (in): Pointer to endpoint descriptor.
Kernel-space APIs
Description: Arguments:
Function: Description: Arguments:
int usb_ep_disable(struct usb_ep *ep); Disables specified endpoint. ep (in): Pointer to endpoint structure.
Function: Description: Arguments:
void usb_ep_fifo_flush(struct usb_ep *ep); Flushes the FIFO of specified endpoint. ep (in): Pointer to endpoint structure.
Function: Description: Arguments:
int usb_ep_fifo_status(struct usb_ep *ep); Queries the status of the FIFO of specified endpoint. ep (in): Pointer to endpoint structure.
Function: Description: Arguments:
int usb_ep_set_halt(struct usb_ep *ep); Sets the halt feature of specified endpoint. ep (in): Pointer to endpoint structure.
Function: Description:
int usb_ep_clear_halt(struct usb_ep *ep); Clear the halt feature of specified endpoint.
45/62
Kernel-space APIs Arguments: ep (in): Pointer to endpoint structure.
UM0479
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); Allocates an I/O request data structure. ep (in): Pointer to endpoint structure. gfp_flags (in): GFP flags.
Description: Arguments:
Function:
void usb_ep_free_request( struct usb_ep *ep, struct usb_request *req); Deallocates an I/O request data structure. ep (in): Pointer to endpoint structure. req (in): Pointer to request structure.
Description: Arguments:
46/62
UM0479 Function: int usb_ep_queue( struct usb_ep *ep, struct usb_request *req, gfp_t gfp_flags); Sends an I/O request to the transmission queue. ep (in): Pointer to endpoint structure. req (in): Pointer to request structure. gfp_flags (in): GFP flags.
Kernel-space APIs
Description: Arguments:
Function:
int usb_ep_dequeue( struct usb_ep *ep, struct usb_request *req); Cancels the transmission of an I/O request to the transmission queue. ep (in): Pointer to endpoint structure. req (in): Pointer to request structure.
Description: Arguments:
Function:
void *usb_ep_alloc_buffer( struct usb_ep *ep, unsigned len, dma_addr_t *dma, gfp_t gfp_flags); Allocates a buffer to be used in I/O requests. ep (in): Pointer to endpoint structure. len (in): Buffer length. dma (out): DMA address. gfp_flags (in): GFP flags.
Description: Arguments:
47/62
Kernel-space APIs Function: void usb_ep_free_buffer( struct usb_ep *ep, void *buf, dma_addr_t dma, unsigned len); Deallocates a buffer used in I/O requests. ep (in): Pointer to endpoint structure. buf (in): Pointer to buffer. dma (in): DMA address. len (in): Buffer length. Finally, the following utility functions are available:
UM0479
Description: Arguments:
Function:
int usb_gadget_config_buf( const struct usb_config_descriptor *config, void *buf, unsigned buflen, const struct usb_descriptor_header **desc); Fills a buffer from a configuration descriptor. config (in): Descriptor configuration. buf (out): Buffer to be filled. buflen (in): Buffer length. desc (in): Pointer to descriptor header.
Description: Arguments:
Function:
int usb_descriptor_fillbuf( void * buf, unsigned buflen, const struct usb_descriptor_header **src); Fills a descriptor buffer.
Description:
48/62
UM0479 Arguments: buf (out): Buffer to be filled. buflen (in): Buffer length. src (in): Pointer to descriptor header.
Kernel-space APIs
Function:
int usb_gadget_get_string( struct usb_gadget_strings *table, int id, u8 *buf); Performs lookup in a strings table (typically for internationalization purposes). table (in): Pointer to strings table. id (in): String identifier. buf (out): Pointer to buffer for returned string.
Description: Arguments:
Function:
struct usb_ep* usb_ep_autoconfig( struct usb_gadget *gadget, struct usb_endpoint_descriptor *desc ); Autoconfiguration of endpoints. Return pointer to configured endpoint. gadget (in): Pointer to gadget driver. desc (in): Pointer to endpoint descriptor.
Description: Arguments:
Function: Description: Arguments:
void usb_ep_autoconfig_reset(struct usb_gadget *); Resets the autoconfiguration of a gadget. gadget (in): Pointer to gadget driver.
49/62
Kernel-space APIs
UM0479
5.8
USB hosts
As discussed for the USB host user-space API, there are many off-the-shelf host class drivers made available in the Linux kernel source tree. One of them (mass storage) has been integrated in the default kernel configuration delivered in this SDK. Other class drivers may be added to the configuration, each of them exposing its own specific interfaces to applications. Anyway, all such drivers are compliant to a USB host stack framework standardized by Linux and defined inside the include/linux/usb.h header file. Understanding such kernel-space framework is only required when a custom USB host class driver must be developed as kernel extension. An example could be a PictBridge class driver for a printer. Each USB class driver has to be defined through the following data structure: struct usb_driver { const char *name; int (*probe) (struct usb_interface usb_device_id *id); void (*disconnect) (struct usb_interface int (*ioctl) (struct usb_interface code,void *buf); int (*suspend) (struct usb_interface message); int (*resume) (struct usb_interface void (*pre_reset) (struct usb_interface void (*post_reset) (struct usb_interface const struct usb_device_id *id_table; struct usb_dynids dynids; struct usbdrv_wrap drvwrap; unsigned int no_dynamic_id:1; unsigned int supports_autosuspend:1; }; where the fields have the following meanings: Table 11. USB driver structure fields
Description Driver name, should be unique among USB host drivers and should normally be the same as the module name. Pointer to custom callback function invoked to see if the driver is willing to manage a particular interface on a device. If it is, probe returns zero and uses dev_set_drvdata() to associate driver-specific data with the interface. It may also use usb_set_interface() to specify the appropriate altsetting. If unwilling to manage the interface, return a negative errno value. Pointer to custom callback function invoked when the interface is no longer accessible, usually because its device has been (or is being) disconnected or the driver module is being unloaded. Pointer to custom callback function used for drivers that want to talk to userspace through the usbfs filesystem. This lets devices provide ways to expose information to user space regardless of where they do (or don't) show up otherwise in the filesystem.
*intf,const struct *intf); *intf, unsigned int *intf, pm_message_t *intf); *intf); *intf);
Field name
probe
disconnect
ioctl
50/62
UM0479 Table 11. USB driver structure fields
Description
Kernel-space APIs
Field suspend resume pre_reset post_reset
Pointer to custom callback function called when the device is going to be suspended by the system. Pointer to custom callback function called when the device is being resumed by the system. Pointer to custom callback function called by usb_reset_composite_device() when the device is about to be reset. Pointer to custom callback function called by usb_reset_composite_device() after the device has been reset. ID 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. Used internally to hold the list of dynamically added device ids for this driver. Driver-model core structure wrapper. if 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. if set to 0, the USB core will not allow autosuspend for interfaces bound to this driver.
id_table
dynids drvwrap no_dynamic_id suppor ts_autosuspend
All callbacks receive a standard argument defined as a pointer to the following structure: struct usb_interface { struct usb_host_interface *altsetting; struct usb_host_interface *cur_altsetting; unsigned num_altsetting; int minor; enum usb_interface_condition condition; unsigned is_active:1; unsigned needs_remote_wakeup:1; struct device dev; struct class_device *class_dev; int pm_usage_cnt; }; where the fields have the following meanings: Table 12. USB interface structure fields
Description Array 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. The current altsetting. Number of altsettings defined.
Field altsetting cur_altsetting num_altsetting
51/62
Kernel-space APIs Table 12. USB interface structure fields (continued)
Description
UM0479
Field
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(). Binding state of the interface: not bound, binding (in probe()), bound to a driver, or unbinding (in disconnect()). Flag set when the interface is bound and not suspended. Flag set when the driver requires remote-wakeup capability during autosuspend. Driver model's view of this device. Driver model's class view of this device. Power management usage counter for this interface; autosuspend is not allowed unless the counter is 0.
condition is_active needs_remote_wakeup dev class_device pm_usage_cnt
The main kernel API functions available for class driver management are as follows:
Function: Description: Arguments:
int usb_register(struct usb_driver *driver); Registers a driver with the USB host stack. This is usually invoked in a module initialization function (defined by module_init macro). driver (in): Pointer to the driver structure.
Function: Description: Arguments:
void usb_deregister(struct usb_driver *driver); Unregisters a driver from the USB host stack. This is usually invoked in a module termination function (defined by module_exit macro). driver (in): Pointer to the driver structure. The rest of kernel-space USB host API is quite complex and can not be entirely documented here. It is recommended to look at the include/linux/usb.h header file as well as an example of skeleton driver provided inside the kernel source tree at path: /opt/splus_linux_sdk_1_1/src/linux-2.6.19.2/drivers/usb/usbskeleton.c
5.9
Watchdog timer (WDT)
A device driver for the SPEAr Plus hardware watchdog timer (WDT) and the relevant kernelspace API shall be provided in future SDK releases.
52/62
UM0479
Source files for built-in drivers
Appendix A
Source files for built-in drivers
A reference to source files implementing the SPEAr Plus device drivers provided with SDK 1.1 is reported in the following table. All paths are relative to Linux kernel top directory. The availability of user-space and/or kernel-space API for each device is also reported. A standard naming convention is adopted. All source files have a fixed "spr_" prefix, followed by a general device identifier (dma, eth, gpio, etc.) and a cell-specific identifier (pl080, syn, pl061, etc.). The "_hal" suffix, where applied, refers to source files directly accessing hardware registers (Hardware Abstraction Layer). Table 13. SDK 1.1 driver summary
User API Kernel API Driver source files 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 drivers/net/arm/spr_eth_syn.h drivers/net/arm/spr_eth_syn.c drivers/net/arm/spr_eth_syn_hal.c drivers/char/spr_gpio_pl061.h drivers/char/spr_gpio_pl061.c drivers/char/spr_gpio_pl061_hal.h drivers/char/spr_gpio_pl061_hal.c drivers/i2c/busses/spr_i2c_syn.h drivers/i2c/busses/spr_i2c_syn.c drivers/i2c/busses/spr_i2c_syn_hal.h drivers/i2c/busses/spr_i2c_syn_hal.c drivers/i2c/chips/spr_m24cxx.c drivers/r tc/spr_r tc_st.c drivers/rtc/spr_rtc_st_hal.h drivers/rtc/spr_rtc_st_hal.c drivers/serial/spr_uar t_pl011.h drivers/serial/spr_uart_pl011.c drivers/serial/spr_uart_pl011_hal.hdrivers/serial /spr_uar t_pl011_hal.c X drivers/usb/gadget/spr_udc_syn.h drivers/usb/gadget/spr_udc_syn.c drivers/usb/host/spr_hcd.h drivers/usb/host/spr_ehci_syn.c drivers/usb/host/spr_ohci_syn.c
Device
DMA
X
Ethernet
X
GPIO
X
X
I2C Bus / EEPROM
X
X
Real-Time Clock (RTC)
X
UARTs
X
USB Device Controller
USB Host Controllers
X
53/62
Default kernel configuration
UM0479
Appendix B
Default kernel configuration
This section provides the contents of the default kernel configuration file (spearplus_defconfig). For the sake of better readability, unused sections and commented lines have been omitted. CONFIG_ARM=y CONFIG_MMU=y CONFIG_GENERIC_HARDIRQS=y CONFIG_TRACE_IRQFLAGS_SUPPORT=y CONFIG_HARDIRQS_SW_RESEND=y CONFIG_GENERIC_IRQ_PROBE=y CONFIG_RWSEM_GENERIC_SPINLOCK=y CONFIG_GENERIC_HWEIGHT=y CONFIG_GENERIC_CALIBRATE_DELAY=y CONFIG_VECTORS_BASE=0xffff0000 CONFIG_DEFCONFIG_LIST="/lib/modules/$UNAME_RELEASE/.config" # # Code maturity level options # CONFIG_BROKEN_ON_SMP=y CONFIG_INIT_ENV_ARG_LIMIT=32 # # General setup # CONFIG_LOCALVERSION="" CONFIG_LOCALVERSION_AUTO=y CONFIG_SWAP=y CONFIG_SYSVIPC=y CONFIG_INITRAMFS_SOURCE="" CONFIG_SYSCTL=y CONFIG_EMBEDDED=y CONFIG_UID16=y CONFIG_TINY_SHMEM=y CONFIG_BASE_SMALL=1 CONFIG_SLOB=y # # Loadable module support # CONFIG_MODULES=y CONFIG_MODULE_UNLOAD=y CONFIG_KMOD=y # # Block layer # CONFIG_BLOCK=y
54/62
UM0479 # # IO Schedulers # CONFIG_IOSCHED_NOOP=y CONFIG_IOSCHED_AS=y CONFIG_IOSCHED_DEADLINE=y CONFIG_IOSCHED_CFQ=y CONFIG_DEFAULT_CFQ=y CONFIG_DEFAULT_IOSCHED="cfq" # # System Type # CONFIG_ARCH_SPEARPLUS=y # # SPEAR platform options # CONFIG_SPEAR_MISC_CONFIG=y CONFIG_SPEAR_LOCK=y # # Processor Type # CONFIG_CPU_32=y CONFIG_CPU_ARM926T=y CONFIG_CPU_32v5=y CONFIG_CPU_ABRT_EV5TJ=y CONFIG_CPU_CACHE_VIVT=y CONFIG_CPU_COPY_V4WB=y CONFIG_CPU_TLB_V4WBI=y CONFIG_CPU_CP15=y CONFIG_CPU_CP15_MMU=y # # Processor Features # CONFIG_ARM_THUMB=y # # Kernel Features # CONFIG_HZ=100 CONFIG_FLATMEM=y CONFIG_FLAT_NODE_MEM_MAP=y CONFIG_SPLIT_PTLOCK_CPUS=4096 CONFIG_ALIGNMENT_TRAP=y # # Boot options # CONFIG_ZBOOT_ROM_TEXT=0x0
Default kernel configuration
55/62
Default kernel configuration CONFIG_ZBOOT_ROM_BSS=0x0
UM0479
CONFIG_CMDLINE="console=ttyS0 quiet mem=64M root=/dev/mtdblock3 # # Floating point emulation # CONFIG_FPE_NWFPE=y # # Userspace binary formats # CONFIG_BINFMT_ELF=y # # Networking # CONFIG_NET=y # # Networking options # CONFIG_PACKET=y CONFIG_PACKET_MMAP=y CONFIG_UNIX=y CONFIG_XFRM=y CONFIG_INET=y CONFIG_IP_FIB_HASH=y CONFIG_IP_PNP=y CONFIG_INET_XFRM_MODE_TRANSPORT=y CONFIG_INET_XFRM_MODE_TUNNEL=y CONFIG_INET_XFRM_MODE_BEET=y CONFIG_INET_DIAG=y CONFIG_INET_TCP_DIAG=y CONFIG_TCP_CONG_CUBIC=y CONFIG_DEFAULT_TCP_CONG="cubic" # # Generic Driver Options # CONFIG_STANDALONE=y CONFIG_PREVENT_FIRMWARE_BUILD=y
# # Memory Technology Devices (MTD) # CONFIG_MTD=y CONFIG_MTD_CONCAT=y CONFIG_MTD_PARTITIONS=y #
56/62
UM0479 # User Modules And Translation Layers # CONFIG_MTD_CHAR=y CONFIG_MTD_BLOCK=y # # RAM/ROM/Flash chip drivers # CONFIG_MTD_MAP_BANK_WIDTH_1=y CONFIG_MTD_MAP_BANK_WIDTH_2=y CONFIG_MTD_MAP_BANK_WIDTH_4=y CONFIG_MTD_CFI_I1=y CONFIG_MTD_CFI_I2=y # # Self-contained MTD device drivers # CONFIG_SPEAR_MTD_NOR=y CONFIG_MTD_STATIC_MEMORY_BANKS=y CONFIG_MTD_STATIC_PARTITIONING=y # # SCSI device support # CONFIG_SCSI=y CONFIG_SCSI_NETLINK=y CONFIG_SCSI_PROC_FS=y # # SCSI support type (disk, tape, CD-ROM) # CONFIG_BLK_DEV_SD=y CONFIG_CHR_DEV_ST=y CONFIG_CHR_DEV_OSST=y CONFIG_BLK_DEV_SR=y CONFIG_BLK_DEV_SR_VENDOR=y
Default kernel configuration
# # Some SCSI devices (e.g. CD jukebox) support multiple LUNs # CONFIG_SCSI_MULTI_LUN=y CONFIG_SCSI_CONSTANTS=y CONFIG_SCSI_LOGGING=y # # SCSI Transports # CONFIG_SCSI_FC_ATTRS=y # # Network device support #
57/62
Default kernel configuration CONFIG_NETDEVICES=y CONFIG_ETH_SPEAR_SYN=y # # Ethernet (10 or 100Mbit) # CONFIG_NET_ETHERNET=y CONFIG_MII=y # # Non-8250 serial port support # CONFIG_SERIAL_CORE=y CONFIG_SERIAL_CORE_CONSOLE=y CONFIG_SPEAR_UART_pl011=y CONFIG_SPEAR_UART_CONSOLE_pl011=y CONFIG_UNIX98_PTYS=y CONFIG_LEGACY_PTYS=y CONFIG_LEGACY_PTY_COUNT=256 # # Ftape, the floppy tape device driver # CONFIG_SPEAR_GPIO_pl061=y CONFIG_SPEAR_DMA_pl080=y # # I2C support # CONFIG_I2C=y # # I2C Hardware Bus support # CONFIG_SPEAR_I2C_Syn=y # # Miscellaneous I2C Chip support # CONFIG_SPEAR_M24CXX=y # # USB support # CONFIG_USB_ARCH_HAS_HCD=y CONFIG_USB_ARCH_HAS_OHCI=y CONFIG_USB=y # # Miscellaneous USB options # CONFIG_USB_DEVICEFS=y
UM0479
58/62
UM0479
Default kernel configuration
# # USB Host Controller Drivers # CONFIG_USB_EHCI_HCD=y CONFIG_USB_OHCI_HCD=y CONFIG_USB_OHCI_LITTLE_ENDIAN=y # # NOTE: USB_STORAGE enables SCSI, and 'SCSI disk support' # may also be needed; see USB_STORAGE Help for more information # CONFIG_USB_STORAGE=y # # USB Gadget Support # CONFIG_USB_GADGET=y CONFIG_USB_GADGET_SELECTED=y CONFIG_USB_GADGET_SPEAR_SYN=y CONFIG_USB_SPEAR_SYN=y CONFIG_USB_GADGET_DUALSPEED=y CONFIG_USB_ZERO=y # # Real Time Clock # CONFIG_RTC_LIB=y CONFIG_SPEAR_RTC_ST=y # # DOS/FAT/NT Filesystems # CONFIG_FAT_FS=y CONFIG_VFAT_FS=y CONFIG_FAT_DEFAULT_CODEPAGE=437 CONFIG_FAT_DEFAULT_IOCHARSET="iso8859-1" # # Pseudo filesystems # CONFIG_PROC_FS=y CONFIG_PROC_SYSCTL=y CONFIG_SYSFS=y CONFIG_TMPFS=y CONFIG_RAMFS=y # # Miscellaneous filesystems # CONFIG_CRAMFS=y
59/62
Default kernel configuration # # Network File Systems # CONFIG_NFS_FS=y CONFIG_ROOT_NFS=y CONFIG_LOCKD=y CONFIG_NFS_COMMON=y CONFIG_SUNRPC=y # # Partition Types # CONFIG_MSDOS_PARTITION=y # # Native Language Support # CONFIG_NLS=y CONFIG_NLS_DEFAULT="iso8859-1" CONFIG_NLS_CODEPAGE_437=y CONFIG_NLS_CODEPAGE_850=y CONFIG_NLS_ASCII=y CONFIG_NLS_ISO8859_1=y CONFIG_NLS_UTF8=y # # Kernel hacking # CONFIG_ENABLE_MUST_CHECK=y CONFIG_LOG_BUF_SHIFT=14 CONFIG_FRAME_POINTER=y # # Library routines # CONFIG_CRC_CCITT=y CONFIG_CRC32=y CONFIG_ZLIB_INFLATE=y
UM0479
60/62
UM0479
Revision history
6
Revision history
Table 14.
Date 14-Nov-2007 17-Sep-2008
Document revision history
Revision 1 2 Initial release. Minor package upgrade, mainly extending DDR clock to 266 MHz and supporting Gigabit Ethernet. Changes
61/62
UM0479
Please Read Carefully:
Information in this document is provided solely in connection with ST products. STMicroelectronics NV and its subsidiaries ("ST") reserve the right to make changes, corrections, modifications or improvements, to this document, and the products and services described herein at any time, without notice. All ST products are sold pursuant to ST's terms and conditions of sale. Purchasers are solely responsible for the choice, selection and use of the ST products and services described herein, and ST assumes no liability whatsoever relating to the choice, selection or use of the ST products and services described herein. No license, express or implied, by estoppel or otherwise, to any intellectual property rights is granted under this document. If any part of this document refers to any third party products or services it shall not be deemed a license grant by ST for the use of such third party products or services, or any intellectual property contained therein or considered as a warranty covering the use in any manner whatsoever of such third party products or services or any intellectual property contained therein.
UNLESS OTHERWISE SET FORTH IN ST'S TERMS AND CONDITIONS OF SALE ST DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY WITH RESPECT TO THE USE AND/OR SALE OF ST PRODUCTS INCLUDING WITHOUT LIMITATION IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE (AND THEIR EQUIVALENTS UNDER THE LAWS OF ANY JURISDICTION), OR INFRINGEMENT OF ANY PATENT, COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT. UNLESS EXPRESSLY APPROVED IN WRITING BY AN AUTHORIZE REPRESENTATIVE OF ST, ST PRODUCTS ARE NOT DESIGNED, AUTHORIZED OR WARRANTED FOR USE IN MILITARY, AIR CRAFT, SPACE, LIFE SAVING, OR LIFE SUSTAINING APPLICATIONS, NOR IN PRODUCTS OR SYSTEMS, WHERE FAILURE OR MALFUNCTION MAY RESULT IN PERSONAL INJURY, DEATH, OR SEVERE PROPERTY OR ENVIRONMENTAL DAMAGE.
Resale of ST products with provisions different from the statements and/or technical features set forth in this document shall immediately void any warranty granted by ST for the ST product or service described herein and shall not create or extend in any manner whatsoever, any liability of ST.
ST and the ST logo are trademarks or registered trademarks of ST in various countries. Information in this document supersedes and replaces all information previously supplied. The ST logo is a registered trademark of STMicroelectronics. All other names are the property of their respective owners.
2008 STMicroelectronics - All rights reserved STMicroelectronics group of companies Australia - Belgium - Brazil - Canada - China - Czech Republic - Finland - France - Germany - Hong Kong - India - Israel - Italy - Japan Malaysia - Malta - Morocco - Singapore - Spain - Sweden - Switzerland - United Kingdom - United States of America www.st.com
62/62
|
