Manual

Manuals Brands Comtrol Manuals Accessories communication eCos

eCos Reference Manual

Summary of content (814 pages)

PAGE 1

eCos Reference Manual
PAGE 2

eCos Reference Manual Copyright © 1998, 1999, 2000, 2001, 2002, 2003 by Red Hat, Inc.Nick Garnett (eCosCentric)Jonathan Larmour (eCosCentric)Andrew Lunn (Ascom)Gary Thomas (MLB Associates)Bart Veer (eCosCentric) 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/).
PAGE 3
PAGE 4
PAGE 5

Table of Contents I. The eCos Kernel ............................................................................................................................................... xxv Kernel Overview ............................................................................................................................................ 27 SMP Support ..................................................................................................................................................
PAGE 6

alias ............................................................................................................................................. 13 baudrate....................................................................................................................................... 15 cache ........................................................................................................................................... 17 channel .........................................................
PAGE 7

Memory Maps............................................................................................................................. 87 Rebuilding RedBoot.................................................................................................................... 87 ARM/ARM7 ARM Evaluator7T.......................................................................................................... 88 Overview............................................................................................
PAGE 8

Rebuilding RedBoot.................................................................................................................. 104 ARM/StrongARM(SA110) Intel EBSA 285...................................................................................... 104 Overview................................................................................................................................... 104 Initial Installation Method..............................................................................
PAGE 9

Additional commands ............................................................................................................... 119 Memory Maps........................................................................................................................... 119 Rebuilding RedBoot.................................................................................................................. 120 ARM/StrongARM(SA11X0) Intrinsyc CerfCube............................................................
PAGE 10

Overview................................................................................................................................... 139 Initial Installation Method......................................................................................................... 139 Special RedBoot Commands .................................................................................................... 140 Special Note on Serial Channel ......................................................................
PAGE 11

Ethernet Driver.......................................................................................................................... 154 Rebuilding RedBoot.................................................................................................................. 154 PowerPC/MPC860T Analogue & Micro PowerPC 860T .................................................................. 154 Overview............................................................................................................
PAGE 12

III. The eCos Hardware Abstraction Layer (HAL).......................................................................................... 169 6. Introduction .............................................................................................................................................. 171 7. Architecture, Variant and Platform .......................................................................................................... 173 8. General principles .....................................
PAGE 13

10. Exception Handling................................................................................................................................ 197 HAL Startup ....................................................................................................................................... 197 Vectors and VSRs ............................................................................................................................... 198 Default Synchronous Exception Handling .................
PAGE 14

HAL Platform CDL .................................................................................................................. 226 eCos Database ................................................................................................................. 226 CDL File Layout ............................................................................................................. 227 Startup Type .....................................................................................................
PAGE 15

Serial testing with ser_filter................................................................................................................ 281 Rationale ................................................................................................................................... 281 The Protocol.............................................................................................................................. 281 The Serial Tests............................................................
PAGE 16

cyg_drv_interrupt_set_cpu ....................................................................................................... 304 cyg_drv_interrupt_get_cpu ....................................................................................................... 305 cyg_ISR_t ................................................................................................................................. 305 cyg_DSR_t...........................................................................................
PAGE 17

Functions Implemented............................................................................................................. 354 Functions Omitted..................................................................................................................... 354 Notes ......................................................................................................................................... 354 Input and Output [POSIX Section 6]........................................................
PAGE 18

Thread Cancellation [POSIX Section 18] .......................................................................................... 364 Functions Implemented............................................................................................................. 364 Functions Omitted..................................................................................................................... 365 Notes ..................................................................................................
PAGE 19

byteorder............................................................................................................................................. 405 ethers................................................................................................................................................... 407 getaddrinfo.......................................................................................................................................... 408 gethostbyname................................
PAGE 20

44. APIs........................................................................................................................................................ 489 Standard networking........................................................................................................................... 489 Enhanced Select()............................................................................................................................... 489 XIII. DNS for eCos and RedBoot ....................
PAGE 21

XVI. Embedded HTTP Server ........................................................................................................................... 527 48. Embedded HTTP Server ........................................................................................................................ 529 Intrduction .......................................................................................................................................... 529 Server Organization .................................
PAGE 22

XXI. eCos Power Management Support............................................................................................................ 551 Introduction .................................................................................................................................................. 553 Power Management Information.................................................................................................................. 557 Changing Power Modes .................................
PAGE 23

List of Tables 13-1. Behavior of math exception handling........................................................................................................... 253 List of Examples 1-1. Sample DHCP configuration file........................................................................................................................ 8 1-2. Sample /etc/named.conf for Red Hat Linux 7.x ...........................................................................................
PAGE 24

xxiv
PAGE 25

I.
PAGE 26
PAGE 27

Kernel Overview Name Kernel — Overview of the eCos Kernel Description The kernel is one of the key packages in all of eCos. It provides the core functionality needed for developing multi-threaded applications: 1. The ability to create new threads in the system, either during startup or when the system is already running. 2. Control over the various threads in the system, for example manipulating their priorities. 3. A choice of schedulers, determining which thread should currently be running. 4.
PAGE 28

Kernel Overview loosely defined because of the many configuration options. For example cyg_mutex_lock will always attempt to lock a mutex, but various configuration options determine the behaviour when the mutex is already locked and there is a possibility of priority inversion. The optional nature of the kernel package presents some complications for other code, especially device drivers. Wherever possible a device driver should work whether or not the kernel is present.
PAGE 29

Kernel Overview waiting on a semaphore which has no pending events. The default behaviour of the system is last-in-first-out queuing. For example if several threads are waiting on a semaphore and an event is posted, the thread that gets woken up is the last one that called cyg_semaphore_wait. This allows for a simple and fast implementation of both the queue and dequeue operations.
PAGE 30

Kernel Overview The eCos common HAL package provides its own device driver API which contains some of the above synchronization primitives. These allow the DSR for an interrupt handler to signal events to higher-level code. If the configuration includes the eCos kernel package then the driver API routines map directly on to the equivalent kernel routines, allowing interrupt handlers to interact with threads.
PAGE 31

Kernel Overview shared with an ISR. For example if a thread needs to add another buffer to a linked list of free buffers and the ISR may remove a buffer from this list at any time, the thread would need to disable interrupts for the few instructions needed to manipulate the list. If the hardware raises an interrupt at this time, it remains pending until interrupts are reenabled. Analogous to interrupts being disabled or enabled, the kernel has a scheduler lock.
PAGE 32

Kernel Overview Calling Contexts eCos defines a number of contexts. Only certain calls are allowed from inside each context, for example most operations on threads or synchronization primitives are not allowed from ISR context. The different contexts are initialization, thread, ISR and DSR. When eCos starts up it goes through a number of phases, including setting up the hardware and invoking C++ static constructors. During this time interrupts are disabled and the scheduler is locked.
PAGE 33

Kernel Overview ones related to the interrupt subsystem itself, for example masking an interrupt or acknowledging that an interrupt has been processed. On SMP systems it is also possible to use spinlocks from ISR context. When an ISR returns it can request that the corresponding DSR be run as soon as it is safe to do so, and that will run in DSR context. This context is also used for running alarm functions, and threads can switch temporarily to DSR context by locking the scheduler.
PAGE 34

Kernel Overview 2. Because the final application will not suffer any overheads, it is reasonable for the system to do more work during the development process. In particular the various assertions can test for more error conditions and more complicated errors. When an error is detected it is possible to give a text message describing the error rather than just return an error code. 3. There is no need for application programmers to handle error codes returned by various kernel function calls.
PAGE 35

SMP Support Name SMP — Support Symmetric Multiprocessing Systems Description eCos contains support for limited Symmetric Multi-Processing (SMP). This is only available on selected architectures and platforms. The implementation has a number of restrictions on the kind of hardware supported. These are described in the Section called SMP Support in Chapter 9. The following sections describe the changes that have been made to the eCos kernel to support SMP operation.
PAGE 36

SMP Support routines that can. Instead all such operations are deferred to an associated DSR routine that is run during the lock release operation, when the data structures are in a consistent state. By choosing a kernel locking mechanism that does not rely on interrupt manipulation to protect data structures, it is easier to convert eCos to SMP than would otherwise be the case. The principal change needed to make eCos SMP-safe is to convert the scheduler lock into a nestable spin lock.
PAGE 37

SMP Support functions correctly. Typically a device driver would use the driver API rather than call the kernel directly, but it is unlikely that anybody would attempt to use a multiprocessor system without the kernel package. Two new functions have been added to the Kernel API to do interrupt routing: cyg_interrupt_set_cpu and cyg_interrupt_get_cpu.
PAGE 38

SMP Support 38
PAGE 39

Thread creation Name cyg_thread_create — Create a new thread Synopsis #include void cyg_thread_create(cyg_addrword_t sched_info, cyg_thread_entry_t* entry, cyg_addrword_t entry_data, char* name, void* stack_base, cyg_ucount32 stack_size, cyg_handle_t* handle, cyg_thread* thread); Description The cyg_thread_create function allows application code and eCos packages to create new threads.
PAGE 40

Thread creation The second argument to cyg_thread_create is a pointer to such a function. The third argument entry_data is used to pass additional data to the function. Typically this takes the form of a pointer to some static data, or a small integer, or 0 if the thread does not require any additional data. If the thread entry function ever returns then this is equivalent to the thread calling cyg_thread_exit. Even though the thread will no longer run again, it remains registered with the scheduler.
PAGE 41

Thread creation of space is reserved at the stack limit and filled with a special signature: every time a thread context switch occurs this signature is checked, and if invalid that is a good indication (but not absolute proof) that a stack overflow has occurred. This form of stack checking is enabled by default when the system is built with debugging enabled.
PAGE 42

Thread creation cyg_thread_create(PRODUCER_PRIORITY, &producer, 0, "producer", producer_stack, PRODUCER_STACKSIZE, &producer_handle, &producer_thread); cyg_thread_resume(producer_handle); for (i = 0; i < NUMBER_OF_WORKERS; i++) { cyg_thread_create(WORKER_PRIORITY, &worker, i, "worker", worker_stacks[i], WORKER_STACKSIZE, &(worker_handles[i]), &(worker_threads[i])); cyg_thread_resume(worker_handles[i]); } } Thread Entry Points and C++ For code written in C++ the thread entry function must be either a stati
PAGE 43

Thread information Name cyg_thread_self, cyg_thread_idle_thread, cyg_thread_get_stack_base, cyg_thread_get_stack_size, cyg_thread_measure_stack_usage, cyg_thread_get_next, cyg_thread_get_info, cyg_thread_find — Get basic thread information Synopsis #include
PAGE 44

Thread information handle and ID of the next thread in the system will be installed each time, until a false return value indicates the end of the list. cyg_thread_get_info fills in the cyg_thread_info structure with information about the thread described by the thread and id arguments. The information returned includes the thread’s handle and id, its state and name, priorities and stack parameters. If the thread does not exist the function returns false.
PAGE 45

