eCos Reference Manual

Documentation licensing terms

This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at http://www.opencontent.org/openpub/).

Distribution of substantively modified versions of this document is prohibited without the explicit permission of the copyright holder.

Distribution of the work or derivative of the work in any standard (paper) book form is prohibited unless prior permission is obtained from the copyright holder.

Trademarks

Altera® and Excalibur™ are trademarks of Altera Corporation.

AMD® is a registered trademark of Advanced Micro Devices, Inc.

ARM®, StrongARM®, Thumb®, ARM7™, ARM9™ is a registered trademark of Advanced RISC Machines, Ltd.

Cirrus Logic® and Maverick™ are registered trademarks of Cirrus Logic, Inc.

Cogent™ is a trademark of Cogent Computer Systems, Inc.

Compaq® is a registered trademark of the Compaq Computer Corporation.

Fujitsu® is a registered trademark of Fujitsu Limited.

IBM®, and PowerPC™ are trademarks of International Business Machines Corporation.

IDT® is a registered trademark of Integrated Device Technology Inc.

Intel®, i386™, Pentium®, StrataFlash® and XScale™ are trademarks of Intel Corporation.

Intrinsyc® and Cerf™ are trademarks of Intrinsyc Software, Inc.

Linux® is a registered trademark of Linus Torvalds.

Matsushita™ and Panasonic® are trademarks of the Matsushita Electric Industrial Corporation.

Microsoft®, Windows®, Windows NT® and Windows XP® are registered trademarks of Microsoft Corporation, Inc.

MIPS®, MIPS32™ MIPS64™, 4K™, 5K™ Atlas™ and Malta™ are trademarks of MIPS Technologies, Inc.

Motorola®, ColdFire® is a trademark of Motorola, Inc.

NEC® V800™, V850™, V850/SA1™, V850/SB1™, VR4300™, and VRC4375™ are trademarks of NEC Corporation.

PMC-Sierra® RM7000™ and Ocelot™ are trademarks of PMC-Sierra Incorporated.

Red Hat, eCos™, RedBoot™, GNUPro®, and Insight™ are trademarks of Red Hat, Inc.

Samsung® and CalmRISC™ are trademarks or registered trademarks of Samsung, Inc.

Sharp® is a registered trademark of Sharp Electronics Corp.

SPARC® is a registered trademark of SPARC International, Inc., and is used under license by Sun Microsystems, Inc.

Sun Microsystems® and Solaris® are registered trademarks of Sun Microsystems, Inc.

SuperH™ and Renesas™ are trademarks owned by Renesas Technology Corp.

Texas Instruments®, OMAP™ and Innovator™ are trademarks of Texas Instruments Incorporated.

Toshiba® is a registered trademark of the Toshiba Corporation.

UNIX® is a registered trademark of The Open Group.

All other brand and product names, trademarks, and copyrights are the property of their respective owners.

Warranty

eCos and RedBoot are open source software, covered by a modified version of the GNU General Public Licence, and you are welcome to change it and/or distribute copies of it under certain conditions. See http://ecos.sourceware.org/license-overview.html for more information about the license.

eCos and RedBoot software have NO WARRANTY.

Because this software is licensed free of charge, there are no warranties for it, to the extent permitted by applicable law. Except when otherwise stated in writing, the copyright holders and/or other parties provide the software “as is” without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The entire risk as to the quality and performance of the software is with you. Should the software prove defective, you assume the cost of all necessary servicing, repair or correction.

In no event, unless required by applicable law or agreed to in writing, will any copyright holder, or any other party who may modify and/or redistribute the program as permitted above, be liable to you for damages, including any general, special, incidental or consequential damages arising out of the use or inability to use the program (including but not limited to loss of data or data being rendered inaccurate or losses sustained by you or third parties or a failure of the program to operate with any other programs), even if such holder or other party has been advised of the possibility of such damages.


