A tour of the kernel sources
To Contents | To previous page | To next page

## A tour of the kernel sources

This description takes the form of a tour around the sources explaining their structure and describing the functionality of each component.

The kernel is divided into two basic parts, the largely machine independent parts in `Cygnus/eCos/packages/kernel/` v1_3_x, and the architecture- and platform-specific parts that comprise the Hardware Abstraction Layer ( HAL ) in `Cygnus/eCos/packages/hal` . These will be described separately. Also note that the HAL is described in great detail in its own chapter (see The eCos Hardware Abstraction Layer (HAL) ).

### Kernel headers

Kernel header files (in `Cygnus/eCos/packages/kernel/` v1_3_x `/include` ) provide external interfaces and configuration control for the various kernel objects. In general there is an include file for each major kernel class. Those header files having to do with configuration live in the `pkgconf` subdirectory.

The base name of a header file and the source file that implements it are usually the same. So, for example, the member functions defined in `sched.hxx` are implemented in `sched.cxx` . For a number of classes there are also header files that define inline functions, for example `sched.inl` .

There are some kernel objects that are implemented using C++ templates to allow code re-use in future; it is not intended that these template classes be used generally by applications. The appropriate concrete kernel classes should be used instead.

Now we examine the files one by one for reference:

`include/bitmap.hxx`

Bitmap scheduler definition. See source file `sched/bitmap.cxx`

`include/clock.hxx` ,

`include/clock.inl`

Counter, clock and alarm functions. See source file `common/clock.cxx`

`include/diag.h`

Diagnostic routines. See source file `trace/diag.c`

`include/errors.h`

Kernel error codes. See source file `common/except.cxx`

`include/except.hxx`

Exception handling.

`include/flag.hxx`

Flag synchronization objects. See source file `sync/flag.cxx`

`include/instrmnt.h`

Instrumentation. See source file `instrmnt/meminst.cxx`

`include/intr.hxx`

Interrupts. See source file `intr/intr.cxx`

`include/kapi.h` ,

`include/kapidata.h`

Native 'C' API to the kernel. See source file `common/kapi.cxx`

`include/ktypes.h`

Kernel types.

`include/llistt.hxx`

A simple doubly linked-list template class used elsewhere in the kernel.

`include/lottery.hxx`

Lottery scheduler implementation. See source file `sched/lottery.cxx`

`include/mbox.hxx` ,

`include/mboxt.hxx` ,

`include/mboxt2.hxx` ,

`include/mboxt.inl` ,

`include/mboxt2.inl`

Message boxes. See source file `sync/mbox.cxx` ; `mboxt.hxx` and `mboxt2.hxx` and `mboxt.inl` and `mboxt2.inl` implement the underlying template function.

### NOTE

The files with a 2 suffix are used by default and provide precise µ ITRON semantics.

`include/memfixed.hxx` ,

`include/mempoolt.hxx` ,

`include/mempolt2.hxx` ,

`include/mempoolt.inl` ,

`include/mempolt2.inl` ,

`include/mfiximpl.hxx` ,

`include/mfiximpl.inl`

Fixed-block allocation memory pools. See source file `mem/memfixed.cxx` ; mempoolt[2] and mfiximpl are a thread-safety template function and underlying memory manager respectively.

### NOTE

The files with a 2 suffix are used by default and provide precise µ ITRON semantics.

`include/memvar.hxx` ,

`include/mempoolt.hxx` ,

`include/mempolt2.hxx` ,

`include/mempoolt.inl` ,

`include/mempolt2.inl` ,

`include/mvarimpl.hxx` ,

`include/mvarimpl.inl`

Variable-block allocation memory pools. See source file `mem/memvar.cxx` ; mempoolt[2] and mvar are a thread-safety template function and underlying memory manager respectively.

### NOTE

The files with a 2 suffix are used by default and provide precise µ ITRON semantics.

`include/mlqueue.hxx`

Multi-level queue scheduler. See source file `sched/mlqueue.cxx`

`include/mutex.hxx`

Mutexes. See source file `sync/mutex.cxx`

`include/sched.hxx` ,

`include/sched.inl`

General scheduler functions. See source file `sched/sched.cxx`

`include/sema.hxx` ,

`include/sema2.hxx`

Semaphores. See source files `sync/cnt_sem.cxx` and `sync/bin_sem.cxx` for counting or binary semaphores respectively.

### NOTE

The file with a 2 suffix is used by default and provides precise µ ITRON semantics.

`include/thread.hxx` ,

`include/thread.inl`

Threads, regardless of scheduler. See `common/thread.cxx`

### Kernel source files