Thread information if( !cyg_thread_get_info( thread, id, &info ) ) break; printf("ID: %04x name: %10s pri: %d\n", info.id, info.name?info.name:"----", info.
PAGE 46

Thread information 46
PAGE 47

Thread control Name cyg_thread_yield, cyg_thread_delay, cyg_thread_suspend, cyg_thread_resume, cyg_thread_release — Control whether or not a thread is running Synopsis #include void void void void void cyg_thread_yield(void); cyg_thread_delay(cyg_tick_count_t delay); cyg_thread_suspend(cyg_handle_t thread); cyg_thread_resume(cyg_handle_t thread); cyg_thread_release(cyg_handle_t thread); Description These functions provide some control over whether or not a particular thread can run.
PAGE 48

Thread control If the application requires delays measured in milliseconds or similar units rather than in clock ticks, some calculations are needed to convert between these units as described in Clocks. Usually these calculations can be done by the application developer, or at compile-time. Performing such calculations prior to every call to cyg_thread_delay adds unnecessary overhead to the system. Suspend and Resume Associated with each thread is a suspend counter.
PAGE 49

Thread termination Name cyg_thread_exit, cyg_thread_kill, cyg_thread_delete — Allow threads to terminate Synopsis #include void cyg_thread_exit(void); void cyg_thread_kill(cyg_handle_t thread); void cyg_thread_delete(cyg_handle_t thread); Description In many embedded systems the various threads are allocated statically, created during initialization, and never need to terminate. This avoids any need for dynamic memory allocation or other resource management facilities.
PAGE 50

Thread termination 50
PAGE 51

Thread priorities Name cyg_thread_get_priority, cyg_thread_get_current_priority, cyg_thread_set_priority — Examine and manipulate thread priorities Synopsis #include cyg_priority_t cyg_thread_get_priority(cyg_handle_t thread); cyg_priority_t cyg_thread_get_current_priority(cyg_handle_t thread); void cyg_thread_set_priority(cyg_handle_t thread, cyg_priority_t priority); Description Typical schedulers use the concept of a thread priority to determine which thread should run next.
PAGE 52

Thread priorities 52
PAGE 53

Per-thread data Name cyg_thread_new_data_index, cyg_thread_free_data_index, cyg_thread_get_data, cyg_thread_get_data_ptr, cyg_thread_set_data — Manipulate per-thread data Synopsis #include
PAGE 54

Per-thread data never include the POSIX compatibility package then application code may instead decide to re-use the slot allocated to that package, CYGNUM_KERNEL_THREADS_DATA_POSIX, but obviously this does involve a risk of strange and subtle bugs if the application’s requirements ever change. Valid contexts Typically cyg_thread_new_data_index is only called during initialization, but may also be called at any time in thread context.
PAGE 55

Thread destructors Name cyg_thread_add_destructor, cyg_thread_rem_destructor — Call functions on thread termination Synopsis #include
PAGE 56

Thread destructors 56
PAGE 57

Exception handling Name cyg_exception_set_handler, cyg_exception_clear_handler, cyg_exception_call_handler — Handle processor exceptions Synopsis #include
PAGE 58

Exception handling { ... } The data argument corresponds to the new_data parameter supplied to cyg_exception_set_handler. The exception code is provided as well, in case a single handler is expected to support multiple exceptions. The info argument will depend on the hardware and on the specific exception. cyg_exception_clear_handler can be used to restore the default handler, if desired.
PAGE 59

Counters Name cyg_counter_create, cyg_counter_delete, cyg_counter_current_value, cyg_counter_set_value, cyg_counter_tick — Count event occurrences Synopsis #include
PAGE 60

Counters off between doing work whenever a new alarm is added to a counter and doing work whenever a tick occurs. It is application-dependent which of these is more appropriate. Valid contexts cyg_counter_create is typically called during system initialization but may also be called in thread context. Similarly cyg_counter_delete may be called during initialization or in thread context.
PAGE 61

Clocks Name cyg_clock_create, cyg_clock_delete, cyg_clock_to_counter, cyg_clock_set_resolution, cyg_clock_get_resolution, cyg_real_time_clock, cyg_current_time — Provide system clocks Synopsis #include
PAGE 62

Clocks The main reason for this is that it accurately reflects the hardware: calling something like nanosleep with a delay of ten nanoseconds will not work as intended on any real hardware because timer interrupts simply will not happen that frequently; instead calling cyg_thread_delay with the equivalent delay of 0 ticks gives a much clearer indication that the application is attempting something inappropriate for the target hardware.
PAGE 63

Alarms Name cyg_alarm_create, cyg_alarm_delete, cyg_alarm_initialize, cyg_alarm_enable, cyg_alarm_disable — Run an alarm function when a number of events have occurred Synopsis #include
PAGE 64

Alarms Alarms can be temporarily disabled and reenabled using cyg_alarm_disable and cyg_alarm_enable. Alternatively another call to cyg_alarm_initialize can be used to modify the behaviour of an existing alarm. If an alarm is no longer required then the associated resources can be released using cyg_alarm_delete. The alarm function is invoked when a counter tick occurs, in other words when there is a call to cyg_counter_tick, and will happen in the same context.
PAGE 65

Mutexes Name cyg_mutex_init, cyg_mutex_destroy, cyg_mutex_lock, cyg_mutex_trylock, cyg_mutex_unlock, cyg_mutex_release, cyg_mutex_set_ceiling, cyg_mutex_set_protocol — Synchronization primitive Synopsis #include
PAGE 66

Mutexes Sections of code like the above which involve manipulating shared data are generally known as critical regions. Code should claim a lock before entering a critical region and release the lock when leaving. Mutexes provide an appropriate synchronization primitive for this. static volatile int counter = 0; static cyg_mutex_t lock; void process_event(void) { ... cyg_mutex_lock(&lock); counter++; cyg_mutex_unlock(&lock); } A mutex must be initialized before it can be used, by calling cyg_mutex_init.
PAGE 67

Mutexes In simple applications it may be possible to arrange the code such that priority inversion cannot occur, for example by ensuring that a given mutex is never shared by threads running at different priority levels. However this may not always be possible even at the application level. In addition mutexes may be used internally by underlying code, for example the memory allocation package, so careful analysis of the whole system would be needed to be sure that priority inversion cannot occur.
PAGE 68

Mutexes have to be detected by application developers and appropriate precautions have to be taken, for example making sure that all the threads run at suitable priorities at all times. Warning The current implementation of priority inheritance within the eCos kernel does not handle certain exceptional circumstances completely correctly. Problems will only arise if a thread owns one mutex, then attempts to claim another mutex, and there are other threads attempting to lock these same mutexes.
PAGE 69

Mutexes When a thread has just locked a mutex associated with some data structure, it can assume that that data structure is in a consistent state. Before unlocking the mutex again it must ensure that the data structure is again in a consistent state. Recursive mutexes allow a thread to make arbitrary changes to a data structure, then in a recursive call lock the mutex again while the data structure is still inconsistent.
PAGE 70

Mutexes 70
PAGE 71

Condition Variables Name cyg_cond_init, cyg_cond_destroy, cyg_cond_wait, cyg_cond_timed_wait, cyg_cond_signal, cyg_cond_broadcast — Synchronization primitive Synopsis #include
PAGE 72

Condition Variables cyg_mutex_unlock(&res_lock); // unlock the mutex return res; } void res_free(res_t res) { cyg_mutex_lock(&res_lock); // lock the mutex res_pool[res_count] = res; res_count++; // free the resource cyg_mutex_unlock(&res_lock); // unlock the mutex } These routines use the variable res_count to keep track of the resources available. If there are none then res_allocate returns RES_NONE, which the caller must check for and take appropriate error handling actions.
PAGE 73

Condition Variables cyg_mutex_lock(&res_lock); // lock the mutex res_pool[res_count] = res; res_count++; // free the resource cyg_cond_signal(&res_wait); // wake up any waiting allocators cyg_mutex_unlock(&res_lock); // unlock the mutex } In this version of the code, when res_allocate detects that there are no resources it calls cyg_cond_wait. This does two things: it unlocks the mutex, and puts the calling thread to sleep on the condition variable.
PAGE 74

Condition Variables same condition and at most one thread can continue running. A broadcast should be used if threads check slightly different conditions, or if the change to the global state might allow multiple threads to proceed. Valid contexts cyg_cond_init is typically called during system initialization but may also be called in thread context. The same applies to cyg_cond_delete. cyg_cond_wait and cyg_cond_timedwait may only be called from thread context since they may block.
PAGE 75

Semaphores Name cyg_semaphore_init, cyg_semaphore_destroy, cyg_semaphore_wait, cyg_semaphore_timed_wait, cyg_semaphore_post, cyg_semaphore_peek — Synchronization primitive Synopsis #include
PAGE 76

Semaphores cyg_semaphore_post is called when an event has occurs. This increments the counter and wakes up the first thread waiting on the semaphore (if any). Usually that thread will then continue running inside cyg_semaphore_wait and decrement the counter again. However other scenarioes are possible.
PAGE 77

Mail boxes Name cyg_mbox_create, cyg_mbox_delete, cyg_mbox_get, cyg_mbox_timed_get, cyg_mbox_tryget, cyg_mbox_peek_item, cyg_mbox_put, cyg_mbox_timed_put, cyg_mbox_tryput, cyg_mbox_peek, cyg_mbox_waiting_to_get, cyg_mbox_waiting_to_put — Synchronization primitive Synopsis #include
PAGE 78

Mail boxes will never be a call to cyg_mbox_put with a null pointer, because it would not be possible to distinguish between that and a release operation. Messages are always retrieved in the order in which they were put into the mail box, and there is no support for messages with different priorities. There are two variants of cyg_mbox_get. The first, cyg_mbox_timed_get will wait until either a message is available or until a number of clock ticks have occurred.
PAGE 79

Event Flags Name cyg_flag_init, cyg_flag_destroy, cyg_flag_setbits, cyg_flag_maskbits, cyg_flag_wait, cyg_flag_timed_wait, cyg_flag_poll, cyg_flag_peek, cyg_flag_waiting — Synchronization primitive Synopsis #include
PAGE 80

Event Flags A consumer thread can wait for one or more events by calling cyg_flag_wait. This takes three arguments. The first identifies a particular event flag. The second is some combination of bits, indicating which events are of interest. The final argument should be one of the following: CYG_FLAG_WAITMODE_AND The call to cyg_flag_wait will block until all the specified event bits are set. The event flag is not cleared when the wait succeeds, in other words all the bits remain set.
PAGE 81

Event Flags Valid contexts cyg_flag_init is typically called during system initialization but may also be called in thread context. The same applies to cyg_flag_destroy. cyg_flag_wait and cyg_flag_timed_wait may only be called from thread context. The remaining functions may be called from thread or DSR context.
PAGE 82

Event Flags 82
PAGE 83

Spinlocks Name cyg_spinlock_create, cyg_spinlock_destroy, cyg_spinlock_spin, cyg_spinlock_clear, cyg_spinlock_test, cyg_spinlock_spin_intsave, cyg_spinlock_clear_intsave — Low-level Synchronization Primitive Synopsis #include
PAGE 84

Spinlocks get another chance to run and release the spinlock. Even if the two threads were running at the same priority, the one attempting to claim the spinlock would spin until it was timesliced and a lot of cpu time would be wasted. If an interrupt handler tried to claim a spinlock owned by a thread, the interrupt handler would loop forever. Therefore spinlocks are only appropriate for SMP systems where the current owner of a spinlock can continue running on a different processor.
PAGE 85

Scheduler Control Name cyg_scheduler_start, cyg_scheduler_lock, cyg_scheduler_unlock, cyg_scheduler_safe_lock, cyg_scheduler_read_lock — Control the state of the scheduler Synopsis #include void cyg_scheduler_start(void); void cyg_scheduler_lock(void); void cyg_scheduler_unlock(void); cyg_ucount32 cyg_scheduler_read_lock(void); Description cyg_scheduler_start should only be called once, to mark the end of system initialization.
PAGE 86

Scheduler Control number of times. This behaviour is different from mutexes where an attempt by a thread to lock a mutex multiple times will result in deadlock or an assertion failure. Typical application code should not use the scheduler lock. Instead other synchronization primitives such as mutexes and semaphores should be used. While the scheduler is locked the current thread cannot be preempted, so any higher priority threads will not be able to run.
PAGE 87

Interrupt Handling Name cyg_interrupt_create, cyg_interrupt_delete, cyg_interrupt_attach, cyg_interrupt_detach, cyg_interrupt_configure, cyg_interrupt_acknowledge, cyg_interrupt_enable, cyg_interrupt_disable, cyg_interrupt_mask, cyg_interrupt_mask_intunsafe, cyg_interrupt_unmask, cyg_interrupt_unmask_intunsafe, cyg_interrupt_set_cpu, cyg_interrupt_get_cpu, cyg_interrupt_get_vsr, cyg_interrupt_set_vsr — Manage interrupt handlers Synopsis #include
PAGE 88

Interrupt Handling The exact details of interrupt handling vary widely between architectures. The functionality provided by the kernel abstracts away from many of the details of the underlying hardware, thus simplifying application development. However this is not always successful.
PAGE 89

Interrupt Handling Interrupts may currently be disabled globally, especially if the hardware does not support interrupt priorities. Alternatively interrupts may be enabled such that higher priority interrupts are allowed through. The ISR may be running on a separate interrupt stack, or on the stack of whichever thread was running at the time the interrupt happened.
PAGE 90

Interrupt Handling The call to cyg_interrupt_create simply fills in a kernel data structure. A typical next step is to call cyg_interrupt_attach using the handle returned by the create operation. This makes it possible to have several different interrupt handlers for a given vector, attaching whichever one is currently appropriate. Replacing an interrupt handler requires a call to cyg_interrupt_detach, followed by another call to cyg_interrupt_attach for the replacement handler.
PAGE 91

Interrupt Handling VSR Support When an interrupt occurs the hardware will transfer control to a piece of code known as the VSR, or Vector Service Routine. By default this code is provided by eCos. Usually it is written in assembler, but on some architectures it may be possible to implement VSRs in C by specifying an interrupt attribute. Compiler documentation should be consulted for more information on this.
PAGE 92

Interrupt Handling 92
PAGE 93

Kernel Real-time Characterization Name tm_basic — Measure the performance of the eCos kernel Description When building a real-time system, care must be taken to ensure that the system will be able to perform properly within the constraints of that system. One of these constraints may be how fast certain operations can be performed. Another might be how deterministic the overall behavior of the system is. Lastly the memory footprint (size) and unit cost may be important.
PAGE 94

Kernel Real-time Characterization of objects in the system. For example, the mailbox tests measure the cost of a ’peek’ operation when the mailbox is empty, has a single item, and has multiple items present. In this way, any effects of the state of the object or how many items it contains can be determined. There are a few things to consider about these measurements. Firstly, they are quite micro in scale and only measure the operation in question.
PAGE 95

Kernel Real-time Characterization numerical value. A higher priority thread will run in preference to a lower priority thread even though the priority value of the higher priority thread may be numerically less than that of the lower priority thread. Thread Primitives Create thread This test measures the cyg_thread_create() call. Each call creates a totally new thread. The set of threads created by this test will be reused in the subsequent thread primitive tests.
PAGE 96

Kernel Real-time Characterization Suspend [runnable] thread This test measures the cyg_thread_suspend() call again. In this case, each thread has already been made runnable (by previous tests). Yield [only low priority] thread This test measures the cyg_thread_yield() call. In this case, there are many other runnable threads, but they are all lower priority than the main thread, thus no thread switches will take place.
PAGE 97

Kernel Real-time Characterization Scheduler unlock [many low priority threads] This test measures the cyg_scheduler_unlock() call. There are many other threads in the system which are runnable but are lower priority than the main thread. The purpose of this test is to determine the cost of having additional threads in the system when the scheduler is activated by way of cyg_scheduler_unlock(). Mutex Primitives Init mutex This test measures the cyg_mutex_init() call.
PAGE 98

Kernel Real-time Characterization Peek [empty] mbox This test measures the cyg_mbox_peek() call. An attempt is made to peek the value in each mailbox, which is currently empty. The purpose of this test is to measure the cost of checking a mailbox for a value without blocking. Put [first] mbox This test measures the cyg_mbox_put() call. One item is added to a currently empty mailbox. The purpose of this test is to measure the cost of adding an item to a mailbox.
PAGE 99

Kernel Real-time Characterization Peek item [empty] mbox This test measures the cyg_mbox_peek_item() call. An attempt is made to fetch an item from a mailbox that is empty. The purpose of this test is to measure the cost of trying to obtain an item when the mailbox is empty. Tryget [empty] mbox This test measures the cyg_mbox_tryget() call. An attempt is made to fetch an item from a mailbox that is empty. The purpose of this test is to measure the cost of trying to obtain an item when the mailbox is empty.
PAGE 100

Kernel Real-time Characterization Trywait [1] semaphore This test measures the cyg_semaphore_trywait() call. The semaphore has a value of 1 when the call is made. The purpose of this test is to measure the cost of seeing if a semaphore can be “taken” without blocking. In this case, the answer would be yes. Peek semaphore This test measures the cyg_semaphore_peek() call. The purpose of this test is to measure the cost of obtaining the current semaphore count value.
PAGE 101

Kernel Real-time Characterization Initialize alarm This test measures the cyg_alarm_initialize() call. Each alarm is initialized to a small value. Disable alarm This test measures the cyg_alarm_disable() call. Each alarm is explicitly disabled. Enable alarm This test measures the cyg_alarm_enable() call. Each alarm is explicitly enabled. Delete alarm This test measures the cyg_alarm_delete() call. Each alarm is destroyed.
PAGE 102

Kernel Real-time Characterization Alarm latency [many threads] This test attempts to measure the latency in calling an alarm callback function. The time from the clock interrupt until the alarm function is called is measured. In this test, there are a number of threads which are running when the clock interrupt occurs. They are simply passing back and forth by way of the cyg_thread_yield() call. The purpose of this test is to measure the variations in the latency when there are many executing threads.
PAGE 103

II.
PAGE 104

Kernel Real-time Characterization civ
PAGE 105

Chapter 1. Getting Started with RedBoot RedBoot™ is an acronym for "Red Hat Embedded Debug and Bootstrap", and is the standard embedded system debug/bootstrap environment from Red Hat, replacing the previous generation of debug firmware: CygMon and GDB stubs. It provides a complete bootstrap environment for a range of embedded operating systems, such as embedded Linux™ and eCos™, and includes facilities such as network downloading and debugging. It also provides a simple flash file system for boot images.
PAGE 106

Chapter 1. Getting Started with RedBoot the RedBoot image into non-volatile storage varies from platform to platform. In general, it requires that the image be programmed into flash in situ or programmed into the flash or ROM using a device programmer. In some cases this will be done at manufacturing time; the platform being delivered with RedBoot already in place. In other cases, you will have to program RedBoot into the appropriate device(s) yourself.
PAGE 107

Chapter 1. Getting Started with RedBoot • ^P replaces the current line by a previous line from the history buffer. A small number of lines can be kept as history. Using ^P (and ^N), the current line can be replaced by any one of the previously typed lines. • ^N replaces the current line by the next line from the history buffer. In the case of the fconfig command, additional editing commands are possible.
PAGE 108

Chapter 1. Getting Started with RedBoot The chosen mode has influence on flash and RAM resource usage (see the Section called RedBoot Resource Usage) and the procedure of an in situ update of RedBoot in flash (see Chapter 4). The startup mode is controlled by the option CYG_HAL_STARTUP which resides in the platform HAL. Some platforms provide only some of the RAM, ROM, and ROMRAM modes, others provide additional modes.
PAGE 109

Chapter 1. Getting Started with RedBoot To save flash resources, use a ROMRAM mode RedBoot, or if using a ROM mode RedBoot, avoid reserving space for the RedBoot[RAM] image (this is done by changing the RedBoot configuration) and download the RAM mode RedBoot whenever it is needed. If the RedBoot image takes up a fraction of an extra flash block, it may be possible to reduce the image size enough to free this block by removing some features.
PAGE 110

Chapter 1. Getting Started with RedBoot Target Network Configuration Each node in a networked system needs to have a unique address. Since the network support in RedBoot is based on TCP/IP, this address is an IP (Internet Protocol) address. There are two ways for a system to “know” its IP address. First, it can be stored locally on the platform. This is known as having a static IP address. Second, the system can use the network itself to discover its IP address. This is known as a dynamic IP address.
PAGE 111

Chapter 1. Getting Started with RedBoot • dynamic IP address allocation, using BOOTP • TFTP service for file downloading • DNS server for hostname lookups Depending on the host system, these services may or may not be available or enabled by default. See your system documentation for more details. In particular, on Red Hat Linux, neither of these services will be configured out of the box. The following will provide a limited explanation of how to set them up.
PAGE 112

Chapter 1. Getting Started with RedBoot Enable BOOTP/DHCP server on Red Hat Linux First, ensure that you have the proper package, dhcp (not dhcpd) installed. The DHCP server provides Dynamic Host Configuration, that is, IP address and other data to hosts on a network. It does this in different ways. Next, there can be a fixed relationship between a certain node and the data, based on that node’s unique Ethernet Station Address (ESA, sometimes called a MAC address).
PAGE 113

Chapter 1. Getting Started with RedBoot /* * If there is a firewall between you and nameservers you want * to talk to, you might need to uncomment the query-source * directive below. Previous versions of BIND always asked * questions using port 53, but BIND 8.1 uses an unprivileged * port by default. */ // query-source address * port 53; forward first; forwarders { 212.242.40.3; 212.242.40.51; }; }; // // a caching only nameserver config // // Uncomment the following for Red Hat Linux 7.
PAGE 114

Chapter 1. Getting Started with RedBoot RedBoot network gateway RedBoot cannot communicate with machines on different subnets because it does not support routing. It always assumes that it can get to an address directly, therefore it always tries to ARP and then send packets directly to that unit. This means that whatever it talks to must be on the same subnet.
PAGE 115

Chapter 2. RedBoot Commands and Examples Introduction RedBoot provides three basic classes of commands: • Program loading and execution • Flash image and configuration management • Miscellaneous commands Given the extensible and configurable nature of eCos and RedBoot, there may be extended or enhanced sets of commands available. The basic format for commands is: RedBoot> COMMAND [-S]... [-s val]... operand Commands may require additional information beyond the basic command name.
PAGE 116

Chapter 2. RedBoot Commands and Examples Format operand Description Example A simple value; some commands RedBoot> fis delete JFFS2 require a single parameter for which an additional -X switch would be redundant. In the example, JFFS2 is the name of a flash image. The image name is always required, thus is no need to qualify it with a switch. Note that any un-qualified operand must always appear at the end of the command.
PAGE 117

Commands can be abbreviated to their shortest unique string. Thus in the list above, d,du,dum and dump are all valid for the dump command. The fconfig command can be abbreviated fc, but f would be ambiguous with fis. There is one additional, special command. When RedBoot detects ’$’ or ’+’ (unless escaped via ’\’) in a command, it switches to GDB protocol mode. At this point, the eCos GDB stubs take over, allowing connections from a GDB host.
PAGE 118

alias If no value is provided, then the current value of the alias is displayed. If the system supports non-volatile configuration data via the fconfig command (see the Section called Persistent State Flash-based Configuration and Control in Chapter 2), then the value will be saved and used when the system is reset. Examples Set an alias. RedBoot> alias joe "This is Joe" Update RedBoot non-volatile configuration - continue (y/n)? n Display an alias. RedBoot> alias joe ’joe’ = ’This is Joe’ Use an alias.
PAGE 119

baudrate Name baudrate — Set the baud rate for the system serial console Synopsis baudrate [-b rate] Arguments Name Type Description Default -b rate Number The baud rate to use for the none serial console. Description The baudrate command sets the baud rate for the system serial console. If no value is provided, then the current value of the console baud rate is displayed.
PAGE 120

baudrate Update RedBoot non-volatile configuration - continue (y/n)? n 16
PAGE 121

cache Name cache — Control hardware caches Synopsis cache [on | off] Arguments Name Type Description Default on Turn the caches on none off Turn the caches off none Description The cache command is used to manipulate the caches on the processor. With no options, this command specifies the state of the system caches. When an option is given, the caches are turned off or on appropriately. Examples Show the current cache state.
PAGE 122

cache RedBoot> cache Data cache: On, Instruction cache: On 18
PAGE 123

channel Name channel — Select the system console channel Synopsis channel [-1 | channel_number] Arguments Name Type -1 channel_number Number Description Default Reset the console channel none Select a channel none Description With no arguments, the channel command displays the current console channel number. When passed an argument of 0 upward, this command switches the console channel to that channel number.
PAGE 124

channel RedBoot> channel -1 20
PAGE 125

cksum Name cksum — Compute POSIX checksums Synopsis cksum {-b location} {-l length} Arguments Name Type Description Default -b location Memory address Location in memory for stat of data. none -l length Number Length of data none Description Computes the POSIX checksum on a range of memory (either RAM or FLASH). The values printed (decimal cksum, decimal length, hexadecimal cksum, hexadecimal length) can be compared with the output from the Linux program ’cksum’. Examples Checksum a buffer.
PAGE 126

cksum 22
PAGE 127

disks Name disks — List available disk partitions. Synopsis disks Arguments None. Description The disks command is used to list disk partitions recognized by RedBoot. Examples Show what disk partitions are available. RedBoot> disks hda1 Linux Swap hda2 Linux 00100000: 00 3E 00 06 00 06 00 06 00100010: 00 00 00 78 00 70 00 60 00 00 00 00 00 00 00 00 00 60 00 60 00 60 00 60 |.>..............| |...x.p.‘.‘.‘.‘.
PAGE 128

disks 24
PAGE 129

dump Name dump — Display memory. Synopsis dump {-b location} [-l length] [-s] [-1 | -2 | -4] Arguments Name Type Description Default -b location Memory address Location in memory for start of data. none -l length Number Length of data 32 -s Boolean Format data using Motorola S-records. -1 Access one byte (8 bits) at -1 a time. Only the least significant 8 bits of the pattern will be used. -2 Access two bytes (16 bits) -1 at a time.
PAGE 130

dump Examples Display a buffer, one byte at a time. RedBoot> mfill -b 0x100000 -l 0x20 -p 0xDEADFACE RedBoot> x -b 0x100000 00100000: CE FA AD DE CE FA AD DE CE FA AD DE CE FA AD DE 00100010: CE FA AD DE CE FA AD DE CE FA AD DE CE FA AD DE |................| |................| Display a buffer, one short (16 bit) word at a time. Note in this case that the ASCII interpretation is suppressed.
PAGE 131

help Name help — Display help on available commands Synopsis help [ topic] Arguments Name Type Description Default topic String Which command to provide help for. All commands Description The help command displays information about the available RedBoot commands. If a topic is given, then the display is restricted to information about that specific command. If the command has sub-commands, e.g. fis, then the topic specific display will print additional information about the available sub-commands.
PAGE 132

help Execute code at a location go [-w ] [entry] Help about help? help [] Set/change IP addresses ip_address [-l ] [-h ] Load a file load [-r] [-v] [-d] [-h ] [-m {TFTP | HTTP | {x|y}MODEM -c }] [-b ] Compare two blocks of memory mcmp -s -d -l [-1|-2|-4] Fill a block of memory with a pattern mfill -b -l -p [-1|-2|-4] Network connectivity test ping [-v
PAGE 133

ip_address Name ip_address — Set IP addresses Synopsis ip_address [-l local_IP_address] [-h server_IP_address] [-d DNS_server_IP_address] Arguments Name Type Description Default -l local_IP_address Numeric IP or DNS name The IP address RedBoot should use. none -h server_IP_address Numeric IP or DNS name The IP address of the none default server. Use of this address is implied by other commands, such as load. -d Numeric IP or DNS name DNS_server_IP_address The IP address of the DNS none server.
PAGE 134

ip_address Change the DNS server address. RedBoot> ip_address -d 192.168.1.101 IP: 192.168.1.31, Default server: 192.168.1.101, DNS server IP: 192.168.1.101 Change the default server address. RedBoot> ip_address -h 192.168.1.104 IP: 192.168.1.31, Default server: 192.168.1.104, DNS server IP: 192.168.1.
PAGE 135

load Name load — Download programs or data to the RedBoot platform Synopsis load [-v ] [-d ] [-r ] [-m [[xmodem | ymodem] | tftp | disk] ] [-h server_IP_address] [-b location] [-c channel] [file_name] Arguments Name Type Description -v Boolean Display a small spinner quiet (indicator) while the download is in progress. This is just for feedback, especially during long loads. Note that the option has no effect when using a serial download method since it would interfere with the protocol.
PAGE 136

load Name -b location Type Number Description Default Address in memory to load Depends on data format the data. Formatted data streams will have an implied load address which this option may override. -c channel Number Specify which I/O channel Depends on data format to use for download. This option is only supported when using either xmodem or ymodem protocol. file_name String The name of the file on the None TFTP or HTTP server or the local disk.
PAGE 137

load Load an ELF file from /dev/hda1 which should be an EXT2 partition: RedBoot> load -mode disk hda1:hello.
PAGE 138

load 34
PAGE 139

mcmp Name mcmp — Compare two segments of memory Synopsis mcmp {-s location1} {-d location1} {-l length} [-1 | -2 | -4] Arguments Name Type Description Default -s location1 Memory address Location for start of data. none -d location2 Memory address Location for start of data. none -l length Number Length of data none -1 Access one byte (8 bits) at -4 a time. Only the least significant 8 bits of the pattern will be used. -2 Access two bytes (16 bits) -4 at a time.
PAGE 140

mcmp RedBoot> mcmp -s 0x100000 -d 0x200000 -l 0x30 -2 Buffers don’t match - 0x00100020=0x6000, 0x00200020=0x0000 36
PAGE 141

mfill Name mfill — Fill RAM with a specified pattern Synopsis mfill {-b location} {-l length} {-p value} [-1 | -2 | -4] Arguments Name Type Description Default -b location Memory address Location in memory for start of data. none -l length Number Length of data none -p pattern Number Data value to fill with 0 -1 Access one byte (8 bits) at -4 a time. Only the least significant 8 bits of the pattern will be used. -2 Access two bytes (16 bits) -4 at a time.
PAGE 142

mfill 00100010: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| RedBoot> mfill -b 0x100000 -l 0x20 -p 0xDEADFACE RedBoot> x -b 0x100000 -l 0x20 00100000: CE FA AD DE CE FA AD DE CE FA AD DE CE FA AD DE 00100010: CE FA AD DE CE FA AD DE CE FA AD DE CE FA AD DE |................| |................| Fill a buffer with a pattern.
PAGE 143

ping Name ping — Verify network connectivity Synopsis ping [-v ] [-i local_IP_address] [-l server_IP_address} length] [-n count] [-t timeout] [-r rate] {-h Arguments Name Type Description Default -v Boolean Be verbose, displaying information about each packet sent. quiet -n local_IP_address Number Controls the number of packets to be sent. 10 -i local_IP_address Numeric IP or DNS name The IP address RedBoot should use.
PAGE 144

ping Examples Test connectivity to host 192.168.1.101. RedBoot> ping -h 192.168.1.101 Network PING - from 192.168.1.31 to 192.168.1.101 PING - received 10 of 10 expected Test connectivity to host 192.168.1.101, with verbose reporting. RedBoot> ping -h 192.168.1.101 -v -n 4 Network PING - from 192.168.1.31 to 192.168.1.101 seq: 1, time: 1 (ticks) seq: 2, time: 1 (ticks) seq: 3, time: 1 (ticks) seq: 4, time: 1 (ticks) PING - received 10 of 10 expected Test connectivity to a non-existent host (192.168.1.
PAGE 145

reset Name reset — Reset the device Synopsis reset Arguments None Description The reset command causes the target platform to be reset. Where possible (hardware support permitting), this will be equivalent to a power-on reset condition. Examples Reset the platform. RedBoot> reset ... Resetting.+... Waiting for network card: . Socket Communications, Inc: Low Power Ethernet CF Revision C 5V/3.3V 08/27/98 Ethernet eth0: MAC address 00:c0:1b:00:ba:28 IP: 192.168.1.29, Default server: 192.168.1.
PAGE 146

reset 42
PAGE 147

version Name version — Display RedBoot version information Synopsis version Arguments None Description The version command simply displays version information about RedBoot. Examples Display RedBoot’s version. RedBoot> version RedBoot(tm) debug environment - built 09:12:03, Feb 12 2001 Platform: XYZ (PowerPC 860) Copyright (C) 2000, 2001, Red Hat, Inc.
PAGE 148

version 44
PAGE 149

Flash Image System (FIS) If the platform has flash memory, RedBoot can use this for image storage. Executable images, as well as data, can be stored in flash in a simple file store. The fis command (fis is short for Flash Image System) is used to manipulate and maintain flash images.
PAGE 150

fis init *** Initialize FLASH Image System Warning: device contents not erased, some blocks may not be usable ... Erase from 0x00070000-0x00080000: . ... Program from 0x0606f000-0x0607f000 at 0x00070000: . Initialize the FIS directory and all of flash memory, except for first blocks of the flash where the boot monitor resides. RedBoot> fis init -f About to initialize [format] flash image system - continue (y/n)? y *** Initialize FLASH Image System ... Erase from 0x00020000-0x00070000: ..... ...
PAGE 151

fis list Name fis list — List Flash Image System directory Synopsis fis list [-f] Arguments Name Type Description -c Show image checksum instead of memory address (column Mem addr is replaced by Checksum). -d Show image data length instead of amount of flash occupied by image (column Length is replaced by Datalen). Default Description This command lists the images currently available in the FIS.
PAGE 152

fis list List the FIS directory, with image checksums substituted for memory addresses. RedBoot> fis list Name RedBoot RedBoot config FIS directory -c FLASH addr 0x00000000 0x0007F000 0x00070000 Checksum 0x00000000 0x00000000 0x00000000 Length 0x00020000 0x00001000 0x0000F000 Entry point 0x00000000 0x00000000 0x00000000 List the FIS directory with image data lengths substituted for flash block reservation lengths.
PAGE 153

fis free Name fis free — Free flash image Synopsis fis free Description This command shows which areas of the flash memory are currently not in use. When a block contains non-erased contents it is considered in use. Since it is possible to force an image to be loaded at a particular flash location, this command can be used to check whether that location is in use by any other image.
PAGE 154

fis free 50
PAGE 155

fis create Name fis create — Create flash image Synopsis fis create {-b data address} {-l length} [-f flash address] [-e entry] [-r relocation address] [-s data length] [-n ] [name] Arguments Name Type Description Default -b Number Address of data to be written to the flash. Address of last loaded file. If not set in a load operation, it must be specified. -l Number Length of flash area to occopy.
PAGE 156

fis create Name -s Type Number -n name Description Default Actual length of data It defaults to the length of written to image. This is the last loaded file. used to control the range over which the checksum is made. When set, no image data will be written to the flash. Only the FIS directory will be updated. String Name of flash image. Description This command creates an image in the FIS directory. The data for the image must exist in RAM memory before the copy.
PAGE 157

fis create 53
PAGE 158

fis create 54
PAGE 159

fis load Name fis load — Load flash image Synopsis fis load [-b load address] [-c ] [-d ] [name] Arguments Name Type Description Default -b Number Address the image should be loaded to. Executable images normally load at the location to which the file was linked. This option allows the image to be loaded to a specific memory location, possibly overriding any assumed location. If not specified, the address associated with the image in the FIS directory will be used.
PAGE 160

fis load Examples Load and run RedBoot[RAM] image.
PAGE 161

fis delete Name fis delete — Delete flash image Synopsis fis delete {name} Arguments Name Type Description name Number Name of image that should be deleted. Default Description This command removes an image from the FIS. The flash memory will be erased as part of the execution of this command, as well as removal of the name from the FIS directory. Note: Certain images are reserved by RedBoot and cannot be deleted. RedBoot will issue a warning if this is attempted.
PAGE 162

fis delete 58
PAGE 163

fis lock Name fis lock — Lock flash area Synopsis fis lock {-f flash_address} {-l length} Arguments Name Type Description flash_address Number Address of area to be locked. length Number Length of area to be locked. Default Description This command is used to write-protect (lock) a portion of flash memory, to prevent accidental overwriting of images. In order to make make any modifications to the flash, a matching fis unlock command must be issued.
PAGE 164

fis lock 60
PAGE 165

fis unlock Name fis unlock — Unlock flash area Synopsis fis unlock {-f flash_address} {-l length} Arguments Name Type Description flash_address Number Address of area to be unlocked. length Number Length of area to be unlocked. Default Description This command is used to unlock a portion of flash memory forcibly, allowing it to be updated. It must be issued for regions which have been locked before the FIS can reuse those portions of flash.
PAGE 166

fis unlock 62
PAGE 167

fis erase Name fis erase — Erase flash area Synopsis fis erase {-f flash_address} {-l length} Arguments Name Type Description flash_address Number Address of area to be erased. length Number Length of area to be erased. Default Description This command is used to erase a portion of flash memory forcibly. There is no cross-checking to ensure that the area being erased does not correspond to an existing image. Examples Erase an area of the flash RedBoot> fis erase -f 0xa0040000 -l 0x20000 ...
PAGE 168

fis erase 64
PAGE 169

fis write Name fis write — Write flash area Synopsis fis write {-b mem_address} {-l length} {-f flash_address} Arguments Name Type Description mem_address Number Address of data to be written to flash. length Number Length of data to be writtem. flash_address Number Address of flash to write to. Default Description This command is used to write data from memory to flash. There is no cross-checking to ensure that the area being written to does not correspond to an existing image.
PAGE 170

fis write 66
PAGE 171

Chapter 2. RedBoot Commands and Examples Persistent State Flash-based Configuration and Control RedBoot provides flash management support for storage in the flash memory of multiple executable images and of non-volatile information such as IP addresses and other network information.
PAGE 172

Chapter 2. RedBoot Commands and Examples ... Unlock from 0x507c0000-0x507e0000: . ... Erase from 0x507c0000-0x507e0000: . ... Program from 0x0000a8d0-0x0000acd0 at 0x507c0000: . ... Lock from 0x507c0000-0x507e0000: . RedBoot> Additionally, nicknames can be used like aliases via the format %{nickname}. This allows the values stored by fconfig to be used directly by scripts and commands.
PAGE 173

Chapter 2. RedBoot Commands and Examples GDB connection port: 9000 Network debug at boot time: false The following example sets a boot script and then shows it running. RedBoot> fconfig Run script at boot: false t Boot script: Enter script, terminate with empty line >> fi li Boot script timeout: 0 10 Use BOOTP for network configuration: false . Update RedBoot non-volatile configuration - continue (y/n)? y ... Erase from 0xa0fc0000-0xa0fe0000: . ... Program from 0x8c021f60-0x8c022360 at 0xa0fc0000: .
PAGE 174

Chapter 2. RedBoot Commands and Examples RedBoot> fco Run script at boot: false t Boot script: Enter script, terminate with empty line >> {ROM}fis load RedBoot[RAM] >> {ROM}go >> {RAM}fis li >> Boot script timeout (1000ms resolution): 2 Use BOOTP for network configuration: false ... Update RedBoot non-volatile configuration - continue (y/n)? y ... Unlock from 0x007c0000-0x007e0000: . ... Erase from 0x007c0000-0x007e0000: . ... Program from 0xa0015030-0xa0016030 at 0x007df000: . ...
PAGE 175

Executing Programs from RedBoot Once an image has been loaded into memory, either via the load command or the fis load command, execution may be transfered to that image. NOTE: The image is assumed to be a stand-alone entity, as RedBoot gives the entire platform over to it. Typical examples would be an eCos application or a Linux kernel.
PAGE 176

go Examples Execute a program - no explicit output from RedBoot. RedBoot> go 0x40040 Execute a program with a timeout. RedBoot> go -w 10 About to start execution at 0x00000000 - abort with ^C within 10 seconds ^C RedBoot> Note that the starting address was implied (0x00000000 in this example). The user is prompted that execution will commence in 10 seconds.
PAGE 177

exec Name exec — Execute a Linux kernel Synopsis exec [-w timeout] [-r ramdisk_address] [-s ramdisk_length] [-b load_length} ] [-c kernel_command_line] [ entry_point] load_address {-l Arguments Name Type Description Default -w timeout Number Time to wait before starting 0 execution. -r ramdisk_address Number Address in memory of "initrd"-style ramdisk passed to Linux kernel. -s ramdisk_length Number Length of ramdisk image - None passed to Linux kernel.
PAGE 178

exec loaded ramdisk (initrd) is located. The "-c" option can be used to pass textual "command line" information to the kernel. If the command line data contains any punctuation (spaces, etc), then it must be quoted using the double-quote character ’"’. If the quote character is required, it should be written as ’\"’. Examples Execute a Linux kernel, passing a command line, which needs relocation. The result from RedBoot is normally quiet, with the target platform being passed over to Linux immediately.
PAGE 179

Chapter 3. Rebuilding RedBoot Introduction RedBoot is built as an application on top of eCos. The makefile rules for building RedBoot are part of the eCos CDL package, so it’s possible to build eCos from the Configuration Tool, as well as from the command line using ecosconfig. Building RedBoot requires only a few steps: selecting the platform and the RedBoot template, importing a platform specific configuration file, and finally starting the build.
PAGE 180

Chapter 3. Rebuilding RedBoot U U U U CYGDBG_HAL_COMMON_CONTEXT_SAVE_MINIMUM, new inferred value 0 CYGDBG_HAL_DEBUG_GDB_INCLUDE_STUBS, new inferred value 1 CYGFUN_LIBC_STRING_BSD_FUNCS, new inferred value 0 CYGPKG_NS_DNS_BUILD, new inferred value 0 Replace the platform name ("se7751") with the appropriate name for the chosen platform. Then import the appropriate platform RedBoot configuration file, here for RAM configuration: $ ecosconfig import ${ECOS_REPOSITORY}/hal/sh/se7751/VERSION /misc/redboot_RAM.
PAGE 181

Chapter 3. Rebuilding RedBoot As noted above, each platform’s details are mation provided in the shell variables to find described in Chapter 5. Use the the configuration file - the path to inforit is ${ECOS_REPOSITORY}/hal/${ARCH_DIR}/${PLATFORM_DIR}/${VERSION}/misc/${REDBOOT_CFG}.ecm, where ECOS_REPOSITORY points to the eCos/RedBoot sources, VERSION is the version of the package (usually "current") and REDBOOT_CFG is the desired configuration, e.g. redboot_RAM.
PAGE 182

Chapter 3.
PAGE 183

Chapter 4. Updating RedBoot Introduction RedBoot normally resides in an EPROM or, more common these days, a flash on the board. In the former case, updating RedBoot necessitates physically removing the part and reprogramming a new RedBoot image into it using prommer hardware. In the latter case, it is often possible to update RedBoot in situ using Redboot’s flash management commands. The process of updating RedBoot in situ is documented in this section.
PAGE 184

Chapter 4. Updating RedBoot RedBoot> fis create RedBoot[RAM] An image named ’RedBoot[RAM]’ exists - continue (y/n)? y * CAUTION * about to program ’RedBoot[RAM]’ at 0x00020000..0x000369c7 from 0x06020000 - continue (y/n)?y ... Erase from 0x00020000-0x00040000: .. ... Program from 0x06020000-0x060369c8 at 0x00020000: .. ... Erase from 0x00070000-0x00080000: . ... Program from 0x0606f000-0x0607f000 at 0x00070000: . RedBoot> fis lock RedBoot[RAM] ... Lock from 0x00000000-0x00020000: ..
PAGE 185

Chapter 4. Updating RedBoot Note: This command loads the RedBoot image using the TFTP protocol via a network connection. Other methods of loading are available, refer to the load command for more details. Note: Note that the binary version of the image is being downloaded. This is to ensure that the memory after the image is loaded should match the contents of the file on the host.
PAGE 186

Chapter 4.
PAGE 187

Chapter 5. Installation and Testing AM3x/MN103E010 Matsushita MN103E010 (AM33/2.0) ASB2305 Board Overview RedBoot supports the debug serial port and the built in ethernet port for communication and downloads. The default serial port settings are 115200,8,N,1 with RTS/CTS flow control. RedBoot can run from either flash, and can support flash management for either the boot PROM or the system flash regions.
PAGE 188

Chapter 5. Installation and Testing The RedBoot binary image files should also be copied to the TFTP pickup area on the host providing TFTP services if that is how RedBoot should pick up the images it is going to program into the flash. Alternatively, the images can be passed by YMODEM over the serial link. Preparing to use the JTAG debugger The JTAG debugger will also need setting up: 1.
PAGE 189

Chapter 5. Installation and Testing ed ed ed ed 0xd8c00130, 0xd8c00230, 0xd8c00234, 0xd8c00238, 0x8680ff81 0x21111000 0x00100200 0x00000004 ed ed ed ed 0xd8c00140, 0xd8c00240, 0xd8c00244, 0xd8c00248, 0x9800f801 0x00140000 0x11011100 0x01000001 ed ed ed ed ed 0xda000000, 0xda000004, 0xda000008, 0xda00000c, 0xda000000, 0x55561645 0x000003c0 0x9000fe01 0x9200fe01 0xa89b0654 3.
PAGE 190

Chapter 5. Installation and Testing 1. Instruct RedBoot to initialise the boot PROM: RedBoot> fi init 2. Write the previously loaded redboot.prom image into the boot PROM: RedBoot> fi write -f 0x80000000 -b 0x91020000 -l 0x00020000 3. Check that RedBoot has written the image: RedBoot> dump -b 0x91020000 RedBoot> dump -b 0x80000000 Barring the difference in address, the two dumps should be the same. 4. Close the JTAG software and power-cycle the board.
PAGE 191

Chapter 5. Installation and Testing -w Wait time in seconds before starting kernel -c "params" Parameters passed to kernel Kernel entry point, defaulting to the entry point of the last image loaded The parameter string is stored in the on-chip memory at location 0x8C001000, and is prefixed by “cmdline:” if it was supplied. Memory Maps RedBoot sets up the following memory map on the ASB2305 board. NOTE: The regions mapped between 0x80000000-0x9FFFFFFF are cached by the CPU.
PAGE 192

Chapter 5. Installation and Testing Rebuilding RedBoot These shell variables provide the platform-specific information needed for building RedBoot according to the procedure described in Chapter 3: export TARGET=asb2305 export ARCH_DIR=mn10300 export PLATFORM_DIR=asb2305 The names of configuration files are listed above with the description of the associated modes. ARM/ARM7 ARM Evaluator7T Overview RedBoot supports both serial ports for communication and downloads.
PAGE 193

Chapter 5. Installation and Testing • Prepare to download the UU-encoded version of the RedBoot image: Boot: download 10000 Ready to download. Use ’transmit’ option on terminal emulator to download file. • Either use ASCII transmit option in the terminal emulator, or on Linux, simply cat the file to the serial port: $ cat redboot.UU > /dev/ttyS0 When complete, you should see: Loaded file redboot.
PAGE 194

Chapter 5. Installation and Testing Rebuilding RedBoot These shell variables provide the platform-specific information needed for building RedBoot according to the procedure described in Chapter 3: export TARGET=e7t export ARCH_DIR=arm export PLATFORM_DIR=e7t The names of configuration files are listed above with the description of the associated modes. ARM/ARM7+ARM9 ARM Integrator Overview RedBoot supports both serial ports for communication and downloads.
PAGE 195

Chapter 5. Installation and Testing ARM bootPROM [Version 1.3] Rebuilt on Jun 26 2001 at 22:04:10 Running on a Integrator Evaluation Board Board Revision V1.0, ARM966E-S Processor Memory Size is 16MBytes, Flash Size is 32MBytes Copyright (c) ARM Limited 1999 - 2001. All rights reserved. Board designed by ARM Limited Hardware support provided at http://www.arm.
PAGE 196

Chapter 5.
PAGE 197

Chapter 5. Installation and Testing ARM/ARM7+ARM9 ARM PID Board and EPI Dev7+Dev9 Overview RedBoot uses either of the serial ports. The default serial port settings are 38400,8,N,1. Management of onboard flash is also supported. The following RedBoot configurations are supported: Configuration Mode Description File ROM [ROM] RedBoot running from the redboot_ROM.ecm board’s flash boot sector. RAM [RAM] RedBoot running from redboot_RAM.ecm RAM with RedBoot in the flash boot sector.
PAGE 198

Chapter 5. Installation and Testing Rebuilding RedBoot These shell variables provide the platform-specific information needed for building RedBoot according to the procedure described in Chapter 3: export TARGET=pid export ARCH_DIR=arm export PLATFORM_DIR=pid The names of configuration files are listed above with the description of the associated modes. ARM/ARM7 Atmel AT91 Evaluation Board (EB40) Overview RedBoot supports both serial ports. The default serial port settings are 38400,8,N,1.
PAGE 199

Chapter 5. Installation and Testing to flash. arm-elf-gdb redboot_RAM.elf (gdb) tar rdi s=/dev/ttyS0 Angel Debug Monitor (serial) 1.04 (Advanced RISC Machines SDT 2.5) for AT91EB40 (2.00) Angel Debug Monitor rebuilt on Apr 07 2000 at 12:40:31 Serial Rate: 9600 Connected to ARM RDI target. (gdb) set $cpsr=0xd3 (gdb) load Loading section .rom_vectors, size 0x40 lma 0x2020000 Loading section .text, size 0x7fd8 lma 0x2020040 Loading section .rodata, size 0x15a0 lma 0x2028018 Loading section .
PAGE 200

Chapter 5. Installation and Testing Memory Maps This processor has no MMU, so the only memory map is for physical addresses.
PAGE 201

Chapter 5. Installation and Testing Initial Installation Method A Windows or Linux utility is used to program flash using serial port #1 via on-chip programming firmware. See board documentation for details on in situ flash programming. Special RedBoot Commands None. Memory Maps The MMU page tables and LCD display buffer, if enabled, are located at the end of DRAM. NOTE: The virtual memory maps in this section use a C and B column to indicate whether or not the region is cached (C) or buffered (B).
PAGE 202

Chapter 5. Installation and Testing Platform Resource Usage The EP7xxx timer #2 is used as a polled timer to provide timeout support for network and XModem file transfers. Rebuilding RedBoot These shell variables provide the platform-specific information needed for building RedBoot according to the procedure described in Chapter 3: export export export export export TARGET=edb7211 TARGET=edb7212 TARGET=edb7312 ARCH_DIR=arm PLATFORM_DIR=edb7xxx Use one of the TARGET settings only.
PAGE 203

Chapter 5. Installation and Testing RedBoot as Primary Bootmonitor RedBoot is installed in flash using the on-board ARM Boot Monitor. Boot the board while pressing SPACE. This should bring up the Boot Monitor: ARM bootPROM [Version 1.3] Rebuilt on Jul 16 2001 at 16:21:36 Running on a P920 board Evaluation Board Board Revision V1.0, ARM920T processor Processor Memory Size is 32MBytes, Flash Size is 32MBytes Copyright (c) ARM Limited 1999 - 2001. All rights reserved.
PAGE 204

Chapter 5. Installation and Testing Download the ROMRAM mode image of RedBoot via ethernet: RedBoot> load -b %{FREEMEMLO} redboot_primary_ROMRAM/redboot.srec or using serial Y-modem protocol: RedBoot> load -mode ymodem -b %{FREEMEMLO} (Use the terminal emulator’s Y-modem upload command to send the file redWhen the image has been downloaded, program it into boot_primary_ROMRAM/redboot.srec.
PAGE 205

Chapter 5. Installation and Testing Raw file loaded 0x00100000-0x001a3d6c RedBoot> exec -c "console=ttyAC0,38400" Using base address 0x00100000 and length 0x000a3d6c Uncompressing Linux..... An image could also be put in flash and started directly: RedBoot> exec -b 0x60040000 -l 0xc0000 -c "console=ttyAC0,38400" Uncompressing Linux..... Memory Maps The MMU page tables are located at 0x4000.
PAGE 206

Chapter 5. Installation and Testing export ARCH_DIR=arm export PLATFORM_DIR=arm9/aaed2000 The names of configuration files are listed above with the description of the associated modes. ARM/ARM9 Altera Excalibur Overview RedBoot supports the serial port labelled P2 on the board. The default serial port settings are 57600,8,N,1. RedBoot also supports flash management on the Excalibur.
PAGE 207

Chapter 5. Installation and Testing Flash management The ROMRAM and REDBOOT configurations supported on this platform differ only in the memory layout (ROMRAM configuration runs RedBoot from 0x00008000 while REDBOOT configuration runs RedBoot from 0x07f80000). The REDBOOT configuration allows applications to be loaded and run from address 0x00008000.
PAGE 208

Chapter 5. Installation and Testing Memory Maps The MMU page tables are located at 0x4000. NOTE: The virtual memory maps in this section use a C and B column to indicate whether or not the region is cached (C) or buffered (B).
PAGE 209

Chapter 5. Installation and Testing Configuration Mode Description File ROM [ROM] RedBoot running from the redboot_ROM.ecm board’s flash boot sector. RAM [RAM] RedBoot running from redboot_RAM.ecm RAM with RedBoot in the flash boot sector. Initial Installation Method A linux application is used to program the flash over the PCI bus.
PAGE 210

Chapter 5. Installation and Testing Platform Resource Usage Timer3 is used as a polled timer to provide timeout support for networking and XModem file transfers. Rebuilding RedBoot These shell variables provide the platform-specific information needed for building RedBoot according to the procedure described in Chapter 3: export TARGET=ebsa285 export ARCH_DIR=arm export PLATFORM_DIR=ebsa285 The names of configuration files are listed above with the description of the associated modes.
PAGE 211

Chapter 5. Installation and Testing Memory Maps The first level page table is located at physical address 0xc0004000. No second level tables are used. NOTE: The virtual memory maps in this section use a C and B column to indicate whether or not the region is cached (C) or buffered (B).
PAGE 212

Chapter 5. Installation and Testing The names of configuration files are listed above with the description of the associated modes. ARM/StrongARM(SA1100) Intel SA1100 Multimedia Board Overview RedBoot supports both board serial ports. The default serial port settings are 38400,8,N,1. flash management is also supported. The following RedBoot configurations are supported: Configuration Mode Description File ROM [ROM] RedBoot running from the redboot_ROM.ecm board’s flash boot sector.
PAGE 213

Chapter 5.
PAGE 214

Chapter 5. Installation and Testing ARM/StrongARM(SA1110) Intel SA1110 (Assabet) Overview RedBoot supports the board serial port and the compact flash ethernet port. The default serial port settings are 38400,8,N,1. RedBoot also supports flash management on the Assabet. The following RedBoot configurations are supported: Configuration Mode Description File ROM [ROM] RedBoot running from the redboot_ROM.ecm board’s flash boot sector. RAM [RAM] RedBoot running from redboot_RAM.
PAGE 215

Chapter 5.
PAGE 216

Chapter 5. Installation and Testing The following RedBoot configurations are supported: Configuration Mode Description File POST [ROM] RedBoot running from the redboot_ROM.ecm first free flash block at 0x40000. RAM [RAM] RedBoot running from redboot_RAM.ecm RAM with RedBoot in the flash boot sector. Initial Installation Unlike other targets, the nanoEngine comes equipped with boot firmware which you cannot modify.
PAGE 217

Chapter 5. Installation and Testing NOTE: the BSE firmware runs its serial IO at 9600 Baud; RedBoot runs instead at 38400 Baud. You must select the right baud rate in your terminal program to be able to set up the BSE firmware. After a reset, the BSE firmware will print Boot: BSE 2000 Sep 12 2000 14:00:30 autoboot: "go 40000" [hit ESC to abort] and then RedBoot starts, switching to 38400 Baud.
PAGE 218

Chapter 5. Installation and Testing Special RedBoot Commands The nanoEngine/commEngine has one or two Intel i82559 Ethernet controllers installed, but these have no associated serial EEPROM in which to record their Ethernet Station Address (ESA, or MAC address). The BSE firmware records an ESA for the device it uses, but this information is not available to RedBoot; we cannot share it. To keep the ESAs for the two ethernet interfaces, two new items of RedBoot configuration data are introduced.
PAGE 219

Chapter 5. Installation and Testing The ethernet devices use a "PCI window" to communicate with the CPU. This is 1Mb of SDRAM which is shared with the ethernet devices that are on the PCI bus. It is neither cached nor buffered, to ensure that CPU and PCI accesses see correct data in the correct order. By default it is configured to be megabyte number 30, at addresses 0x01e00000-0x01efffff.
PAGE 220

Chapter 5. Installation and Testing Rebuilding RedBoot These shell variables provide the platform-specific information needed for building RedBoot according to the procedure described in Chapter 3: export TARGET=nano export ARCH_DIR=arm export PLATFORM_DIR=sa11x0/nano The names of configuration files are listed above with the description of the associated modes.
PAGE 221

Chapter 5. Installation and Testing loader can be accessed over the serial port at 115200/8N1. Using this loader, the contents of the iPAQ flash memory can be saved to a Compact Flash memory card. NOTE: We have only tested this operation with a 32Mbyte CF memory card. Given that the backup will take 16MBytes + 1KByte, something more than a 16MByte card will be required. Use the "r2c" command to dump Flash contents to the CF memory card.
PAGE 222

Chapter 5. Installation and Testing Platform: Compaq iPAQ Pocket PC (StrongARM 1110) Copyright (C) 2000, 2001, Red Hat, Inc. RAM: 0x00000000-0x01fc0000, 0x0001f200-0x01f70000 available FLASH: 0x50000000 - 0x51000000, 64 blocks of 0x00040000 bytes each. Since the LCD touchscreen is only 30 characters wide, some of this data will be off the right hand side of the display. The joypad may be used to pan left and right in order to see the full lines.
PAGE 223

Chapter 5. Installation and Testing WARNING You must type these commands exactly! Failure to do so may render your iPAQ totally useless. Once you’ve done this, RedBoot should come up every time you reset. Restoring Windows/CE To restore Windows/CE from the backup taken in the Section called Installing RedBoot permanently, visit http://www.handhelds.org/projects/wincerestoration.html for directions.
PAGE 224

Chapter 5. Installation and Testing Memory Maps RedBoot sets up the following memory map on the iPAQ: The first level page table is located at physical address 0xC0004000. No second level tables are used. NOTE: The virtual memory maps in this section use a C and B column to indicate whether or not the region is cached (C) or buffered (B).
PAGE 225

Chapter 5. Installation and Testing ARM/StrongARM(SA11X0) Intrinsyc CerfCube Overview RedBoot supports the serial port and the builtin ethernet connection for communication and downloads. The default serial port settings are 38400,8,N,1. RedBoot runs from and supports flash management for the system flash region. The following RedBoot configurations are supported: Configuration Mode Description File ROM [ROM] RedBoot running from the redboot_ROM.ecm board’s flash boot sector.
PAGE 226

Chapter 5. Installation and Testing -c "params" Parameters passed to kernel -r ’initrd’ ramdisk location -s Length of initrd ramdisk Memory Maps RedBoot sets up the following memory map on the CerfCube: The first level page table is located at physical address 0xC0004000. No second level tables are used. NOTE: The virtual memory maps in this section use a C and B column to indicate whether or not the region is cached (C) or buffered (B).
PAGE 227

Chapter 5. Installation and Testing Rebuilding RedBoot These shell variables provide the platform-specific information needed for building RedBoot according to the procedure described in Chapter 3: export TARGET=cerf export ARCH_DIR=arm export PLATFORM_DIR=sa11x0/cerf The names of configuration files are listed above with the description of the associated modes. ARM/Xscale Cyclone IQ80310 Overview RedBoot supports both serial ports and the built-in ethernet port for communication and downloads.
PAGE 228

Chapter 5. Installation and Testing To install RedBoot to run from the flash boot sector, use the manufacturer’s flash utility to install the ROM mode image at address zero. To install RedBoot to run from address 0x40000 with the ARM bootloader in the flash boot sector, use the manufacturer’s flash utility to install the ROMA mode image at address 0x40000.
PAGE 229

Chapter 5. Installation and Testing Using RedBoot with ARM Bootloader RedBoot can coexist with ARM tools in flash on the IQ80310 board. In this configuration, the ARM bootloader will occupy the flash boot sector while RedBoot is located at flash address 0x40000. The sixteen position rotary switch is used to tell the ARM bootloader to jump to the RedBoot image located at address 0x40000. RedBoot is selected by switch position 0 or 1.
PAGE 230

Chapter 5. Installation and Testing 15 - Battery Backup SDRAM Memory Test 16 - GPIO Test 17 - Repeat-On-Fail Memory Test 18 - Coyonosa Cache Loop (No return) 19 - Show Software and Hardware Revision 0 - quit Enter the menu item number (0 to quit): Tests for various hardware subsystems are provided, and some tests require special hardware in order to execute normally. The Ethernet Configuration item may be used to set the board ethernet address.
PAGE 231

Chapter 5.
PAGE 232

Chapter 5. Installation and Testing #define CYGNUM_HAL_INTERRUPT_P_SERR #define CYGNUM_HAL_INTERRUPT_S_SERR 47 48 The data passed to the ISR is pulled from a data table (hal_interrupt_data) which immediately follows the interrupt vector table. With 49 interrupts, the data table starts at address 0xA000A0C8. An application may create a normal C function with the above prototype to be an ISR. Just poke its address into the table at the correct index and enable the interrupt at its source.
PAGE 233

Chapter 5. Installation and Testing 0xc0000000 - 0xcfffffff 0xd0000000 - 0xd0000fff 0xf0000000 - 0xffffffff Y Y Y N N N Cache Flush Region first 4k page of flash 80200 Internal Registers Platform Resource Usage The external timer is used as a polled timer to provide timeout support for networking and XModem file transfers. ARM/Xscale Intel IQ80321 Overview RedBoot supports the serial port and the built-in ethernet port for communication and downloads. The default serial port settings are 115200,8,N,1.
PAGE 234

Chapter 5. Installation and Testing ... Erase from 0xf07e0000-0xf0800000: . ... Program from 0x01ddf000-0x01ddf400 at 0xf07e0000: . ... Lock from 0xf07e0000-0xf0800000: . Switch Settings The 80321 board is highly configurable through a number of switches and jumpers.
PAGE 235

Chapter 5. Installation and Testing Enable coprocessor access Drain write and fill buffer Setup PBIU chip selects A1 Enable the Icache A2 Move FLASH chip select from 0x0 to 0xF0000000 Jump to new FLASH location A3 Setup and enable the MMU A4 I2C interface initialization 90 Wait for I2C initialization to complete 91 Send address (via I2C) to the DIMM 92 Wait for transmit complete 93 Read SDRAM PD data from DIMM 94 Read remainder of EEPROM data.
PAGE 236

Chapter 5.
PAGE 237

Chapter 5. Installation and Testing Enter the menu item number (0 to quit): Tests for various hardware subsystems are provided, and some tests require special hardware in order to execute normally. The Ethernet Configuration item may be used to set the board ethernet address. Memory Tests This test is used to test installed DDR SDRAM memory. Five different tests are run over the given address ranges. If errors are encountered, the test is aborted and information about the failure is printed.
PAGE 238

Chapter 5. Installation and Testing 7 Segment LED Tests This tests the operation of the seven segment displays. When run, each LED cycles through 0 through F and a decimal point. i82544 Ethernet Configuration This test initializes the ethernet controller’s serial EEPROM if the current contents are invalid. In any case, this test will also allow the user to enter a six byte ethernet MAC address into the serial EEPROM.
PAGE 239

Chapter 5. Installation and Testing PCI Bus Test This tests the secondary PCI-X bus and socket. This test requires that an IQ80310 board be plugged into the secondary slot of the IOP80321 board. The test assumes at least 32MB of installed memory on the IQ80310. That memory is mapped into the IOP80321 address space and the memory tests are run on that memory. CPU Cache Loop This test puts the CPU into a tight loop run entirely from the ICache. This should prevent all external bus accesses.
PAGE 240

Chapter 5.
PAGE 241

Chapter 5.
PAGE 242

Chapter 5. Installation and Testing The calmRISC16 is a harvard architecture with separate 22-bit program and data addresses. The instruction set provides no instruction for writing to program memory. The MDSChip board firmware (called CalmBreaker) provides a pseudo register interface so that code running on the core has access to a serial channel and a mechanism to write to program memory. The serial channel is fixed at 57600-8-N-1 by the firmware.
PAGE 243

Chapter 5. Installation and Testing Rebuilding RedBoot These shell variables provide the platform-specific information needed for building RedBoot according to the procedure described in Chapter 3: export TARGET=calm16_ceb export ARCH_DIR=calmrisc16 export PLATFORM_DIR=ceb The names of configuration files are listed above with the description of the associated modes.
PAGE 244

Chapter 5. Installation and Testing The ’Run’ LED on the core board should be on. Connecting to the MDSboard with a terminal and typing enter should result in RedBoot reprinting the command prompt. Special RedBoot Commands None. Special Note on Serial Channel The MDSChip board uses a relatively slow microcontroller to provide the pseudo-register interface to the core board. This pseudo-register interface provides access to the serial channel and write access to program memory.
PAGE 245

Chapter 5. Installation and Testing Configuration ROMRAM Mode [ROMRAM] Description File RedBoot running from redboot_ROMRAM.ecm RAM, but contained in the board’s flash boot sector. RAM [RAM] RedBoot running from redboot_RAM.ecm RAM with RedBoot in the flash boot sector. Initial Installation Method RedBoot can be installed by directly programming the FLASH device in IC7 or by using the Fujitsu provided software to download and install a version into the FLASH device.
PAGE 246

Chapter 5. Installation and Testing Rebuilding RedBoot These shell variables provide the platform-specific information needed for building RedBoot according to the procedure described in Chapter 3: export TARGET=frv400 export ARCH_DIR=frv export PLATFORM_DIR=frv400 The names of configuration files are listed above with the description of the associated modes.
PAGE 247

Chapter 5. Installation and Testing $ dd conv=sync if=install/bin/redboot.bin of=/dev/fd0 Insert this floppy in the A: drive of the PC to be used as a target and ensure that the BIOS is configured to boot from A: by default. On reset, the PC will boot from the floppy and be ready to be debugged via either serial line, or via the ethernet interface if it is installed. NOTE: Unreliable floppy media may cause the write to silently fail. This can be determined if the RedBoot image does not correctly boot.
PAGE 248

Chapter 5. Installation and Testing flash region. The following RedBoot configurations are supported: Configuration Mode Description ROM [ROM] RedBoot running from the redboot_ROM.ecm board’s flash boot sector. File RAM [RAM] RedBoot running from redboot_RAM.ecm RAM with RedBoot in the flash boot sector. Initial Installation RedBoot is installed using the code download facility built into the Atlas board.
PAGE 249

Chapter 5. Installation and Testing The Atlas Developer’s Kit CD contains an srec2flash utility. The source code for this utility is part of the yamon/yamon-src-01.01.tar.gz tarball on the Dev Kit CD. The path in the expanded tarball is yamon/bin/tools. To use srec2flash to convert the S-record file: $ srec2flash -EL -S29 redboot.srec >redboot.dl The Atlas/Malta Developer’s Kit CD contains an srecconv.pl utility which requires Perl. This utilty is part of the yamon/yamon-src-02.00.tar.
PAGE 250

Chapter 5. Installation and Testing void Linux(int argc, char **argv, char **envp); RedBoot will place the appropriate data at the offset specified by the -b parameter, or by default at address 0x80080000, and will set the arguments accordingly when calling into the kernel. The default entry point, if no image with explicit entry point has been loaded and none is specified, is 0x80000750. Interrupts RedBoot uses an interrupt vector table which is located at address 0x80000400.
PAGE 251

Chapter 5. Installation and Testing Memory Maps Memory Maps RedBoot sets up the following memory map on the Atlas board.
PAGE 252

Chapter 5. Installation and Testing Initial Installation RedBoot is installed using the code download facility built into the Malta board. See the Malta User manual for details, and also the Malta download format in the Section called Malta download format. Quick download instructions Here are quick start instructions for downloading the prebuilt RedBoot image. 1. Locate the prebuilt files in the bin directory: deleteall.fl and redboot_ROM.fl. 2. Make sure switch S5-1 is ON.
PAGE 253

Chapter 5.
PAGE 254

Chapter 5. Installation and Testing #define #define #define #define CYGNUM_HAL_INTERRUPT_MOUSE CYGNUM_HAL_INTERRUPT_19 CYGNUM_HAL_INTERRUPT_IDE_PRIMARY CYGNUM_HAL_INTERRUPT_IDE_SECONDARY 18 19 20 21 The data passed to the ISR is pulled from a data table (hal_interrupt_data) which immediately follows the interrupt vector table. With 22 interrupts, the data table starts at address 0x80000258. An application may create a normal C function with the above prototype to be an ISR.
PAGE 255

Chapter 5. Installation and Testing MIPS/RM7000 PMC-Sierra Ocelot Overview RedBoot uses the front facing serial port. The default serial port settings are 38400,8,N,1. RedBoot also supports ethernet. Management of onboard flash is also supported. The following RedBoot configurations are supported: Configuration Mode Description File ROM [ROM] RedBoot running from the redboot_ROM.ecm board’s flash boot sector. RAM [RAM] RedBoot running from redboot_RAM.ecm RAM with RedBoot in the flash boot sector.
PAGE 256

Chapter 5. Installation and Testing Memory Maps RedBoot sets up the following memory map on the Ocelot board. Note that these addresses are accessed through kseg0/1 and thus translate to the actual address range 0x800000000xbfffffff, depending on the need for caching/non-caching access to the bus. NOTE: The virtual memory maps in this section use a C and B column to indicate whether or not the region is cached (C) or buffered (B).
PAGE 257

Chapter 5. Installation and Testing Configuration RAM Mode [RAM] Description File RedBoot running from redboot_RAM.ecm RAM with RedBoot in the flash boot sector. Initial Installation Method A device programmer should be used to program a socketed FLASH part (AMD 29F040). The board as delivered is configured for a 512K EPROM. To install a FLASH ROM, Jumpers J30, J31 and J36 need to be changed as described in the board’s User Manual. Special RedBoot Commands None.
PAGE 258

Chapter 5. Installation and Testing NOTE: The MMU has been set up to relocate the VRC4372 supported devices mapped at physical addresses 0x8xxxxxxx to virtual addresses 0xCxxxxxxx. Ethernet Driver The ethernet driver is in two parts: A generic ether driver for the Intel i21143 device is located in devs/eth/intel/i21143. Its package name is CYGPKG_DEVS_ETH_INTEL_I21143. The platform-specific ether driver is devs/eth/mips/vrc4375. Its package is CYGPKG_DEVS_ETH_MIPS_VRC4375.
PAGE 259

Chapter 5. Installation and Testing Initial Installation Method RedBoot must be installed at the A & M factory. Special RedBoot Commands None. Memory Maps Memory Maps RedBoot sets up the following memory map on the MBX board.
PAGE 260

Chapter 5. Installation and Testing Configuration RAM Mode [RAM] Description File RedBoot running from redboot_RAM.ecm RAM with RedBoot in the flash boot sector. Initial Installation Method Device programmer is used to program the XU1 socketed flash part (AM29F040B) with the ROM mode image of RedBoot. Use the on-board EPPC-Bug monitor to update RedBoot. This assumes that you have EPPC-Bug in the on-board flash.
PAGE 261

Chapter 5. Installation and Testing Memory Maps Memory Maps RedBoot sets up the following memory map on the MBX board.
PAGE 262

Chapter 5. Installation and Testing Memory Maps RedBoot sets up the following memory map on the EDK7708 board.
PAGE 263

Chapter 5. Installation and Testing Initial Installation Method The Solution Engine ships with the Hitachi boot monitor in EPROM which allows for initial programming of RedBoot: 1. Set switch SW4-1 to ON [boot from EPROM] 2. Connect a serial cable to CN1 (SCI) and power up the board. 3. After the boot monitor banner, invoke the flash download/program command: Ready >fl 4.
PAGE 264

Chapter 5. Installation and Testing -r Root device specification. /dev/ram is 0x0101 -l Loader type Finally the kernel entry address can be specified as an optional argument. The default is 0x8c102000 For the the SE77x9, Linux by default expects to be loaded at 0x8c001000 which conflicts with the data space used by RedBoot. To work around this, either change the CONFIG_MEMORY_START kernel option to a higher address, or use the compressed kernel image and load it at a higher address.
PAGE 265

Chapter 5. Installation and Testing SuperH/SH3(SH7729) Hitachi HS7729PCI Overview RedBoot uses the COM1 and COM2 serial ports (and the debug port on the motherboard). The default serial port settings are 38400,8,N,1. Ethernet is also supported using a D-Link DFE-530TX PCI plugin card. Management of onboard flash is also supported. The following RedBoot configurations are supported: Configuration Mode Description File ROM [ROM] RedBoot running from the redboot_ROM.ecm board’s flash boot sector.
PAGE 266

Chapter 5. Installation and Testing -b Parameter block address. This is normally the first page of the kernel image and defaults to 0x8c101000 -i Start address of initrd image -j Size of initrd image -c "args" Kernel arguments string -m Mount rdonly flags. If set to a non-zero value the root partition will be mounted read-only. -f RAM disk flags. Should normally be 0x4000 -r Root device specification.
PAGE 267

Chapter 5. Installation and Testing Rebuilding RedBoot These shell variables provide the platform-specific information needed for building RedBoot according to the procedure described in Chapter 3: export TARGET=hs7729pci export ARCH_DIR=sh export PLATFORM_DIR=hs7729pci The names of configuration files are listed above with the description of the associated modes. SuperH/SH3(SH77X9) Hitachi Solution Engine 77X9 Overview This description covers the MS7729SE01 and MS7709SSE0101 variants.
PAGE 268

Chapter 5. Installation and Testing 4. The monitor should now ask for input: Flash ROM data copy to RAM Please Send A S-format Record At this point copy the RedBoot ROM SREC file to the serial port: $ cat redboot_ROM.eprom.srec > /dev/ttyS0 Eventually you should see something like Start Addrs = A1000000 End Addrs = A1xxxxxx Transfer complete from the monitor. 5. Set switch SW4-3 to OFF [boot from flash] and reboot the board. You should now see the RedBoot banner.
PAGE 269

Chapter 5. Installation and Testing Memory Maps RedBoot sets up the following memory map on the SE77x9 board.
PAGE 270

Chapter 5. Installation and Testing Configuration RAM Mode [RAM] Description File RedBoot running from redboot_RAM.ecm RAM with RedBoot in the flash boot sector. Initial Installation Method The Solution Engine ships with the Hitachi boot monitor in EPROM which allows for initial programming of RedBoot: 1. Set switches SW5-3 and SW5-4 to ON [boot from EPROM] 2. Connect a serial cable to COM1 and power up the board. 3. After the boot monitor banner, invoke the flash download/program command: Ready >fl 4.
PAGE 271

Chapter 5. Installation and Testing -c "args" Kernel arguments string -m Mount rdonly flags. If set to a non-zero value the root partition will be mounted read-only. -f RAM disk flags. Should normally be 0x4000 -r Root device specification. /dev/ram is 0x0101 -l Loader type Finally the kernel entry address can be specified as an optional argument.
PAGE 272

Chapter 5. Installation and Testing export PLATFORM_DIR=se7751 The names of configuration files are listed above with the description of the associated modes.
PAGE 273

III.
PAGE 274
PAGE 275

Chapter 6. Introduction This is an initial specification of the eCos Hardware Abstraction Layer (HAL). The HAL abstracts the underlying hardware of a processor architecture and/or the platform to a level sufficient for the eCos kernel to be ported onto that platform. Caveat: This document is an informal description of the HAL capabilities and is not intended to be full documentation, although it may be used as a source for such.
PAGE 276

Chapter 6.
PAGE 277

Chapter 7. Architecture, Variant and Platform We have identified three levels at which the HAL must operate. • The architecture HAL abstracts the basic CPU architecture and includes things like interrupt delivery, context switching, CPU startup etc. • The variant HAL encapsulates features of the CPU variant such as caches, MMU and FPU features. It also deals with any on-chip peripherals such as memory and interrupt controllers.
PAGE 278

Chapter 7.
PAGE 279

Chapter 8. General principles The HAL has been implemented according to the following general principles: 1. The HAL is implemented in C and assembler, although the eCos kernel is largely implemented in C++. This is to permit the HAL the widest possible applicability. 2. All interfaces to the HAL are implemented by CPP macros. This allows them to be implemented as inline C code, inline assembler or function calls to external C or assembler code.
PAGE 280

Chapter 8.
PAGE 281

Chapter 9. HAL Interfaces This section describes the main HAL interfaces. Base Definitions These are definitions that characterize the properties of the base architecture that are used to compile the portable parts of the kernel. They are concerned with such things a portable type definitions, endianness, and labeling. These definitions are supplied by the cyg/hal/basetype.h header file which is supplied by the architecture HAL. It is included automatically by cyg/infra/cyg_type.h.
PAGE 282

Chapter 9. HAL Interfaces These macros define the C base types that should be used to define variables of the given size. They only need to be defined if the default types specified in cyg/infra/cyg_type.h cannot be used. Note that these are only the base types, they will be composed with signed and unsigned to form full type specifications. Atomic types cyg_halatomic CYG_ATOMIC These types are guaranteed to be read or written in a single uninterruptible operation.
PAGE 283

Chapter 9. HAL Interfaces arg A value that is passed as the first argument to the entry point function. entry The address of an entry point function. This will be called according the C calling conventions, and the value of arg will be passed as the first argument. This function should have the following type signature void entry(CYG_ADDRWORD arg). id A thread id value.
PAGE 284

Chapter 9. HAL Interfaces Note that interrupts are not disabled during this process, any interrupts that occur will be delivered onto the stack to which the current CPU stack pointer points. Hence the stack pointer should never be invalid, or loaded with a value that might cause the saved state to become corrupted by an interrupt. However, the current interrupt state is saved and restored as part of the thread context.
PAGE 285

Chapter 9. HAL Interfaces HAL_BREAKINST contains the breakpoint instruction code as an integer value. HAL_BREAKINST_SIZE is the size of that breakpoint instruction in bytes. Together these may be used to place a breakpoint in any code. GDB support HAL_THREAD_GET_SAVED_REGISTERS( sp, regs ) HAL_GET_GDB_REGISTERS( regval, regs ) HAL_SET_GDB_REGISTERS( regs, regval ) These macros provide support for interfacing GDB to the HAL.
PAGE 286

Chapter 9. HAL Interfaces CYGNUM_HAL_STACK_SIZE_TYPICAL is a reasonable increment over CYGNUM_HAL_STACK_SIZE_MINIMUM, usu- ally about 1kB. This should be adequate for most modest thread needs. Only threads that need to define significant amounts of local data, or have very deep call trees should need to use a larger stack size.
PAGE 287

Chapter 9. HAL Interfaces Vector numbers CYGNUM_HAL_VECTOR_XXXX CYGNUM_HAL_VSR_MIN CYGNUM_HAL_VSR_MAX CYGNUM_HAL_VSR_COUNT CYGNUM_HAL_INTERRUPT_XXXX CYGNUM_HAL_ISR_MIN CYGNUM_HAL_ISR_MAX CYGNUM_HAL_ISR_COUNT CYGNUM_HAL_EXCEPTION_XXXX CYGNUM_HAL_EXCEPTION_MIN CYGNUM_HAL_EXCEPTION_MAX CYGNUM_HAL_EXCEPTION_COUNT All possible VSR, interrupt and exception vectors are specified here, together with maximum and minimum values for range checking.
PAGE 288

Chapter 9. HAL Interfaces HAL_DISABLE_INTERRUPTS() disables the delivery of interrupts and stores the original state of the interrupt mask in the variable passed in the old argument. HAL_RESTORE_INTERRUPTS() restores the state of the interrupt mask to that recorded in old. HAL_ENABLE_INTERRUPTS() simply enables interrupts regardless of the current state of the mask. HAL_QUERY_INTERRUPTS() stores the state of the interrupt mask in the variable passed in the state argument.
PAGE 289

Chapter 9. HAL Interfaces HAL_INTERRUPT_CONFIGURE( vector, level, up ) HAL_INTERRUPT_SET_LEVEL( vector, level ) These macros exert control over any prioritized interrupt controller that is present. If no priority controller exists, then these macros should be empty. Note: These macros may not be reentrant, so care should be taken to prevent them being called while interrupts are enabled. This means that they can be safely used in initialization code before interrupts are enabled, and in ISRs.
PAGE 290

Chapter 9. HAL Interfaces Clock control HAL_CLOCK_INITIALIZE( period ) HAL_CLOCK_RESET( vector, period ) HAL_CLOCK_READ( pvalue ) These macros provide control over a clock or timer device that may be used by the kernel to provide time-out, delay and scheduling services. The clock is assumed to be implemented by some form of counter that is incremented or decremented by some external source and which raises an interrupt when it reaches a predetermined value.
PAGE 291

Chapter 9. HAL Interfaces Register address HAL_IO_REGISTER This type is used to store the address of an I/O register. It will normally be a memory address, an integer port address or an offset into an I/O space. More complex architectures may need to code an address space plus offset pair into a single word, or may represent it as a structure. Values of variables and constants of this type will usually be supplied by configuration mechanisms or in target specific headers.
PAGE 292

Chapter 9. HAL Interfaces These definitions are usually found in the header file cyg/hal/hal_cache.h. This file may be defined in the architecture, variant or platform HAL, depending on where the caches are implemented for the target. Often there will be a generic implementation of the cache control macros in the architecture HAL with the ability to override or undefine them in the variant or platform HAL.
PAGE 293

Chapter 9. HAL Interfaces HAL_XCACHE_SETS Defines the number of sets in the cache, and is calculated from the previous values. Global Cache Control HAL_XCACHE_ENABLE() HAL_XCACHE_DISABLE() HAL_XCACHE_INVALIDATE_ALL() HAL_XCACHE_SYNC() HAL_XCACHE_BURST_SIZE( size ) HAL_DCACHE_WRITE_MODE( mode ) HAL_XCACHE_LOCK( base, size ) HAL_XCACHE_UNLOCK( base, size ) HAL_XCACHE_UNLOCK_ALL() These macros affect the state of the entire cache, or a large part of it.
PAGE 294

Chapter 9. HAL Interfaces HAL_XCACHE_BURST_SIZE() Allows the size of cache to/from memory bursts to be controlled. This macro will only be defined if this functionality is available. HAL_DCACHE_WRITE_MODE() Controls the way in which data cache lines are written back to memory. There will be definitions for the possible modes. Typical definitions are HAL_DCACHE_WRITEBACK_MODE and HAL_DCACHE_WRITETHRU_MODE. This macro will only be defined if this functionality is available.
PAGE 295

Chapter 9. HAL Interfaces HAL_XCACHE_INVALIDATE() Invalidates all cache lines in the region. Any dirty lines are invalidated without being written to memory. HAL_DCACHE_STORE() Writes all dirty lines in the region to memory, but does not invalidate any lines. HAL_DCACHE_READ_HINT() Hints to the cache that the region is going to be read from in the near future. This may cause the region to be speculatively read into the cache.
PAGE 296

Chapter 9. HAL Interfaces in the platform HAL. This file is used by the MLT to manufacture both the .ldi and .h files. Users should beware that direct edits the either of these files may be overwritten if the MLT is run and regenerates them from the .mlt file. The names of the .ldi and .h files are defined by macro definitions in pkgconf/system.h. These are CYGHWR_MEMORY_LAYOUT_LDI and CYGHWR_MEMORY_LAYOUT_H respectively. While there will be little need for the application to refer to the .
PAGE 297

Chapter 9. HAL Interfaces isters which can be used to serialize implementations of these operations. Whatever hardware facilities are available, they are used in eCos to implement spinlocks. • Coherent caches. It is assumed that no extra effort will be required to access shared memory from any processor. This means that either there are no caches, they are shared by all processors, or are maintained in a coherent state by the hardware.
PAGE 298

Chapter 9. HAL Interfaces HAL_SMP_CPU_MAX The maximum number of CPUs that can be supported. This is used to provide the size of any arrays that have an element per CPU. HAL_SMP_CPU_COUNT() Returns the number of CPUs currently operational. This may differ from HAL_SMP_CPU_MAX depending on the runtime environment. HAL_SMP_CPU_THIS() Returns the CPU id of the current CPU. HAL_SMP_CPU_NONE A value that does not match any real CPU id. This is uses where a CPU type variable must be set to a null value.
PAGE 299

Chapter 9. HAL Interfaces Spinlocks Spinlocks provide inter-CPU locking. Normally they will be implemented on top of the test-and-set mechanism above, but may also be implemented by other means if, for example, the hardware has more direct support for spinlocks. HAL_SPINLOCK_TYPE The type for all spinlock variables. HAL_SPINLOCK_INIT_CLEAR A value that may be assigned to a spinlock variable to initialize it to clear.
PAGE 300

Chapter 9. HAL Interfaces HAL_SMP_SCHEDLOCK_INC( lock, data ) Increment the scheduler lock. The first increment of the lock from zero to one for any CPU may cause it to wait until the lock is zeroed by another CPU. Subsequent increments should be less expensive since this CPU already holds the lock. HAL_SMP_SCHEDLOCK_ZERO( lock, data ) Zero the scheduler lock. This operation will also clear the lock so that other CPUs may claim it.
PAGE 301

Chapter 10. Exception Handling Most of the HAL consists of simple macros or functions that are called via the interfaces described in the previous section. These just perform whatever operation is required by accessing the hardware and then return. The exception to this is the handling of exceptions: either synchronous hardware traps or asynchronous device interrupts. Here control is passed first to the HAL, which then passed it on to eCos or the application.
PAGE 302

Chapter 10. Exception Handling • Set up any bus bridges and support chips. Often access to device registers needs to go through various bus bridges and other intermediary devices. In many systems these are combined with the memory controller, so it makes sense to set these up together. This is particularly important if early diagnostic output needs to go through one of these devices. • Set up diagnostic mechanisms.
PAGE 303

Chapter 10. Exception Handling Vectors and VSRs The CPU delivers all exceptions, whether synchronous faults or asynchronous interrupts, to a set of hardware defined vectors. Depending on the architecture, these may be implemented in a number of different ways. Examples of existing mechanisms are: PowerPC Exceptions are vectored to locations 256 bytes apart starting at either zero or 0xFFF00000.
PAGE 304

Chapter 10. Exception Handling PowerPC A separate trampoline is contained in each of the vector locations. This code saves a few work registers away to the special purposes registers available, loads the exception number into a register and then uses that to index the VSR table and jump to the VSR. The VSR is entered with some registers move to the SPRs, and one of the data register containing the number of the vector taken.
PAGE 305

Chapter 10. Exception Handling The default interrupt VSR has a number of responsibilities if it is going to interact with the Kernel cleanly and allow interrupts to cause thread preemption. To support this VSR an ISR vector table is needed. For each valid vector three pointers need to be stored: the ISR, its data pointer and an opaque (to the HAL) interrupt object pointer needed by the kernel. It is implementation defined whether these are stored in a single table of triples, or in three separate tables.
PAGE 306

Chapter 10. Exception Handling interrupted thread. Depending on the architecture, it may be necessary to disable interrupts again for part of this. The detailed order of these steps may vary slightly depending on the architecture, in particular where interrupts are enabled and disabled.
PAGE 307

Chapter 11. Porting Guide Introduction eCos has been designed to be fairly easy to port to new targets. A target is a specific platform (board) using a given architecture (CPU type). The porting is facilitated by the hierarchical layering of the eCos sources - all architecture and platform specific code is implemented in a HAL (hardware abstraction layer). By porting the eCos HAL to a new target the core functionality of eCos (infra, kernel, uITRON, etc) will be able to run on the target.
PAGE 308

Chapter 11. Porting Guide HAL Classes The eCos HAL consists of four HAL sub-classes. This table gives a brief description of each class and partly reiterates the description in Chapter 7. The links refer to the on-line CVS tree (specifically to the sub-HALs used by the PowerPC MBX target). HAL type Description Functionality Overview Common HAL (hal/common) Configuration options and (http://sourceware.cygnus.com/cgi- functionality shared by all HALs. bin/cvsweb.
PAGE 309

Chapter 11. Porting Guide please try to follow it as closely as possible. Still, no two targets are the same, so sometimes it makes sense to use additional files. Common HAL File Description include/dbg-thread-syscall.h Defines the thread debugging syscall function. This is used by the ROM monitor to access the thread debugging API in the RAM application. . include/dbg-threads-api.h Defines the thread debugging API. . include/drv_api.h Defines the driver API. include/generic-stub.
PAGE 310

Chapter 11. Porting Guide Note that many of the definitions in these files are only conditionally defined - if the equivalent variant or platform headers provide the definitions, those override the generic architecture definitions. File Description include/arch.inc Various assembly macros used during system initialization. include/basetype.h Endian, label, alignment, and type size definitions. These override common defaults in CYGPKG_INFRA. include/hal_arch.
PAGE 311

Chapter 11. Porting Guide File include/var_arch.h Description Saved register frame format, various thread, register and stack related macros. include/var_cache.h Cache related macros. include/var_intr.h Interrupt related macros. include/var_regs.h Extra register definitions for the CPU variant. include/variant.inc Various assembly macros used during system initialization. src/var_intr.c Interrupt functions if necessary. src/var_misc.c hal_variant_init function and any necessary extra functions.
PAGE 312

Chapter 11. Porting Guide File src/plf_stub.c Description Platform specific stub initialization and possibly the low-level device driver. The platform HAL also contains files specifying the platform’s memory layout. These files are located in include/pkgconf. Auxiliary HAL Auxiliary HALs contain whatever files are necessary to provide the required functionality. There are no predefined set of files required in an auxiliary HAL.
PAGE 313

Chapter 11. Porting Guide The appropriate use of the mechanism is specified loosely by a policy. The general policy dictates that the vectors are initialized in whole by ROM monitors (built for ROM or RAM), or by stand-alone applications. For configurations relying on a ROM monitor environment, the policy is to allow initialization on a service by service basis.
PAGE 314

Chapter 11. Porting Guide Con: The layer of indirection is another point of failure. The concern primarily being that of vectors being trashed by rogue writes from bad code, causing a complete loss of the service and possibly a crash. But this does not differ much from a rogue write to anywhere else in the address space which could cause the same amount of mayhem. But it is arguably an additional point of failure for the service in question.
PAGE 315

Chapter 11. Porting Guide Having two separate channels allows, e.g., for simple logging without conflicts with the debugger or interactive IO which some debuggers do not allow. Mangling As debuggers usually have a protocol using specialized commands when communicating with the stub on the target, sending out text as raw ASCII from the target on the same channel will either result in protocol errors (with loss of control over the target) or the text may just be ignored as junk by the debugger.
PAGE 316

Chapter 11. Porting Guide • For debugging with raw diagnostic output, mangling is disabled. Debugging session continues as initiated by the ROM monitor, whether the application was launched via serial or Ethernet. Diagnostic output is directed at the IO port configured in the application configuration. Note:: There is one caveat to be aware of.
PAGE 317

Chapter 11. Porting Guide The problem also occurred on any targets with multiple serial ports where the ROM monitor was configured to use a different port than the CDL defaults. • Proper control of when to mangle or just write out raw ASCII text. Sometimes it’s desirable to disable mangling, even if the channel specified is the same as that used for debugging.
PAGE 318

Chapter 11. Porting Guide CONSOLE_PROCS The communication procedure table used for console IO (see the Section called IO channels. DEBUG_PROCS The communication procedure table used for debugger IO (see the Section called IO channels). FLUSH_DCACHE Flushes the data cache for the specified region. Some implementations may flush the entire data cache. FLUSH_ICACHE Flushes (invalidates) the instruction cache for the specified region. Some implementations may flush the entire instruction cache.
PAGE 319

Chapter 11. Porting Guide Compatibility When a platform is changed to support the calling interface, applications will use it if so configured. That means that if an application is run on a platform with an older ROM monitor, the service is almost guaranteed to fail. For this reason, applications should only use Console Comm for HAL diagnostics output if explicitly configured to do so (CYGSEM_HAL_VIRTUAL_VECTOR_DIAG). As for asynchronous GDB interrupts, the service will always be used.
PAGE 320

Chapter 11. Porting Guide IO channels The calling interface provides procedure tables for all IO channels on the platform. These are used for console (diagnostic) and debugger IO, allowing a ROM monitor to provided all the needed IO routines. At the same time, this makes it easy to switch console/debugger channels at run-time (the old implementation had hardwired drivers for console and debugger IO, preventing these to change at run-time).
PAGE 321

Chapter 11. Porting Guide IRQ_DISABLE Disable debugging receive interrupts on the device. IRQ_ENABLE Enable debugging receive interrupts on the device. DBG_ISR_VECTOR Returns the ISR vector used by the device for debugging receive interrupts. SET_TIMEOUT Set GETC timeout in milliseconds. FLUSH_OUTPUT Forces driver to flush data in its buffers. Note that this may not affect hardware buffers (e.g. FIFOs). DBG_ISR ISR used to handle receive interrupts from the device (see ).
PAGE 322

Chapter 11. Porting Guide } Beware that if doing something like the above, you should only do it to a channel which does not have GDB at the other end: GDB ignores raw data, so you would not see the output. Compatibility The use of this service is controlled by the option CYGSEM_HAL_VIRTUAL_VECTOR_DIAG which is disabled per default on most older platforms (thus preserving backwards compatibility with older stubs). On newer ports, this option should always be set.
PAGE 323

Chapter 11. Porting Guide Note:: When vector table console code is not used, the platform HAL must map the HAL_DIAG_INIT, HAL_DIAG_WRITE_CHAR and HAL_DIAG_READ_CHAR macros directly to the low-level IO functions, hardwired to use a compile-time configured channel. Note:: On old ports the hardwired HAL_DIAG_INIT, HAL_DIAG_WRITE_CHAR and HAL_DIAG_READ_CHAR implementations will also contain code to O-packetize the output for GDB.
PAGE 324

Chapter 11. Porting Guide Assertions The code should contain assertions to validate argument values, state information and any assumptions the code may be making. Assertions are not enabled in production builds, so liberally sprinkling assertions throughout the code is good. Testing The ability to test your code is very important. In general, do not add new code to the eCos runtime unless you also add a new test to exercise that code. The test also serves as an example of how to use the new code.
PAGE 325

Chapter 11. Porting Guide (set-variable ’add-log-full-name "Your Name") (set-variable ’add-log-mailing-address "Your email address")) (setq auto-mode-alist (append ’(("/local/ecc/.*\\.C$" . ecos-c-mode) ("/local/ecc/.*\\.cc$" . ecos-c-mode) ("/local/ecc/.*\\.cpp$" . ecos-c-mode) ("/local/ecc/.*\\.inl$" . ecos-c-mode) ("/local/ecc/.*\\.c$" . ecos-c-mode) ("/local/ecc/.*\\.h$" . ecos-c-mode) ("/local/ecc/.*\\.S$" . ecos-asm-mode) ("/local/ecc/.*\\.inc$" . ecos-asm-mode) ("/local/ecc/.*\\.cdl$" .
PAGE 326

Chapter 11. Porting Guide Platform HAL Porting This is the type of port that takes the least effort. It basically consists of describing the platform (board) for the HAL: memory layout, early platform initialization, interrupt controllers, and a simple serial device driver. Doing a platform port requires a preexisting architecture and possibly a variant HAL port.
PAGE 327

Chapter 11. Porting Guide substantially different. Please try to adhere to the following as much is possible without causing yourself too much grief integrating with a HAL which does not follow this layout. Minimal requirements These are the changes you must make before you attempt to build RedBoot. You are advised to read all the sources though. 1. Copy an existing platform HAL from the same or another architecture.
PAGE 328

Chapter 11. Porting Guide % ecosconfig import $(ECOS_REPOSITORY)/hal////misc/redboot_R % ecosconfig tree % make You may have to make further changes than suggested above to get the make command to succeed. But when it does, you should find a RedBoot image in install/bin. To program this image into flash or EPROM, you may need to convert to some other file type, and possibly adjust the start address.
PAGE 329

Chapter 11. Porting Guide 3. Real-time clock interrupts drive the eCos scheduler clock. Many embedded CPUs have an on-core timer (e.g. SH) or decrementer (e.g. MIPS, PPC) that can be used, and in this case it will already be supported by the architecture/variant HAL. You only have to calculate and enter the proper CYGNUM_HAL_RTC_CONSTANTS definitions in the platform CDL file. On some targets it may be necessary to use a platform-specific timer source for driving the real-time clock.
PAGE 330

Chapter 11. Porting Guide Being able to display memory content, CPU registers, interrupt controller details at the time of an interrupt can save a lot of time. • Using assertions is a good idea. They can sometimes reveal subtle bugs or missing features long before you would otherwise have found them, let alone notice them. The default eCos configuration does not use assertions, so you have to enable them by switching on the option CYGPKG_INFRA_DEBUG in the infra package.
PAGE 331

Chapter 11. Porting Guide This contains the title and description presented in the Configuration Tool when the package is selected. It also specifies where in the tree the package files can be found (directory) and the name of the CDL file which contains the package details (script). To be able to build and test a configuration for the new target, there also needs to be a target entry in the ecos.db file.
PAGE 332

Chapter 11. Porting Guide ... } This specifies that the platform package should be parented under the MIPS packages, requires the TX39 variant HAL and all configuration settings should be saved in cyg/hal/hal_mips_tx39_jmt3904.h. The compile line specifies which files should be built when this package is enabled, and the define_proc defines some macros that are used to access the variant or architecture (the _TARGET_ name is a bit of a misnomer) and platform configuration options.
PAGE 333

Chapter 11. Porting Guide cdl_option CYGBLD_GLOBAL_COMMAND_PREFIX { display "Global command prefix" flavor data no_define default_value { "mips-tx39-elf" } description " This option specifies the command prefix used when invoking the build tools.
PAGE 334

Chapter 11. Porting Guide define -file system.h CYGHWR_MEMORY_LAYOUT_H calculated { CYG_HAL_STARTUP == "RAM" ? "" : \ "" } } } Common Target Options All platforms also specify real-time clock details: # Real-time clock/counter specifics cdl_component CYGNUM_HAL_RTC_CONSTANTS { display "Real-time clock constants.
PAGE 335

Chapter 11. Porting Guide legal_values 0 to CYGNUM_HAL_VIRTUAL_VECTOR_COMM_CHANNELS-1 default_value 0 description " The EDK/7708 board has only one serial port. This option chooses which port will be used to connect to a host running GDB." } cdl_option CYGNUM_HAL_VIRTUAL_VECTOR_CONSOLE_CHANNEL { display "Diagnostic serial port" flavor data legal_values 0 to CYGNUM_HAL_VIRTUAL_VECTOR_COMM_CHANNELS-1 default_value 0 description " The EDK/7708 board has only one serial port.
PAGE 336

Chapter 11. Porting Guide interrupt stack when exceptions are generated.
PAGE 337

Chapter 11. Porting Guide $(OBJCOPY) -O srec $< $(@:.bin=.srec) $(OBJCOPY) -O binary $< $@ } } } The important part here is the make command in the CYGBLD_BUILD_REDBOOT_BIN option which emits makefile commands to translate the .elf file generated by the link phase into both a binary file and an S-Record file. If a different format is required by a PROM programmer or ROM monitor, then different output formats would need to be generated here.
PAGE 338

Chapter 11. Porting Guide Platform Serial Device Support The first step is to set up the CDL definitions. The configuration options that need to be set are the following: CYGNUM_HAL_VIRTUAL_VECTOR_COMM_CHANNELS The number of channels, usually 0, 1 or 2. CYGNUM_HAL_VIRTUAL_VECTOR_DEBUG_CHANNEL The channel to use for GDB. CYGNUM_HAL_VIRTUAL_VECTOR_DEBUG_CHANNEL_BAUD Initial baud rate for debug channel. CYGNUM_HAL_VIRTUAL_VECTOR_CONSOLE_CHANNEL The channel to use for the console.
PAGE 339

Chapter 11. Porting Guide bool cyg_hal_plf_serial_getc_nonblock(void* __ch_data, cyg_uint8* ch) This function tests the device and if a character is available, places it in *ch and returns TRUE. If no character is available, then the function returns FALSE immediately. int cyg_hal_plf_serial_control(void *__ch_data, __comm_control_cmd_t __func, ...) This is an IOCTL-like function for controlling various aspects of the serial device.
PAGE 340

Chapter 11. Porting Guide Note: Some CPU variants may require specific compiler support. That support must be in place before you can undertake the eCos variant port. HAL Variant CDL The CDL in a variant HAL tends to depend on the exact functionality supported by the variant. If it implements some of the devices described in the platform HAL, then the CDL for those will be here rather than there (for example the real-time clock).
PAGE 341

Chapter 11. Porting Guide cdl_option CYGHWR_HAL_MIPS_FPU { display "Variant FPU support" calculated 1 } cdl_option CYGHWR_HAL_MIPS_FPU_64BIT { display "Variant 64 bit FPU support" calculated 1 } These tell the architecture that this is a 64 bit MIPS architecture, that it has a floating point unit, and that we are going to use it in 64 bit mode rather than 32 bit mode. The CDL file finishes off with some build options. define_proc { puts $::cdl_header "#include " } compile var_misc.
PAGE 342

Chapter 11. Porting Guide In architectures such as the MIPS and PowerPC where cache instructions are part of the ISA, most of the actual cache operations are implemented in the architecture HAL. In this case the variant HAL only needs to define the cache dimensions. The following are the cache dimensions defined in the MIPS VR4300 variant var_cache.h.
PAGE 343

Chapter 11. Porting Guide 1. Make a new directory for the new architecture under the hal directory in the source repository. Make an arch directory under this and populate this with the standard set of package directories. 2. Copy the CDL file from an example HAL changing its name to match the new HAL. Edit the file, changing option names as appropriate. Delete any options that are specific to the original HAL, and and any new options that are necessary for the new architecture.
PAGE 344

Chapter 11. Porting Guide address bits. • Define global pointer save/restore macros. These really only need defining if the calling conventions of the architecture require a global pointer (as does the MIPS architecture), they may be empty otherwise. If it is necessary to define these, then take a look at the MIPS implementation for an example. 4. Copy hal_intr.h from an example HAL. Within this file you should change or define the following: • Define the exception vectors.
PAGE 345

Chapter 11. Porting Guide • hal_cache.h. This file contains cache access macros. If the architecture defines cache instructions, or control registers, then the access macros should be defined here. Otherwise they must be defined in the variant or platform HAL. Usually the cache dimensions (total size, line size, ways etc.) are defined in the variant HAL. and .inc. These files are assembler headers used by vectors.S and context.S. .
PAGE 346

Chapter 11. Porting Guide • Write hal_interrupt_stack_call_pending_dsrs(). If this function is defined in hal_arch.h then it should appear here. The purpose of this function is to call DSRs on the interrupt stack rather than the current thread’s stack. This is not an essential feature, and may be left until later. However it interacts with the stack switching that goes on in the interrupt VSR, so it may make sense to write these pieces of code at the same time to ensure consistency.
PAGE 347

Chapter 11. Porting Guide function pointers between labels __CTOR_LIST__ and __CTOR_END__ which must called in order from the top down. Generally, this function can be copied directly from an existing architecture HAL. • Bit indexing functions. If the macros HAL_LSBIT_INDEX() and HAL_MSBIT_INDEX() are defined as function calls, then the functions should appear here.
PAGE 348

Chapter 11. Porting Guide CDL Requirements The CDL needed for any particular architecture HAL depends to a large extent on the needs of that architecture. This includes issues such as support for different variants, use of FPUs, MMUs and caches. The exact split between the architecture, variant and platform HALs for various features is also somewhat fluid. To give a rough idea about how the CDL for an architecture is structured, we will take as an example the I386 CDL.
PAGE 349

Chapter 11. Porting Guide The i386 is currently the only architecture that supports SMP. The following CDL simply enabled the HAL SMP support if required. Generally this will get enabled as a result of a requires statement in the kernel. The requires statement here turns off lazy FPU switching in the FPU support code, since it is inconsistent with SMP operation.
PAGE 350

Chapter 11. Porting Guide display "Enable Pentium class CPU features" default_value 0 description "This component enables support for various features of Pentium class CPUs." cdl_option CYGHWR_HAL_I386_PENTIUM_SSE { display "Save/Restore SSE registers on context switch" flavor bool default_value 0 description " This option enables SSE state switching. The default behaviour for eCos is to ignore the SSE registers. Enabling this option adds SSE state information to every thread context.
PAGE 351

Chapter 12. Future developments The HAL is not complete, and will evolve and increase over time. Among the intended developments are: • Common macros for interpreting the contents of a saved machine context. These would allow portable code, such as debug stubs, to extract such values as the program counter and stack pointer from a state without having to interpret a HAL_SavedRegisters structure directly. • Debugging support. Macros to set and clear hardware and software breakpoints.
PAGE 352

Chapter 12.
PAGE 353

IV.
PAGE 354
PAGE 355

Chapter 13. C and math library overview eCos provides compatibility with the ISO 9899:1990 specification for the standard C library, which is essentially the same as the better-known ANSI C3.159-1989 specification (C-89). There are three aspects of this compatibility supplied by eCos. First there is a C library which implements the functions defined by the ISO standard, except for the mathematical functions. This is provided by the eCos C library packages.
PAGE 356

Chapter 13. C and math library overview CYG_LIBC_TIME_DSTON on void cyg_libc_time_setzoneoffsets( time_t stdoffset, time_t dstoffset ); This function sets the offsets from UTC used when Daylight Savings Time is enabled or disabled. The offsets are in time_t’s, which are seconds in the current inplementation.
PAGE 357

Chapter 13.
PAGE 358

Chapter 13. C and math library overview Type Behavior DOMAIN 0.0 returned, errno=EDOM, and a message printed on stderr SING HUGE of appropriate sign is returned, errno=EDOM, and a message is printed on stderr OVERFLOW HUGE of appropriate sign is returned, and errno=ERANGE UNDERFLOW 0.0 is returned and errno=ERANGE TLOSS 0.
PAGE 359

Chapter 13. C and math library overview • For faster execution speed you should avoid this option and let the compiler use its built-ins. This can be turned off by invoking GCC with the -fno-builtin option. • memcpy() and memset() are located in the infrastructure package, not in the C library package. This is because the compiler calls these functions, and the kernel needs to resolve them even if the C library is not configured.
PAGE 360

Chapter 13. C and math library overview environ = (char **)&env; str = getenv("PATH"); if (str==NULL) { printf("The current PATH is unset\n"); } else { printf("The current PATH is \"%s\"\n", str); } return 0; } Thread safety The ISO C library has configuration options that control thread safety, i.e. working behavior if multiple threads call the same function at the same time.
PAGE 361

Chapter 13. C and math library overview This function is used to start an environment in which an ISO C style program can run in the most compatible way. What this function does is to create a thread which will invoke main() — normally considered a program’s entry point.
PAGE 362

Chapter 13.
PAGE 363

V.
PAGE 364
PAGE 365

Chapter 14. Introduction The I/O package is designed as a general purpose framework for supporting device drivers. This includes all classes of drivers from simple serial to networking stacks and beyond. Components of the I/O package, such as device drivers, are configured into the system just like all other components. Additionally, end users may add their own drivers to this set.
PAGE 366

Chapter 14.
PAGE 367

Chapter 15. User API All functions, except cyg_io_lookup() require an I/O “handle”. All functions return a value of the type Cyg_ErrNo. If an error condition is detected, this value will be negative and the absolute value indicates the actual error, as specified in cyg/error/codes.h. The only other legal return value will be ENOERR. All other function arguments are pointers (references). This allows the drivers to pass information efficiently, both into and out of the driver.
PAGE 368

Chapter 15. User API data retrieved is placed in *len. The appropriate key values differ for each driver and are all listed in the file . // Change the configuration of a device Cyg_ErrNo cyg_io_set_config( cyg_io_handle_t handle, cyg_uint32 key, const void *buf, cyg_uint32 *len ) This function is used to manipulate or change the run-time configuration of a device. The type of information is specified by the key. The data will be obtained from the given buffer.
PAGE 369

Chapter 16. Serial driver details Two different classes of serial drivers are provided as a standard part of the eCos system. These are described as “raw serial” (serial) and “tty-like” (tty). Raw Serial Driver Use the include file for this driver. The raw serial driver is capable of sending and receiving blocks of raw data to a serial device. Controls are provided to configure the actual hardware, but there is no manipulation of the data by this driver.
PAGE 370

Chapter 16. Serial driver details CYGNUM_SERIAL_BAUD_1200 CYGNUM_SERIAL_BAUD_1800 CYGNUM_SERIAL_BAUD_2400 CYGNUM_SERIAL_BAUD_3600 CYGNUM_SERIAL_BAUD_4800 CYGNUM_SERIAL_BAUD_7200 CYGNUM_SERIAL_BAUD_9600 CYGNUM_SERIAL_BAUD_14400 CYGNUM_SERIAL_BAUD_19200 CYGNUM_SERIAL_BAUD_38400 CYGNUM_SERIAL_BAUD_57600 CYGNUM_SERIAL_BAUD_115200 CYGNUM_SERIAL_BAUD_234000 The field stop contains the number of stop bits.
PAGE 371

Chapter 16. Serial driver details The field tx_bufsize contains the total size of the transmit data buffer. This is set to zero on devices that do not support buffering (i.e. polled devices). The field tx_count contains the number of bytes currently occupied in the transmit data buffer. This is set to zero on devices that do not support buffering (i.e. polled devices). API Details cyg_io_write cyg_io_write(handle, buf, len) Send the data from buf to the device.
PAGE 372

Chapter 16. Serial driver details cyg_io_get_config cyg_io_get_config(handle, key, buf, len) This function returns current [runtime] information about the device and/or driver. CYG_IO_GET_CONFIG_SERIAL_INFO Buf type: cyg_serial_info_t Function: This function retrieves the current state of the driver and hardware. This information contains fields for hardware baud rate, number of stop bits, and parity mode. It also includes a set of flags that control the port, such as hardware flow control.
PAGE 373

Chapter 16. Serial driver details CYG_IO_GET_CONFIG_SERIAL_OUTPUT_FLUSH Buf type: void * Function: This function discards any buffered output for the device. CYG_IO_GET_CONFIG_SERIAL_INPUT_DRAIN Buf type: void * Function: This function discards any buffered input for the device. CYG_IO_GET_CONFIG_SERIAL_ABORT Buf type: void* Function: This function will cause any pending read or write calls on this device to return with -EABORT.
PAGE 374

Chapter 16. Serial driver details CYG_IO_GET_CONFIG_SERIAL_WRITE_BLOCKING Buf type: cyg_uint32 (values 0 or 1) Function: This function will read back the blocking-mode setting for write calls on this device. This call is only available if the configuration option CYGOPT_IO_SERIAL_SUPPORT_NONBLOCKING is enabled. cyg_io_set_config cyg_io_set_config(handle, key, buf,len) This function is used to update or change runtime configuration of a port.
PAGE 375

Chapter 16. Serial driver details CYG_IO_SET_CONFIG_SERIAL_WRITE_BLOCKING Buf type: cyg_uint32 (values 0 or 1) Function: This function will set the blocking-mode for write calls on this device. This call is only available if the configuration option CYGOPT_IO_SERIAL_SUPPORT_NONBLOCKING is enabled. TTY driver Use the include file for this driver. This driver is built on top of the simple serial driver and is typically used for a device that interfaces with humans such as a terminal.
PAGE 376

Chapter 16. Serial driver details If this bit is set in tty_in_flags, the character sequence "\n\r" (often sent by DOS/Windows based terminals) will be mapped to "\n". #define CYG_TTY_IN_FLAGS_BINARY 0x0004 // No input processing If this bit is set in tty_in_flags, the input will not be manipulated in any way before being placed in the user’s buffer.
PAGE 377

Chapter 16. Serial driver details This function is used to modify the channel’s configuration at runtime. CYG_IO_SET_CONFIG_TTY_INFO Buf type: cyg_tty_info_t Function: This function changes the current state of the driver. Serial driver keys (see above) may also be specified in which case the call is passed directly to the serial driver.
PAGE 378

Chapter 16.
PAGE 379

Chapter 17. How to Write a Driver A device driver is nothing more than a named entity that supports the basic I/O functions - read, write, get config, and set config. Typically a device driver also uses and manages interrupts from the device. While the interface is generic and device driver independent, the actual driver implementation is completely up to the device driver designer.
PAGE 380

Chapter 17. How to Write a Driver lookup A function called when cyg_io_lookup() is called for this device. priv A placeholder for any device specific data required by the driver. The interface to the driver is through the handlers field. This is a pointer to a set of functions which implement the various cyg_io_XXX() routines. This table is defined by the macro: DEVIO_TABLE(l, write, read, get_config, set_config) Arguments l The "C" label for this table of handlers.
PAGE 381

Chapter 17. How to Write a Driver Note: In the sections below we use the notation <> to mean a module specific value, referred to as “xx” below. DevTab Entry The interface module contains the devtab entry (or entries if a single module supports more than one interface).
PAGE 382

Chapter 17. How to Write a Driver Arguments l The "C" label for this structure. funs The set of interface functions (see below). dev_priv A placeholder for any device specific data for this channel. baud The initial baud rate value (cyg_serial_baud_t). stop The initial stop bits value (cyg_serial_stop_bits_t). parity The initial parity mode value (cyg_serial_parity_t). word_length The initial word length value (cyg_serial_word_length_t). flags The initial driver flags value.
PAGE 383

Chapter 17. How to Write a Driver Serial Functions Structure SERIAL_FUNS(l, putc, getc, set_config, start_xmit, stop_xmit) Arguments l The "C" label for this structure. putc bool (*putc)(serial_channel *priv, unsigned char c) This function sends one character to the interface. It should return true if the character is actually consumed. It should return false if there is no space in the interface getc unsigned char (*getc)(serial_channel *priv) This function fetches one character from the interface.
PAGE 384

Chapter 17. How to Write a Driver Callbacks The device interface module can execute functions in the hardware independent driver via chan->callbacks. These functions are available: void (*serial_init)( serial_channel *chan ) This function is used to initialize the serial channel. It is only required if the channel is being used in interrupt mode.
PAGE 385

Chapter 17. How to Write a Driver Serial testing with ser_filter Rationale Since some targets only have one serial connection, a serial testing harness needs to be able to share the connection with GDB (however, the test and GDB can also run on separate lines). The serial filter (ser_filter) sits between the serial port and GDB and monitors the exchange of data between GDB and the target. Normally, no changes are made to the data.
PAGE 386

Chapter 17. How to Write a Driver DUPLEX_ECHO (serial driver duplex receive and send test) Smaller packets of data are sent back and forth in a pattern that ensures that the serial driver will be both sending and receiving at the same time. Again, checksums are computed and verified resulting in PASS/FAIL. TEXT This is a test of the text translations in the TTY layer. Requests a transfer of text data from the target to the filter and possibly back again.
PAGE 387

Chapter 17. How to Write a Driver -c: Output data on console instead of via GDB. -n: No GDB. The normal way to use it with GDB is to start the filter: $ ser_filter -t 9000 com1 38400 In this case, the filter will be listening on port 9000 and connect to the target via the serial port COM1 at 38400 baud. On a UNIX host, replace "COM1" with a device such as "/dev/ttyS0". The -t option enables tracing which will cause the filter to describe its actions on the console.
PAGE 388

Chapter 17. How to Write a Driver [400 [400 [400 [400 [400 [400 11:35:16] 11:35:16] 11:35:16] 11:35:16] 11:35:16] 11:35:16] Binary data (Size:16, Flags:1). Sending CRC: ’170231!’, len: 7. Reading 16 bytes from target. Done. in_crc 170231, out_crc 170231. Responding with status OK Received DONE from target. This tracing output is normally sent as O-packets to GDB which will display the tracing text.
PAGE 389

Chapter 18. Device Driver Interface to the Kernel This chapter describes the API that device drivers may use to interact with the kernel and HAL. It is primarily concerned with the control and management of interrupts and the synchronization of ISRs, DSRs and threads. The same API will be present in configurations where the kernel is not present. In this case the functions will be supplied by code acting directly on the HAL. Interrupt Model eCos presents a three level interrupt model to device drivers.
PAGE 390

Chapter 18. Device Driver Interface to the Kernel chronization, this mechanism should be used sparingly. Only DSRs and threads may use this synchronization mechanism, ISRs are not allowed to do this. 3. Synchronization with threads. This is implemented with mutexes and condition variables. Only threads may lock the mutexes and wait on the condition variables, although DSRs may signal condition variables. Any data that is accessed from more than one level must be protected against concurrent access.
PAGE 391

Chapter 18. Device Driver Interface to the Kernel The second model is to defer device processing to the DSR. The ISR simply prevents further delivery of interrupts by either programming the device, or by calling cyg_drv_interrupt_mask(). It must then call cyg_drv_interrupt_acknowledge() to allow other interrupts to be delivered and then request that its DSR be called.
PAGE 392

Chapter 18.
PAGE 393

Chapter 18. Device Driver Interface to the Kernel Description: Disables delivery of interrupts, preventing all ISRs running. This function maintains a counter of the number of times it is called. cyg_drv_isr_unlock Function: void cyg_drv_isr_unlock() Arguments: None Result: None Level: ISR Description: Re-enables delivery of interrupts, allowing ISRs to run. This function decrements the counter maintained by cyg_drv_isr_lock(), and only re-allows interrupts when it goes to zero.
PAGE 394

Chapter 18. Device Driver Interface to the Kernel cyg_drv_spinlock_destroy Function: void cyg_drv_spinlock_destroy(cyg_spinlock_t *lock ) Arguments: lock - pointer to spinlock destroy Result: None Level: Thread Description: Destroy a spinlock that is no longer of use. There should be no CPUs attempting to claim the lock at the time this function is called, otherwise the behavior is undefined.
PAGE 395

Chapter 18. Device Driver Interface to the Kernel Arguments: lock - pointer to spinlock to clear Result: None Level: ISR Description: Clear a spinlock. This clears the spinlock and allows another CPU to claim it. If there is more than one CPU waiting in cyg_drv_spinlock_spin() then just one of them will be allowed to proceed.
PAGE 396

Chapter 18. Device Driver Interface to the Kernel Level: ISR Description: Inspect the state of the spinlock. If the spinlock is not locked then the result is TRUE. If it is locked then the result will be FALSE.
PAGE 397

Chapter 18. Device Driver Interface to the Kernel Arguments: lock - pointer to spinlock to clear istate - interrupt state to restore Result: None Level: ISR Description: This function behaves exactly like cyg_drv_spinlock_clear() except that it also restores an interrupt state saved by cyg_drv_spinlock_spin_intsave(). The istate argument must have been initialized by a previous call to cyg_drv_spinlock_spin_intsave().
PAGE 398

Chapter 18. Device Driver Interface to the Kernel Result: None Level: DSR Description: Re-enables scheduling of DSRs. This function decrements the counter incremented cyg_drv_dsr_lock(). DSRs are only allowed to be delivered when the counter goes to zero. cyg_drv_mutex_init Function: void cyg_drv_mutex_init(cyg_drv_mutex *mutex) Arguments: mutex - pointer to mutex to initialize Result: None Level: Thread Description: Initialize the mutex pointed to by the mutex argument.
PAGE 399

Chapter 18. Device Driver Interface to the Kernel Level: Thread Description: Destroy the mutex pointed to by the mutex argument. The mutex should be unlocked and there should be no threads waiting to lock it when this call in made. cyg_drv_mutex_lock Function: cyg_bool cyg_drv_mutex_lock( cyg_drv_mutex *mutex ) Arguments: mutex - pointer to mutex to lock Result: TRUE it the thread has claimed the lock, FALSE otherwise. Level: Thread Description: Attempt to lock the mutex pointed to by the mutex argument.
PAGE 400

Chapter 18. Device Driver Interface to the Kernel Description: Attempt to lock the mutex pointed to by the mutex argument without waiting. If the mutex is already locked by some other thread then this function returns FALSE. If the function can lock the mutex without waiting, then TRUE is returned.
PAGE 401

Chapter 18. Device Driver Interface to the Kernel cyg_drv_cond_init Function: void cyg_drv_cond_init( cyg_drv_cond *cond, cyg_drv_mutex *mutex ) Arguments: cond - condition variable to initialize mutex - mutex to associate with this condition variable Result: None Level: Thread Description: Initialize the condition variable pointed to by the cond argument. The mutex argument must point to a mutex with which this condition variable is associated.
PAGE 402

Chapter 18. Device Driver Interface to the Kernel cyg_drv_cond_wait Function: void cyg_drv_cond_wait( cyg_drv_cond *cond ) Arguments: cond - condition variable to wait on Result: None Level: Thread Description: Wait for a signal on the condition variable pointed to by the cond argument. The thread must have locked the associated mutex, supplied in cyg_drv_cond_init(), before waiting on this condition variable.
PAGE 403

Chapter 18. Device Driver Interface to the Kernel cyg_drv_cond_broadcast Function: void cyg_drv_cond_broadcast( cyg_drv_cond *cond ) Arguments: cond - condition variable to broadcast to Result: None Level: DSR Description: Signal the condition variable pointed to by the cond argument. If there are any threads waiting on this variable they will all be awakened.
PAGE 404

Chapter 18. Device Driver Interface to the Kernel Level: Thread Description: Create an interrupt object and returns a handle to it. The object contains information about which interrupt vector to use and the ISR and DSR that will be called after the interrupt object is attached to the vector. The interrupt object will be allocated in the memory passed in the intr parameter. The interrupt object is not immediately attached; it must be attached with the cyg_interrupt_attach() call.
PAGE 405

Chapter 18. Device Driver Interface to the Kernel Description: Attach the interrupt to the vector so that interrupts will be delivered to the ISR when the interrupt occurs. cyg_drv_interrupt_detach Function: void cyg_drv_interrupt_detach( cyg_handle_t interrupt ) Arguments: interrupt - interrupt to detach Result: None Level: ISR Description: Detach the interrupt from the vector so that interrupts will no longer be delivered to the ISR.
PAGE 406

Chapter 18. Device Driver Interface to the Kernel cyg_drv_interrupt_mask_intunsafe Function: void cyg_drv_interrupt_mask_intunsafe(cyg_vector_t vector ) Arguments: vector - vector to mask Result: None Level: ISR Description: Program the interrupt controller to stop delivery of interrupts on the given vector. On architectures which implement interrupt priority levels this may also disable all lower priority interrupts. This version differs from cyg_drv_interrupt_mask() in not being interrupt safe.
PAGE 407

Chapter 18. Device Driver Interface to the Kernel Arguments: vector - vector to unmask Result: None Level: ISR Description: Program the interrupt controller to re-allow delivery of interrupts on the given vector. This version differs from cyg_drv_interrupt_unmask() in not being interrupt safe.
PAGE 408

Chapter 18. Device Driver Interface to the Kernel level - level or edge triggered up - rising/falling edge, high/low level Result: None Level: ISR Description: Program the interrupt controller with the characteristics of the interrupt source. The level argument chooses between level- or edge-triggered interrupts. The up argument chooses between high and low level for level triggered interrupts or rising and falling edges for edge triggered interrupts.
PAGE 409

Chapter 18. Device Driver Interface to the Kernel cyg_drv_interrupt_set_cpu Function: void cyg_drv_interrupt_set_cpu( cyg_vector_t vector, cyg_cpu_t cpu ) Arguments: vector - interrupt vector to route cpu - destination CPU Result: None Level: ISR Description: This function causes all interrupts on the given vector to be routed to the specified CPU. Subsequently, all such interrupts will be handled by that CPU. This only works if the underlying hardware is capable of performing this kind of routing.
PAGE 410

Chapter 18. Device Driver Interface to the Kernel cyg_ISR_t Type: typedef cyg_uint32 cyg_ISR_t( cyg_vector_t vector, cyg_addrword_t data ) Fields: vector - vector being delivered data - data value supplied by client Result: Bit mask indicating whether interrupt was handled and whether the DSR should be called. Description: Interrupt Service Routine definition. A pointer to a function with this prototype is passed to cyg_interrupt_create() when an interrupt object is created.
PAGE 411

Chapter 18. Device Driver Interface to the Kernel Result: None Description: Deferred Service Routine prototype. A pointer to a function with this prototype is passed to cyg_interrupt_create() when an interrupt object is created. When the ISR requests the scheduling of its DSR, this function will be called at some later point.
PAGE 412

Chapter 18.
PAGE 413

VI.
PAGE 414
PAGE 415

Chapter 19. Introduction This document describes the filesystem infrastructure provided in eCos. This is implemented by the FILEIO package and provides POSIX compliant file and IO operations together with the BSD socket API. These APIs are described in the relevant standards and original documentation and will not be described here. See Chapter 31 for details of which parts of the POSIX standard are supported.
PAGE 416

Chapter 19.
PAGE 417

Chapter 20. File System Table The filesystem table is an array of entries that describe each filesystem implementation that is part of the system image. Each resident filesystem should export an entry to this table using the FSTAB_ENTRY() macro. Note: At present we do not support dynamic addition or removal of table entries. However, an API similar to mount() would allow new entries to be added to the table.
PAGE 418

Chapter 20. File System Table The remaining fields are pointers to functions that implement filesystem operations that apply to files and directories as whole objects. The operation implemented by each function should be obvious from the names, with a few exceptions: The opendir() function pointer opens a directory for reading. See Chapter 23 for details. The getinfo() and setinfo() function pointers provide support for various minor control and information functions such as pathconf() and access().
PAGE 419

Chapter 21. Mount Table The mount table records the filesystems that are actually active. These can be seen as being analogous to mount points in Unix systems. There are two sources of mount table entries. Filesystems (or other components) may export static entries to the table using the MTAB_ENTRY() macro. Alternatively, new entries may be installed at run time using the mount() function. Both types of entry may be unmounted with the umount() function.
PAGE 420

Chapter 21. Mount Table The data field is a private data value. This may be installed either statically when the table entry is defined, or may be installed during the mount() operation. The valid field indicates whether this mount point has actually been mounted successfully. Entries with a false valid field are ignored when searching for a name match. The fs field is installed after a successful mount() operation to point to the implementing filesystem.
PAGE 421

Chapter 22. File Table Once a file has been opened it is represented by an open file object. These are allocated from an array of available file objects. User code accesses these open file objects via a second array of pointers which is indexed by small integer offsets. This gives the usual Unix file descriptor functionality, complete with the various duplication mechanisms.
PAGE 422

Chapter 22.
PAGE 423

Chapter 23. Directories Filesystem operations all take a directory pointer as one of their arguments. A directory pointer is an opaque handle managed by the filesystem. It should encapsulate a reference to a specific directory within the filesystem. For example, it may be a pointer to the data structure that represents that directory (such as an inode), or a pointer to a pathname for the directory. The chdir() filesystem function pointer has two modes of use.
PAGE 424

Chapter 23.
PAGE 425

Chapter 24. Synchronization The FILEIO infrastructure provides a synchronization mechanism for controlling concurrent access to filesystems. This allows existing filesystems to be ported to eCos, even if they do not have their own synchronization mechanisms. It also allows new filesystems to be implemented easily without having to consider the synchronization issues. The infrastructure maintains a mutex for each entry in each of the main tables: filesystem table, mount table and file table.
PAGE 426

Chapter 24.
PAGE 427

Chapter 25. Initialization and Mounting As mentioned previously, mount table entries can be sourced from two places. Static entries may be defined by using the MTAB_ENTRY() macro. Such entries will be automatically mounted on system startup. For each entry in the mount table that has a non-null name field the filesystem table is searched for a match with the fsname field.
PAGE 428

Chapter 25.
PAGE 429

Chapter 26. Sockets If a network stack is present, then the FILEIO infrastructure also provides access to the standard BSD socket calls. The netstack table contains entries which describe the network protocol stacks that are in the system image. Each resident stack should export an entry to this table using the NSTAB_ENTRY() macro.
PAGE 430

Chapter 26. Sockets void *optval, socklen_t *optlen); int (*setsockopt)( cyg_file *fp, int level, int optname, const void *optval, socklen_t optlen); int (*sendmsg) ( cyg_file *fp, const struct msghdr *m, int flags, ssize_t *retsize ); int (*recvmsg) ( cyg_file *fp, struct msghdr *m, socklen_t *namelen, ssize_t *retsize ); }; It should be obvious from the names of these functions which API calls they provide support for.
PAGE 431

Chapter 27. Select The infrastructure provides support for implementing a select mechanism. This is modeled on the mechanism in the BSD kernel, but has been modified to make it implementation independent. The main part of the mechanism is the select() API call. This processes its arguments and calls the fo_select() function pointer on all file objects referenced by the file descriptor sets passed to it.
PAGE 432

Chapter 27.
PAGE 433

Chapter 28. Devices Devices are accessed by means of a pseudo-filesystem, "devfs", that is mounted on "/dev". Open operations are translated into calls to cyg_io_lookup() and if successful result in a file object whose f_ops functions translate filesystem API functions into calls into the device API.
PAGE 434

Chapter 28.
PAGE 435

Chapter 29. Writing a New Filesystem To create a new filesystem it is necessary to define the fstab entry and the file IO operations. The easiest way to do this is to copy an existing filesystem: either the test filesystem in the FILEIO package, or the RAM or ROM filesystem packages. To make this clearer, the following is a brief tour of the FILEIO relevant parts of the RAM filesystem.
PAGE 436

Chapter 29. Writing a New Filesystem static int ramfs_fo_dirread static int ramfs_fo_dirlseek (struct CYG_FILE_TAG *fp, struct CYG_UIO_TAG *uio); (struct CYG_FILE_TAG *fp, off_t *pos, int whence ); We define all of the fstab entries and all of the file IO operations. We also define alternatives for the fo_read and fo_lseek file IO operations. We can now define the filesystem table entry.
PAGE 437

Chapter 29. Writing a New Filesystem }; These all point to functions supplied by the filesystem except the fo_select field which is filled with a pointer to cyg_fileio_seltrue(). This is provided by the FILEIO package and is a select function that always returns true to all operations. Finally, we need to define a set of file operations for use when reading directories. This table only defines the fo_read and fo_lseek operations.
PAGE 438

