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.

eCos® is a registered trademark of eCosCentric Limited.

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, 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. The uSTL Library
9. uSTL library overview
eCos specific changes/enhancements
Using uSTL in eCos applications
V. I/O Package (Device Drivers)
10. Introduction
11. User API
12. Serial driver details
Raw Serial Driver
TTY driver
13. How to Write a Driver
How to Write a Serial Hardware Interface Driver
Serial testing with ser_filter
14. Device Driver Interface to the Kernel
Interrupt Model
Synchronization
SMP Support
Device Driver Models
Synchronization Levels
The API
VI. File System Support Infrastructure
15. Introduction
16. File System Table
17. Mount Table
18. File Table
19. Directories
20. Synchronization
21. Initialization and Mounting
22. Sockets
23. Select
24. Devices
25. Writing a New Filesystem
VII. PCI Library
26. The eCos PCI Library
PCI Library
PCI Library reference
VIII. FLASH Library
27. The eCos FLASH Library
Notes on using the FLASH library
Danger, Will Robinson! Danger!
28. The Version 2 eCos FLASH API
FLASH user API
FLASH device API
29. The legacy Version 1 eCos FLASH API
FLASH user API
FLASH device API
30. FLASH I/O devices
Overview and CDL Configuration
Using FLASH I/O devices
IX. 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
X. 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
XI. CAN Support
31. Overview
Description
eCos Support for CAN
32. User API
33. CAN driver details
Description
API Details
Runtime Configuration
34. Configuration
35. Writing a CAN hardware device driver
How to Write a CAN Hardware Interface Driver
XII. ADC Support
Overview -- eCos Support for Analog/Digital Converters
ADC Device Drivers -- ADC Device Drivers
XIII. 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
XIV. eCos POSIX compatibility layer
36. 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
XV. µITRON
37. µ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
XVI. TCP/IP Stack Support for eCos
38. Ethernet Driver Design
39. Sample Code
40. Configuring IP Addresses
41. Tests and Demonstrations
Loopback tests
Building the Network Tests
Standalone Tests
Performance Test
Interactive Tests
Maintenance Tools
42. Support Features
TFTP
DHCP
43. 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
XVII. FreeBSD TCP/IP Stack port for eCos
44. Networking Stack Features
45. Freebsd TCP/IP stack port
Targets
Building the Network Stack
46. APIs
Standard networking
Enhanced Select()
Disabling IPv6 Support at Runtime
XVIII. OpenBSD TCP/IP Stack port for eCos
47. Networking Stack Features
Introduction
48. OpenBSD TCP/IP stack port
Targets
Building the Network Stack
Inclusion of bridge code
49. APIs
Standard networking
Enhanced Select()
OpenBSD networking facilities
Bridging
Spanning Tree Protocol
XIX. DNS for eCos and RedBoot
50. DNS
DNS API
DNS Client Testing
XX. IPSEC for eCos
51. Installation and Configuration
52. libipsec Reference
ipsec_set_policy
ipsec_strerror
XXI. eCos PPP User Guide
53. Features
54. Using PPP
55. 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
56. Installing and Configuring PPP
Including PPP in a Configuration
Configuring PPP
57. CHAT Scripts
Chat Script
ABORT Strings
TIMEOUT
Sending EOT
Escape Sequences
58. PPP Enabled Device Drivers
59. Testing
Test Programs
Test Script
XXII. Ethernet Device Drivers
60. Generic Ethernet Device Driver
Generic Ethernet API
Review of the functions
Upper Layer Functions
Calling graph for Transmission and Reception
XXIII. Ethernet PHY Device Support
61. Ethernet PHY Device Support
Ethernet PHY Device API
XXIV. SNMP
62. 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
XXV. Embedded HTTP Server
63. Embedded HTTP Server
Intrduction
Server Organization
Server Configuration
Support Functions and Macros
System Monitor
XXVI. FTP Client for eCos TCP/IP Stack
64. FTP Client Features
FTP Client API
XXVII. Simple Network Time Protocol Client
65. 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
XXVIII. Another Tiny HTTP Server for eCos
66. The ATHTTP Server
Features
Starting the server
MIME types
C language callback functions
CGI
Authentication
Directory Listing
Form Variables
Internal Resources
XXIX. Memory Allocation
67. eCos Memory Pools
eCos Memory pools
XXX. CRC Algorithms
68. CRC Functions
CRC API
XXXI. CPU load measurements
69. CPU Load Measurements
CPU Load API
XXXII. gprof Profiling Support
Profiling -- eCos Support for the gprof profiling tool
XXXIII. 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
XXXIV. 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
XXXV. 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
XXXVI. 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
XXXVII. eCos Support for USB Mass Storage Peripherals
Introduction --  eCos support for USB Mass Storage Peripherals
Configuration -- Configuration USB Mass Storage Peripherals
Host Configuration -- Host Configuration for USB Mass Storage like Peripherals
Example -- Example for USB Mass Storage like Peripherals
XXXVIII. 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
XXXIX. M68000 Architectural Support
Overview -- eCos Support for the M68K Family of Processors
Configuration -- Configuring the M68K Architectural Package
The HAL Port -- Implementation Details
XL. Freescale MCFxxxx Variant Support
MCFxxxx ColdFire Processors -- eCos Support for Freescale MCFxxxx Processors
XLI. Freescale MCF5272 Processor Support
The MCF5272 ColdFire Processor -- eCos Support for the Freescale MCF5272 Processor
XLII. Freescale M5272C3 Board Support
Overview -- Overview
Setup -- Preparing the M5272C3 board for eCos Development
Configuration -- Platform-specific Configuration Options
The HAL Port -- Implementation Details
XLIII. Freescale Kinetis Family Support
Freescale Kinetis Variant -- eCos Support for Freescale Kinetis Micro-controllers
TWR-K70F120M Development kit -- eCos Support for Freescale TWR-K70F120M development kit
TWR-K60N512-KIT Development kit -- eCos Support for the Freescale TWR-K60N512 development kit
TWR-K40X256-KIT Development kit -- eCos Support for the Freescale TWR-K40X256 development kit
XLIV. Actel Smartfusion Board Support
70. Actel Smartfusion Board Support
Overview -- Actel Smartfusion Board Support
HAL and Device Drivers -- Actel HAL and Device Drivers
Configuration -- Configure, compile and debug the application
XLV. Stellaris EKK-LM3S811 Board Support
Overview -- Overview
XLVI. 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
XLVII. SA11X0 USB Device Driver
SA11X0 USB Device Driver -- Device driver for the on-chip SA11X0 USB device
XLVIII. NEC uPD985xx USB Device Driver
NEC uPD985xx USB Device Driver -- Device driver for the on-chip NEC uPD985xx USB device
XLIX. Synthetic Target Ethernet Driver
Synthetic Target Ethernet Driver -- Allow synthetic target applications to perform ethernet I/O
L. Freescale ColdFire Ethernet Driver
Freescale ColdFire Ethernet Driver -- eCos Support for Freescale ColdFire On-chip Ethernet Devices
LI. Freescale MCFxxxx Serial Driver
MCFxxxx Serial Driver -- eCos Support for the MCFxxxx On-chip Serial Devices
LII. Synthetic Target Watchdog Device
Synthetic Target Watchdog Device -- Emulate watchdog hardware in the synthetic target
LIII. Dallas DS1307 Wallclock Device Driver
Dallas DS1307 Wallclock Device Driver -- eCos Support for the Dallas DS1307 Serial Real-Time Clock
LIV. MMC MultiMedia Card Disk Driver
Device Driver for MMC MultiMedia Cards -- eCos Support for MMC MultiMedia Cards
LV. Synthetic Target Framebuffer Device
Synthetic Target Framebuffer Device -- Emulate framebuffer hardware in the synthetic target
LVI. 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
LVII. 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
LVIII. 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
1. Linker script name segments
1. TWR-K70F120M Jumper setting
1. TWR-K60N512 Jumper setting differences from factory settings
2. TWR-SER Jumper settings differences from factory settings