eCos Reference Manual

eCos Reference ManualCopyright 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.

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 (http://www.gnu.org/copyleft/gpl.html),

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 ContentsI. The eCos Kernel ....................................................................................................................................... xxiii

Kernel Overview ..................................................................................................................................... 25SMP Support ........................................................................................................................................... 33Thread creation ....................................................................................................................................... 37Thread information ................................................................................................................................. 41Thread control ......................................................................................................................................... 45Thread termination .................................................................................................................................. 47Thread priorities ...................................................................................................................................... 49Per-thread data ........................................................................................................................................ 51Thread destructors................................................................................................................................... 53Exception handling ................................................................................................................................. 55Counters .................................................................................................................................................. 57Clocks...................................................................................................................................................... 59Alarms..................................................................................................................................................... 61Mutexes ................................................................................................................................................... 63Condition Variables................................................................................................................................. 69Semaphores ............................................................................................................................................. 73Mail boxes............................................................................................................................................... 75Event Flags.............................................................................................................................................. 77Spinlocks ................................................................................................................................................. 81Scheduler Control ................................................................................................................................... 83Interrupt Handling................................................................................................................................... 85Kernel Real-time Characterization.......................................................................................................... 91

II. The eCos Hardware Abstraction Layer (HAL) ........................................................................................ci1. Introduction ........................................................................................................................................... 12. Architecture, Variant and Platform ....................................................................................................... 33. General principles ................................................................................................................................. 54. HAL Interfaces...................................................................................................................................... 7

Base Definitions............................................................................................................................... 7Byte order............................................................................................................................... 7Label Translation ................................................................................................................... 7Base types .............................................................................................................................. 7Atomic types .......................................................................................................................... 8

Architecture Characterization.......................................................................................................... 8Register Save Format ............................................................................................................. 8Thread Context Initialization ................................................................................................. 8Thread Context Switching ..................................................................................................... 9Bit indexing............................................................................................................................ 9Idle thread activity ............................................................................................................... 10Reorder barrier ..................................................................................................................... 10Breakpoint support............................................................................................................... 10GDB support ........................................................................................................................ 10Setjmp and longjmp support ................................................................................................ 11Stack Sizes ........................................................................................................................... 11Address Translation ............................................................................................................. 11Global Pointer ...................................................................................................................... 12

Interrupt Handling ......................................................................................................................... 12Vector numbers .................................................................................................................... 12Interrupt state control........................................................................................................... 13

v

ISR and VSR management .................................................................................................. 13Interrupt controller management.......................................................................................... 14

Clocks and Timers ......................................................................................................................... 15Clock Control....................................................................................................................... 15Microsecond Delay .............................................................................................................. 15Clock Frequency Definition................................................................................................. 16

HAL I/O......................................................................................................................................... 17Register address ................................................................................................................... 17Register read ........................................................................................................................ 17Register write ....................................................................................................................... 18

Cache Control ................................................................................................................................ 18Cache Dimensions ............................................................................................................... 19Global Cache Control .......................................................................................................... 19Cache Line Control .............................................................................................................. 20

Linker Scripts ................................................................................................................................ 21Diagnostic Support ........................................................................................................................ 22SMP Support ................................................................................................................................. 22

Target Hardware Limitations ............................................................................................... 23HAL Support........................................................................................................................ 23

CPU Control ............................................................................................................... 24Test-and-set Support................................................................................................... 24Spinlocks .................................................................................................................... 25Scheduler Lock........................................................................................................... 25Interrupt Routing ........................................................................................................ 26

5. Exception Handling............................................................................................................................. 27HAL Startup .................................................................................................................................. 27Vectors and VSRs .......................................................................................................................... 28Default Synchronous Exception Handling .................................................................................... 30Default Interrupt Handling ............................................................................................................ 30

6. Porting Guide ...................................................................................................................................... 33Introduction ................................................................................................................................... 33HAL Structure ............................................................................................................................... 33

HAL Classes ........................................................................................................................ 33File Descriptions .................................................................................................................. 34

Common HAL............................................................................................................ 34Architecture HAL....................................................................................................... 35Variant HAL ............................................................................................................... 36Platform HAL............................................................................................................. 37Auxiliary HAL ........................................................................................................... 37

Virtual Vectors (eCos/ROM Monitor Calling Interface) ............................................................... 37Virtual Vectors ..................................................................................................................... 38

Initialization (or Mechanism vs. Policy) .................................................................... 38Pros and Cons of Virtual Vectors ............................................................................... 38Available services....................................................................................................... 39

The COMMS channels ........................................................................................................ 40Console and Debugging Channels ............................................................................. 40Mangling .................................................................................................................... 40Controlling the Console Channel ............................................................................... 40Footnote: Design Reasoning for Control of Console Channel................................... 41

The calling Interface API..................................................................................................... 42Implemented Services ................................................................................................ 42Compatibility.............................................................................................................. 43

vi

Implementation details ............................................................................................... 44New Platform Ports .................................................................................................... 44New architecture ports................................................................................................ 44

IO channels .......................................................................................................................... 44Available Procedures .................................................................................................. 45Usage.......................................................................................................................... 46Compatibility.............................................................................................................. 46Implementation Details .............................................................................................. 46New Platform Ports .................................................................................................... 47

HAL Coding Conventions ............................................................................................................. 47Implementation issues.......................................................................................................... 48Source code details .............................................................................................................. 48Nested Headers .................................................................................................................... 49

Platform HAL Porting ................................................................................................................... 50HAL Platform Porting Process ............................................................................................ 50

Brief overview ............................................................................................................ 50Step-by-step................................................................................................................ 51

Minimal requirements....................................................................................... 51Adding features................................................................................................. 52

Hints ........................................................................................................................... 53HAL Platform CDL ............................................................................................................. 54

eCos Database ............................................................................................................ 54CDL File Layout ........................................................................................................ 55Startup Type ............................................................................................................... 56Build options .............................................................................................................. 56Common Target Options ............................................................................................ 57

Platform Memory Layout .................................................................................................... 60Layout Files................................................................................................................ 60Reserved Regions ....................................................................................................... 61

Platform Serial Device Support ........................................................................................... 61Variant HAL Porting...................................................................................................................... 62

HAL Variant Porting Process............................................................................................... 63HAL Variant CDL................................................................................................................ 63Cache Support...................................................................................................................... 65

Architecture HAL Porting ............................................................................................................. 65HAL Architecture Porting Process ...................................................................................... 65CDL Requirements .............................................................................................................. 70

7. Future developments ........................................................................................................................... 75

III. The ISO Standard C and Math Libraries ............................................................................................. 778. C and math library overview............................................................................................................... 79

Included non-ISO functions .......................................................................................................... 79Math library compatibility modes ................................................................................................. 80

matherr() .............................................................................................................................. 80Thread-safety and re-entrancy ............................................................................................. 82

Some implementation details ........................................................................................................ 82Thread safety ................................................................................................................................. 83C library startup............................................................................................................................. 84

vii

IV. I/O Package (Device Drivers) .................................................................................................................. 879. Introduction ......................................................................................................................................... 8910. User API............................................................................................................................................ 9111. Serial driver details............................................................................................................................ 93

Raw Serial Driver .......................................................................................................................... 93Runtime Configuration ........................................................................................................ 93API Details........................................................................................................................... 94

cyg_io_write............................................................................................................... 95cyg_io_read ................................................................................................................ 95cyg_io_get_config ...................................................................................................... 95cyg_io_set_config....................................................................................................... 97

TTY driver ..................................................................................................................................... 98Runtime configuration ......................................................................................................... 99API details............................................................................................................................ 99

12. How to Write a Driver..................................................................................................................... 101How to Write a Serial Hardware Interface Driver ....................................................................... 102

DevTab Entry ..................................................................................................................... 102Serial Channel Structure .................................................................................................... 103Serial Functions Structure.................................................................................................. 104Callbacks............................................................................................................................ 105

Serial testing with ser_filter......................................................................................................... 106Rationale ............................................................................................................................ 106The Protocol....................................................................................................................... 106The Serial Tests.................................................................................................................. 107Serial Filter Usage.............................................................................................................. 108A Note on Failures ............................................................................................................. 109Debugging.......................................................................................................................... 109

13. Device Driver Interface to the Kernel ............................................................................................. 111Interrupt Model............................................................................................................................ 111Synchronization........................................................................................................................... 111SMP Support ............................................................................................................................... 112Device Driver Models.................................................................................................................. 112Synchronization Levels ............................................................................................................... 113The API ....................................................................................................................................... 114

cyg_drv_isr_lock................................................................................................................ 114cyg_drv_isr_unlock............................................................................................................ 114cyg_drv_spinlock_init........................................................................................................ 115cyg_drv_spinlock_destroy ................................................................................................. 115cyg_drv_spinlock_spin ...................................................................................................... 116cyg_drv_spinlock_clear ..................................................................................................... 116cyg_drv_spinlock_try ........................................................................................................ 116cyg_drv_spinlock_test ....................................................................................................... 117cyg_drv_spinlock_spin_intsave ......................................................................................... 117cyg_drv_spinlock_clear_intsave ........................................................................................ 118cyg_drv_dsr_lock............................................................................................................... 118cyg_drv_dsr_unlock........................................................................................................... 119cyg_drv_mutex_init ........................................................................................................... 119cyg_drv_mutex_destroy..................................................................................................... 119cyg_drv_mutex_lock.......................................................................................................... 120cyg_drv_mutex_trylock ..................................................................................................... 120cyg_drv_mutex_unlock...................................................................................................... 121

viii

cyg_drv_mutex_release ..................................................................................................... 121cyg_drv_cond_init ............................................................................................................. 122cyg_drv_cond_destroy ....................................................................................................... 122cyg_drv_cond_wait............................................................................................................ 122cyg_drv_cond_signal ......................................................................................................... 123cyg_drv_cond_broadcast ................................................................................................... 123cyg_drv_interrupt_create ................................................................................................... 124cyg_drv_interrupt_delete ................................................................................................... 124cyg_drv_interrupt_attach ................................................................................................... 125cyg_drv_interrupt_detach .................................................................................................. 125cyg_drv_interrupt_mask .................................................................................................... 126cyg_drv_interrupt_mask_intunsafe.................................................................................... 126cyg_drv_interrupt_unmask ................................................................................................ 126cyg_drv_interrupt_unmask_intunsafe................................................................................ 127cyg_drv_interrupt_acknowledge........................................................................................ 127cyg_drv_interrupt_configure.............................................................................................. 128cyg_drv_interrupt_level ..................................................................................................... 128cyg_drv_interrupt_set_cpu ................................................................................................ 129cyg_drv_interrupt_get_cpu ................................................................................................ 129cyg_ISR_t .......................................................................................................................... 130cyg_DSR_t......................................................................................................................... 130

V. File System Support Infrastructure ....................................................................................................... 13314. Introduction ..................................................................................................................................... 13515. File System Table ............................................................................................................................ 13716. Mount Table .................................................................................................................................... 13917. File Table......................................................................................................................................... 14118. Directories ....................................................................................................................................... 14319. Synchronization .............................................................................................................................. 14520. Initialization and Mounting............................................................................................................. 14721. Sockets ............................................................................................................................................ 14922. Select ............................................................................................................................................... 15123. Devices ............................................................................................................................................ 15324. Writing a New Filesystem............................................................................................................... 155

VI. PCI Library ............................................................................................................................................ 15925. The eCos PCI Library ..................................................................................................................... 161

PCI Library.................................................................................................................................. 161PCI Overview..................................................................................................................... 161Initializing the bus.............................................................................................................. 161Scanning for devices .......................................................................................................... 161Generic config information ................................................................................................ 162Specific config information................................................................................................ 163Allocating memory ............................................................................................................ 163Interrupts ............................................................................................................................ 164Activating a device............................................................................................................. 164Links .................................................................................................................................. 165

PCI Library reference .................................................................................................................. 165PCI Library API................................................................................................................. 165Definitions.......................................................................................................................... 165Types and data structures ................................................................................................... 165Functions............................................................................................................................ 166Resource allocation............................................................................................................ 168

ix

PCI Library Hardware API ................................................................................................ 169HAL PCI support ............................................................................................................... 169

VII. FLASH Library .................................................................................................................................... 17126. The eCos FLASH Library............................................................................................................... 173

Notes on using the FLASH library.............................................................................................. 173Danger, Will Robinson! Danger!................................................................................................. 173

27. The Version 2 eCos FLASH API .................................................................................................... 175FLASH user API ......................................................................................................................... 175

Initializing the FLASH library........................................................................................... 175Retrieving information about FLASH devices .................................................................. 175Reading from FLASH........................................................................................................ 175Erasing areas of FLASH .................................................................................................... 176Programming the FLASH.................................................................................................. 176Locking and unlocking blocks ........................................................................................... 176Locking FLASH mutexes .................................................................................................. 176Configuring diagnostic output ........................................................................................... 177Return values and errors .................................................................................................... 177

FLASH device API...................................................................................................................... 177The FLASH device Structure............................................................................................. 178

28. The legacy Version 1 eCos FLASH API......................................................................................... 179FLASH user API ......................................................................................................................... 179

Initializing the FLASH library........................................................................................... 179Retrieving information about the FLASH ......................................................................... 179Reading from FLASH........................................................................................................ 180Erasing areas of FLASH .................................................................................................... 180Programming the FLASH.................................................................................................. 180Locking and unlocking blocks ........................................................................................... 180Return values and errors .................................................................................................... 180Notes on using the FLASH library .................................................................................... 181

FLASH device API...................................................................................................................... 181The flash_info structure ..................................................................................................... 181Initializing the device driver .............................................................................................. 182Querying the FLASH......................................................................................................... 182Erasing a block of FLASH................................................................................................. 182Programming a region of FLASH...................................................................................... 182Reading a region from FLASH.......................................................................................... 182Locking and unlocking FLASH blocks ............................................................................. 183Mapping FLASH error codes to FLASH IO error codes................................................... 183Determining if code is in FLASH...................................................................................... 183Implementation Notes........................................................................................................ 183

29. FLASH I/O devices......................................................................................................................... 185Overview and CDL Configuration .............................................................................................. 185Using FLASH I/O devices........................................................................................................... 186

VIII. SPI Support.......................................................................................................................................... 189Overview ............................................................................................................................................... 191SPI Interface.......................................................................................................................................... 195Porting to New Hardware...................................................................................................................... 199

x

IX. I2C Support ............................................................................................................................................ 201Overview ............................................................................................................................................... 203I2C Interface.......................................................................................................................................... 205Porting to New Hardware...................................................................................................................... 209

X. CAN Support............................................................................................................................................ 21530. Overview ......................................................................................................................................... 217

Description .................................................................................................................................. 217eCos Support for CAN ................................................................................................................ 217

31. User API.......................................................................................................................................... 21932. CAN driver details .......................................................................................................................... 221

Description .................................................................................................................................. 221API Details .................................................................................................................................. 221

cyg_io_write ...................................................................................................................... 221CAN Messages................................................................................................................... 221cyg_io_read........................................................................................................................ 222CAN Events ....................................................................................................................... 223cyg_io_get_config.............................................................................................................. 224cyg_io_set_config .............................................................................................................. 225

Runtime Configuration ................................................................................................................ 225Device configuration .......................................................................................................... 225Timeout configuration........................................................................................................ 226Reading buffer configuration ............................................................................................. 226Reading hardware description information........................................................................ 227Reading hardware message buffer configuration............................................................... 228Reading state of CAN hardware ........................................................................................ 228Changing mode of CAN hardware .................................................................................... 228Flush or drain buffers ......................................................................................................... 229Configuring blocking/non-blocking calls .......................................................................... 229Message buffer management ............................................................................................. 230Remote frame response buffer configuration..................................................................... 231Message filter configuration............................................................................................... 232Message filter deactivation................................................................................................. 234Configuring a callback on events ....................................................................................... 234

33. Configuration .................................................................................................................................. 23734. Writing a CAN hardware device driver .......................................................................................... 239

How to Write a CAN Hardware Interface Driver........................................................................ 239DevTab Entry ..................................................................................................................... 239CAN Channel Structure ..................................................................................................... 240CAN Lowlevel Functions Structure................................................................................... 241Callbacks............................................................................................................................ 242

XI. ADC Support .......................................................................................................................................... 243Overview ............................................................................................................................................... 245ADC Device Drivers ............................................................................................................................. 249

XII. Framebuffer Support ........................................................................................................................... 253Overview ............................................................................................................................................... 255Framebuffer Parameters ........................................................................................................................ 259Framebuffer Control Operations ........................................................................................................... 263Framebuffer Colours ............................................................................................................................. 269Framebuffer Drawing Primitives........................................................................................................... 275Framebuffer Pixel Manipulation ........................................................................................................... 281

xi

Writing a Framebuffer Device Driver ................................................................................................... 285

XIII. eCos POSIX compatibility layer ........................................................................................................ 29335. POSIX Standard Support ................................................................................................................ 295

Process Primitives [POSIX Section 3] ........................................................................................ 295Functions Implemented...................................................................................................... 295Functions Omitted.............................................................................................................. 295Notes .................................................................................................................................. 296

Process Environment [POSIX Section 4] .................................................................................... 296Functions Implemented...................................................................................................... 296Functions Omitted.............................................................................................................. 296Notes .................................................................................................................................. 297

Files and Directories [POSIX Section 5]..................................................................................... 297Functions Implemented...................................................................................................... 297Functions Omitted.............................................................................................................. 298Notes .................................................................................................................................. 298

Input and Output [POSIX Section 6]........................................................................................... 298Functions Implemented...................................................................................................... 298Functions Omitted.............................................................................................................. 299Notes .................................................................................................................................. 299

Device and Class Specific Functions [POSIX Section 7]............................................................ 299Functions Implemented...................................................................................................... 299Functions Omitted.............................................................................................................. 299Notes .................................................................................................................................. 299

C Language Services [POSIX Section 8].................................................................................... 300Functions Implemented...................................................................................................... 300Functions Omitted.............................................................................................................. 300Notes .................................................................................................................................. 300

System Databases [POSIX Section 9]......................................................................................... 301Functions Implemented...................................................................................................... 301Functions Omitted.............................................................................................................. 301Notes .................................................................................................................................. 301

Data Interchange Format [POSIX Section 10] ............................................................................ 301Synchronization [POSIX Section 11].......................................................................................... 301

Functions Implemented...................................................................................................... 301Functions Omitted.............................................................................................................. 302Notes .................................................................................................................................. 302

Memory Management [POSIX Section 12] ................................................................................ 303Functions Implemented...................................................................................................... 303Functions Omitted.............................................................................................................. 303Notes .................................................................................................................................. 303

Execution Scheduling [POSIX Section 13]................................................................................. 303Functions Implemented...................................................................................................... 303Functions Omitted.............................................................................................................. 304Notes .................................................................................................................................. 304

Clocks and Timers [POSIX Section 14]...................................................................................... 304Functions Implemented...................................................................................................... 305Functions Omitted.............................................................................................................. 305Notes .................................................................................................................................. 305

Message Passing [POSIX Section 15]......................................................................................... 305Functions Implemented...................................................................................................... 305Functions Omitted.............................................................................................................. 306

xii

Notes .................................................................................................................................. 306Thread Management [POSIX Section 16]................................................................................... 306

Functions Implemented...................................................................................................... 306Functions Omitted.............................................................................................................. 306Notes .................................................................................................................................. 307

Thread-Specific Data [POSIX Section 17].................................................................................. 307Functions Implemented...................................................................................................... 307Functions Omitted.............................................................................................................. 307Notes .................................................................................................................................. 307

Thread Cancellation [POSIX Section 18] ................................................................................... 308Functions Implemented...................................................................................................... 308Functions Omitted.............................................................................................................. 308Notes .................................................................................................................................. 308

Non-POSIX Functions................................................................................................................. 308General I/O Functions........................................................................................................ 308Socket Functions................................................................................................................ 308Notes .................................................................................................................................. 309

References and Bibliography ................................................................................................................ 311

XIV. ITRON................................................................................................................................................ 31136. ITRON API................................................................................................................................... 313

Introduction to ITRON.............................................................................................................. 313ITRON and eCos ....................................................................................................................... 313Task Management Functions ....................................................................................................... 314

Error checking.................................................................................................................... 315Task-Dependent Synchronization Functions ............................................................................... 315

Error checking.................................................................................................................... 316Synchronization and Communication Functions......................................................................... 316

Error checking.................................................................................................................... 318Extended Synchronization and Communication Functions ........................................................ 319Interrupt management functions.................................................................................................. 319

Error checking.................................................................................................................... 320Memory pool Management Functions......................................................................................... 320

Error checking.................................................................................................................... 321Time Management Functions ...................................................................................................... 322

Error checking.................................................................................................................... 323System Management Functions................................................................................................... 323

Error checking.................................................................................................................... 324Network Support Functions......................................................................................................... 324ITRON Configuration FAQ....................................................................................................... 324

XV. TCP/IP Stack Support for eCos........................................................................................................... 32937. Ethernet Driver Design.................................................................................................................... 33138. Sample Code ................................................................................................................................... 33339. Configuring IP Addresses ............................................................................................................... 33540. Tests and Demonstrations ............................................................................................................... 337

Loopback tests ............................................................................................................................. 337Building the Network Tests ......................................................................................................... 337Standalone Tests .......................................................................................................................... 337Performance Test ......................................................................................................................... 338Interactive Tests ........................................................................................................................... 339Maintenance Tools....................................................................................................................... 340

41. Support Features ............................................................................................................................. 341

xiii

TFTP............................................................................................................................................ 341DHCP .......................................................................................................................................... 343

42. TCP/IP Library Reference .............................................................................................................. 345getdomainname............................................................................................................................ 345gethostname................................................................................................................................. 346byteorder...................................................................................................................................... 347ethers............................................................................................................................................ 348getaddrinfo................................................................................................................................... 350gethostbyname............................................................................................................................. 355getifaddrs ..................................................................................................................................... 357getnameinfo ................................................................................................................................. 359getnetent ...................................................................................................................................... 362getprotoent ................................................................................................................................... 363getrrsetbyname ............................................................................................................................ 365getservent..................................................................................................................................... 366if_nametoindex ............................................................................................................................ 368inet ............................................................................................................................................... 369inet6_option_space ...................................................................................................................... 372inet6_rthdr_space ........................................................................................................................ 376inet_net ........................................................................................................................................ 379ipx ................................................................................................................................................ 380iso_addr ....................................................................................................................................... 381link_addr...................................................................................................................................... 382net_addrcmp ................................................................................................................................ 383ns.................................................................................................................................................. 384resolver ........................................................................................................................................ 385accept ........................................................................................................................................... 388bind .............................................................................................................................................. 389connect......................................................................................................................................... 391getpeername................................................................................................................................. 392getsockname ................................................................................................................................ 394getsockopt.................................................................................................................................... 395ioctl .............................................................................................................................................. 398poll ............................................................................................................................................... 399select ............................................................................................................................................ 401send.............................................................................................................................................. 403shutdown...................................................................................................................................... 406socket ........................................................................................................................................... 406

XVI. FreeBSD TCP/IP Stack port for eCos ............................................................................................... 41143. Networking Stack Features ............................................................................................................. 41344. Freebsd TCP/IP stack port .............................................................................................................. 415

Targets ......................................................................................................................................... 415Building the Network Stack ........................................................................................................ 415

45. APIs................................................................................................................................................. 417Standard networking.................................................................................................................... 417Enhanced Select() ........................................................................................................................ 417

xiv

XVII. OpenBSD TCP/IP Stack port for eCos ............................................................................................ 41946. Networking Stack Features ............................................................................................................. 421

Introduction ................................................................................................................................. 42147. OpenBSD TCP/IP stack port........................................................................................................... 423

Targets ......................................................................................................................................... 423Building the Network Stack ........................................................................................................ 423Inclusion of bridge code .............................................................................................................. 423

48. APIs................................................................................................................................................. 425Standard networking.................................................................................................................... 425Enhanced Select() ........................................................................................................................ 425OpenBSD networking facilities................................................................................................... 426Bridging....................................................................................................................................... 429Spanning Tree Protocol ............................................................................................................... 436

XVIII. DNS for eCos and RedBoot ............................................................................................................. 43949. DNS................................................................................................................................................. 441

DNS API...................................................................................................................................... 441DNS Client Testing...................................................................................................................... 442

XIX. IPSEC for eCos .................................................................................................................................... 44550. Installation and Configuration......................................................................................................... 44751. libipsec Reference ........................................................................................................................... 449

ipsec_set_policy .......................................................................................................................... 449ipsec_strerror ............................................................................................................................... 451

XX. eCos PPP User Guide............................................................................................................................ 45352. Features ........................................................................................................................................... 45553. Using PPP ....................................................................................................................................... 45754. PPP Interface................................................................................................................................... 461

cyg_ppp_options_init()................................................................................................................ 461cyg_ppp_up()............................................................................................................................... 465cyg_ppp_down() .......................................................................................................................... 467cyg_ppp_wait_up() ...................................................................................................................... 469cyg_ppp_wait_down() ................................................................................................................. 471cyg_ppp_chat() ............................................................................................................................ 473

55. Installing and Configuring PPP....................................................................................................... 475Including PPP in a Configuration ................................................................................................ 475Configuring PPP .......................................................................................................................... 475

56. CHAT Scripts .................................................................................................................................. 479Chat Script ................................................................................................................................... 479ABORT Strings ........................................................................................................................... 480TIMEOUT ................................................................................................................................... 480Sending EOT ............................................................................................................................... 481Escape Sequences........................................................................................................................ 481

57. PPP Enabled Device Drivers........................................................................................................... 48358. Testing ............................................................................................................................................. 485

Test Programs .............................................................................................................................. 485Test Script .................................................................................................................................... 486

xv

XXI. Ethernet Device Drivers...................................................................................................................... 48959. Generic Ethernet Device Driver ...................................................................................................... 491

Generic Ethernet API .................................................................................................................. 491Review of the functions ............................................................................................................... 493

Init function........................................................................................................................ 493Start function...................................................................................................................... 494Stop function...................................................................................................................... 494Control function ................................................................................................................. 494Can-send function .............................................................................................................. 495Send function ..................................................................................................................... 495Deliver function ................................................................................................................. 496Receive function ................................................................................................................ 497Poll function....................................................................................................................... 497Interrupt-vector function.................................................................................................... 497

Upper Layer Functions ................................................................................................................ 498Callback Init function ........................................................................................................ 498Callback Tx-Done function................................................................................................ 498Callback Receive function ................................................................................................. 498

Calling graph for Transmission and Reception ........................................................................... 499Transmission ...................................................................................................................... 499Receive............................................................................................................................... 499

XXII. Ethernet PHY Device Support.......................................................................................................... 50160. Ethernet PHY Device Support ........................................................................................................ 503

Ethernet PHY Device API........................................................................................................... 503

XXIII. SNMP................................................................................................................................................. 50561. SNMP for eCos ............................................................................................................................... 507

Version......................................................................................................................................... 507SNMP packages in the eCos source repository........................................................................... 507MIBs supported ........................................................................................................................... 507Changes to eCos sources ............................................................................................................. 508Starting the SNMP Agent............................................................................................................ 508Configuring eCos......................................................................................................................... 509

Version usage (v1, v2 or v3) .............................................................................................. 509Traps................................................................................................................................... 510snmpd.conf file ................................................................................................................. 510

Test cases ..................................................................................................................................... 511SNMP clients and package use.................................................................................................... 511Unimplemented features.............................................................................................................. 512MIB Compiler ............................................................................................................................. 512snmpd.conf .................................................................................................................................. 513

XXIV. Embedded HTTP Server ................................................................................................................. 52362. Embedded HTTP Server ................................................................................................................. 525

Intrduction ................................................................................................................................... 525Server Organization ..................................................................................................................... 525Server Configuration ................................................................................................................... 526

CYGNUM_HTTPD_SERVER_PORT ........................................................................................... 526CYGDAT_HTTPD_SERVER_ID ............................................................................................... 526CYGNUM_HTTPD_THREAD_COUNT ......................................................................................... 526CYGNUM_HTTPD_THREAD_PRIORITY ................................................................................... 526CYGNUM_HTTPD_THREAD_STACK_SIZE ............................................................................... 526

xvi

CYGNUM_HTTPD_SERVER_BUFFER_SIZE ............................................................................. 527CYGNUM_HTTPD_SERVER_AUTO_START ............................................................................... 527CYGNUM_HTTPD_SERVER_DELAY ......................................................................................... 527

Support Functions and Macros.................................................................................................... 527HTTP Support.................................................................................................................... 527General HTML Support..................................................................................................... 528Table Support ..................................................................................................................... 528Forms Support.................................................................................................................... 528Predefined Handlers ........................................................................................................... 529

System Monitor ........................................................................................................................... 530

XXV. FTP Client for eCos TCP/IP Stack................................................................................................... 53163. FTP Client Features ........................................................................................................................ 533

FTP Client API ............................................................................................................................ 533ftp_get ................................................................................................................................ 533ftp_put ................................................................................................................................ 533ftpclient_printf ................................................................................................................... 533

XXVI. Simple Network Time Protocol Client............................................................................................ 53564. The SNTP Client ............................................................................................................................. 537

Starting the SNTP client .............................................................................................................. 537What it does................................................................................................................................. 537Configuring the unicast list of NTP servers ................................................................................ 537Warning: timestamp wrap around................................................................................................ 538The SNTP test program............................................................................................................... 538

XXVII. Another Tiny HTTP Server for eCos ............................................................................................ 53965. The ATHTTP Server ....................................................................................................................... 541

Features........................................................................................................................................ 541Starting the server...............................................................................................