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 ............................................................................................................................................... xxv

Kernel Overview ............................................................................................................................................ 27SMP Support .................................................................................................................................................. 35Thread creation .............................................................................................................................................. 39Thread information ........................................................................................................................................ 45Thread control ................................................................................................................................................ 49Thread termination ......................................................................................................................................... 51Thread priorities ............................................................................................................................................. 53Per-thread data ............................................................................................................................................... 55Thread destructors.......................................................................................................................................... 57Exception handling ........................................................................................................................................ 59Counters ......................................................................................................................................................... 61Clocks............................................................................................................................................................. 63Alarms............................................................................................................................................................ 65Mutexes .......................................................................................................................................................... 67Condition Variables........................................................................................................................................ 73Semaphores .................................................................................................................................................... 77Mail boxes...................................................................................................................................................... 79Event Flags..................................................................................................................................................... 81Spinlocks ........................................................................................................................................................ 85Scheduler Control .......................................................................................................................................... 87Interrupt Handling.......................................................................................................................................... 89Kernel Real-time Characterization................................................................................................................. 95

II. The eCos Hardware Abstraction Layer (HAL) ............................................................................................. cv1. 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................................................................................................................................. 10Idle thread activity ...................................................................................................................... 10Reorder barrier ............................................................................................................................ 10Breakpoint support...................................................................................................................... 10GDB support ............................................................................................................................... 11Setjmp and longjmp support ....................................................................................................... 11Stack Sizes .................................................................................................................................. 11Address Translation .................................................................................................................... 12

v

Global Pointer ............................................................................................................................. 12Interrupt Handling ................................................................................................................................ 12

Vector numbers ........................................................................................................................... 12Interrupt state control.................................................................................................................. 13ISR and VSR management ......................................................................................................... 14Interrupt controller management................................................................................................. 14

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

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

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

Linker Scripts ....................................................................................................................................... 22Diagnostic Support ............................................................................................................................... 23SMP Support ........................................................................................................................................ 23

Target Hardware Limitations ...................................................................................................... 24HAL Support............................................................................................................................... 24

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

5. Exception Handling.................................................................................................................................... 29HAL Startup ......................................................................................................................................... 29Vectors and VSRs ................................................................................................................................. 30Default Synchronous Exception Handling ........................................................................................... 32Default Interrupt Handling ................................................................................................................... 32

6. Porting Guide ............................................................................................................................................. 35Introduction .......................................................................................................................................... 35HAL Structure ...................................................................................................................................... 35

HAL Classes ............................................................................................................................... 35File Descriptions ......................................................................................................................... 36

Common HAL................................................................................................................... 37Architecture HAL.............................................................................................................. 37Variant HAL ...................................................................................................................... 38Platform HAL.................................................................................................................... 39Auxiliary HAL .................................................................................................................. 40

Virtual Vectors (eCos/ROM Monitor Calling Interface) ...................................................................... 40Virtual Vectors ............................................................................................................................ 40

Initialization (or Mechanism vs. Policy) ........................................................................... 40Pros and Cons of Virtual Vectors ...................................................................................... 41Available services.............................................................................................................. 42

vi

The COMMS channels ............................................................................................................... 42Console and Debugging Channels .................................................................................... 42Mangling ........................................................................................................................... 42Controlling the Console Channel ...................................................................................... 43Footnote: Design Reasoning for Control of Console Channel.......................................... 44

The calling Interface API............................................................................................................ 44Implemented Services ....................................................................................................... 45Compatibility..................................................................................................................... 46Implementation details ...................................................................................................... 46New Platform Ports ........................................................................................................... 47New architecture ports....................................................................................................... 47

IO channels ................................................................................................................................. 47Available Procedures ......................................................................................................... 47Usage................................................................................................................................. 49Compatibility..................................................................................................................... 49Implementation Details ..................................................................................................... 49New Platform Ports ........................................................................................................... 50

HAL Coding Conventions .................................................................................................................... 50Implementation issues................................................................................................................. 51Source code details ..................................................................................................................... 51Nested Headers ........................................................................................................................... 52