Chapter 29.
PAGE 439

VII.
PAGE 440
PAGE 441

Chapter 30. The eCos PCI Library The PCI library is an optional part of eCos, and is only applicable to some platforms. PCI Library The eCos PCI library provides the following functionality: 1. Scan the PCI bus for specific devices or devices of a certain class. 2. Read and change generic PCI information. 3. Read and change device-specific PCI information. 4. Allocate PCI memory and IO space to devices. 5. Translate a device’s PCI interrupts to equivalent HAL vectors.
PAGE 442

Chapter 30. The eCos PCI Library Scanning for devices After the bus has been initialized, it is possible to scan it for devices. This is done using the function: cyg_bool cyg_pci_find_next( cyg_pci_device_id cur_devid, cyg_pci_device_id *next_devid ); It will scan the bus for devices starting at cur_devid. If a device is found, its devid is stored in next_devid and the function returns true.
PAGE 443

Chapter 30. The eCos PCI Library The cyg_pci_device structure (defined in pci.h) primarily holds information as described by the PCI specification [1]. The pci1 test prints out some of this information: // Get device info cyg_pci_get_device_info(devid, &dev_info); diag_printf("\n Command 0x%04x, Status 0x%04x\n", dev_info.command, dev_info.status); The command register can also be written to, controlling (among other things) whether the device responds to IO and memory access from the bus.
PAGE 444