Table of Contents
I. The eCos Kernel
Kernel Overview -- Overview of the eCos Kernel
SMP Support -- Support Symmetric Multiprocessing Systems
Thread creation -- Create a new thread
Thread information -- Get basic thread information
Thread control -- Control whether or not a thread is running
Thread termination -- Allow threads to terminate
Thread priorities -- Examine and manipulate thread priorities
Per-thread data -- Manipulate per-thread data
Thread destructors -- Call functions on thread termination
Exception handling -- Handle processor exceptions
Counters -- Count event occurrences
Clocks -- Provide system clocks
Alarms -- Run an alarm function when a number of events have occurred
Mutexes -- Synchronization primitive
Condition Variables -- Synchronization primitive
Semaphores -- Synchronization primitive
Mail boxes -- Synchronization primitive
Event Flags -- Synchronization primitive
Spinlocks -- Low-level Synchronization Primitive
Scheduler Control -- Control the state of the scheduler
Interrupt Handling -- Manage interrupt handlers
Kernel Real-time Characterization -- Measure the performance of the eCos kernel
II. The eCos Hardware Abstraction Layer (HAL)
1. Introduction
2. Architecture, Variant and Platform
3. General principles
4. HAL Interfaces
Base Definitions
Architecture Characterization
Interrupt Handling
Clocks and Timers
HAL I/O
Cache Control
Linker Scripts
Diagnostic Support
SMP Support
5. Exception Handling
HAL Startup
Vectors and VSRs
Default Synchronous Exception Handling
Default Interrupt Handling
6. Porting Guide
Introduction
HAL Structure
Virtual Vectors (eCos/ROM Monitor Calling Interface)
HAL Coding Conventions
Platform HAL Porting
Variant HAL Porting
Architecture HAL Porting
7. Future developments
III. The ISO Standard C and Math Libraries
8. C and math library overview
Included non-ISO functions
Math library compatibility modes
Some implementation details
Thread safety
C library startup
IV. I/O Package (Device Drivers)
9. Introduction
10. User API
11. Serial driver details
Raw Serial Driver
TTY driver
12. How to Write a Driver
How to Write a Serial Hardware Interface Driver
Serial testing with ser_filter
13. Device Driver Interface to the Kernel
Interrupt Model
Synchronization
SMP Support
Device Driver Models
Synchronization Levels
The API
V. File System Support Infrastructure
14. Introduction
15. File System Table
16. Mount Table
17. File Table
18. Directories
19. Synchronization
20. Initialization and Mounting
21. Sockets
22. Select
23. Devices
24. Writing a New Filesystem
VI. PCI Library
25. The eCos PCI Library
PCI Library
PCI Library reference
VII. FLASH Library
26. The eCos FLASH Library
Notes on using the FLASH library
Danger, Will Robinson! Danger!
27. The Version 2 eCos FLASH API
FLASH user API
FLASH device API
28. The legacy Version 1 eCos FLASH API
FLASH user API
FLASH device API
29. FLASH I/O devices
Overview and CDL Configuration
Using FLASH I/O devices
VIII. SPI Support
Overview -- eCos Support for SPI, the Serial Peripheral Interface
SPI Interface -- allow applications and other packages to access SPI devices
Porting to New Hardware -- Adding SPI support to new hardware
IX. I2C Support
Overview -- eCos Support for I2C, the Inter IC Bus
I2C Interface -- allow applications and other packages to access I2C devices
Porting to New Hardware -- Adding I2C support to new hardware
X. CAN Support
30. Overview
Description
eCos Support for CAN
31. User API
32. CAN driver details
Description
API Details
Runtime Configuration
33. Configuration
34. Writing a CAN hardware device driver
How to Write a CAN Hardware Interface Driver
XI. ADC Support
Overview -- eCos Support for Analog/Digital Converters
ADC Device Drivers -- ADC Device Drivers
XII. Framebuffer Support
Overview -- eCos Support for Framebuffer Devices
Framebuffer Parameters -- determining framebuffer capabilities
Framebuffer Control Operations -- managing a framebuffer
Framebuffer Colours -- formats and palette management
Framebuffer Drawing Primitives -- updating the display
Framebuffer Pixel Manipulation -- iterating over the display
Writing a Framebuffer Device Driver -- writing a new framebuffer device driver
XIII. eCos POSIX compatibility layer
35. POSIX Standard Support
Process Primitives [POSIX Section 3]
Process Environment [POSIX Section 4]
Files and Directories [POSIX Section 5]
Input and Output [POSIX Section 6]
Device and Class Specific Functions [POSIX Section 7]
C Language Services [POSIX Section 8]
System Databases [POSIX Section 9]
Data Interchange Format [POSIX Section 10]
Synchronization [POSIX Section 11]
Memory Management [POSIX Section 12]
Execution Scheduling [POSIX Section 13]
Clocks and Timers [POSIX Section 14]
Message Passing [POSIX Section 15]
Thread Management [POSIX Section 16]
Thread-Specific Data [POSIX Section 17]
Thread Cancellation [POSIX Section 18]
Non-POSIX Functions
References and Bibliography
XIV. µITRON
36. µITRON API
Introduction to µITRON
µITRON and eCos
Task Management Functions
Task-Dependent Synchronization Functions
Synchronization and Communication Functions
Extended Synchronization and Communication Functions
Interrupt management functions
Memory pool Management Functions
Time Management Functions
System Management Functions
Network Support Functions
µITRON Configuration FAQ
XV. TCP/IP Stack Support for eCos
37. Ethernet Driver Design
38. Sample Code
39. Configuring IP Addresses
40. Tests and Demonstrations
Loopback tests
Building the Network Tests
Standalone Tests
Performance Test
Interactive Tests
Maintenance Tools
41. Support Features
TFTP
DHCP
42. TCP/IP Library Reference
getdomainname
gethostname
byteorder
ethers
getaddrinfo
gethostbyname
getifaddrs
getnameinfo
getnetent
getprotoent
getrrsetbyname
getservent
if_nametoindex
inet
inet6_option_space
inet6_rthdr_space
inet_net
ipx
iso_addr
link_addr
net_addrcmp
ns
resolver
accept
bind
connect
getpeername
getsockname
getsockopt
ioctl
poll
select
send
shutdown
socket
XVI. FreeBSD TCP/IP Stack port for eCos
43. Networking Stack Features
44. Freebsd TCP/IP stack port
Targets
Building the Network Stack
45. APIs
Standard networking
Enhanced Select()
XVII. OpenBSD TCP/IP Stack port for eCos
46. Networking Stack Features
Introduction
47. OpenBSD TCP/IP stack port
Targets
Building the Network Stack
Inclusion of bridge code
48. APIs
Standard networking
Enhanced Select()
OpenBSD networking facilities
Bridging
Spanning Tree Protocol
XVIII. DNS for eCos and RedBoot
49. DNS
DNS API
DNS Client Testing
XIX. IPSEC for eCos
50. Installation and Configuration
51. libipsec Reference
ipsec_set_policy
ipsec_strerror
XX. eCos PPP User Guide
52. Features
53. Using PPP
54. PPP Interface
cyg_ppp_options_init() -- Initialize PPP link options
cyg_ppp_up() -- Bring PPP connection up
cyg_ppp_down() -- Bring PPP connection down
cyg_ppp_wait_up() -- Wait for PPP connection to come up
cyg_ppp_wait_down() -- Wait for PPP connection to terminate
cyg_ppp_chat() -- Execute chat script
55. Installing and Configuring PPP
Including PPP in a Configuration
Configuring PPP
56. CHAT Scripts
Chat Script
ABORT Strings
TIMEOUT
Sending EOT
Escape Sequences
57. PPP Enabled Device Drivers
58. Testing
Test Programs
Test Script
XXI. Ethernet Device Drivers
59. Generic Ethernet Device Driver
Generic Ethernet API
Review of the functions
Upper Layer Functions
Calling graph for Transmission and Reception
XXII. Ethernet PHY Device Support
60. Ethernet PHY Device Support
Ethernet PHY Device API
XXIII. SNMP
61. SNMP for eCos
Version
SNMP packages in the eCos source repository
MIBs supported
Changes to eCos sources
Starting the SNMP Agent
Configuring eCos
Test cases
SNMP clients and package use
Unimplemented features
MIB Compiler
snmpd.conf
XXIV. Embedded HTTP Server
62. Embedded HTTP Server
Intrduction
Server Organization
Server Configuration
Support Functions and Macros
System Monitor
XXV. FTP Client for eCos TCP/IP Stack
63. FTP Client Features
FTP Client API
XXVI. Simple Network Time Protocol Client
64. The SNTP Client
Starting the SNTP client
What it does
Configuring the unicast list of NTP servers
Warning: timestamp wrap around
The SNTP test program
XXVII. Another Tiny HTTP Server for eCos
65. The ATHTTP Server
Features
Starting the server
MIME types
C language callback functions
CGI
Authentication
Directory Listing
Form Variables
Internal Resources
XXVIII. Memory Allocation
66. eCos Memory Pools
eCos Memory pools
XXIX. CRC Algorithms
67. CRC Functions
CRC API
XXX. CPU load measurements
68. CPU Load Measurements
CPU Load API
XXXI. gprof Profiling Support
Profiling -- eCos Support for the gprof profiling tool
XXXII. eCos Power Management Support
Introduction -- eCos support for Power Management
Power Management Information -- finding out about the various power controllers in the system
Changing Power Modes -- reducing or increasing power consumption as needed
Support for Policy Modules -- closer integration with higher-level code
Attached and Detached Controllers -- control which power controllers are affected by global changes
Implementing a Power Controller -- adding power management support to device drivers and other packages
XXXIII. eCos USB Slave Support
Introduction -- eCos support for USB slave devices
USB Enumeration Data -- The USB enumeration data structures
Starting up a USB Device -- Starting up a USB Device
Devtab Entries -- Data endpoint data structure
Receiving Data from the Host -- Receiving Data from the Host
Sending Data to the Host -- Sending Data to the Host
Halted Endpoints -- Support for Halting and Halted Endpoints
Control Endpoints -- Control endpoint data structure
Data Endpoints -- Data endpoint data structures
Writing a USB Device Driver -- USB Device Driver Porting Guide
Testing -- Testing of USB Device Drivers
XXXIV. eCos Support for Developing USB-ethernet Peripherals
Introduction -- eCos support for developing USB ethernet peripherals
Initializing the USB-ethernet Package -- Initializing the USB-ethernet Package
USB-ethernet Data Transfers -- Exchanging ethernet packets with the USB host
USB-ethernet State Handling -- Maintaining the USB-ethernet connection with the host
Network Device for the eCos TCP/IP Stack -- USB-ethernet support for the eCos TCP/IP Stack
Example Host-side Device Driver -- Provide host-side support for the eCos USB-ethernet package
Communication Protocol -- Protocol used between the host-side device driver and the eCos USB-ethernet package
XXXV. eCos Support for USB Serial like Peripherals
Introduction --  eCos support for USB Serial like Peripherals
Configuration -- Configuration USB Serial like Peripherals
Host Configuration -- Host Configuration for USB Serial like Peripherals
API Function --  eCos USB Serial like Peripherals API
XXXVI. eCos Synthetic Target
Overview -- Overview
Installation -- Preparing to use the synthetic target
Running a Synthetic Target Application -- Arguments and configuration files
The I/O Auxiliary's User Interface -- Controlling the I/O Auxiliary
The Console Device -- Show output from the eCos application
System Calls -- Access Linux system facilities
Writing New Devices - target -- extending the synthetic target, target-side
Writing New Devices - host -- extending the synthetic target, host-side
Porting -- Adding support for other hosts
XXXVII. M68000 Architectural Support
Overview -- eCos Support for the M68K Family of Processors
Configuration -- Configuring the M68K Architectural Package
The HAL Port -- Implementation Details
XXXVIII. Freescale MCFxxxx Variant Support
MCFxxxx ColdFire Processors -- eCos Support for Freescale MCFxxxx Processors
XXXIX. Freescale MCF5272 Processor Support
The MCF5272 ColdFire Processor -- eCos Support for the Freescale MCF5272 Processor
XL. Freescale M5272C3 Board Support
Overview -- Overview
Setup -- Preparing the M5272C3 board for eCos Development
Configuration -- Platform-specific Configuration Options
The HAL Port -- Implementation Details
XLI. SuperH SH4-202 MicroDev Board Support
Overview -- Overview
Setup -- Preparing the MicroDev board for eCos Development
Configuration -- Platform-specific Configuration Options
The HAL Port -- Implementation Details
XLII. SA11X0 USB Device Driver
SA11X0 USB Device Driver -- Device driver for the on-chip SA11X0 USB device
XLIII. NEC uPD985xx USB Device Driver
NEC uPD985xx USB Device Driver -- Device driver for the on-chip NEC uPD985xx USB device
XLIV. Synthetic Target Ethernet Driver
Synthetic Target Ethernet Driver -- Allow synthetic target applications to perform ethernet I/O
XLV. Freescale ColdFire Ethernet Driver
Freescale ColdFire Ethernet Driver -- eCos Support for Freescale ColdFire On-chip Ethernet Devices
XLVI. Freescale MCFxxxx Serial Driver
MCFxxxx Serial Driver -- eCos Support for the MCFxxxx On-chip Serial Devices
XLVII. Synthetic Target Watchdog Device
Synthetic Target Watchdog Device -- Emulate watchdog hardware in the synthetic target
XLVIII. Dallas DS1307 Wallclock Device Driver
Dallas DS1307 Wallclock Device Driver -- eCos Support for the Dallas DS1307 Serial Real-Time Clock
XLIX. MMC MultiMedia Card Disk Driver
Device Driver for MMC MultiMedia Cards -- eCos Support for MMC MultiMedia Cards
L. Synthetic Target Framebuffer Device
Synthetic Target Framebuffer Device -- Emulate framebuffer hardware in the synthetic target
LI. AMD AM29xxxxx Flash Device Driver
Overview -- eCos Support for AMD AM29xxxxx Flash Devices and Compatibles
Instantiating an AM29xxxxx Device -- including the driver in an eCos target
LII. Intel Strata Flash Device Driver
Overview -- eCos Support for Intel Strata Flash Devices and Compatibles
Instantiating a Strata Device -- including the driver in an eCos target
Strata-Specific Functions -- driver-specific functions
LIII. Motorola MCF52xx ColdFire I2C Bus Driver
Motorola MCF52xx Coldfire I2C Bus Driver -- eCos Support for the Motorola Coldfire I2C Bus
List of Tables
8-1. Behavior of math exception handling