Chapter 5. Native kernel C language API

Table of Contents
Types used in programming eCos
Thread operations
Priority manipulation
Exception handling
Interrupt handling
Counters, clocks and alarms
Memory pools
Message boxes

The eCos kernel, like many other real-time kernels, is a library to which the programmer links an application. System calls resemble library API calls, and there is no trap mechanism to switch from user to system mode.

We present here the eCos kernel API and the APIs for other kernels provided as compatibility layers on top of eCos.

Since this API sits on top of a configurable system, the semantics are only weakly defined. The exact semantics and even the API itself depend on the configuration. For example if returned error codes were supported this would change the prototype of the functions. The semantics given in this chapter describe the default configuration.

As mentioned above, all source files which use the kernel C API should have the following #include statement:

#include <cyg/kernel/kapi.h>

at the head of the file.

Types used in programming eCos

We now describe the types defined for use with eCos. These are available to programs that include kapi.h.

Most of these types are meant to be opaque — in other words, programmers do not need to know (and probably should not know) how they are defined. But the types that are numeric are marked, since it can be useful to use comparison operators.

The definitions for these types can be found in the installed tree, in the file include/cyg/kernel/kapi.h.

The eCos kernel uses the following naming convention for types:


A type which is large enough to store the larger of an address and a machine word. This is used for convenience when a function is passed data which could be either a pointer to a block of data or a single word.


A handle is a variable used to refer to eCos system objects (such as a thread or an alarm). Most eCos system calls that create system objects will return a handle that is used to access that object from then on.


A numeric type used to represent the priority of a thread, or the priority of an interrupt level. A lower number means a higher (i.e. more important) priority thread.


A numeric type used for various error or status codes, such as exception numbers.


A numeric type used to identify an interrupt vector. Its value is called the interrupt vector id. This type is used for both ISR vector ids and VSR vector ids.


A numeric type used to count counter ticks. The resolution and other details regarding tick quantities depend on the configuration, but this is a 64 bit type, and no matter what configuration is chosen it should still last for centuries before it overflows.


A boolean type whose values can be false (0) or true (1).


A function type for functions that are entry points for threads. It is used in the thread creation call cyg_thread_create().

To help write thread entry point functions, here is how cyg_thread_entry_t is defined:

typedef void cyg_thread_entry_t(void *);

Examples of thread functions can be found in the programming tutorial in Getting Started with eCos.


A function type used for installing exception handlers. It is defined as:

typedef void cyg_exception_handler_t(
 cyg_addrword_t data,
 cyg_code_t exception_number,
 cyg_addrword_t info

cyg_thread, cyg_interrupt, cyg_counter, cyg_clock, cyg_alarm, cyg_mbox, cyg_mempool_var, and cyg_mempool_fix

These types are of the appropriate size to contain the memory used by the respective kernel objects. These types are only used in the corresponding create call where the programmer allocates the memory for the object and passes the address to the kernel. After creation the provided handle is used to reference the object.


Contains information about a memory pool.

typedef struct {
 cyg_int32 totalmem;
 cyg_int32 freemem;
 void *base;
 cyg_int32 size;
 cyg_int32 blocksize;
 cyg_int32 maxfree; // The largest free block
} cyg_mempool_info;

cyg_sem_t, cyg_mutex_t, and cyg_cond_t

These types are of the appropriate size to contain the memory used by their respective kernel objects. These objects are always referred to by a pointer to an object of this type.

cyg_VSR_t, cyg_ISR_t, and cyg_DSR_t

These are function types used when vector, interrupt and delayed service routines are installed.

typedef void cyg_VSR_t();
typedef cyg_uint32 cyg_ISR_t(cyg_vector_t vector,
 cyg_addrword_t data);
typedef void cyg_DSR_t(cyg_uint32 vector,
 cyg_ucount32 count,
 cyg_addrword_t data);


Stores the resolution of a clock. The resolution is defined to be (dividend/divisor) nanoseconds per tick.

	typedef struct { cyg_uint32 dividend;
 cyg_uint32 divisor; }


The function type used for alarm handlers.

typedef void cyg_alarm_t(cyg_handle_t alarm,
 cyg_addrword_t data);