Platform HAL Porting .......................................................................................................................... 53HAL Platform Porting Process ................................................................................................... 53

Brief overview ................................................................................................................... 53Step-by-step....................................................................................................................... 54

Minimal requirements.............................................................................................. 54Adding features........................................................................................................ 56

Hints .................................................................................................................................. 57HAL Platform CDL .................................................................................................................... 57

eCos Database ................................................................................................................... 58CDL File Layout ............................................................................................................... 59Startup Type ...................................................................................................................... 59Build options ..................................................................................................................... 60Common Target Options ................................................................................................... 61

Platform Memory Layout ........................................................................................................... 64Layout Files....................................................................................................................... 64Reserved Regions .............................................................................................................. 65

Platform Serial Device Support .................................................................................................. 65Variant HAL Porting............................................................................................................................. 67

HAL Variant Porting Process...................................................................................................... 67HAL Variant CDL....................................................................................................................... 67Cache Support............................................................................................................................. 69

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

7. Future developments .................................................................................................................................. 79

vii

III. The ISO Standard C and Math Libraries .................................................................................................... 818. C and math library overview...................................................................................................................... 83

Included non-ISO functions ................................................................................................................. 83Math library compatibility modes ........................................................................................................ 84

matherr() ..................................................................................................................................... 84Thread-safety and re-entrancy .................................................................................................... 86

Some implementation details ............................................................................................................... 86Thread safety ........................................................................................................................................ 88C library startup.................................................................................................................................... 88

IV. I/O Package (Device Drivers) ......................................................................................................................... 919. Introduction ................................................................................................................................................ 9310. User API................................................................................................................................................... 9511. Serial driver details................................................................................................................................... 97

Raw Serial Driver ................................................................................................................................. 97Runtime Configuration ............................................................................................................... 97API Details.................................................................................................................................. 99

cyg_io_write...................................................................................................................... 99cyg_io_read ....................................................................................................................... 99cyg_io_get_config ............................................................................................................. 99cyg_io_set_config............................................................................................................ 102

TTY driver .......................................................................................................................................... 103Runtime configuration .............................................................................................................. 103API details................................................................................................................................. 104

12. How to Write a Driver............................................................................................................................ 107How to Write a Serial Hardware Interface Driver .............................................................................. 108

DevTab Entry ............................................................................................................................ 109Serial Channel Structure ........................................................................................................... 109Serial Functions Structure......................................................................................................... 110Callbacks................................................................................................................................... 111

Serial testing with ser_filter................................................................................................................ 112Rationale ................................................................................................................................... 112The Protocol.............................................................................................................................. 113The Serial Tests......................................................................................................................... 114Serial Filter Usage..................................................................................................................... 114A Note on Failures .................................................................................................................... 116Debugging................................................................................................................................. 116

13. Device Driver Interface to the Kernel .................................................................................................... 117Interrupt Model................................................................................................................................... 117Synchronization.................................................................................................................................. 117SMP Support ...................................................................................................................................... 118Device Driver Models......................................................................................................................... 118Synchronization Levels ...................................................................................................................... 119The API .............................................................................................................................................. 120

cyg_drv_isr_lock....................................................................................................................... 120cyg_drv_isr_unlock................................................................................................................... 121cyg_drv_spinlock_init............................................................................................................... 121cyg_drv_spinlock_destroy ........................................................................................................ 121

viii