Chapter 30. The eCos PCI Library cyg_bool cyg_pci_allocate_io( cyg_pci_device *dev_info, cyg_uint32 bar, CYG_PCI_ADDRESS32 *base ); The memory bases (in two distinct address spaces) are increased as memory regions are allocated to devices. Allocation will fail (the function returns false) if the base exceeds the limits of the address space (IO is 1MB, memory is 2^32 or 2^64 bytes). These functions can also be called directly by the application/driver if necessary, but this should not be necessary.
PAGE 445

Chapter 30. The eCos PCI Library Activating the device is done by enabling flags in its command word. As an example, see the pci1 test which can be configured to enable the devices it finds. This allows these to be accessed from GDB (if a breakpoint is set on cyg_test_exit): #ifdef ENABLE_PCI_DEVICES { cyg_uint16 cmd; // Don’t use cyg_pci_set_device_info since it clears // some of the fields we want to print out below. cyg_pci_read_config_uint16(dev_info.
PAGE 446

Chapter 30. The eCos PCI Library PCI Library API The PCI library provides the following routines and types for accessing the PCI configuration space. The API for the PCI library is found in the header file . Definitions The header file contains definitions for the common configuration structure offsets and specimen values for device, vendor and class code.
PAGE 447

Chapter 30. The eCos PCI Library Functions void cyg_pci_init(void); Initialize the PCI library and establish contact with the hardware. This function is idempotent and can be called either by all drivers in the system, or just from an application initialization function. cyg_bool cyg_pci_find_device( cyg_uint16 vendor, cyg_uint16 device, cyg_pci_device_id *devid ); Searches the PCI bus configuration space for a device with the given vendor and device ids.
PAGE 448

