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
FLASH Library
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
27. Overview
Description
eCos Support for CAN
28. User API
29. CAN driver details
Description
API Details
Runtime Configuration
30. Configuration
31. Writing a CAN hardware device driver
How to Write a CAN Hardware Interface Driver
XI. eCos POSIX compatibility layer
32. 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
XII. µITRON
33. µ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
XIII. TCP/IP Stack Support for eCos
34. Ethernet Driver Design
35. Sample Code
36. Configuring IP Addresses
37. Tests and Demonstrations
Loopback tests
Building the Network Tests
Standalone Tests
Performance Test
Interactive Tests
Maintenance Tools
38. Support Features
TFTP
DHCP
39. 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
XIV. FreeBSD TCP/IP Stack port for eCos
40. Networking Stack Features
41. Freebsd TCP/IP stack port
Targets
Building the Network Stack
42. APIs
Standard networking
Enhanced Select()
XV. OpenBSD TCP/IP Stack port for eCos
43. Networking Stack Features
Introduction
44. OpenBSD TCP/IP stack port
Targets
Building the Network Stack
Inclusion of bridge code
45. APIs
Standard networking
Enhanced Select()
OpenBSD networking facilities
Bridging
Spanning Tree Protocol
XVI. DNS for eCos and RedBoot
46. DNS
DNS API
DNS Client Testing
XVII. IPSEC for eCos
47. Installation and Configuration
48. libipsec Reference
ipsec_set_policy
ipsec_strerror
XVIII. eCos PPP User Guide
49. Features
50. Using PPP
51. 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
52. Installing and Configuring PPP
Including PPP in a Configuration
Configuring PPP
53. CHAT Scripts
Chat Script
ABORT Strings
TIMEOUT
Sending EOT
Escape Sequences
54. PPP Enabled Device Drivers
55. Testing
Test Programs
Test Script
XIX. Ethernet Device Drivers
56. Generic Ethernet Device Driver
Generic Ethernet API
Review of the functions
Upper Layer Functions
Calling graph for Transmission and Reception
XX. Ethernet PHY Device Support
57. Ethernet PHY Device Support
Ethernet PHY Device API
XXI. SNMP
58. 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
XXII. Embedded HTTP Server
59. Embedded HTTP Server
Intrduction
Server Organization
Server Configuration
Support Functions and Macros
System Monitor
XXIII. FTP Client for eCos TCP/IP Stack
60. FTP Client Features
FTP Client API
XXIV. Simple Network Time Protocol Client
61. 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
XXV. Another Tiny HTTP Server for eCos
62. The ATHTTP Server
Features
Starting the server
MIME types
C language callback functions
CGI
Authentication
Directory Listing
Form Variables
Internal Resources
XXVI. Memory Allocation
63. eCos Memory Pools
eCos Memory pools
XXVII. CRC Algorithms
64. CRC Functions
CRC API
XXVIII. CPU load measurements
65. CPU Load Measurements
CPU Load API
XXIX. gprof Profiling Support
Profiling -- eCos Support for the gprof profiling tool
XXX. 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
XXXI. 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
XXXII. 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
XXXIII. 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
XXXIV. SA11X0 USB Device Driver
SA11X0 USB Device Driver -- Device driver for the on-chip SA11X0 USB device
XXXV. NEC uPD985xx USB Device Driver
NEC uPD985xx USB Device Driver -- Device driver for the on-chip NEC uPD985xx USB device
XXXVI. Synthetic Target Ethernet Driver
Synthetic Target Ethernet Driver -- Allow synthetic target applications to perform ethernet I/O
XXXVII. Synthetic Target Watchdog Device
Synthetic Target Watchdog Device -- Emulate watchdog hardware in the synthetic target
XXXVIII. Dallas DS1307 Wallclock Device Driver
Dallas DS1307 Wallclock Device Driver -- eCos Support for the Dallas DS1307 Serial Real-Time Clock
XXXIX. MMC MultiMedia Card Disk Driver
Device Driver for MMC MultiMedia Cards -- eCos Support for MMC MultiMedia Cards
List of Tables
8-1. Behavior of math exception handling