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 I²C Bus Driver

Motorola MCF52xx Coldfire I²C Bus Driver -- eCos Support for the Motorola Coldfire I²C 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

		Next
		The eCos Kernel