Chapter 30. The eCos PCI Library device’s configuration space. If the device has not been enabled, then this function will also fetch the size and type information from the base address registers and place it in the base_size[] array. void cyg_pci_set_device_info ( cyg_pci_device_id devid, cyg_pci_device *dev_info ); This function sets the PCI configuration information for the device indicated in devid. Only the configuration space registers that are writable are actually written.
PAGE 449

Chapter 30. The eCos PCI Library number will be incremented as new busses are discovered. If successful, true is returned. Otherwise, false is returned. cyg_bool cyg_pci_translate_interrupt( cyg_pci_device *dev_info, CYG_ADDRWORD *vec ); Translate the device’s PCI interrupt (INTA#-INTD#) to the associated HAL vector. This may also depend on which slot the device occupies. If the device may generate interrupts, the translated vector number will be stored in vec and the result is true.
PAGE 450

Chapter 30. The eCos PCI Library void cyg_pcihw_write_config_uint16( cyg_uint8 bus, cyg_uint8 devfn, cyg_uint8 offset, cyg_uint16 val); void cyg_pcihw_write_config_uint32( cyg_uint8 bus, cyg_uint8 devfn, cyg_uint8 offset, cyg_uint32 val); These functions write a register of the appropriate size to the PCI configuration space at an address composed from the bus, devfn and offset arguments.
PAGE 451

Chapter 30. The eCos PCI Library Note: The chunk of PCI memory space directly addressable though the window by the CPU may be smaller than the amount of PCI memory actually provided. In that case drivers will have to access PCI memory space in segments. Doing this will be platform specific and is currently beyond the scope of the HAL. HAL_PCI_IGNORE_DEVICE( bus, dev, fn ) This macro, if defined, may be used to limit the devices which are found by the bus scanning functions.
PAGE 452

Chapter 30.
PAGE 453

VIII.
PAGE 454
PAGE 455

Chapter 31. POSIX Standard Support eCos contains support for the POSIX Specification (ISO/IEC 9945-1)[POSIX]. POSIX support is divided between the POSIX and the FILEIO packages. The POSIX package provides support for threads, signals, synchronization, timers and message queues. The FILEIO package provides support for file and device I/O. The two packages may be used together or separately, depending on configuration. This document takes a functional approach to the POSIX library.
PAGE 456

Chapter 31. POSIX Standard Support unsigned int sleep( unsigned int seconds ); Functions Omitted pid_t fork(void); int execl( const char ∗path, const char ∗arg, ... ); int execv( const char ∗path, char ∗const argv[] ); int execle( const char ∗path, const char ∗arg, ... ); int execve( const char ∗path, char ∗const argv[], char ∗const envp[] ); int execlp( const char ∗path, const char ∗arg, ...
PAGE 457

Chapter 31.
PAGE 458

Chapter 31. POSIX Standard Support • All system variables supported by sysconf will yield a value. However, those that are irrelevant to eCos will either return the default minimum defined in , or zero.
PAGE 459

Chapter 31. POSIX Standard Support • The maximum number of open files allowed is supplied by the CYGNUM_FILEIO_NFILE option. The maximum number of file descriptors is supplied by the CYGNUM_FILEIO_NFD option. Input and Output [POSIX Section 6] Functions Implemented int dup( int fd ); int dup2( int fd, int fd2 ); int close(int fd); ssize_t read(int fd, void ∗buf, size_t nbyte); ssize_t write(int fd, const void ∗buf, size_t nbyte); int fcntl( int fd, int cmd, ...
PAGE 460

Chapter 31.
PAGE 461

Chapter 31. POSIX Standard Support int rand_r( unsigned int ∗seed ); Functions Omitted void flockfile( FILE ∗file ); int ftrylockfile( FILE ∗file ); void funlockfile( FILE ∗file ); int sigsetjmp( sigjmp_buf env, int savemask ); // TBA void siglongjmp( sigjmp_buf env, int val ); // TBA void tzset(void); // TBA Notes • setlocale() is implemented in the C library Internationalization package. • Functions fileno() and fdopen() are implemented in the C library STDIO package.
PAGE 462

Chapter 31. POSIX Standard Support Notes • None of the functions in this section are implemented. Data Interchange Format [POSIX Section 10] This section details tar and cpio formats. Neither of these is supported by eCos.
PAGE 463

Chapter 31. POSIX Standard Support int int int pshared ); pthread_condattr_getpshared( const pthread_condattr_t ∗attr, int ∗pshared); pthread_condattr_setpshared( const pthread_condattr_t ∗attr, int pshared); Notes • The presence of semaphores is controlled by the CYGPKG_POSIX_SEMAPHORES option. This in turn causes the _POSIX_SEMAPHORES feature test macro to be defined and the semaphore API to be made available. • The pshared argument to sem_init() is not implemented, its value is ignored.
PAGE 464

Chapter 31. POSIX Standard Support Notes None of these functions are currently provided. Some may be implemented in a restricted form in the future.
PAGE 465

Chapter 31. POSIX Standard Support Notes • The functions sched_setparam(), sched_getparam(), sched_setscheduler() and sched_getscheduler() are present but always return an error. • The scheduler policy SCHED_OTHER is equivalent to SCHED_RR. • Only PTHREAD_SCOPE_SYSTEM is supported as a contentionscope attribute. • The default thread scheduling attributes are: contentionscope inheritsched schedpolicy schedparam.
PAGE 466

Chapter 31. POSIX Standard Support Notes • Currently timer_getoverrun() only reports timer notifications that are delayed in the timer subsystem. If they are delayed in the signal subsystem, due to signal masks for example, this is not counted as an overrun. • The option CYGPKG_POSIX_TIMERS allows the timer support to be enabled or disabled, and causes _POSIX_TIMERS to be defined appropriately. This will cause other parts of the POSIX system to have limited functionality.
PAGE 467

Chapter 31.
PAGE 468

Chapter 31. POSIX Standard Support available, then the thread creator must supply a stack. If only a stack address is supplied then the stack is assumed to be PTHREAD_STACK_MIN bytes long. This size is seldom useful for any but the most trivial of threads. If a different sized stack is used, both the stack address and stack size must be supplied. • The value of PTHREAD_THREADS_MAX is supplied by the CYGNUM_POSIX_PTHREAD_THREADS_MAX option. This defines the maximum number of threads allowed.
PAGE 469

Chapter 31. POSIX Standard Support int pthread_setcanceltype(int type, int ∗oldtype); void pthread_testcancel(void); void pthread_cleanup_push( void (∗routine)(void ∗), void ∗arg); void pthread_cleanup_pop( int execute); Functions Omitted Notes Asynchronous cancellation is only partially implemented. In particular, cancellation may occur in unexpected places in some functions. It is strongly recommended that only synchronous cancellation be used.
PAGE 470

Chapter 31. POSIX Standard Support int shutdown( int s, int how); Notes • 366 The precise behaviour of these functions depends mainly on the functionality of the underlying filesystem or network stack to which they are applied.
PAGE 471

References and Bibliography [Lewine] Donald A. Lweine Posix Programmer’s Guide: Writing Portable Unix Programs With the POSIX.1 Standard O’Reilly & Associates; ISBN: 0937175730. [Lewis1] Bil Lewis Daniel J. Berg Threads Primer: A Guide to Multithreaded Programming Prentice Hall ISBN: 013443698 [Lewis2] Bil Lewis Daniel J.
PAGE 472
PAGE 473

Chapter 32. µITRON API Introduction to µITRON The µITRON specification defines a highly flexible operating system architecture designed specifically for application in embedded systems. The specification addresses features which are common to the majority of processor architectures and deliberately avoids virtualization which would adversely impact real-time performance.
PAGE 474

Chapter 32. µITRON API file pkgconf/uitron.h, and can be set using the configuration tool or editing the .ecc file in your build directory by hand. An important configuration option for the µITRON compatibility layer is “Option: Return Error Codes for Bad Params” ( CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS ), which allows a lot of the error checking code in the µITRON compatibility layer to be removed.
PAGE 475

Chapter 32. µITRON API The following two functions are supported in this release, when enabled with the configuration option CYGPKG_UITRON_TASKS_CREATE_DELETE with some restrictions: ER cre_tsk( ID tskid, T_CTSK *pk_ctsk ) ER del_tsk( ID tskid ) These functions are restricted as follows: Because of the static initialization facilities provided for system objects, a task is allocated stack space statically in the configuration.
PAGE 476

Chapter 32.
PAGE 477

Chapter 32.
PAGE 478

Chapter 32.
PAGE 479

Chapter 32.
PAGE 480

Chapter 32. µITRON API ER iwup_tsk( ID tskid ) ER isig_sem( ID semid ) ER iset_flg( ID flgid , UID setptn ) ER isend_msg( ID mbxid , T_MSG *pk_msg ) Note that ret_int() and the ret_wup() are implemented as macros, containing a “return” statement. Also note that ret_wup() and the ixxx_yyy() style functions will only work when called from an ISR whose associated DSR is cyg_uitron_dsr(), as specified in include file , which defines the ixxx_yyy() style functions also.
PAGE 481

Chapter 32.
PAGE 482

Chapter 32. µITRON API of memory is used for that memory pool (memory pool ID number) each time. The requested variable pool size (pk_cmpl->mplsz) or the number of fixed-size blocks (pk_cmpf->mpfcnt) times the block size (pk_cmpf->blfsz) are checked for fitting within the statically allocated memory area, so if a create call succeeds, the resulting pool will be at least as large as that requested.
PAGE 483

Chapter 32.
PAGE 484

Chapter 32.
PAGE 485

Chapter 32. µITRON API Network Support Functions None of these functions are supported in this release. µITRON Configuration FAQ Q: How are µITRON objects created? For each type of uITRON object (tasks, semaphores, flags, mboxes, mpf, mpl) these two quantities are controlled by configuration: • The maximum number of this type of object. • The number of these objects which exist initially.
PAGE 486

Chapter 32. µITRON API CYG_UIT_SEMA_NOEXS, CYG_UIT_SEMA_NOEXS, CYG_UIT_SEMA_NOEXS \ \ Semaphore 1 will have initial count 1, semaphores 2 and 3 will be zero, number 4 will be 99 initially, 5 will be one and numbers 6 though 10 do not exist initially. Aside: this is how the definition of the symbol would appear in the configuration header file pkgconf/uitron.h — unfortunately editing such a long, multi-line definition is somewhat cumbersome in the GUI config tool in current releases.
PAGE 487

Chapter 32. µITRON API #define CYGDAT_UITRON_TASK_INITIALIZERS CYG_UIT_TASK("main task", 8, startup, CYG_UIT_TASK("worker 2" , 9, worktask, CYG_UIT_TASK("worker 3" , 9, worktask, CYG_UIT_TASK("low task" ,20, lowtask, \ &stack1, &stack2, &stack3, &stack4, sizeof( sizeof( sizeof( sizeof( stack1 stack2 stack3 stack4 )), )), )), )), \ \ \ \ So this example has all four tasks statically configured to exist, ready to run, from the start of time.
PAGE 488

Chapter 32. µITRON API (you must have at least one task at startup in order that the system can actually run; this is not so for other uITRON object types) Q: Can I have different stack sizes for µITRON tasks? Simply set aside different amounts of memory for each task to use for its stack. Going back to a typical default setting for the µITRON tasks, the definitions in pkgconf/uitron.
PAGE 489

Chapter 32.
PAGE 490

Chapter 32.
PAGE 491

X. TCP/IP Stack Support for eCos The Common Networking for eCos package provides support for a complete TCP/IP networking stack. The design allows for the actual stack to be modular and at the current time two different implementations, one based on OpenBSD from 2000 and a new version based on FreeBSD, are available. The particulars of each stack implementation are presented in separate sections following this top-level discussion.
PAGE 492
PAGE 493

Chapter 33. Ethernet Driver Design Currently, the networking stack only supports ethernet based networking. The network drivers use a two-layer design. One layer is hardware independent and contains all the stack specific code. The other layer is platform dependent and communicates with the hardware independent layer via a very simple API. In this way, hardware device drivers can actually be used with other stacks, if the same API can be provided by that stack.
PAGE 494

Chapter 33.
PAGE 495

Chapter 34. Sample Code Many examples using the networking support are provided. These are arranged as eCos test programs, primarily for use in verifying the package, but they can also serve as useful frameworks for program design. We have taken a KISS approach to building programs which use the network. A single include file is all that is required to access the stack. A complete, annotated test program can be found at net/common/VERSION /tests/ftp_test.c, with its associated files.
PAGE 496

Chapter 34.
PAGE 497

Chapter 35. Configuring IP Addresses Each interface (“eth0” and “eth1”) has independent configuration of its setup. Each can be set up manually (in which case you must write code to do this), or by using BOOTP/DHCP, or explicitly, with configured values. If additional interfaces are added, these must be configured manually. The configurable values are: • IP address • netmask • broadcast address • gateway/router • server address.
PAGE 498

Chapter 35. Configuring IP Addresses • As readable example code from which further development might start. If your application has different requirements for bringing up available network interfaces, setting up routes, determining IP addresses and the like from the defaults that the example code provides, you can write your own initialization code to use whatever sequence of ioctl() function calls carries out the desired setup.
PAGE 499

Chapter 36. Tests and Demonstrations Loopback tests By default, only tests which can execute on any target will be built. These therefore do not actually use external network interfaces (though they may configure and initialize them) but are limited to testing via the loopback interface.
PAGE 500

Chapter 36. Tests and Demonstrations Standalone Tests socket_test - trivial test of socket creation API mbuf_test - trivial test of mbuf allocation API These two do not communicate over the net; they just perform simple API tests then exit. ftp_test - simple FTP test, connects to “server” This test initializes the interface(s) then connects to the FTP server on the “server” machine for for each active interface in turn, confirms that the connection was successful, disconnects and exits.
PAGE 501

Chapter 36. Tests and Demonstrations Next, in another LINUX terminal window, invoke tcp_source, giving it the IP address (or hostname) of an interface of the target board, and optionally a background load to apply to the target while the test runs. For example, “tcp_source 194.130.39.66” to run the test with no additional target CPU load, or “tcp_source 194.130.39.66 85” to load it up to 85% used. The target load must be a multiple of 5.
PAGE 502

Chapter 36. Tests and Demonstrations This is only partially interactive. You need to set things up on the “server” in order for this to work, and you will need to look at the server afterwards to confirm that all was well. For each interface in turn, this test attempts to read by tftp from the server, a file called tftp_get and prints the status and contents it read (if any). It then writes the same data to a file called tftp_put on the same server.
PAGE 503

Chapter 36. Tests and Demonstrations this operation, because most ethernet hardware does not support it — or it comes pre-set from the factory. Do not use this program.
PAGE 504

Chapter 36.
PAGE 505

Chapter 37. Support Features TFTP The TFTP client and server are described in tftp_support.h; the client API is simple and can be easily understood by reading tftp_client_test.c. The server is more complex.
PAGE 506

Chapter 37. Support Features open-my-listen-sockets(); while ( 1 ) { serve-one-request(); // sleeps if no connections, but not forever; // so this loop is polled a few times a minute... if ( cyg_semaphore_trywait( &dhcp_needs_attention )) { if ( ! dhcp_bind() ) { close-my-listen-sockets(); dhcp_halt(); break; } } } } If the configuration option CYGOPT_NET_DHCP_DHCP_THREAD is defined, then eCos provides a thread as described initially.
PAGE 507

Chapter 38. TCP/IP Library Reference getdomainname GETDOMAINNAME(3) System Library Functions Manual GETDOMAINNAME(3) NAME getdomainname, setdomainname - get/set YP domain name of current host SYNOPSIS #include int getdomainname(char *name, size_t namelen); int setdomainname(const char *name, size_t namelen); DESCRIPTION The getdomainname() function returns the YP domain name for the current processor, as previously set by setdomainname().
PAGE 508

Chapter 38. TCP/IP Library Reference If the buffer passed to getdomainname() is too small, other operating systems may not guarantee termination with NUL. HISTORY The getdomainname function call appeared in SunOS 3.x. BSD May 6, 1994 BSD gethostname GETHOSTNAME(3) System Library Functions Manual GETHOSTNAME(3) NAME gethostname, sethostname - get/set name of current host SYNOPSIS #include
PAGE 509

Chapter 38. TCP/IP Library Reference The gethostname() function call conforms to X/Open Portability Guide Issue 4.2 (“XPG4.2”). HISTORY The gethostname() function call appeared in 4.2BSD. BUGS Host names are limited to MAXHOSTNAMELEN (from ) characters, currently 256. This includes the terminating NUL character. If the buffer passed to gethostname() is smaller than MAXHOSTNAMELEN, other operating systems may not guarantee termination with NUL.
PAGE 510

Chapter 38. TCP/IP Library Reference u_int32_t htole32(u_int32_t host32); u_int16_t htole16(u_int16_t host16); u_int32_t letoh32(u_int32_t little32); u_int16_t letoh16(u_int16_t little16); u_int32_t swap32(u_int32_t val32); u_int16_t swap16(u_int16_t val16); DESCRIPTION These routines convert 16- and 32-bit quantities between different byte orderings.
PAGE 511

Chapter 38. TCP/IP Library Reference endian so either the “be” or “le” variants are implemented as null macros. The routines mentioned above which have either {src-order} or {dst-order} set to ‘n’ are most often used in conjunction with Internet addresses and ports as returned by gethostbyname(3) and getservent(3). SEE ALSO gethostbyname(3), getservent(3) HISTORY The byteorder functions appeared in 4.2BSD.
PAGE 512

Chapter 38. TCP/IP Library Reference The ether_ntoa() function converts this structure into an ASCII string of the form “xx:xx:xx:xx:xx:xx”, consisting of 6 hexadecimal numbers separated by colons. It returns a pointer to a static buffer that is reused for each call. The ether_aton() converts an ASCII string of the same form and to a structure containing the 6 octets of the address. It returns a pointer to a static structure that is reused for each call.
PAGE 513

Chapter 38. TCP/IP Library Reference SYNOPSIS #include #include #include int getaddrinfo(const char *nodename, const char *servname, const struct addrinfo *hints, struct addrinfo **res); void freeaddrinfo(struct addrinfo *ai); char * gai_strerror(int ecode); DESCRIPTION The getaddrinfo() function is defined for protocol-independent nodenameto-address translation.
PAGE 514

Chapter 38. TCP/IP Library Reference only IPv4 and not IPv6, then the ai_family member of the hints structure should be set to PF_INET when getaddrinfo() is called. If the third argument to getaddrinfo() is a null pointer, this is the same as if the caller had filled in an addrinfo structure initialized to zero with ai_family set to PF_UNSPEC. Upon successful return a pointer to a linked list of one or more addrinfo structures is returned through the final argument.
PAGE 515

Chapter 38. TCP/IP Library Reference ai_socktype to SOCK_RAW, getaddrinfo() will raise an error, because service names are not defined for the internet SOCK_RAW space. o If you specify a numeric servname, while leaving ai_socktype and ai_protocol unspecified, getaddrinfo() will raise an error. This is because the numeric servname does not identify any socket type, and getaddrinfo() is not allowed to glob the argument in such case.
PAGE 516

Chapter 38. TCP/IP Library Reference hints.ai_family = PF_UNSPEC; hints.ai_socktype = SOCK_STREAM; error = getaddrinfo("www.kame.
PAGE 517

Chapter 38. TCP/IP Library Reference continue; } if (bind(s[nsock], res->ai_addr, res->ai_addrlen) < 0) { cause = "bind"; close(s[nsock]); continue; } (void) listen(s[nsock], 5); nsock++; } if (nsock == 0) { err(1, cause); /*NOTREACHED*/ } freeaddrinfo(res0); DIAGNOSTICS Error return status from getaddrinfo() is zero on success and non-zero on errors. Non-zero error codes are defined in
PAGE 518

Chapter 38. TCP/IP Library Reference kit. STANDARDS The getaddrinfo() function is defined in IEEE POSIX 1003.1g draft specification, and documented in “Basic Socket Interface Extensions for IPv6” (RFC2553). BUGS The current implementation is not thread-safe. The text was shamelessly copied from RFC2553.
PAGE 519

Chapter 38. TCP/IP Library Reference to an object with the following structure describing an internet host referenced by name or by address, respectively. This structure contains either information obtained from the name server (i.e., resolver(3) and named(8)), broken-out fields from a line in /etc/hosts, or database entries supplied by the yp(8) system. resolv.conf(5) describes how the particular database is chosen.
PAGE 520

Chapter 38. TCP/IP Library Reference the same as that returned by hstrerror() with argument h_errno. FILES /etc/hosts /etc/resolv.conf DIAGNOSTICS Error return status from gethostbyname(), gethostbyname2(), and gethostbyaddr() is indicated by return of a null pointer. The external integer h_errno may then be checked to see whether this is a temporary failure or an invalid or unknown host. The variable h_errno can have the following values: HOST_NOT_FOUND No such host is known.
PAGE 521

Chapter 38. TCP/IP Library Reference YP does not support any address families other than AF_INET and uses the traditional database format. BSD March 13, 1997 BSD getifaddrs GETIFADDRS(3) System Library Functions Manual GETIFADDRS(3) NAME getifaddrs - get interface addresses SYNOPSIS #include #include #include
PAGE 522

Chapter 38. TCP/IP Library Reference address of the interface, if one exists, otherwise it is NULL. (The sa_family field of the ifa_addr field should be consulted to determine the format of the ifa_addr address.) ifa_netmask References the netmask associated with ifa_addr, if one is set, otherwise it is NULL. ifa_broadaddr This field, which should only be referenced for non-P2P interfaces, references the broadcast address associated with ifa_addr, if one exists, otherwise it is NULL.
PAGE 523

Chapter 38. TCP/IP Library Reference getnameinfo GETNAMEINFO(3) System Library Functions Manual GETNAMEINFO(3) NAME getnameinfo - address-to-nodename translation in protocol-independent manner SYNOPSIS #include #include #include int getnameinfo(const struct sockaddr *sa, socklen_t salen, char *host, size_t hostlen, char *serv, size_t servlen, int flags); DESCRIPTION The getnameinfo() function is defined for protocol-independent addressto-nodename translation.
PAGE 524

Chapter 38. TCP/IP Library Reference listed in the current Assigned Numbers RFC. The final argument is a flag that changes the default actions of this function. By default the fully-qualified domain name (FQDN) for the host is looked up in the DNS and returned. If the flag bit NI_NOFQDN is set, only the nodename portion of the FQDN is returned for local hosts.
PAGE 525

Chapter 38. TCP/IP Library Reference /*NOTREACHED*/ } printf("host=%s\n", hbuf); DIAGNOSTICS The function indicates successful completion by a zero return value; a non-zero return value indicates failure. Error codes are as below: EAI_AGAIN The name could not be resolved at this time. attempts may succeed. Future EAI_BADFLAGS The flags had an invalid value. EAI_FAIL A non-recoverable error occurred.
PAGE 526

Chapter 38. TCP/IP Library Reference OpenBSD intentionally uses different NI_MAXHOST value from what RFC2553 suggests, to avoid buffer length handling mistakes. BSD May 25, 1995 BSD getnetent GETNETENT(3) System Library Functions Manual GETNETENT(3) NAME getnetent, getnetbyaddr, getnetbyname, setnetent, endnetent - get network entry SYNOPSIS #include
PAGE 527

Chapter 38. TCP/IP Library Reference n_net The network number. byte order. Network numbers are returned in machine The getnetent() function reads the next line of the file, opening the file if necessary. The setnetent() function opens and rewinds the file. If the stayopen flag is non-zero, the net database will not be closed after each call to getnetbyname() or getnetbyaddr(). The endnetent() function closes the file.
PAGE 528

Chapter 38. TCP/IP Library Reference getprotoent(void); struct protoent * getprotobyname(char *name); struct protoent * getprotobynumber(int proto); void setprotoent(int stayopen); void endprotoent(void); DESCRIPTION The getprotoent(), getprotobyname(), and getprotobynumber() functions each return a pointer to an object with the following structure containing the broken-out fields of a line in the network protocol database, /etc/protocols.
PAGE 529

Chapter 38. TCP/IP Library Reference protocols(5) HISTORY The getprotoent(), getprotobynumber(), getprotobyname(), setprotoent(), and endprotoent() functions appeared in 4.2BSD. BUGS These functions use a static data space; if the data is needed for future use, it should be copied before any subsequent calls overwrite it. Only the Internet protocols are currently understood.
PAGE 530

Chapter 38. TCP/IP Library Reference struct rrsetinfo { unsigned int unsigned int unsigned int unsigned int unsigned int unsigned int char struct rdatainfo struct rdatainfo rri_flags; rri_rdclass; rri_rdtype; rri_ttl; rri_nrdatas; rri_nsigs; *rri_name; *rri_rdatas; *rri_sigs; /* /* /* /* /* /* /* /* /* RRSET_VALIDATED ...
PAGE 531

Chapter 38. TCP/IP Library Reference BSD Oct 18, 2000 BSD getservent GETSERVENT(3) System Library Functions Manual GETSERVENT(3) NAME getservent, getservbyport, getservbyname, setservent, endservent - get service entry SYNOPSIS #include
PAGE 532

Chapter 38. TCP/IP Library Reference The getservent() function reads the next line of the file, opening the file if necessary. The setservent() function opens and rewinds the file. If the stayopen flag is non-zero, the net database will not be closed after each call to getservbyname() or getservbyport(). The endservent() function closes the file.
PAGE 533

Chapter 38. TCP/IP Library Reference struct if_nameindex * if_nameindex(void); void if_freenameindex(struct if_nameindex *ptr); DESCRIPTION These functions map interface indexes to interface names (such as “lo0”), and vice versa. The if_nametoindex() function converts an interface name specified by the ifname argument to an interface index (positive integer value). If the specified interface does not exist, 0 will be returned.
PAGE 534

Chapter 38. TCP/IP Library Reference inet INET(3) System Library Functions Manual INET(3) NAME inet_addr, inet_aton, inet_lnaof, inet_makeaddr, inet_netof, inet_network, inet_ntoa, inet_ntop, inet_pton - Internet address manipulation routines SYNOPSIS #include #include #include
PAGE 535

Chapter 38. TCP/IP Library Reference and inet_network() functions return numbers suitable for use as Internet addresses and Internet network numbers, respectively. The function inet_ntop() converts an address from network format (usually a struct in_addr or some other binary form, in network byte order) to presentation format (suitable for external display purposes). It returns NULL if a system error occurs (in which case, errno will have been set), or it returns a pointer to the destination string.
PAGE 536

Chapter 38. TCP/IP Library Reference getnameinfo(3) are recommended rather than the functions presented here. The presentation format of an IPv6 address is given in [RFC1884 2.2]: There are three conventional forms for representing IPv6 addresses as text strings: 1. The preferred form is x:x:x:x:x:x:x:x, where the ’x’s are the hexadecimal values of the eight 16-bit pieces of the address.
PAGE 537

Chapter 38. TCP/IP Library Reference ::FFFF:129.144.52.38 DIAGNOSTICS The constant INADDR_NONE is returned by inet_addr() and inet_network() for malformed requests. SEE ALSO byteorder(3), gethostbyname(3), getnetent(3), inet_net(3), hosts(5), networks(5) STANDARDS The inet_ntop and inet_pton functions conforms to the IETF IPv6 BSD API and address formatting specifications. Note that inet_pton does not accept 1-, 2-, or 3-part dotted addresses; all four parts must be specified.
PAGE 538

Chapter 38.
PAGE 539

Chapter 38. TCP/IP Library Reference type is either IPV6_HOPOPTS or IPV6_DSTOPTS. This type is stored in the cmsg_type member of the cmsghdr structure pointed to by *cmsgp. inet6_option_append This function appends a Hop-by-Hop option or a Destination option into an ancillary data object that has been initialized by inet6_option_init(). This function returns 0 if it succeeds or -1 on an error. cmsg is a pointer to the cmsghdr structure that must have been initialized by inet6_option_init().
PAGE 540

Chapter 38. TCP/IP Library Reference inet6_option_next This function processes the next Hop-by-Hop option or Destination option in an ancillary data object. If another option remains to be processed, the return value of the function is 0 and *tptrp points to the 8-bit option type field (which is followed by the 8-bit option data length, followed by the option data). If no more options remain to be processed, the return value is -1 and *tptrp is NULL.
PAGE 541

Chapter 38. TCP/IP Library Reference S. Deering and R. Hinden, Internet Protocol, Version 6 (IPv6) Specification, RFC2460, December 1998. HISTORY The implementation first appeared in KAME advanced networking kit. STANDARDS The functions are documented in “Advanced Sockets API for IPv6” (RFC2292). BUGS The text was shamelessly copied from RFC2292.
PAGE 542

Chapter 38. TCP/IP Library Reference inet6_rthdr_getflags(const struct cmsghdr *cmsg, int index); DESCRIPTION RFC2292 IPv6 advanced API defines eight functions that the application calls to build and examine a Routing header.
PAGE 543

Chapter 38. TCP/IP Library Reference Upon success the return value is the pointer to the cmsghdr structure, and this is then used as the first argument to the next two functions. Upon an error the return value is NULL. inet6_rthdr_add This function adds the address pointed to by addr to the end of the Routing header being constructed and sets the type of this hop to the value of flags. For an IPv6 Type 0 Routing header, flags must be either IPV6_RTHDR_LOOSE or IPV6_RTHDR_STRICT.
PAGE 544

Chapter 38. TCP/IP Library Reference Upon an error the return value of the function is -1. Note: Addresses are indexed starting at 1, and flags starting at 0, to maintain consistency with the terminology and figures in RFC2460. DIAGNOSTICS inet6_rthdr_space() returns 0 on errors. inet6_rthdr_add(), inet6_rthdr_lasthop() and inet6_rthdr_reverse() return 0 on success, and returns -1 on error. inet6_rthdr_init() and inet6_rthdr_getaddr() return NULL on error.
PAGE 545

Chapter 38. TCP/IP Library Reference char * inet_net_ntop(int af, const void *src, int bits, char *dst, size_t size); int inet_net_pton(int af, const char *src, void *dst, size_t size); DESCRIPTION The inet_net_ntop() function converts an Internet network number from network format (usually a struct in_addr or some other binary form, in network byte order) to CIDR presentation format (suitable for external display purposes). bits is the number of bits in src that are the network number.
PAGE 546

Chapter 38. TCP/IP Library Reference network number without any byte rearrangement. All numbers supplied as “parts” in a ‘.’ notation may be decimal, octal, or hexadecimal, as specified in the C language (i.e., a leading 0x or 0X implies hexadecimal; otherwise, a leading 0 implies octal; otherwise, the number is interpreted as decimal). SEE ALSO byteorder(3), inet(3), networks(5) HISTORY The inet_net_ntop and inet_net_pton functions first appeared in BIND 4.9.4.
PAGE 547

Chapter 38. TCP/IP Library Reference order bytes. Next, the field is inspected for hyphens, in which case the field is assumed to be a number in decimal notation with hyphens separating the millenia. Next, the field is assumed to be a number: It is interpreted as hexadecimal if there is a leading ‘0x’ (as in C), a trailing ‘H’ (as in Mesa), or there are any super-decimal digits present. It is interpreted as octal is there is a leading ‘0’ and there are no superoctal digits.
PAGE 548

Chapter 38. TCP/IP Library Reference The format employed by iso_addr() is a sequence of hexadecimal “digits” (optionally separated by periods), of the form: .. Each pair of hexadecimal digits represents a byte with the leading digit indicating the higher-ordered bits. A period following an even number of bytes has no effect (but may be used to increase legibility).
PAGE 549

Chapter 38. TCP/IP Library Reference string representing some of the information present, including the link level address itself, and the interface name or number, if present. This facility is experimental and is still subject to change.
PAGE 550

Chapter 38. TCP/IP Library Reference and sa2. RETURN VALUES If sa1 and sa2 are for the same address, net_addrcmp() returns 0. The sa_len fields are compared first. If they do not match, net_addrcmp() returns -1 or 1 if sa1->sa_len is less than or greater than sa2->sa_len, respectively. Next, the sa_family members are compared. If they do not match, net_addrcmp() returns -1 or 1 if sa1->sa_family is less than or greater than sa2->sa_family, respectively.
PAGE 551

Chapter 38. TCP/IP Library Reference Unfortunately, no universal standard exists for representing XNS addresses. An effort has been made to ensure that ns_addr() be compatible with most formats in common use. It will first separate an address into 1 to 3 fields using a single delimiter chosen from period (‘.’), colon (‘:’), or pound-sign ‘#’. Each field is then examined for byte separators (colon or period).
PAGE 552

Chapter 38.
PAGE 553

Chapter 38. TCP/IP Library Reference to single-component names (those that do not contain a dot). This option is enabled by default. RES_DNSRCH If this option is set, res_search() will search for host names in the current domain and in parent domains; see hostname(7). This is used by the standard host lookup routine gethostbyname(3). This option is enabled by default. RES_USE_INET6 Enables support for IPv6-only applications. This causes IPv4 addresses to be returned as an IPv4 mapped address.
PAGE 554

Chapter 38. TCP/IP Library Reference The dn_comp() function compresses the domain name exp_dn and stores it in comp_dn. The size of the compressed name is returned or -1 if there were errors. The size of the array pointed to by comp_dn is given by length. The compression uses an array of pointers dnptrs to previously compressed names in the current message. The first pointer points to the beginning of the message and the list ends with NULL. The limit to the array is specified by lastdnptr.
PAGE 555

Chapter 38. TCP/IP Library Reference properties of s, and allocates a new file descriptor for the socket. If no pending connections are present on the queue, and the socket is not marked as non-blocking, accept() blocks the caller until a connection is present. If the socket is marked non-blocking and no pending connections are present on the queue, accept() returns an error as described below. The accepted socket may not be used to accept more connections. The original socket s remains open.
PAGE 556

Chapter 38. TCP/IP Library Reference [EMFILE] The per-process descriptor table is full. [ENFILE] The system file table is full. [ECONNABORTED] A connection has been aborted. SEE ALSO bind(2), connect(2), listen(2), poll(2), select(2), poll(2), socket(2) HISTORY The accept() function appeared in 4.2BSD. BSD February 15, 1999 BSD bind BIND(2) System Calls Manual BIND(2) NAME bind - bind a name to a socket SYNOPSIS #include #include
PAGE 557

Chapter 38. TCP/IP Library Reference [EADDRNOTAVAIL] The specified address is not available from the local machine. [EADDRINUSE] The specified address is already in use. [EINVAL] The socket is already bound to an address. [EINVAL] The family of the socket and that requested in name->sa_family are not equivalent. [EACCES] The requested address is protected, and the current user has inadequate permission to access it. [EFAULT] The name parameter is not in a valid part of the user address space.
PAGE 558

Chapter 38. TCP/IP Library Reference #include #include int connect(int s, const struct sockaddr *name, socklen_t namelen); DESCRIPTION The parameter s is a socket. If it is of type SOCK_DGRAM, this call specifies the peer with which the socket is to be associated; this address is that to which datagrams are to be sent, and the only address from which datagrams are to be received. If the socket is of type SOCK_STREAM, this call attempts to make a connection to another socket.
PAGE 559

Chapter 38. TCP/IP Library Reference [EINPROGRESS] The socket is non-blocking and the connection cannot be completed immediately. It is possible to select(2) or poll(2) for completion by selecting the socket for writing, and also use getsockopt(2) with SO_ERROR to check for error conditions. [EALREADY] The socket is non-blocking and a previous connection attempt has not yet been completed. The following errors are specific to connecting names in the UNIX domain.
PAGE 560

Chapter 38. TCP/IP Library Reference getpeername() returns the address information of the peer connected to socket s. One common use occurs when a process inherits an open socket, such as TCP servers forked from inetd(8). In this scenario, getpeername() is used to determine the connecting client’s IP address. getpeername() takes three parameters: s Contains the file descriptor of the socket whose peer should be looked up.
PAGE 561

Chapter 38. TCP/IP Library Reference BSD July 17, 1999 BSD getsockname GETSOCKNAME(2) System Calls Manual GETSOCKNAME(2) NAME getsockname - get socket name SYNOPSIS #include #include int getsockname(int s, struct sockaddr *name, socklen_t *namelen); DESCRIPTION getsockname() returns the locally bound address information for a specified socket.
PAGE 562

Chapter 38. TCP/IP Library Reference If name does not point to enough space to hold the entire socket address, the result will be truncated to namelen bytes. RETURN VALUES On success, getsockname() returns a 0, and namelen is set to the actual size of the socket address returned in name. Otherwise, errno is set, and a value of -1 is returned. ERRORS If getsockname() fails, errno is set to one of the following: [EBADF] The argument s is not a valid descriptor.
PAGE 563

Chapter 38. TCP/IP Library Reference DESCRIPTION getsockopt() and setsockopt() manipulate the options associated with a socket. Options may exist at multiple protocol levels; they are always present at the uppermost “socket” level. When manipulating socket options the level at which the option resides and the name of the option must be specified. To manipulate options at the socket level, level is specified as SOL_SOCKET.
PAGE 564

Chapter 38. TCP/IP Library Reference SO_DEBUG enables debugging in the underlying protocol modules. SO_REUSEADDR indicates that the rules used in validating addresses supplied in a bind(2) call should allow reuse of local addresses. SO_REUSEPORT allows completely duplicate bindings by multiple processes if they all set SO_REUSEPORT before binding the port. This option permits multiple instances of a program to each receive UDP/IP multicast or broadcast datagrams destined for the bound port.
PAGE 565

Chapter 38. TCP/IP Library Reference data next in the receive queue is different than that returned. SO_SNDTIMEO is an option to set a timeout value for output operations. It accepts a struct timeval parameter with the number of seconds and microseconds used to limit waits for output operations to complete. If a send operation has blocked for this much time, it returns with a partial count or with the error EWOULDBLOCK if no data was sent.
PAGE 566

Chapter 38. TCP/IP Library Reference ioctl IOCTL(2) System Calls Manual IOCTL(2) NAME ioctl - control device SYNOPSIS #include int ioctl(int d, unsigned long request, ...); DESCRIPTION The ioctl() function manipulates the underlying device parameters of special files. In particular, many operating characteristics of character special files (e.g., terminals) may be controlled with ioctl() requests. The argument d must be an open file descriptor.
PAGE 567

Chapter 38. TCP/IP Library Reference An ioctl() function call appeared in Version 7 AT&T UNIX. BSD December 11, 1993 BSD poll POLL(2) System Calls Manual POLL(2) NAME poll - synchronous I/O multiplexing SYNOPSIS #include int poll(struct pollfd *fds, int nfds, int timeout); DESCRIPTION poll() provides a mechanism for reporting I/O conditions across a set of file descriptors.
PAGE 568

Chapter 38. TCP/IP Library Reference POLLOUT Data can be written to the file descriptor without blocking. POLLERR This flag is not used in this implementation and is provided only for source code compatibility. POLLHUP The file descriptor was valid before the polling process and invalid after. Presumably, this means that the file descriptor was closed sometime during the poll. POLLNVAL The corresponding file descriptor is invalid. POLLRDNORM Same as POLLIN. POLLRDBAND Same as POLLIN.
PAGE 569

Chapter 38. TCP/IP Library Reference SEE ALSO poll(2), select(2), sysconf(3) HISTORY A poll() system call appeared in AT&T System V UNIX. BSD December 13, 1994 BSD select SELECT(2) System Calls Manual SELECT(2) NAME select - synchronous I/O multiplexing SYNOPSIS #include #include #include
PAGE 570

Chapter 38. TCP/IP Library Reference imum number of descriptors supported by the system. If timeout is a non-null pointer, it specifies a maximum interval to wait for the selection to complete. If timeout is a null pointer, the select blocks indefinitely. To effect a poll, the timeout argument should be non-null, pointing to a zero-valued timeval structure.
PAGE 571

Chapter 38. TCP/IP Library Reference fd_set *fdsr; int max = fd; fdsr = (fd_set *)calloc(howmany(max+1, NFDBITS), sizeof(fd_mask)); if (fdsr == NULL) { ... return (-1); } FD_SET(fd, fdsr); n = select(max+1, fdsr, NULL, NULL, &tv); ... free(fdsr); Alternatively, it is possible to use the poll(2) interface. poll(2) is more efficient when the size of select()’s fd_set bit-arrays are very large, and for fixed numbers of file descriptors one need not size and dynamically allocate a memory object.
PAGE 572

Chapter 38. TCP/IP Library Reference ssize_t send(int s, const void *msg, size_t len, int flags); ssize_t sendto(int s, const void *msg, size_t len, int flags, const struct sockaddr *to, socklen_t tolen); ssize_t sendmsg(int s, const struct msghdr *msg, int flags); DESCRIPTION send(), sendto(), and sendmsg() are used to transmit a message to another socket. send() may be used only when the socket is in a connected state, while sendto() and sendmsg() may be used at any time.
PAGE 573

Chapter 38. TCP/IP Library Reference and the size of the message to be sent made this impossible. [EAGAIN] The socket is marked non-blocking and the requested operation would block. [ENOBUFS] The system was unable to allocate an internal buffer. The operation may succeed when buffers become available. [ENOBUFS] The output queue for a network interface was full. This generally indicates that the interface has stopped sending, but may be caused by transient congestion.
PAGE 574

Chapter 38. TCP/IP Library Reference SEE ALSO fcntl(2), getsockopt(2), poll(2), recv(2), select(2), poll(2), socket(2), write(2) HISTORY The send() function call appeared in 4.2BSD. BSD July 28, 1998 BSD shutdown SHUTDOWN(2) System Calls Manual SHUTDOWN(2) NAME shutdown - shut down part of a full-duplex connection SYNOPSIS #include #include
PAGE 575

Chapter 38. TCP/IP Library Reference BSD June 4, 1993 BSD socket SOCKET(2) System Calls Manual SOCKET(2) NAME socket - create an endpoint for communication SYNOPSIS #include #include int socket(int domain, int type, int protocol); DESCRIPTION socket() creates an endpoint for communication and returns a descriptor. The domain parameter specifies a communications domain within which communication will take place; this selects the protocol family which should be used.
PAGE 576

Chapter 38. TCP/IP Library Reference described here. The protocol specifies a particular protocol to be used with the socket. Normally only a single protocol exists to support a particular socket type within a given protocol family. However, it is possible that many protocols may exist, in which case a particular protocol must be specified in this manner. The protocol number to use is particular to the communication domain in which communication is to take place; see protocols(5).
PAGE 577

Chapter 38. TCP/IP Library Reference The socket() call fails if: [EPROTONOSUPPORT] The protocol type or the specified protocol is not supported within this domain. [EMFILE] The per-process descriptor table is full. [ENFILE] The system file table is full. [EACCES] Permission to create a socket of the specified type and/or protocol is denied. [ENOBUFS] Insufficient buffer space is available. The socket cannot be created until sufficient resources are freed.
PAGE 578

Chapter 38. TCP/IP Library Reference RETURN VALUES A 0 is returned if the call succeeds, -1 if it fails. ERRORS The call succeeds unless: [EMFILE] Too many descriptors are in use by this process. [EAFNOSUPPORT] The specified address family is not supported on this machine. [EPROTONOSUPPORT] The specified protocol is not supported on this machine. [EOPNOTSUPP] The specified protocol does not support creation of socket pairs.
PAGE 579

XI. FreeBSD TCP/IP Stack port for eCos TCP/IP Networking for eCos now provides a complete TCP/IP networking stack, based on a recent snapshot of the FreeBSD code, released by the KAME project. The networking support is fully featured and well tested within the eCos environment.
PAGE 580
PAGE 581

Chapter 39. Networking Stack Features Since this networking package is based on BSD code, it is very complete and robust.
PAGE 582

Chapter 39.
PAGE 583

Chapter 40. Freebsd TCP/IP stack port This document describes how to get started with the Freebsd TCP/IP network stack. Targets A number of ethernet devices may be supported. The default configuration supports two instances of the interface by default, and you will need to write your own driver instantiation code, and supplemental startup and initialization code, if you should add additional ones.
PAGE 584

Chapter 40.
PAGE 585

Chapter 41. APIs Standard networking The APIs for the standard networking calls such as socket(), recv() and so on, are in header files relative to the top-level include directory, within the standard subdirectories as conventionally found in /usr/include. For example: install/include/arpa/tftp.h install/include/netinet/tcpip.h install/include/sys/socket.h install/include/sys/socketvar.h install/include/sys/sockio.
PAGE 586

Chapter 41.
PAGE 587

XII. OpenBSD TCP/IP Stack port for eCos TCP/IP Networking for eCos now provides a complete TCP/IP networking stack, which is derived from a recent stable release of OpenBSD. The networking support is fully featured and well tested within the eCos environment.
PAGE 588
PAGE 589

Chapter 42. Networking Stack Features Since this networking package is based on BSD code, it is very complete and robust.
PAGE 590

Chapter 42.
PAGE 591

Chapter 43. OpenBSD TCP/IP stack port This document describes how to get started with the OpenBSD TCP/IP network stack. Targets A number of ethernet devices may be supported. The default configuration supports two instances of the interface by default, and you will need to write your own driver instantiation code, and supplemental startup and initialization code, if you should add additional ones.
PAGE 592

Chapter 43.
PAGE 593

Chapter 44. APIs Standard networking The APIs for the standard networking calls such as socket(), recv() and so on, are in header files relative to the top-level include directory, within the standard subdirectories as conventionally found in /usr/include. For example: install/include/arpa/tftp.h install/include/netinet/tcpip.h install/include/sys/socket.h install/include/sys/socketvar.h install/include/sys/sockio.h network.
PAGE 594

Chapter 44. APIs select(int nfd, fd_set ∗in, fd_set ∗out, fd_set ∗ex, struct timeval ∗tv); does not support the restart. The additional API: int cyg_select_with_abort(int nfd, fd_set ∗in, fd_set ∗out, fd_set ∗ex, struct timeval ∗tv) behaves exactly as select() with the additional feature that a call to void cyg_select_abort(void) will cause all threads waiting in any cyg_select_with_abort() call to cease waiting and continue execution.
PAGE 595

XIII. DNS for eCos and RedBoot eCos and RedBoot can both use the DNS package to perform network name lookups.
PAGE 596
PAGE 597

Chapter 45. DNS DNS API The DNS client uses the normal BSD API for performing lookups: gethostbyname() and gethostbyaddr(). There are a few restrictions: • Only IPv4 is supported, ie IPv6 addresses cannot be looked up. • If the DNS server returns multiple authoritive records for a host name, the hostent will only contain a record for the first entry. • The code has been made thread safe. ie multiple threads may call gethostbyname() without causing problems to the hostent structure returned.
PAGE 598

Chapter 45.
PAGE 599

XIV.
PAGE 600
PAGE 601

Chapter 46. Generic Ethernet Device Driver Generic Ethernet API This file provides a simple description of how to write a low-level, hardware dependent ethernet driver. There is a high-level driver (which is only code — with no state of its own) that is part of the stack. There will be one or more low-level drivers tied to the actual network hardware. Each of these drivers contains one or more driver instances.
PAGE 602

Chapter 46. Generic Ethernet Device Driver struct arpcom sc_arpcom; /* ethernet common */ }; Note: If you have two instances of the same hardware, you only need one struct eth_hwr_funs shared between them.
PAGE 603

Chapter 46. Generic Ethernet Device Driver The device_instance entry here would point to the struct eth_drv_sc entry previously defined. This allows the network driver setup to work with any class of driver, not just ethernet drivers. In the future, there will surely be serial PPP drivers, etc. These will use the NETDEVTAB_ENTRY() setup to create the basic driver, but they will most likely be built on top of other high-level device driver layers.
PAGE 604

Chapter 46. Generic Ethernet Device Driver Init function static bool DRV_HDWR_init(struct cyg_netdevtab_entry *tab) This function is called as part of system initialization. Its primary function is to decide if the hardware (as indicated via tab->device_instance) is working and if the interface needs to be made available in the system. If this is the case, this function needs to finish with a call to the ethernet driver function: struct eth_drv_sc *sc = (struct eth_drv_sc *)tab->device_instance; ....
PAGE 605

Chapter 46. Generic Ethernet Device Driver Stop function static void HRDWR_stop(struct eth_drv_sc *sc) This function is the inverse of “start.” It should shut down the hardware, disable the receiver, and keep it from interacting with the physical network. Control function static int HRDWR_control( struct eth_drv_sc *sc, unsigned long key, void *data, int len) This function is used to perform low-level “control” operations on the interface.
PAGE 606

Chapter 46. Generic Ethernet Device Driver }; ETH_DRV_SET_MC_ALL This entry instructs the device to receive all multicast packets, and delete any explicit filtering which had been set up. This function should return zero if the specified operation was completed successfully. It should return non-zero if the operation could not be performed, for any reason.
PAGE 607