cyg_drv_spinlock_spin ............................................................................................................. 122cyg_drv_spinlock_clear ............................................................................................................ 122cyg_drv_spinlock_try ............................................................................................................... 123cyg_drv_spinlock_test .............................................................................................................. 123cyg_drv_spinlock_spin_intsave ................................................................................................ 124cyg_drv_spinlock_clear_intsave ............................................................................................... 124cyg_drv_dsr_lock...................................................................................................................... 125cyg_drv_dsr_unlock.................................................................................................................. 125cyg_drv_mutex_init .................................................................................................................. 126cyg_drv_mutex_destroy............................................................................................................ 126cyg_drv_mutex_lock................................................................................................................. 126cyg_drv_mutex_trylock ............................................................................................................ 127cyg_drv_mutex_unlock............................................................................................................. 127cyg_drv_mutex_release ............................................................................................................ 128cyg_drv_cond_init .................................................................................................................... 128cyg_drv_cond_destroy .............................................................................................................. 129cyg_drv_cond_wait................................................................................................................... 129cyg_drv_cond_signal ................................................................................................................ 130cyg_drv_cond_broadcast .......................................................................................................... 130cyg_drv_interrupt_create .......................................................................................................... 131cyg_drv_interrupt_delete .......................................................................................................... 131cyg_drv_interrupt_attach .......................................................................................................... 132cyg_drv_interrupt_detach ......................................................................................................... 132cyg_drv_interrupt_mask ........................................................................................................... 133cyg_drv_interrupt_mask_intunsafe........................................................................................... 133cyg_drv_interrupt_unmask ....................................................................................................... 134cyg_drv_interrupt_unmask_intunsafe....................................................................................... 134cyg_drv_interrupt_acknowledge............................................................................................... 134cyg_drv_interrupt_configure..................................................................................................... 135cyg_drv_interrupt_level ............................................................................................................ 135cyg_drv_interrupt_set_cpu ....................................................................................................... 136cyg_drv_interrupt_get_cpu ....................................................................................................... 136cyg_ISR_t ................................................................................................................................. 137cyg_DSR_t................................................................................................................................ 138

V. File System Support Infrastructure .............................................................................................................. 13914. Introduction ............................................................................................................................................ 14115. File System Table ................................................................................................................................... 14316. Mount Table ........................................................................................................................................... 14517. File Table................................................................................................................................................ 14718. Directories .............................................................................................................................................. 14919. Synchronization ..................................................................................................................................... 15120. Initialization and Mounting.................................................................................................................... 15321. Sockets ................................................................................................................................................... 15522. Select ...................................................................................................................................................... 15723. Devices ................................................................................................................................................... 15924. Writing a New Filesystem...................................................................................................................... 161

ix

VI. PCI Library ................................................................................................................................................... 16525. The eCos PCI Library ............................................................................................................................ 167

PCI Library......................................................................................................................................... 167PCI Overview............................................................................................................................ 167Initializing the bus..................................................................................................................... 167Scanning for devices ................................................................................................................. 167Generic config information ....................................................................................................... 168Specific config information....................................................................................................... 169Allocating memory ................................................................................................................... 169Interrupts ................................................................................................................................... 170Activating a device.................................................................................................................... 170Links ......................................................................................................................................... 171

PCI Library reference ......................................................................................................................... 171PCI Library API........................................................................................................................ 172Definitions................................................................................................................................. 172Types and data structures .......................................................................................................... 172Functions................................................................................................................................... 173Resource allocation................................................................................................................... 174PCI Library Hardware API ....................................................................................................... 175HAL PCI support ...................................................................................................................... 176

VII. FLASH Library ........................................................................................................................................... 17926. The eCos FLASH Library...................................................................................................................... 181

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

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

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

FLASH device API............................................................................................................................. 186The FLASH device Structure.................................................................................................... 186

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

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

x

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

29. FLASH I/O devices................................................................................................................................ 195Overview and CDL Configuration ..................................................................................................... 195Using FLASH I/O devices.................................................................................................................. 196

VIII. SPI Support................................................................................................................................................. 199Overview ...................................................................................................................................................... 201SPI Interface................................................................................................................................................. 205Porting to New Hardware............................................................................................................................. 209

IX. I2C Support ................................................................................................................................................... 211Overview ...................................................................................................................................................... 213I2C Interface................................................................................................................................................. 215Porting to New Hardware............................................................................................................................. 219

X. CAN Support................................................................................................................................................... 22530. Overview ................................................................................................................................................ 227

Description ......................................................................................................................................... 227eCos Support for CAN ....................................................................................................................... 227