The kernel source directory (`Cygnus/eCos/packages/kernel/` v1_3_x `/src` ) is divided into a number of sub-directories each containing the source files for a particular kernel subsystem. These sources divide into two classes: those that are generic to all configurations, and those that are specific to a particular configuration.

### Sched subdirectory

`sched/sched.cxx`

This contains the implementation of the base scheduler classes. The most important function here is `Cyg_Scheduler::unlock_inner()` which runs DSRs and performs any rescheduling and thread switching.

`sched/bitmap.cxx`

This contains the bitmap scheduler implementation. It represents each runnable thread with a bit in a bitmap. Each thread must have a unique priority and there is a strict upper limit on the number of threads allowed.

`sched/mlqueue.cxx`

This contains the multi-level queue scheduler implementation. It implements a number of thread priorities and is capable of timeslicing between threads at the same priority. This scheduler can also support priority inheritance.

`sched/lottery.cxx`

This contains the lottery scheduler implementation. This implements a CPU share scheduler based on threads holding a number of lottery tickets. At the start of each time quantum, a random number is generated and the thread holding the matching ticket is scheduled. Compensation tickets and ticket donation allow fair sharing for I/O bound threads and an equivalent mechanism to priority inheritance.

### NOTE

This scheduler is experimental, and is meant to test the behavior of other parts of the kernel with a non-orthodox scheduler. It is not meant to be used for real applications. It is currently under development and is incomplete.

### Common subdirectory

`common/thread.cxx`

This implements the basic thread classes. The functions in this file implement the basic thread controls to sleep and wake threads, change priorities and delay and time-out. Also defined here is the idle thread that runs when there is nothing else to do.

`common/clock.cxx`

This implements the counter, clock and alarm functions. Also defined here is the system real-time clock that is used to drive timeslicing, delays and time-outs.

`common/kapi.cxx`

This implements a C API to the basic kernel functions.

`common/memcpy.c` ,

`common/memset.c`

Standard ANSI memcpy and memset operations; these are here because the compiler may invoke them for structure operations regardless of the presence of a C library.

### Interrupt subdirectory

`intr/intr.cxx`

This implements the Interrupt class. Most of this code is concerned with posting and calling DSRs. The remainder of the interrupt handling code is machine specific and is in `hal_intr.cxx` in the HAL directory.

### Synchronization subdirectory

`sync/mutex.cxx`

This contains the implementation of mutexes and condition variables. Mutexes can optionally be configured to use a priority inheritance mechanism supplied by the scheduler.

`sync/cnt_sem.cxx`

This contains the implementation of counting semaphores.

`sync/cnt_sem2.cxx`

This contains the alternate implementation of counting semaphores which implements precise µ ITRON semantics.

`sync/bin_sem.cxx`

This contains the implementation of binary semaphores.

`sync/mbox.cxx`

This contains wrapper functions for a message box of (void *) values. The implementation is the template defined in `include/mboxt.hxx` which `include/mboxt.inl` implements in turn. Message boxes exist in the kernel specifically to support µ ITRON compatibility.

`sync/flag.cxx`

This contains the implementation of flag objects. Flag objects exist in the kernel specifically to support µ ITRON compatibility.

### Memory management subdirectory

`mem/memfixed.cxx`

This contains the wrapper functions for a fixed-block allocation memory manager. The actual implementation is in two parts: `include/mfiximpl.hxx` implements the fixed-block memory management algorithms, and template `include/mempoolt.hxx` implements thread safety and waiting for memory management classes. These are combined in `memfixed.cxx` . Memory pools exist in the kernel specifically to support µ ITRON compatibility.

`mem/memvar.cxx`

This contains the wrapper functions for a variable-block allocation memory manager. The actual implementation is in two parts: `include/mvarimpl.hxx` implements the variable-block memory management algorithms, and template `include/mempoolt.hxx` implements thread safety and waiting for memory management classes. These are combined in `memvar.cxx` . Memory pools exist in the kernel specifically to support µ ITRON compatibility.

### Instrumentation subdirectory

`instrmnt/meminst.cxx`

This contains an implementation of the instrumentation mechanism that stores instrumentation records in a circular buffer in memory. The size of this buffer is configurable. The instrumentation flags mechanism allows the generation of instrumentation records to be controlled on a per-record basis. The header file `cyg/kernel/instrmnt.h` contains macros to generate instrumentation records in various places, and may be configured to only generate instrumentation records where required.

`instrmnt/nullinst.cxx`

This contains an implementation of the instrumentation mechanism that does nothing. By substituting its object file `nullinst.o` for `meminst.o` in a build, the instrumentation mechanism may be disabled without recompiling.

### Trace subdirectory

`trace/simple.cxx`