Chapter 46. Generic Ethernet Device Driver Note: In future, this function may be extended so that the data need not be copied by having the function return a “disposition” code (done, send pending, etc). At this point, you should move the data to some “safe” location before returning.
PAGE 608

Chapter 46. Generic Ethernet Device Driver has been called itself from your deliver function when it knows that a packet of data is available on the interface. The (sc->funs->eth_drv->recv)() function then arranges network buffers and structures for the data and then calls HRDWR_recv() to actually move the data from the interface. A scatter-gather list (struct eth_drv_sg) is used once more, just like in the send case.
PAGE 609

Chapter 46. Generic Ethernet Device Driver These functions require a pointer to a struct eth_drv_sc which describes the interface at a logical level. It is assumed that the low level hardware driver will keep track of this pointer so it may be passed “up” as appropriate. Callback Init function void (sc->funs->eth_drv->init)( struct eth_drv_sc *sc, unsigned char *enaddr) This function establishes the device at initialization time.
PAGE 610

Chapter 46. Generic Ethernet Device Driver Transmission 1. Some foreground task such as the application, SNMP “daemon”, DHCP management thread or whatever, calls into network stack to send a packet, or the stack decides to send a packet in response to incoming traffic such as a “ping” or ARP request. 2. The driver calls the HRDWR_can_send() function in the hardware driver. 3. HRDWR_can_send() returns the number of available "slots" in which it can store a pending transmit packet.
PAGE 611