31. User API................................................................................................................................................. 22932. CAN driver details ................................................................................................................................. 231

Description ......................................................................................................................................... 231API Details ......................................................................................................................................... 231

cyg_io_write ............................................................................................................................. 231CAN Messages.......................................................................................................................... 232cyg_io_read............................................................................................................................... 233CAN Events .............................................................................................................................. 233cyg_io_get_config..................................................................................................................... 235cyg_io_set_config ..................................................................................................................... 235

Runtime Configuration ....................................................................................................................... 236Device configuration ................................................................................................................. 236Timeout configuration............................................................................................................... 236Reading buffer configuration .................................................................................................... 237Reading hardware description information............................................................................... 237Reading hardware message buffer configuration...................................................................... 238Reading state of CAN hardware ............................................................................................... 239Changing mode of CAN hardware ........................................................................................... 239Flush or drain buffers ................................................................................................................ 240Configuring blocking/non-blocking calls ................................................................................. 240Message buffer management .................................................................................................... 240

xi

Remote frame response buffer configuration............................................................................ 242Message filter configuration...................................................................................................... 243Message filter deactivation........................................................................................................ 245Configuring a callback on events .............................................................................................. 245

33. Configuration ......................................................................................................................................... 24734. Writing a CAN hardware device driver ................................................................................................. 249

How to Write a CAN Hardware Interface Driver............................................................................... 249DevTab Entry ............................................................................................................................ 249CAN Channel Structure ............................................................................................................ 250CAN Lowlevel Functions Structure.......................................................................................... 251Callbacks................................................................................................................................... 252

XI. ADC Support ................................................................................................................................................. 255Overview ...................................................................................................................................................... 257ADC Device Drivers .................................................................................................................................... 263

XII. Framebuffer Support .................................................................................................................................. 267Overview ...................................................................................................................................................... 269Framebuffer Parameters ............................................................................................................................... 273Framebuffer Control Operations .................................................................................................................. 279Framebuffer Colours .................................................................................................................................... 287Framebuffer Drawing Primitives.................................................................................................................. 293Framebuffer Pixel Manipulation .................................................................................................................. 299Writing a Framebuffer Device Driver .......................................................................................................... 303

XIII. eCos POSIX compatibility layer ............................................................................................................... 31135. POSIX Standard Support ....................................................................................................................... 313

Process Primitives [POSIX Section 3] ............................................................................................... 313Functions Implemented............................................................................................................. 313Functions Omitted..................................................................................................................... 314Notes ......................................................................................................................................... 314

Process Environment [POSIX Section 4] ........................................................................................... 314Functions Implemented............................................................................................................. 315Functions Omitted..................................................................................................................... 315Notes ......................................................................................................................................... 315

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

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

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

C Language Services [POSIX Section 8]........................................................................................... 318Functions Implemented............................................................................................................. 318Functions Omitted..................................................................................................................... 319

xii

Notes ......................................................................................................................................... 319System Databases [POSIX Section 9]................................................................................................ 319

Functions Implemented............................................................................................................. 319Functions Omitted..................................................................................................................... 319Notes ......................................................................................................................................... 320

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

Functions Implemented............................................................................................................. 320Functions Omitted..................................................................................................................... 321Notes ......................................................................................................................................... 321

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

Execution Scheduling [POSIX Section 13]........................................................................................ 322Functions Implemented............................................................................................................. 322Functions Omitted..................................................................................................................... 323Notes ......................................................................................................................................... 323

Clocks and Timers [POSIX Section 14]............................................................................................. 323Functions Implemented............................................................................................................. 323Functions Omitted..................................................................................................................... 324Notes ......................................................................................................................................... 324

Message Passing [POSIX Section 15]................................................................................................ 324Functions Implemented............................................................................................................. 324Functions Omitted..................................................................................................................... 325Notes ......................................................................................................................................... 325

Thread Management [POSIX Section 16].......................................................................................... 325Functions Implemented............................................................................................................. 325Functions Omitted..................................................................................................................... 326Notes ......................................................................................................................................... 326

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

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

