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