Chapter 46. Generic Ethernet Device Driver 6. It then calls back into the hardware driver routine HRDWR_recv(). HRDWR_recv() must copy the data from the hardware’s buffers into the scatter-gather buffers provided, and return. 7. The network stack now has the data in-hand, and does with it what it will. This might include recursive calls to transmit a response packet. When this all is done, these calls return, and the “Network Delivery Thread” sleeps once more, awaiting the next asynchronous event.
PAGE 612

Chapter 46.
PAGE 613

XV.
PAGE 614
PAGE 615

Chapter 47. SNMP for eCos Version This is a port of UCD-SNMP-4.1.2 Originally this document said: See http://ucd-snmp.ucdavis.edu/ for details. And send them a postcard. The project has since been renamed “net-snmp” and re-homed at http://net-snmp.sourceforge.net/ (http://netsnmp.sourceforge.net/) where various new releases (of the original, not eCos ports) are available. The original source base from which we worked to create the eCos port is available from various archive sites such as ftp://ftp.freesnmp.
PAGE 616

Chapter 47. SNMP for eCos dot3 snmp [ cmot { mib2 9 } is “historic”, just a placeholder ] { mib2 10 7 } == { transmission 7 } “EtherLike MIB” { mib2 11 } On inclusion of SNMPv3 support packages, the following MIBs are added to the default set of MIBs enumerated above : snmpEngine { snmpFrameworkMIBObjects 1 } SNMP-FRAMEWORK-MIB, as described in RFC-2571 for support of SNMPv3 framework.
PAGE 617

Chapter 47. SNMP for eCos cyg_net_snmp_init(); } #endif In case you need to perform initialization, for example setting up SNMPv3 security features, when the snmp agent starts and every time it restarts, you can register a callback function by simply writing the global variable: externC void (*snmpd_reinit_function)( void ); with a suitable function pointer.
PAGE 618

Chapter 47. SNMP for eCos Version usage (v1, v2 or v3) The default build supports all three versions of the SNMP protocol, but without any dispatcher functionality (rfc 2571, section 3.1.1.2). This has the following implications : 1. There is no community authentication for v1 and v2c. 2. Security provided by v3 can be bypassed by using v1/v2c protocol. To provide the dispatcher with rfc 2571 type functionality, it is required to set up security models and access profiles.
PAGE 619

Chapter 47. SNMP for eCos location specified in SNMPCONFPATH, or the standard builtin locations, and use these profiles. Only the profiles specified in the ACCESS-CONTROL section of snmpd.conf file have been tested and shown to work. Other profiles which have been implemented in UCD-SNMP-4.1.2’s snmpd.conf may not work because the sole purpose of adding support for the snmpd.conf file has been to set up ACCESS-CONTROL models. At startup, the SNMP module tries to look for file snmp.conf.
PAGE 620

Chapter 47.
PAGE 621

Chapter 47. SNMP for eCos tation. As required, a cleaner interface to permit application code to manage persistent data will be developed in consultation with customers. MIB Compiler In the directory /snmp/agent/VERSION/utils/mib2c, there are the following files: README-eCos README.mib2c mib2c mib2c.conf mib2c.conf-ORIG mib2c.storage.conf mib2c.vartypes.conf notes about running with a nonstandard perl path.
PAGE 622

Chapter 47. SNMP for eCos #include “mibgroup/mibII/my_new_mib.h” PACKAGES/net/snmp/agent/VERSION/include/mib_module_inits.h contains a number of lines like init_interfaces(); init_dot3(); and so on; add your new MIB as follows: init_my_new_mib(); and this should work correctly. snmpd.conf SNMPD.CONF(5) SNMPD.CONF(5) NAME share/snmp/snmpd.conf snmp SNMP agent. - configuration file for the ucd- DESCRIPTION snmpd.conf is the configuration file which defines how the ucd-smnp SNMP agent operates.
PAGE 623

Chapter 47. SNMP for eCos This is a flag returning either the integer value 1 or 0 if an error is detected for this table entry. .101 -- errorMsg This is a DISPLAY-STRING describing any error triggering the errorFlag above. .102 -- errorFix If this entry is SNMPset to the integer value of 1 AND the errorFlag defined above is indeed a 1, a program or script will get executed with the table entry name from above as the argument. The program to be executed is configured in the config.h file at compile time.
PAGE 624

Chapter 47. SNMP for eCos If MIBNUM is specified, it acts as above but returns the exit status to MIBNUM.100.0 and the entire STDOUT output to the table MIBNUM.101 in a mib table. In this case, the MIBNUM.101 mib contains the entire STDOUT output, one mib table entry per line of output (ie, the first line is output as MIBNUM.101.1, the second at MIBNUM.101.2, etc...). Note: The MIBNUM must be specified in dotted-integer notation and can not be specified as ".iso.org.dod.internet...
PAGE 625

Chapter 47. SNMP for eCos the associated maximum values. If any of the MAX1, MAX5, or MAX15 values are unspecified, they default to a value of DEFMAXLOADAVE. file FILE [MAXSIZE] Monitors file sizes and makes sure they don’t grow beyond a certain size. MAXSIZE defaults to infinite if not specified, and only monitors the size without reporting errors about it. Errors Any errors in obtaining the above information are reported via the 1.3.6.1.4.1.2021.101.100 flag and the 1.3.6.1.4.1.2021.101.
PAGE 626

Chapter 47. SNMP for eCos The minimum level of authentication and privacy the user must use is specified by the first token (which defaults to "auth"). The OID parameter restricts access for that user to everything below the given OID. com2sec NAME SOURCE COMMUNITY This directive specifies the mapping from a source/community pair to a security name. SOURCE can be a hostname, a subnet, or the word "default". A subnet can be specified as IP/MASK or IP/BITS.
PAGE 627

Chapter 47. SNMP for eCos # group group group group group group group group group mygroup mygroup mygroup local local local public public public # view all view system view mib2 sec.model v1 v2c usm v1 v2c usm v1 v2c usm incl/excl included included included sec.name mynet mynet mynet local local local public public public # context access mygroup "" access public "" access local "" subtree .1 system .iso.org.dod.internet.mgmt.mib-2 sec.model any any any sec.
PAGE 628

Chapter 47. SNMP for eCos but you must have built the package with openssl installed in order to use SHA. The only privacy protocol currently supported is DES. If the privacy passphrase is not specified, it is assumed to be the same as the authentication passphrase. Note that the users created will be useless unless they are also added to the VACM access control tables described above. Warning: acters. the minimum pass phrase length is 8 char- SNMPv3 users can be created at snmpusm command.
PAGE 629

Chapter 47. SNMP for eCos PASS-THROUGH CONTROL pass MIBOID EXEC Passes entire control of MIBOID to the EXEC program. The EXEC program is called in one of the following three ways: EXEC -g MIBOID EXEC -n MIBOID These call lines match to SNMP get and getnext requests. It is expected that the EXEC program will take the arguments passed to it and return the appropriate response through it’s stdout. The first line of stdout should be the mib OID of the returning value.
PAGE 630

Chapter 47. SNMP for eCos Note: By default, the only community allowed to write (ie snmpset) to your script will be the "private" community,or community #2 if defined differently by the "community" token discussed above. Which communities are allowed write access are controlled by the RWRITE definition in the snmplib/snmp_impl.h source file. EXAMPLE See the EXAMPLE.CONF file in the top level source directory for a more detailed example of how the above information is used in real examples.
PAGE 631

XVI.
PAGE 632
PAGE 633

Chapter 48. Embedded HTTP Server Intrduction The eCos HTTPD package provides a simple HTTP server for use with applications in eCos. This server is specifically aimed at the remote control and monitoring requirements of embedded applications. For this reason the emphasis is on dynamically generated content, simple forms handling and a basic CGI interface. It is not intended to be a general purpose server for delivering arbitrary web content.
PAGE 634

Chapter 48. Embedded HTTP Server When a pattern is matched, the hander function is called. It has the following prototype: cyg_bool cyg_httpd_handler(FILE char char void *client, *filename, *formdata, *arg); The client argument is the TCP connection to the client: anything output through this stream will be returned to the browser. The filename argument is the filename from the HTTP request and the formdata argument is any form response data, or NULL if none was sent.
PAGE 635

Chapter 48. Embedded HTTP Server CYGNUM_HTTPD_THREAD_STACK_SIZE This is the amount of stack to be allocated for each of the HTTPD threads. The actual stack size allocated will be this value plus the values of CYGNUM_HAL_STACK_SIZE_MINIMUM and CYGNUM_HTTPD_SERVER_BUFFER_SIZE. CYGNUM_HTTPD_SERVER_BUFFER_SIZE This defines the size of the buffer used to receive the first line of each HTTP request. If you expect to use particularly long URLs or have very complex forms, this should be increased.
PAGE 636

Chapter 48. Embedded HTTP Server The macro html_begin() generates an HTTP header with a "text/html" content type followed by an opening "" tag. html_end() generates a closing "" tag and calls cyg_http_finish().
PAGE 637

Chapter 48.
PAGE 638

Chapter 48. Embedded HTTP Server char cyg_html_message[] = "Welcome\n" "
Welcome to my Web Page
\n" CYG_HTTPD_TABLE_ENTRY( cyg_html_message_entry, "/message.html", cyg_httpd_send_html, cyg_html_message ); cyg_httpd_send_data() Sends arbitrary data to the client. The argument is a pointer to a cyg_httpd_data structure that defines the content type and length of the data, and a pointer to the data itself.
PAGE 639

XVII. FTP Client for eCos TCP/IP Stack The ftpclient package provides an FTP (File Transfer Protocol) client for use with the TCP/IP stack in eCos.
PAGE 640
PAGE 641

Chapter 49. FTP Client Features FTP Client API This package implements an FTP client. The API is in include file install/include/ftpclient.h and it can be used thus: #include #include It looks like this: ftp_get int ftp_get(char ∗ hostname, char ∗ username, char ∗ passwd, char ∗ filename, char ∗ buf, unsigned buf_size, ftp_printf_t ftp_printf); Use the FTP protocol to retrieve a file from a server. Only binary mode is supported. The filename can include a directory name.
PAGE 642

Chapter 49. FTP Client Features true when the message to print is an error message. Otherwise the message is diagnostic, eg. the commands sent and received from the server.
PAGE 643

XVIII. CRC Algorithms The CRC package provides implementation of CRC algorithms. This includes the POSIX CRC calculation which produces the same result as the cksum command on Linux, another 32 bit CRC by Gary S. Brown and a 16bit CRC. The CRC used for Ethernet FCS is also implemented.
PAGE 644
PAGE 645

Chapter 50. CRC Functions CRC API The package implements a number of CRC functions as described below. The API to these functions is in the include file cyg/crc/crc.h. cyg_posix_crc32 This function implements a 32 bit CRC which is compliant to the POSIX 1008.2 Standard. This is the same as the Linux cksum program. cyg_uint32 cyg_posix_crc32(unsigned char ∗ s, int len); The CRC calculation is run over the data pointed to by s, of length len. The CRC is returned as an unsigned long.
PAGE 646

Chapter 50. CRC Functions The CRC calculation is run over the data pointed to by s, of length len. The CRC is returned as an unsigned short.
PAGE 647

XIX. CPU load measurements The cpuload package provides a way to estimate the cpuload. It gives an estimated percentage load for the last 100 milliseconds, 1 second and 10 seconds.
PAGE 648
PAGE 649

Chapter 51. CPU Load Measurements CPU Load API The package allows the CPU load to be estimated. The measurement code must first be calibrated to the target it is running on. Once this has been performed the measurement process can be started. This is a continuous process, so always providing the most up to data measurements. The process can be stopped at any time if required. Once the process is active, the results can be retrieved.
PAGE 650

Chapter 51. CPU Load Measurements handle should be the value returned by the create function. cyg_cpuload_get This function returns the latest measurements. void cyg_cpuload_get(cyg_handle_t handle, cyg_uint32 *average_point1s, cyg_uint32 *average_1s, cyg_uint32 *average_10s); handle should be the value returned by the create function. The load measurements for the last 100ms, 1s and 10s are returned in *average_point1s,*average_1s and *average_10s respectively.
PAGE 651

XX. Application profiling The profile_gprof package provides a mechanism to measure the runtime performance of an application. This is done by gathering an execution histogram. When profiling is started on the target device, a TFTP server will be started which exports the single file PROFILE.DAT This analysis data can then be fetched by connecting to the target with a TFTP client program and then be processed by the gprof utility program.
PAGE 652
PAGE 653

Chapter 52. Profiling functions API In order for profile data to be gathered for an application, the program has to initiate the process. Once started, execution histogram data will be collected in a dynamic memory buffer. This data can be uploaded to a host using TFTP. A side effect of the upload of the data is that the histogram is reset. This is useful, especially for high resolution histograms, since the histogram data are collected as 16-bit counters which can be quickly saturated.
PAGE 654

Chapter 52.
PAGE 655

XXI.
PAGE 656
PAGE 657

Introduction Name Introduction — eCos support for Power Management Introduction The eCos Power Management package provides a framework for incorporating power management facilities in an embedded application. However its functionality is deliberately limited. 1. The package does not contain any support for controlling the current power mode of any given processor, device or board.
PAGE 658

Introduction seconds. A possible action when entering idle mode is to reduce the system’s clock speed, thus reducing the power drawn by the cpu. Note that typically this power mode is not entered automatically whenever the idle thread starts running. Instead it is entered when the policy module discovers that for a certain period of time the system has been spending most of its time in the idle thread.
PAGE 659

Introduction are integrated with the processor, power_controller_cpu will take care of the integrated devices as a side effect. In other cases the hardware may not provide any functionality that allows power consumption to be controlled. For any given device driver it is also possible that no power controller exists either because it was not required when the driver was written, or because the driver predates the availability of power management.
PAGE 660

Introduction mode. This check happens between every power controller invocation. Usefully this makes it possible for power controllers themselves to manipulate power modes: a power controller is invoked to change mode; for some reason it determines that the new mode is inappropriate; it calls power_set_mode to move the system back to another mode; when the power controller returns this event will be detected; the power management thread will abort the current mode change, and start the new one.
PAGE 661

Power Management Information Name Obtaining Power Management Information — finding out about the various power controllers in the system Synopsis #include
PAGE 662

Power Management Information Global Power Modes The function power_get_mode can be called at any time to determine the current power mode for the system as a whole. The return value will be one of PowerMode_Active, PowerMode_Idle, PowerMode_Sleep or PowerMode_Off. In normal circumstances it is unlikely that PowerMode_Off would be returned since that mode generally means that the cpu is no longer running. The function power_get_desired_mode returns the power mode that the system should be running at.
PAGE 663

Power Management Information #endif #include
PAGE 664

Power Management Information 560
PAGE 665

Changing Power Modes Name Changing Power Modes — reducing or increasing power consumption as needed Synopsis #include void power_set_mode ( PowerMode new_mode ); void power_set_controller_mode ( PowerController* controller , PowerMode new_mode ); void power_set_controller_mode_now ( PowerController* controller , PowerMode new_mode ); Changing the Global Power Mode The primary functionality supported by the power management package is to change the system’s global power mode.
PAGE 666

Changing Power Modes However, it is still legal for a power controller to call power_set_mode: effectively this is a recursive call; it is detected by the system, and internal state is updated; the recursive power_set_mode call now returns, and when the power controller returns back to the original power_set_mode call it detects what has happened, aborts the previous mode change, and starts a new mode change as requested by the controller. power_set_mode is normally invoked from thread context.
PAGE 667

Support for Policy Modules Name Support for Policy Modules — closer integration with higher-level code Synopsis #include
PAGE 668

Support for Policy Modules PowerController* controller, PowerMode old_mode, PowerMode new_mode, PowerMode old_desired_mode, powerMode new_desired_mode) { printf("Power mode change: %s, %s -> %d\n", power_get_controller_id(controller), mode_to_string(old_mode), mode_to_string(new_mode)); CYG_UNUSED_PARAM(PowerMode, old_desired_mode); CYG_UNUSED_PARAM(PowerMode, new_desired_mode); } int main(int argc, char** argv) { ... power_set_policy_callback(&power_callback); ...
PAGE 669

Support for Policy Modules Not all policy modules will require per-controller data. The configuration option CYGIMP_POWER_PROVIDE_POLICY_DATA can be used to control this functionality, thus avoiding wasting a small amount of memory inside each power controller structure.
PAGE 670

Support for Policy Modules 566
PAGE 671

Attached and Detached Controllers Name Attached and Detached Controllers — control which power controllers are affected by global changes Synopsis #include cyg_bool power_get_controller_attached ( PowerController* controller ); void power_set_controller_attached ( PowerController* controller , cyg_bool new_state ); Detaching Power Controllers By default the global operation power_set_mode affects all power controllers. There may be circumstances when this is not desirable.
PAGE 672

Attached and Detached Controllers 568
PAGE 673

Implementing a Power Controller Name Implementing a Power Controller — adding power management support to device drivers and other packages Implementing a Power Controller A system will have some number of power controllers. Usually there will be one power controller for the cpu, power_controller_cpu, typically provided by one of the HAL packages and responsible for managing the processor itself and associated critical components such as memory.
PAGE 674

Implementing a Power Controller #include #ifdef CYGPKG_POWER # include
PAGE 675

Implementing a Power Controller Some care has to be taken to ensure that the power controllers actually end up in the final executable. If a power controller variable ends up in an ordinary library and is never referenced directly then typically the linker will believe that the variable is not needed and it will not end up in the executable. For eCos packages this can be achieved in the CDL, by specifying that the containing source file should end up in libextras.a rather than the default libtarget.
PAGE 676

Implementing a Power Controller a. If the request cannot be satisfied immediately but may be feasible in a short while, leave the mode field unchanged. Higher-level code in the policy module can interpret this as a hint to retry the operation a little bit later. This approach is also useful if the mode change can be started but will take some time to complete, for example shutting down a socket connection, and additional processing will be needed later on. b.
PAGE 677

XXII.
PAGE 678

Implementing a Power Controller 574
PAGE 679

Introduction Name Introduction — eCos support for USB slave devices Introduction The eCos USB slave support allows developers to produce USB peripherals. It consists of a number of different eCos packages: 1. Device drivers for specific implementations of USB slave hardware, for example the on-chip USB Device Controller provided by the Intel SA1110 processor. A typical USB peripheral will only provide one USB slave port and therefore only one such device driver package will be needed.
PAGE 680

Introduction USB supports four different types of communication: control messages, interrupt transfers, isochronous transfers, and bulk transfers. Control messages are further subdivided into four categories: standard, class, vendor and a reserved category. All USB peripherals must respond to certain standard control messages, and usually this will be handled by the common USB slave package (for complicated peripherals, application support will be needed).
PAGE 681

Introduction required information such as the vendor id cannot be supplied by generic packages; only by the application developer. Class support code such as the USB-ethernet package could in theory supply some of the information automatically, but there are also hardware dependencies such as which endpoints get used for incoming and outgoing ethernet frames. Instead it is the responsibility of the application developer to provide all the enumeration data and perform some additional initialisation.
PAGE 682

Introduction GLO_IO_USB_SLAVE_APPLICATION, and the USB device driver and related packages will adjust accordingly. Al- ternatively, the device driver may provide some configuration options to provide more fine-grained control.
PAGE 683

USB Enumeration Data Name Enumeration Data — The USB enumeration data structures Synopsis #include #include typedef struct usb_device_descriptor { ... } usb_device_descriptor __attribute__((packed)); typedef struct usb_configuration_descriptor { ... } usb_configuration_descriptor __attribute__((packed)); typedef struct usb_interface_descriptor { ... } usb_interface_descriptor __attribute__((packed)); typedef struct usb_endpoint_descriptor { ...
PAGE 684

USB Enumeration Data }; int main(int argc, char** argv) { usbs_sa11x0_ep0.enumeration_data = &usb_enum_data; ... usbs_start(&usbs_sa11x0_ep0); ... } For most applications the enumeration data will be static, although the usbs_enumeration_data structure can be filled in at run-time if necessary. Full details of the enumeration data can be found in the Universal Serial Bus specification obtainable from the USB Implementers Forum web site (http://www.usb.
PAGE 685

USB Enumeration Data example mass-storage devices and human-interface devices. If a peripheral implements one of the standard classes then a standard existing host-side device driver may exist, eliminating the need to write a custom driver. The value 0xFF (VENDOR) is reserved for peripherals that implement a vendor-specific protocol rather than a standard one. Such peripherals will require a custom host-side device driver.
PAGE 686

USB Enumeration Data calculate this: the first argument to the macros specify the number of interfaces, the second the number of endpoints. The number_interfaces field is self-explanatory. If the peripheral involves multiple configurations then each one must have a unique id, and this will be used in the set-configuration control message. The id 0 is reserved, and a set-configuration control message that uses this id indicates that the peripheral should be inactive.
PAGE 687

USB Enumeration Data usb_endpoint_descriptor The host also needs information about which endpoint should be used for what.
PAGE 688

USB Enumeration Data Strings The enumeration data can contain a number of strings with additional information. Unicode encoding is used for the strings, and it is possible for a peripheral to supply a given string in multiple languages using the appropriate characters. The first two bytes of each string give a length and type field. The first string is special; after the two bytes header it consists of an array of 2-byte language id codes, indicating the supported languages.
PAGE 689

Starting up a USB Device Name usbs_start — Starting up a USB Device Synopsis #include void usbs_start(usbs_control_endpoint* ep0); Description Initializing a USB device requires some support from higher-level code, typically the application, in the form of enumeration data. Hence it is not possible for the low-level USB driver to activate a USB device itself. Instead the higher-level code has to take care of this by invoking usbs_start.
PAGE 690

Starting up a USB Device 586
PAGE 691

Devtab Entries Name Devtab Entries — Data endpoint data structure Synopsis /dev/usb0c /dev/usb1r /dev/usb2w Devtab Entries USB device drivers provide two ways of transferring data between host and peripheral. The first involves USBspecific functionality such as usbs_start_rx_buffer. This provides non-blocking I/O: a transfer is started, and some time later the device driver will call a supplied completion function.
PAGE 692

Devtab Entries read operations cyg_io_read and similar functions in higher-level packages can be used to perform a transfer from host to pe- ripheral. This should be a complete transfer: higher-level protocols should define an upper bound on the amount of data being transferred, and the read operation should involve at least this amount of data. The return value will indicate the actual transfer size, which may be less than requested.
PAGE 693

Devtab Entries Presence The devtab entries are optional. If the USB device is accessed primarily by class-specific code such as the USBethernet package and that package uses the USB-specific API directly, the devtab entries are redundant. Even if application code does need to access the USB device, the non-blocking API may be more convenient than the blocking I/O provided via the devtab entries. In these cases the devtab entries serve no useful purpose, but they still impose a memory overhead.
PAGE 694

Devtab Entries 590
PAGE 695

Receiving Data from the Host Name usbs_start_rx_buffer — Receiving Data from the Host Synopsis #include void usbs_start_rx_buffer(usbs_rx_endpoint* ep, unsigned char* buffer, int length, void (*)(void*,int) complete_fn, void * complete_data); void usbs_start_rx(usbs_rx_endpoint* ep); Description usbs_start_rx_buffer is a USB-specific function to accept a transfer from host to peripheral. It can be used for bulk, interrupt or isochronous transfers, but not for control messages.
PAGE 696

Receiving Data from the Host between the host and the target has been broken, and -EAGAIN for when the endpoint has been halted. Specific USB device drivers may specify additional error conditions. The normal sequence of events is that the USB device driver will update the appropriate hardware registers. At some point after that the host will attempt to send data by transmitting an OUT token followed by a data packet, and since a receive operation is now in progress the data will be accepted and ACK’d.
PAGE 697

Receiving Data from the Host There is also a utility function usbs_start_rx. This can be used by code that wants to manipulate data endpoints directly, specifically the complete_fn, complete_data, buffer and buffer_size fields. usbs_start_tx just invokes a function supplied by the device driver.
PAGE 698

Receiving Data from the Host 594
PAGE 699

Sending Data to the Host Name usbs_start_tx_buffer — Sending Data to the Host Synopsis #include void usbs_start_tx_buffer(usbs_tx_endpoint* ep, const unsigned char* buffer, int length, void (*)(void*,int) complete_fn, void * complete_data); void usbs_start_tx(usbs_tx_endpoint* ep); Description usbs_start_tx_buffer is a USB-specific function to transfer data from peripheral to host.
PAGE 700

Sending Data to the Host The normal sequence of events is that the USB device driver will update the appropriate hardware registers. At some point after that the host will attempt to fetch data by transmitting an IN token. Since a transmit operation is now in progress the peripheral can send a packet of data, and the host will generate an ACK. At this point the USB hardware will generate an interrupt, and the device driver will service this interrupt and arrange for a DSR to be called.
PAGE 701

Halted Endpoints Name Halted Endpoints — Support for Halting and Halted Endpoints Synopsis #include
PAGE 702

Halted Endpoints ble to use a single completion function and have the foreground code invoke either usbs_start_rx_buffer or usbs_start_rx_endpoint_wait depending on the current state of the endpoint.
PAGE 703

Control Endpoints Name Control Endpoints — Control endpoint data structure Synopsis #include typedef struct usbs_control_endpoint { *hellip; } usbs_control_endpoint; usbs_control_endpoint Data Structure The device driver for a USB slave device should supply one usbs_control_endpoint data structure per USB device. This corresponds to endpoint 0 which will be used for all control message interaction between the host and that device.
PAGE 704

Control Endpoints ... const usbs_enumeration_data* enumeration_data; void (*start_fn)(usbs_control_endpoint*); ... }; It is the responsibility of higher-level code, usually the application, to define the USB enumeration data. This needs to be installed in the control endpoint data structure early on during system startup, before the USB device is actually started and any interaction with the host is possible. Details of the enumeration data are supplied in the section USB Enumeration Data.
PAGE 705