Non-POSIX Functions........................................................................................................................ 327General I/O Functions............................................................................................................... 328Socket Functions....................................................................................................................... 328Notes ......................................................................................................................................... 328

References and Bibliography ....................................................................................................................... 329

xiii

XIV. µITRON....................................................................................................................................................... 32936. µITRON API.......................................................................................................................................... 331

Introduction to µITRON..................................................................................................................... 331µITRON and eCos .............................................................................................................................. 331Task Management Functions .............................................................................................................. 332

Error checking........................................................................................................................... 333Task-Dependent Synchronization Functions ...................................................................................... 334

Error checking........................................................................................................................... 334Synchronization and Communication Functions................................................................................ 335

Error checking........................................................................................................................... 336Extended Synchronization and Communication Functions ............................................................... 337Interrupt management functions......................................................................................................... 337

Error checking........................................................................................................................... 338Memory pool Management Functions................................................................................................ 338

Error checking........................................................................................................................... 340Time Management Functions ............................................................................................................. 341

Error checking........................................................................................................................... 341System Management Functions.......................................................................................................... 342

Error checking........................................................................................................................... 342Network Support Functions................................................................................................................ 342µITRON Configuration FAQ.............................................................................................................. 343

XV. TCP/IP Stack Support for eCos.................................................................................................................. 34937. Ethernet Driver Design........................................................................................................................... 35138. Sample Code .......................................................................................................................................... 35339. Configuring IP Addresses ...................................................................................................................... 35540. Tests and Demonstrations ...................................................................................................................... 357

Loopback tests .................................................................................................................................... 357Building the Network Tests ................................................................................................................ 357Standalone Tests ................................................................................................................................. 357Performance Test ................................................................................................................................ 358Interactive Tests .................................................................................................................................. 359Maintenance Tools.............................................................................................................................. 360

41. Support Features .................................................................................................................................... 363TFTP................................................................................................................................................... 363DHCP ................................................................................................................................................. 365

42. TCP/IP Library Reference ..................................................................................................................... 367getdomainname................................................................................................................................... 367gethostname........................................................................................................................................ 368byteorder............................................................................................................................................. 369ethers................................................................................................................................................... 371getaddrinfo.......................................................................................................................................... 372gethostbyname.................................................................................................................................... 378getifaddrs ............................................................................................................................................ 381getnameinfo ........................................................................................................................................ 383getnetent ............................................................................................................................................. 386getprotoent .......................................................................................................................................... 387getrrsetbyname ................................................................................................................................... 389

xiv

getservent............................................................................................................................................ 391if_nametoindex ................................................................................................................................... 392inet ...................................................................................................................................................... 394inet6_option_space ............................................................................................................................. 398inet6_rthdr_space ............................................................................................................................... 401inet_net ............................................................................................................................................... 405ipx ....................................................................................................................................................... 406iso_addr .............................................................................................................................................. 407link_addr............................................................................................................................................. 409net_addrcmp ....................................................................................................................................... 410ns......................................................................................................................................................... 410resolver ............................................................................................................................................... 412accept .................................................................................................................................................. 415bind ..................................................................................................................................................... 416connect................................................................................................................................................ 418getpeername........................................................................................................................................ 420getsockname ....................................................................................................................................... 421getsockopt........................................................................................................................................... 423ioctl ..................................................................................................................................................... 426poll ...................................................................................................................................................... 427select ................................................................................................................................................... 429send..................................................................................................................................................... 432shutdown............................................................................................................................................. 434socket .................................................................................................................................................. 435

XVI. FreeBSD TCP/IP Stack port for eCos ...................................................................................................... 43943. Networking Stack Features .................................................................................................................... 44144. Freebsd TCP/IP stack port ..................................................................................................................... 443

Targets ................................................................................................................................................ 443Building the Network Stack ............................................................................................................... 443

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

XVII. OpenBSD TCP/IP Stack port for eCos ................................................................................................... 44746. Networking Stack Features .................................................................................................................... 449