This contains an implementation of the trace and assert mechanisms that output textual messages via a set of externally defined functions. These are currently supplied by the code in `trace/diag.c` but may be supplied by a device driver in the future.

`trace/fancy.cxx`

This contains a (fancier) implementation of the trace and assert mechanisms that output textual messages via a set of externally defined functions. These are currently supplied by the code in `trace/diag.c` but may be supplied by a device driver in the future.

This more elaborate view was introduced mainly to validate the trace and assertion macros during development.

`trace/null.cxx`

This contains an implementation of the trace and assert mechanisms that do nothing. By substituting its object file `null.o` for `simple.o` in a build, the trace mechanisms may be disabled without recompiling.

`trace/diag.c`

This contains a number of diagnostic routines that use the HAL supplied diagnostic output mechanism to format and print strings and numbers. There is currently no formatted output.

`trace/tcdiag.c`

This contains an implementation of the testing internal API which uses the kernel's diagnostic routines to perform output.

### Sload subdirectory

This contains the sources of a simple S-Record loader that may be used in a ROM for various microprocessor development boards to download code via a serial port.

### HAL source files

The HAL is divided into architecture- and platform-specific files. For each architecture supported, there is an `arch` directory, containing files generic to that architecture, and a `platform` directory, containing files specific to each platform supported.

Amongst the architectures supported are: the PowerPC, the Tx39 and the MN10300. To find the code corresponding to each architecture, substitute "powerpc", "mips" and "mn10300", respectively, for "ARCH" in the following file descriptions. Similarly substitute the appropriate platform name representing your development board for "PLATFORM".

### Architecture files

`ARCH/arch/` v1_3_x `/include/basetype.h`

This file is used to define the base architecture configuration such as endianness and word size.

`ARCH/arch/` v1_3_x `/include/hal_arch.h`

This file contains macros that implement various architecture-specific functions. The most important macros here are the thread context initialization and switch macros that are used to implement multithreading.

`ARCH/arch/` v1_3_x `/include/hal_intr.h`

This file contains the HAL support for interrupt management and clock support.

`ARCH/arch/` v1_3_x `/include/hal_io.h`

This file contains the HAL support for accessing hardware registers. It provides a portable API that allows more generic device drivers to be written.

`ARCH/arch/` v1_3_x `/include/hal_cache.h`

This file contains macros to control any caches that may be present.

`ARCH/arch/` v1_3_x `/include/ARCH_stub.h`

This file contains architectural information for a GDB stub, such as the register layout in a GDB packet.

`ARCH/arch/` v1_3_x `/src/vectors.S`

This is an assembly code file that contains the code to handle interrupt and exception vectors. Since system reset can also be considered an exception, this is handled here also. Interrupts are currently handled by placing a stub routine in the hardware vector which calls a Vector Service Routine via an indirection table. There is a API to allow user-defined VSRs to be installed. The default VSR reads the interrupt controller registers and decodes the interrupt source into an offset into a further table of interrupt service routines. It also handles interrupt cleanup, which may result in the execution of deferred service routines (DSRs) and the preemption of the current thread.

`ARCH/arch/` v1_3_x `/src/context.S`

If present, this is an assembly code file that contains the code to support thread contexts. The routines to switch between various contexts, as well as initialize a thread context may be present in this file.

`ARCH/arch/` v1_3_x `/src/hal_misc.c`

This file contains the implementation of various miscellaneous HAL routines that are needed by the kernel or C++ runtime.

`ARCH/arch/` v1_3_x `/src/ARCH_stub.c`

This file contains the architectural part of a GDB stub. This deals with CPU-specific details of the stub, such as the setting of breakpoints and translating exception data into signals that GDB understands.

`ARCH/arch/` v1_3_x `/src/ARCH.ld`

This file is the linker script. During preprocessing it includes linker script fragments that define the memory layout.

### P latform files

`ARCH/PLATFORM/` v1_3_x `/include/hal_diag.h`

This file contains the definitions of macros that support the HAL diagnostic output mechanism.

`ARCH/PLATFORM/` v1_3_x `/include/plf_stub.h`

This file contains a set of macros that allow the common GDB stub code to access the platform-specific minimal serial driver functions.

`ARCH/PLATFORM/` v1_3_x `/src/hal_diag.c`

This file contain the implementation of the HAL diagnostic output mechanism.

`ARCH/PLATFORM/` v1_3_x `/src/plf_stub.c`

This file contains a minimal serial driver for the target platform that is used by the GDB stub.

`ARCH/PLATFORM/` v1_3_x `/src/PLATFORM.S`

This is an assembler file that contains any platform-specific code. It often contains platform initialization code called from vectors.S.

A tour of the kernel sources
To Contents | To previous page | To next page