Control Endpoints } usbs_state_change; The USB standard defines a number of states for a given USB peripheral. The initial state is detached, where the peripheral is either not connected to a host at all or, from the host’s perspective, the peripheral has not started up yet because the relevant pins are tristated. The peripheral then moves via intermediate attached and powered states to its default or reset state, at which point the host and peripheral can actually start exchanging data.
PAGE 706

Control Endpoints extern usbs_control_return usbs_handle_standard_control(struct usbs_control_endpoint*); When a USB peripheral is connected to the host it must always respond to control messages sent to endpoint 0. Control messages always consist of an initial eight-byte header, containing fields such as a request type. This may be followed by a further data transfer, either from host to peripheral or from peripheral to host. The way this is handled is described in the Buffer Management section below.
PAGE 707

Control Endpoints Non-standard control messages always have to be processed by higher-level code. This could be class-specific packages. For example, the USB-ethernet package will handle requests for getting the MAC address and for enabling or disabling promiscuous mode.
PAGE 708

Control Endpoints 4. When buffer_size is 0 and fill_buffer_fn is NULL, no more data is available and the transfer has completed. 5. Optionally a completion function can be installed. This will be invoked with 0 if the transfer completes successfully, or with an error code if the transfer is cancelled because of another control messsage. If the requested data is contiguous then the only fields that need to be manipulated are buffer and buffer_size, and optionally complete_fn.
PAGE 709

Data Endpoints Name Data Endpoints — Data endpoint data structures Synopsis #include
PAGE 710

Data Endpoints indicates that the connection between the host and the peripheral has been broken. Certain device drivers may generate other error codes. If higher-level code needs to halt or unhalt an endpoint then it can invoke the set_halted_fn member. When an endpoint is halted, invoking start_rx_fn wit buffer_size set to 0 indicates that higher-level code wants to block until the endpoint is no longer halted; at that point the completion function will be invoked.
PAGE 711

Writing a USB Device Driver Name Writing a USB Device Driver — USB Device Driver Porting Guide Introduction Often the best way to write a USB device driver will be to start with an existing one and modify it as necessary. The information given here is intended primarily as an outline rather than as a complete guide. Note: At the time of writing only one USB device driver has been implemented. Hence it is possible, perhaps probable, that some portability issues have not yet been addressed.
PAGE 712

Writing a USB Device Driver state change to and from configured state cannot easily be handled by the device driver itself, instead higher-level code such as the common USB slave package will take care of this. Once the connection between host and peripheral has been established, the peripheral must be ready to accept control messages at all times, and must respond to these within certain time constraints. For example, the standard set-address control message must be handled within 50ms.
PAGE 713

Writing a USB Device Driver Note: Giving a buffer size of 0 bytes a special meaning is problematical because it prevents transfers of that size. Such transfers are allowed by the USB protocol, consisting of just headers and acknowledgements and an empty data phase, although rarely useful. A future modification of the device driver specification will address this issue, although care has to be taken that the functionality remains accessible through devtab entries as well as via low-level accesses.
PAGE 714

Writing a USB Device Driver Interrupt Handling A typical USB device driver will need to service interrupts for all of the endpoints and possibly for additional USB events such as entering or leaving suspended mode. Usually these interrupts need not be serviced directly by the ISR. Instead, they can be left to a DSR. If the peripheral is not able to accept or send another packet just yet, the hardware will generate a NAK and the host will just retry a little bit later.
PAGE 715

Writing a USB Device Driver calls like open and read. min_size This indicates the smallest transfer size that the hardware can support on this endpoint. Typically this will be one. Note: Strictly speaking a minimum size of one is not quite right since it is valid for a USB transfer to involve zero bytes, in other words a transfer that involves just headers and acknowledgements and an empty data phase, and that should be tested as well.
PAGE 716

Writing a USB Device Driver usbs_testing_endpoint usbs_testing_endpoints[] = { { endpoint_type : USB_ENDPOINT_DESCRIPTOR_ATTR_CONTROL, endpoint_number : 0, endpoint_direction : USB_ENDPOINT_DESCRIPTOR_ENDPOINT_IN, endpoint : (void*) &ep0.common, devtab_entry : (const char*) 0, min_size : 1, max_size : 0x0FFFF, max_in_padding : 0, alignment : 0 }, ...
PAGE 717

Testing Name Testing — Testing of USB Device Drivers Introduction The support for USB testing provided by the eCos USB common slave package is somewhat different in nature from the kind of testing used in many other packages. One obvious problem is that USB tests cannot be run on just a bare target platform: instead the target platform must be connected to a suitable USB host machine, and that host machine must be running appropriate software for the test code to interact with.
PAGE 718

Testing Building and Running the Target-side Code The target-side component of the USB testing software consists of a single program usbtarget which contains support for a range of different tests, under the control of host-side software.
PAGE 719

Testing or alternatively using some combination of --with-tcl-include, --with-tcl-lib and --withtcl-version. ➍ One of the host-side executables that gets built, usbchmod, needs to be installed with suid root privileges. Although the Linux kernel makes it possible for applications to perform low-level USB operations such as transmitting bulk packets, by default access to this functionality is restricted to programs with superuser privileges.
PAGE 720

Testing 3. The -V or --verbose option can be used to obtain more information at run-time, for example some output for every USB transfer. This option can be repeated multiple times to increase the amount of output. 4. The first argument that does not begin with a hyphen specifies a test that should be run, in the form of a Tcl script. For example an argument of list.tcl will cause usbhost to look for a script with that name, adding a .tcl suffix if necessarary, and run that script.
PAGE 721

Testing endpoint will not be listed. When usbhost first contacts the usbtarget program running on the target platform, it obtains this information and makes it available to test scripts via Tcl variables: bulk_in_endpoints This is a simple list of the endpoints which can support bulk IN transfers.
PAGE 722

Testing devtab This is a string indicating whether or not the target-side USB device driver supports access to this endpoint via entries in the device table, in other words through conventional calls like open and write. Some device drivers may only support low-level USB access because typically that is what gets used by USB class-specific packages such as USB-ethernet. An empty string indicates that no devtab entry is available, otherwise it will be something like "/dev/usbs2w".
PAGE 723

Testing interrupt_in_endpoints and interrupt_in() These variables provide the same information as bulk_in_endpoints and bulk_in, but for endpoints that support interrupt IN transfers. interrupt_out_endpoints and interrupt_out() These variables provide the same information as bulk_out_endpoints and bulk_out, but for endpoints that support interrupt OUT transfers. Testing Bulk Transfers The main function for initiating a bulk test is usbtest::bulktest.
PAGE 724

Testing intfill The buffer will be treated as an array of 32-bit integers, and will be filled with the same integer repeated the appropriate number of times. If the buffer size is not a multiple of four bytes then the last few bytes will be set to 0. byteseq The buffer will be filled with a sequence of bytes, generated by a linear congruential generator. If the first byte in the buffer is filled with the value x, the next byte will be (m*x)+i.
PAGE 725

Testing Transmit Size The next set of arguments can be used to control the size of the transmitted buffer: txsize1, txsize>=, txsize<= txsize*, txsize/, and txsize+. txsize1 determines the size of the first transfer, and has a default value of 32 bytes. The size of the next transfer is calculated by first multiplying by the txsize* value, then dividing by the txsize/ value, and finally adding the txsize+ value.
PAGE 726

Testing The receive delay is controlled by a similar set of six parameters: rxdelay1, rxdelay*, rxdelay/, rxdelay+, rxdelay>= and rxdelay<=. The default values for these are the same as for transmit delays. The transmit delay is used on the side which sends data over the USB bus, so for a bulk IN transfer it is the target that sends data and hence sleeps for the specified transmit delay, while the host receives data sleeps for the receive delay. For an OUT transfer the positions are reversed.
PAGE 727

Testing Possible Problems If all transfers succeed within the specified time then both host and target remain in synch and further tests can be run without problem. However, if at any time a failure occurs then things get more complicated. For example, if the current test involves a series of bulk OUT transfers and the target detects that for one of these transfers it received less data than was expected then the test has failed, and the target will stop accepting data on this endpoint.
PAGE 728

Testing 624
PAGE 729

XXIII.
PAGE 730

Testing 626
PAGE 731

Introduction Name Introduction — eCos support for developing USB ethernet peripherals Introduction The eCos USB-ethernet package provides additional support for USB peripherals that involve some sort of ethernetstyle network. This can be a traditional ethernet, or it can involve some other networking technology that uses ethernet frames as a unit of transfer.
PAGE 732

Introduction address for the host/peripheral combination, corresponding to the connection to the real network, and it is this address which should be supplied during initialization. In a more complicated scenario, there is a TCP/IP stack running inside the peripheral. This involves the USB-ethernet package providing a service both to the host and to the eCos TCP/IP stack. It achieves the latter by acting as an eCos network device. Typically, the TCP/IP stack will be configured to act as a network bridge.
PAGE 733

Initializing the USB-ethernet Package Name usbs_eth_init — Initializing the USB-ethernet Package Synopsis #include void usbs_eth_init(usbs_eth* usbeth, usbs_control_endpoint* ep0, usbs_rx_endpoint* ep1, usbs_tx_endpoint* ep2, unsigned char* mac_address); Description The USB-ethernet package is not tied to any specific hardware.
PAGE 734

Initializing the USB-ethernet Package The call to usbs_eth_init should normally happen after the enumeration data has been provided but before the underlying USB device driver has been started. If the USB device were to be started first then a connection between host and peripheral could be established immediately, and the host-side device driver would attempt to contact the USB-ethernet package for information such as the MAC address.
PAGE 735

USB-ethernet Data Transfers Name USB-ethernet Data Transfers — Exchanging ethernet packets with the USB host Synopsis #include void usbs_eth_start_rx(usbs_eth* usbseth, unsigned char* buffer, void (*)(usbs_eth*, void*, int) complete_fn, void* complete_data); void usbs_eth_start_tx(usbs_eth* usbseth, unsigned char* buffer, void (*)(usbs_eth*, void*, int) complete_fn, void* complete_data); Description The USB-ethernet package provides two main modes of operation.
PAGE 736

USB-ethernet Data Transfers Both usbs_eth_start_tx and usbs_eth_start_rx are asynchronous: the transfer is started and, some time later, a completion function will be invoked. The third and fourth arguments to both usbs_eth_start_tx and usbs_eth_start_rx supply the completion function and an argument to that function respectively. The completion function will be invoked with three arguments: a pointer to the usbs_eth data structure, usually usbs_eth0; the supplied completion data ; and a return code field.
PAGE 737

USB-ethernet State Handling Name USB-ethernet State Handling — Maintaining the USB-ethernet connection with the host Synopsis #include
PAGE 738

USB-ethernet State Handling 634
PAGE 739

Network Device for the eCos TCP/IP Stack Name Network Device — USB-ethernet support for the eCos TCP/IP Stack Description If the USB peripheral involves running the eCos TCP/IP stack and that stack needs to use USB-ethernet as a transport layer (or as one of the transports), then the USB-ethernet package can provide a suitable network device driver.
PAGE 740

Network Device for the eCos TCP/IP Stack 636
PAGE 741

Example Host-side Device Driver Name Example Host-side Device Driver — Provide host-side support for the eCos USB-ethernet package Description The USB-ethernet package is supplied with a single host-side device driver. This driver has been developed against the Linux kernel 2.2.16-22, as shipped with Red Hat 7.
PAGE 742

Example Host-side Device Driver If a suitable USB peripheral is now connected the host will detect this, assign an address in the local USB network, obtain enumeration data, and find a suitable device driver. Assuming the peripheral and device driver agree on the supported vendor ids, the ecos_usbeth.o module will be selected and this will be reported in the system log: Apr 1 18:04:12 grumpy kernel: usb.
PAGE 743

Communication Protocol Name Communication Protocol — Protocol used between the host-side device driver and the eCos USB-ethernet package Description There is a USB standard for the protocol to be used between the host and a class of communication devices, including ethernet. However, the eCos USB-ethernet package does not implement this protocol: the target hardware for which the package was first developed had certain limitations, and could not implement the standard.
PAGE 744

Communication Protocol This control message involves no further data so the length field should be set to 0. The value field should be non-zero to enable promiscuous mode, zero to disable it. The request field should be 0x02. The remaining fields in the control message will be ignored. It is the responsibility of the host-side device driver to keep track of whether or not promiscuous mode is currently enabled.
PAGE 745

XXIV.
PAGE 746

Communication Protocol 642
PAGE 747

Overview Name The eCos synthetic target — Overview Description Usually eCos runs on either a custom piece of hardware, specially designed to meet the needs of a specific application, or on a development board of some sort that is available before the final hardware. Such boards have a number of things in common: 1. Obviously there has to be at least one processor to do the work. Often this will be a 32-bit processor, but it can be smaller or larger.
PAGE 748

Overview standard eCos ISR/DSR mechanisms. The I/O auxiliary is based around Tcl scripting, making it easy to extend and customize. It should be possible to configure the synthetic target so that its I/O functionality is similar to what will be available on the final target hardware for the application being developed.
PAGE 749

Overview no need for a simulator or special tools. This will be much faster and somewhat simpler than using an architectural simulator, but no attempt is made to accurately match the behaviour of a real embedded target.
PAGE 750

Overview 646
PAGE 751

Installation Name Installation — Preparing to use the synthetic target Host-side Software To get the full functionality of the synthetic target, users must build and install the I/O auxiliary ecosynth and various support files. It is possible to develop applications for the synthetic target without the auxiliary, but only limited I/O facilities will be available.
PAGE 752

Installation Toolchain When developing eCos applications for a normal embedded target it is necessary to use a suitable cross-compiler and related tools such as the linker. Developing for the synthetic target is easier because you can just use the standard GNU tools (gcc, g++, ld, . . . ) which were provided with your Linux distribution, or which you used to build your own Linux setup. Any reasonably recent version of the tools, for example gcc 2.
PAGE 753

Running a Synthetic Target Application Name Execution — Arguments and configuration files Description The procedure for configuring and building eCos and an application for the synthetic target is the same as for any other eCos target.
PAGE 754

Running a Synthetic Target Application -nw, --no-windows The I/O auxiliary can either provide a graphical user interface, or it can run in a text-only mode. The default is to provide the graphical interface, but this can be disabled with -nw. Emulation of some devices, for example buttons connected to digital inputs, requires the graphical interface. -w, --windows The -w causes the I/O auxiliary to provide a graphical user interface. This is the default.
PAGE 755

Running a Synthetic Target Application the current standard output. Specifying -l causes most of the text to go into a logfile instead, although some messages such as errors generated by the auxiliary itself will still go to stdout as well. -t , --target During initialization the I/O auxiliary reads in a target definition file. This file holds information such as which Linux devices should be used to emulate the various eCos devices.
PAGE 756

Running a Synthetic Target Application #filter ipv4 #filter ipv6 -hide 1 -hide 1 } A target definition file is actually a Tcl script that gets run in the main interpreter of the I/O auxiliary during initialization. This provides a lot of flexibility if necessary. For example the script could open a socket to a resource management server of some sort to determine which hardware facilities are already in use and adapt accordingly. Another possibility is to adapt based on command line arguments.
PAGE 757

Running a Synthetic Target Application used. The -V command line option can be used to get warnings about unused device entries in the target definition file. If the body of a synth_device command contains an unrecognised option and the relevant device is in use, the I/O auxiliary will always issue a warning about such options. User Configuration Files During initialization the I/O auxiliary will execute two user configuration files, initrc.tcl and mainrc.tcl.
PAGE 758

Running a Synthetic Target Application 654
PAGE 759

The I/O Auxiliary’s User Interface Name User Interface — Controlling the I/O Auxiliary Description The synthetic target auxiliary is designed to support both extensions and user customization. Support for the desired devices is dynamically loaded, and each device can extend the user interface. For example it is possible for a device to add menu options, place new buttons on the toolbar, create its own sub-window within the overall layout, or even create entire new toplevel windows.
PAGE 760

The I/O Auxiliary’s User Interface the right. At the bottom of the window is a status line, including a small animation that shows whether or not the eCos application is still running. Menus and the Toolbar Usually there will be four menus on the menu bar: File, Edit, View and Help. On the File menu there are three entries related to saving the current contents of the central text window. Save is used to save the currently visible contents of the text window.
PAGE 761

The I/O Auxiliary’s User Interface The Preferences menu item brings up a miscellaneous preferences dialog. One of the preferences relates to online help: the I/O auxiliary does not currently have a built-in html viewer; instead it will execute an external browser of some sort. With the example settings shown, the I/O auxiliary will first attempt to interact with an existing mozilla session. If that fails it will try to run a new mozilla instance, or as a last result use the Gnome help viewer.
PAGE 762

The I/O Auxiliary’s User Interface The default appearance for most filters is controlled via the target definition file. An example entry might be: filter trace {^TRACE:.*} -foreground HotPink1 -hide 1 The various colours and the hide flag for each filter can be changed at run-time, using the System Filters item on the View menu. This will bring up a dialog like the following: It should be noted that the text window is line-oriented, not character-oriented.
PAGE 763

The I/O Auxiliary’s User Interface Subwindows are generally packed in one of eight frames surrounding the central text window: .main.nw, .main.n, .main.ne, .main.w, .main.e, .main.sw, .main.s, and .main.se. To position a row of LED’s above the text window and towards the left, a target definition file could contain an entry such as: synth_device led { pack -in .main.n -side left ... } Similarly, to put a traffic monitor window on the right of the text window would involve something like: ...
PAGE 764

The I/O Auxiliary’s User Interface 660
PAGE 765

The Console Device Name The console device — Show output from the eCos application Description The eCos application can generate text output in a variety of ways, including calling printf or diag_printf. When the I/O auxiliary is enabled the eCos startup code will instantiate a console device to process all such output. If operating in text mode the output will simply go to standard output, or to a logfile if the -l command line option is specified.
PAGE 766

The Console Device Any number of additional filters can be created with a filter option, for example: synth_device console { ... filter trace {^TRACE:.*} -foreground HotPink1 -hide 1 ... } The first argument gives the new filter a name which will be used in the filters dialog. Filter names should be unique. The second argument is a Tcl regular expression.
PAGE 767

System Calls Name cyg_hal_sys_xyz — Access Linux system facilities Synopsis #include int cyg_hal_sys_xyzzy(...); Description On a real embedded target eCos interacts with the hardware by peeking and poking various registers, manipulating special regions of memory, and so on. The synthetic target does not access hardware directly. Instead I/O and other operations are emulated by making appropriate Linux system calls.
PAGE 768

System Calls eCos packages and applications should never #include Linux header files directly. For example, doing a #include to access additional macros or structure definitions, or alternatively manipulating the header file search path, will lead to problems because the Linux header files are likely to duplicate and clash with definitions in the eCos headers. Instead the appropriate functionality should be extracted from the Linux headers and moved into either cyg/hal/hal_io.
PAGE 769

Writing New Devices - target Name Writing New Devices — extending the synthetic target, target-side Synopsis #include
PAGE 770

Writing New Devices - target defined point at which the I/O auxiliary knows that all required devices have been loaded. It can then perform various consistency checks and clean-ups, run the user’s mainrc.tcl script, and make the main window visible. For standard devices generic eCos I/O code will call the device initialization routines at the right time, iterating through the DEVTAB table in a static constructor. The same holds for network devices and file systems.
PAGE 771

Writing New Devices - target instance If it is possible to have multiple instances of a device then this argument identifies the particular instance, for example eth0 or eth1. Otherwise a NULL pointer can be used. data This argument can be used to pass additional initialization data from eCos to the host-side support.
PAGE 772

Writing New Devices - target arg1 arg2 For some requests it is convenient to pass one or two additional parameters alongside the request code. For example an ethernet device could define a multicast-all request, with arg1 controlling whether this mode should be enabled or disabled. Both arg1 and arg2 should be signed 32-bit integers, and their values are interpreted only by the device-specific Tcl script. txdata txlen Some I/O operations may involve sending additional data, for example an ethernet packet.
PAGE 773

Writing New Devices - target have some limitations: there is no support for nested interrupts, interrupt priorities, or a separate interrupt stack. Supporting those might be appropriate when targetting a simulator that attempts to model real hardware accurately, but not for the simple emulation provided by the synthetic target. Of course the actual implementation of the ISR and DSR functions will be rather different for a synthetic target device driver.
PAGE 774

Writing New Devices - target 670
PAGE 775

Writing New Devices - host Name Writing New Devices — extending the synthetic target, host-side Description On the host-side adding a new device means writing a Tcl/Tk script that will handle instantiation and subsequent requests from the target-side. These scripts all run in the same full interpreter, extended with various commands provided by the main I/O auxiliary code, and running in an overall GUI framework. Some knowledge of programming with Tcl/Tk is required to implement host-side device support.
PAGE 776

Writing New Devices - host then be processed using aclocal, autoconf and automake in that order. Actually building the software then just involves configure, make and make install, as per the instructions in the toplevel README.host file. To assist developers, if the environment variable ECOSYNTH_DEVEL is set then a slightly different algorithm is used for locating device Tcl scripts.
PAGE 777

Writing New Devices - host ... if { } { synth::send_reply 0 "" return } ... synth::send_reply $packet_len $packet } ... } The id argument is the same device id that was passed to the instantiate function, and is typically used as an array index to access per-device data.
PAGE 778

Writing New Devices - host synth::interrupt_raise can be called any time after initialization. The argument should be the vector returned by synth::interrupt_allocate for this device. It will activate the normal eCos interrupt handling mechanism so, subject to interrupts being enabled and this particular interrupt not being masked out, the appropriate ISR will run. Note: At this time it is not possible for a device to allocate a specific interrupt vector.
PAGE 779

Writing New Devices - host } The first call checks for a flag -o13 or --o13 - the code treats options with single and double hyphens interchangeably. The second call checks for an argument of the form -mark= or a pair of arguments -mark .
PAGE 780

Writing New Devices - host ... } synth::tdf_get_option returns a list of all the arguments for a given option. For example, if the target definition file contains an entry: synth_device console { appearance -foreground white -background black filter trace {^TRACE:.*} -foreground HotPink1 -hide 1 filter xyzzy {.*xyzzy.*} -foreground PapayaWhip } A call synth::tdf_get_option console appearance will return the list {-foreground white -background black}.
PAGE 781

Writing New Devices - host order of device initialization is not sufficiently defined. User scripts run from mainrc.tcl can use any hooks that have been defined.
PAGE 782

Writing New Devices - host Output and Filters Scripts can use conventional facilities for sending text output to the user, for example calling puts or directly manipulating the central text widget .main.centre.text.
PAGE 783

Writing New Devices - host set message "" if { ![synth::filter_parse_options $console_appearance parsed_options message] } { synth::report_error \ "Invalid entry in target definition file $synth::target_definition\ \n synth_device \"console\", entry \"appearance\"\n$message" } else { synth::filter_add_parsed "console" parsed_options } On success parsed_options will be updated with an internal representation of the desired appearance, which can then be used in a call to synth::filter_add_parsed.
PAGE 784

Writing New Devices - host synth::handle_help synth::load_image can be used to add a new image to the current interpreter. If the specified file has a .xbm extension then the image will be a monochrome bitmap, otherwise it will be a colour image of some sort. A boolean will be returned to indicate success or failure, and suitable diagnostics will be generated if necessary. synth::register_balloon_help provides balloon help for a specific widget, usually a button on the toolbar.
PAGE 785

Porting Name Porting — Adding support for other hosts Description The initial development effort of the eCos synthetic target happened on x86 Linux machines. Porting to other platforms involves addressing a number of different issues. Some ports should be fairly straightforward, for example a port to Linux on a processor other than an x86. Porting to Unix or Unix-like operating systems other than Linux may be possible, but would involve more effort.
PAGE 786

Porting The GNU C library sources may also prove very useful: for a normal Linux application it is the C library that provides the startup code and the system call interface. Other Unix Platforms Porting to a Unix or Unix-like operating system other than Linux would be somewhat more involved.
PAGE 787

Porting The next big problem is the system call interface. Under Windows system calls are generally made via DLL’s, and it is not clear that the underlying trap mechanism is well-documented or consistent between different releases of Windows. The current code depends on the operating system providing an implementation of POSIX signal handling. This is used for I/O purposes, for example SIGALRM is used for the system clock, and for exceptions.
PAGE 788

Porting 684
PAGE 789

XXV.
PAGE 790

Porting 686
PAGE 791

SA11X0 USB Device Driver Name SA11X0 USB Support — Device driver for the on-chip SA11X0 USB device SA11X0 USB Hardware The Intel StrongARM SA11x0 family of processors is supplied with an on-chip USB slave device, the UDC (USB Device Controller). This supports three endpoints. Endpoint 0 can only be used for control messages. Endpoint 1 can only be used for bulk transfers from host to peripheral. Endpoint 2 can only be used for bulk transfers from peripheral to host.
PAGE 792

SA11X0 USB Device Driver is enabled, otherwise it is disabled. Usually this has the desired effect. It may be necessary to override this in special circumstances, for example if the target board uses an external USB chip in preference to the UDC and it is that external chip’s device driver that should be used rather than the on-chip UDC.
PAGE 793

SA11X0 USB Device Driver The exact DMA engines that will be used are determined by the configuration options CYGNUM_DEVS_USB_SA11X0_EP1_DMA_CHANNEL and CYGNUM_DEVS_USB_SA11X0_EP2_DMA_CHANNEL. These options have the booldata flavor, allowing the use of DMA to be disabled completely in addition to controlling which DMA engines are used. If DMA is disabled then the device driver will attempt to work purely using the fifos, and the packet size will be limited to only 16 bytes.
PAGE 794

SA11X0 USB Device Driver 690
PAGE 795

XXVI.
PAGE 796

SA11X0 USB Device Driver 692
PAGE 797

NEC uPD985xx USB Device Driver Name NEC uPD985xx USB Support — Device driver for the on-chip NEC uPD985xx USB device NEC uPD985xx USB Hardware The NEC uPD985xx family of processors is supplied with an on-chip USB slave device, the UDC (USB Device Controller). This supports seven endpoints. Endpoint 0 can only be used for control messages. Endpoints 1 and 2 are for isochronous transmits and receives respectively. Endpoints 3 and 4 support bulk transmits and receives.
PAGE 798

NEC uPD985xx USB Device Driver The uPD985xx USB device driver implements the interface specified by the common eCos USB Slave Support package. The documentation for that package should be consulted for further details. The device driver assumes a bulk packet size of 64 bytes, so this value should be used in the endpoint descriptors in the enumeration data provided by application code.
PAGE 799

NEC uPD985xx USB Device Driver point 5, the response is delayed until the bulk transfer has completed. Under typical operating conditions this does not cause any problems: endpoint 0 traffic usually happens only during initialization, when the target is connected to the host, while endpoint 5 traffic only happens after initialization.
PAGE 800

NEC uPD985xx USB Device Driver 696
PAGE 801

XXVII.
PAGE 802

NEC uPD985xx USB Device Driver 698
PAGE 803

Synthetic Target Ethernet Driver Name Synthetic Target Ethernet Support — Allow synthetic target applications to perform ethernet I/O Overview The synthetic target ethernet package can provide up to four network devices, eth0 to eth3. These can be used directly by the eCos application or, more commonly, by a TCP/IP stack that is linked with the eCos application. Each eCos device can be mapped on to a real Linux network device.
PAGE 804

Synthetic Target Ethernet Driver Caution Installing rawether suid root introduces a potential security problem. Although normally rawether is executed only by the I/O auxiliary, theoretically it can be run by any program. Effectively it gives any user the ability to monitor all ethernet traffic and to inject arbitrary packets into the network. Also, as with any suid root programs there may be as yet undiscovered exploits.
PAGE 805

Synthetic Target Ethernet Driver } It is not possible for an ethernet device to be shared by both the eCos TCP/IP stack and the Linux one: there would be no simple way to work out which stack incoming packets are intended for. In theory it might be possible to do some demultiplexing using distinct IP addresses, but it would be impossible to support some functionality such as DHCP. Therefore the rawether program will refuse to access any ethernet device already in use.
PAGE 806

Synthetic Target Ethernet Driver physical hardware to provide these addresses, so normally MAC addresses will be invented. That means that each time the eCos application is run it will have different MAC addresses, which makes it more difficult to compare the results of different runs. To get more deterministic behaviour it is possible to specify the MAC addresses in the target definition file: synth_device ethernet { eth0 ethertap tap3 00:01:02:03:FE:05 eth1 ethertap tap4 00:01:02:03:FE:06 ...
PAGE 807

Synthetic Target Ethernet Driver The protocol analyser is not intended to be a fully functional analyser with knowledge of many different TCP/IP protocols, advanced search facilities, graphical traffic displays, and so on. Functionality like that is already provided by other tools such as ethereal and tcpdump. Achieving similar levels of functionality would require a lot of work, for very little gain.
PAGE 808

Synthetic Target Ethernet Driver max_show 128 } User Interface Additions When running in graphical mode the ethernet script extends the user interface in two ways: a button is added to the toolbar so that users can enable or disable packet logging; and an entry is added to the Help menu for the ethernet-specific documentation. Command Line Arguments The synthetic target ethernet support does not use any command line arguments. All configuration is handled through the target definition file.
PAGE 809

XXVIII.
PAGE 810

Synthetic Target Ethernet Driver 706
PAGE 811

Synthetic Target Watchdog Device Name Synthetic Target Watchdog Device — Emulate watchdog hardware in the synthetic target Overview Some target hardware comes equipped with a watchdog timer. Application code can start this timer and after a certain period of time, typically a second, the watchdog will trigger. Usually this causes the hardware to reboot. The application can prevent this by regularly resetting the watchdog.
PAGE 812

Synthetic Target Watchdog Device Target-side Configuration The watchdog device depends on the generic watchdog support, CYGPKG_IO_WATCHDOG: if the generic support is absent then the watchdog device will be inactive. Some templates include this generic package by default, but not all.
PAGE 813

Synthetic Target Watchdog Device only a short amount of time so their effects can be ignored. If the application makes direct system calls such as cyg_hal_sys_read then the system behaviour becomes undefined. In addition by default the idle thread will make blocking select system calls, effectively waiting until an interrupt occurs. If an application spends much of its time idle then the watchdog device may take much longer to trigger than expected.
PAGE 814

Synthetic Target Watchdog Device By default the watchdog support will not generate an audible alert when the watchdog triggers, to avoid annoying colleagues. Sound can be enabled in the target definition file, and two suitable files sound1.au and sound2.au are supplied as standard: synth_device watchdog { sound sound1.au ... } An absolute path can be specified if desired: synth_device watchdog { sound /usr/share/emacs/site-lisp/emacspeak/sounds/default-8k/alarm.au ...