Introduction ........................................................................................................................................ 44947. OpenBSD TCP/IP stack port.................................................................................................................. 451

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

48. APIs........................................................................................................................................................ 453Standard networking........................................................................................................................... 453Enhanced Select() ............................................................................................................................... 453OpenBSD networking facilities.......................................................................................................... 454Bridging.............................................................................................................................................. 458Spanning Tree Protocol ...................................................................................................................... 465

xv

XVIII. DNS for eCos and RedBoot .................................................................................................................... 46749. DNS........................................................................................................................................................ 469

DNS API............................................................................................................................................. 469DNS Client Testing............................................................................................................................. 470

XIX. IPSEC for eCos ........................................................................................................................................... 47350. Installation and Configuration................................................................................................................ 47551. libipsec Reference .................................................................................................................................. 477

ipsec_set_policy ................................................................................................................................. 477ipsec_strerror ...................................................................................................................................... 479

XX. eCos PPP User Guide................................................................................................................................... 48152. Features .................................................................................................................................................. 48353. Using PPP .............................................................................................................................................. 48554. PPP Interface.......................................................................................................................................... 489

cyg_ppp_options_init()....................................................................................................................... 489cyg_ppp_up()...................................................................................................................................... 493cyg_ppp_down() ................................................................................................................................. 495cyg_ppp_wait_up() ............................................................................................................................. 497cyg_ppp_wait_down() ........................................................................................................................ 499cyg_ppp_chat() ................................................................................................................................... 501

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

56. CHAT Scripts ......................................................................................................................................... 507Chat Script .......................................................................................................................................... 507ABORT Strings .................................................................................................................................. 508TIMEOUT .......................................................................................................................................... 508Sending EOT ...................................................................................................................................... 509Escape Sequences............................................................................................................................... 509

57. PPP Enabled Device Drivers.................................................................................................................. 51158. Testing .................................................................................................................................................... 513

Test Programs ..................................................................................................................................... 513Test Script ........................................................................................................................................... 514

XXI. Ethernet Device Drivers............................................................................................................................. 51759. Generic Ethernet Device Driver ............................................................................................................. 519

Generic Ethernet API ......................................................................................................................... 519Review of the functions ...................................................................................................................... 521

Init function............................................................................................................................... 522Start function............................................................................................................................. 522Stop function............................................................................................................................. 523Control function ........................................................................................................................ 523Can-send function ..................................................................................................................... 524Send function ............................................................................................................................ 524Deliver function ........................................................................................................................ 525Receive function ....................................................................................................................... 525Poll function.............................................................................................................................. 526Interrupt-vector function........................................................................................................... 526

xvi

Upper Layer Functions ....................................................................................................................... 526Callback Init function ............................................................................................................... 527Callback Tx-Done function....................................................................................................... 527Callback Receive function ........................................................................................................ 527

Calling graph for Transmission and Reception .................................................................................. 527Transmission ............................................................................................................................. 527Receive...................................................................................................................................... 528

XXII. Ethernet PHY Device Support................................................................................................................. 53160. Ethernet PHY Device Support ............................................................................................................... 533

Ethernet PHY Device API.................................................................................................................. 533

XXIII. SNMP........................................................................................................................................................ 53561. SNMP for eCos ...................................................................................................................................... 537

Version................................................................................................................................................ 537SNMP packages in the eCos source repository.................................................................................. 537MIBs supported .................................................................................................................................. 537Changes to eCos sources .................................................................................................................... 538Starting the SNMP Agent................................................................................................................... 538Configuring eCos................................................................................................................................ 539

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

Test cases ............................................................................................................................................ 541SNMP clients and package use........................................................................................................... 542Unimplemented features..................................................................................................................... 542MIB Compiler .................................................................................................................................... 543snmpd.conf ......................................................................................................................................... 544

XXIV. Embedded HTTP Server ........................................................................................................................ 55362. Embedded HTTP Server ........................................................................................................................ 555

Intrduction .......................................................................................................................................... 555Server Organization ............................................................................................................................ 555Server Configuration ..........................................................