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.

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://sources.redhat.com/ecos/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. RedBoot™ User's Guide
1. Getting Started with RedBoot
More information about RedBoot on the web
Installing RedBoot
User Interface
RedBoot Editing Commands
RedBoot Startup Mode
RedBoot Resource Usage
Configuring the RedBoot Environment
2. RedBoot Commands and Examples
Introduction
Common Commands
Flash Image System (FIS)
Persistent State Flash-based Configuration and Control
Executing Programs from RedBoot
3. Rebuilding RedBoot
Introduction
4. Updating RedBoot
Introduction
5. Installation and Testing
AM3x/MN103E010 Matsushita MN103E010 (AM33/2.0) ASB2305 Board
ARM/ARM7 ARM Evaluator7T
ARM/ARM7+ARM9 ARM Integrator
ARM/ARM7+ARM9 ARM PID Board and EPI Dev7+Dev9
ARM/ARM7 Atmel AT91 Evaluation Board (EB40)
ARM/ARM7 Cirrus Logic EP7xxx (EDB7211, EDB7212, EDB7312)
ARM/ARM9 Agilent AAED2000
ARM/ARM9 Altera Excalibur
ARM/StrongARM(SA110) Intel EBSA 285
ARM/StrongARM(SA1100) Intel Brutus
ARM/StrongARM(SA1100) Intel SA1100 Multimedia Board
ARM/StrongARM(SA1110) Intel SA1110 (Assabet)
ARM/StrongARM(SA11X0) Bright Star Engineering commEngine and nanoEngine
ARM/StrongARM(SA11X0) Compaq iPAQ PocketPC
ARM/StrongARM(SA11X0) Intrinsyc CerfCube
ARM/Xscale Cyclone IQ80310
ARM/Xscale Intel IQ80321
CalmRISC/CalmRISC16 Samsung CalmRISC16 Core Evaluation Board
CalmRISC/CalmRISC32 Samsung CalmRISC32 Core Evaluation Board
FRV/FRV400 Fujitsu FR-V 400 (MB-93091)
IA32/x86 x86-Based PC
MIPS/MIPS32(CoreLV 4Kc)+MIPS64(CoreLV 5Kc) Atlas Board
MIPS/MIPS32(CoreLV 4Kc)+MIPS64(CoreLV 5Kc) Malta Board
MIPS/RM7000 PMC-Sierra Ocelot
MIPS/VR4375 NEC DDB-VRC4375
PowerPC/MPC860T Analogue & Micro PowerPC 860T
PowerPC/MPC8XX Motorola MBX
SuperH/SH3(SH7708) Hitachi EDK7708
SuperH/SH3(SH7709) Hitachi Solution Engine 7709
SuperH/SH3(SH7729) Hitachi HS7729PCI
SuperH/SH3(SH77X9) Hitachi Solution Engine 77X9
SuperH/SH4(SH7751) Hitachi Solution Engine 7751
III. The eCos Hardware Abstraction Layer (HAL)
6. Introduction
7. Architecture, Variant and Platform
8. General principles
9. HAL Interfaces
Base Definitions
Architecture Characterization
Interrupt Handling
HAL I/O
Cache Control
Linker Scripts
Diagnostic Support
SMP Support
10. Exception Handling
HAL Startup
Vectors and VSRs
Default Synchronous Exception Handling
Default Interrupt Handling
11. Porting Guide
Introduction
HAL Structure
Virtual Vectors (eCos/ROM Monitor Calling Interface)
HAL Coding Conventions
Platform HAL Porting
Variant HAL Porting
Architecture HAL Porting
12. Future developments
IV. The ISO Standard C and Math Libraries
13. C and math library overview
Included non-ISO functions
Math library compatibility modes
Some implementation details
Thread safety
C library startup
V. I/O Package (Device Drivers)
14. Introduction
15. User API
16. Serial driver details
Raw Serial Driver
TTY driver
17. How to Write a Driver
How to Write a Serial Hardware Interface Driver
Serial testing with ser_filter
18. Device Driver Interface to the Kernel
Interrupt Model
Synchronization
SMP Support
Device Driver Models
Synchronization Levels
The API
VI. File System Support Infrastructure
19. Introduction
20. File System Table
21. Mount Table
22. File Table
23. Directories
24. Synchronization
25. Initialization and Mounting
26. Sockets
27. Select
28. Devices
29. Writing a New Filesystem
VII. PCI Library
30. The eCos PCI Library
PCI Library
PCI Library reference
VIII. eCos POSIX compatibility layer
31. 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
IX. µITRON
32. µ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
X. TCP/IP Stack Support for eCos
33. Ethernet Driver Design
34. Sample Code
35. Configuring IP Addresses
36. Tests and Demonstrations
Loopback tests
Building the Network Tests
Standalone Tests
Performance Test
Interactive Tests
Maintenance Tools
37. Support Features
TFTP
DHCP
38. 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
socketpair
XI. FreeBSD TCP/IP Stack port for eCos
39. Networking Stack Features
40. Freebsd TCP/IP stack port
Targets
Building the Network Stack
41. APIs
Standard networking
Enhanced Select()
XII. OpenBSD TCP/IP Stack port for eCos
42. Networking Stack Features
43. OpenBSD TCP/IP stack port
Targets
Building the Network Stack
44. APIs
Standard networking
Enhanced Select()
XIII. DNS for eCos and RedBoot
45. DNS
DNS API
XIV. Ethernet Device Drivers
46. Generic Ethernet Device Driver
Generic Ethernet API
Review of the functions
Upper Layer Functions
Calling graph for Transmission and Reception
XV. SNMP
47. 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
XVI. Embedded HTTP Server
48. Embedded HTTP Server
Intrduction
Server Organization
Server Configuration
Support Functions and Macros
System Monitor
XVII. FTP Client for eCos TCP/IP Stack
49. FTP Client Features
FTP Client API
XVIII. CRC Algorithms
50. CRC Functions
CRC API
XIX. CPU load measurements
51. CPU Load Measurements
CPU Load API
XX. Application profiling
52. Profiling functions
API
XXI. 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
XXII. 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
XXIII. 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
XXIV. 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
XXV. SA11X0 USB Device Driver
SA11X0 USB Device Driver -- Device driver for the on-chip SA11X0 USB device
XXVI. NEC uPD985xx USB Device Driver
NEC uPD985xx USB Device Driver -- Device driver for the on-chip NEC uPD985xx USB device
XXVII. Synthetic Target Ethernet Driver
Synthetic Target Ethernet Driver -- Allow synthetic target applications to perform ethernet I/O
XXVIII. Synthetic Target Watchdog Device
Synthetic Target Watchdog Device -- Emulate watchdog hardware in the synthetic target
List of Tables
13-1. Behavior of math exception handling
List of Examples
1-1. Sample DHCP configuration file
1-2. Sample /etc/named.conf for Red Hat Linux 7.x