2. Port Specific Information¶

2.1. CPU Model Dependent Features¶

Microprocessors are generally classified into families with a variety of CPU models or implementations within that family. Within a processor family, there is a high level of binary compatibility. This family may be based on either an architectural specification or on maintaining compatibility with a popular processor. Recent microprocessor families such as the SPARC or PowerPC are based on an architectural specification which is independent or any particular CPU model or implementation. Older families such as the Motorola 68000 and the Intel x86 evolved as the manufacturer strived to produce higher performance processor models which maintained binary compatibility with older models.

RTEMS takes advantage of the similarity of the various models within a CPU family. Although the models do vary in significant ways, the high level of compatibility makes it possible to share the bulk of the CPU dependent executive code across the entire family. Each processor family supported by RTEMS has a list of features which vary between CPU models within a family. For example, the most common model dependent feature regardless of CPU family is the presence or absence of a floating point unit or coprocessor. When defining the list of features present on a particular CPU model, one simply notes that floating point hardware is or is not present and defines a single constant appropriately. Conditional compilation is utilized to include the appropriate source code for this CPU model’s feature set. It is important to note that this means that RTEMS is thus compiled using the appropriate feature set and compilation flags optimal for this CPU model used. The alternative would be to generate a binary which would execute on all family members using only the features which were always present.

The set of CPU model feature macros are defined in the cpukit/score/cpu/CPU/rtems/score/cpu.h based upon the GNU tools multilib variant that is appropriate for the particular CPU model defined on the compilation command line.

In each of the architecture specific chapters, this section presents the set of features which vary across various implementations of the architecture that may be of importance to RTEMS application developers.

The subsections will vary amongst the target architecture chapters as the specific features may vary. However, each port will include a few common features such as the CPU Model Name and presence of a hardware Floating Point Unit. The common features are described here.

2.2. Multilibs¶

Newlib and GCC provide several target libraries like the libc.a, libm.a and libgcc.a. These libraries are artifacts of the GCC build process. Newlib is built together with GCC. To provide optimal support for various chip derivatives and instruction set revisions multiple variants of these libraries are available for each architecture. For example one set may use software floating point support and another set may use hardware floating point instructions. These sets of libraries are called multilibs. Each library set corresponds to an application binary interface (ABI) and instruction set.

A multilib variant can be usually detected via built-in compiler defines at compile-time. This mechanism is used by RTEMS to select for example the context switch support for a particular BSP. The built-in compiler defines corresponding to multilibs are the only architecture specific defines allowed in the cpukit area of the RTEMS sources.

Invoking the GCC with the -print-multi-lib option lists the available multilibs. Each line of the output describes one multilib variant. The default variant is denoted by . which is selected when no or contradicting GCC machine options are selected. The multilib selection for a target is specified by target makefile fragments (see file t-rtems in the GCC sources and section The Target Makefile Fragment (https://gcc.gnu.org/onlinedocs/gccint/Target-Fragment.html#Target-Fragment) in the GCC Internals Manual (https://gcc.gnu.org/onlinedocs/gccint/).

2.3. Calling Conventions¶

Each high-level language compiler generates subroutine entry and exit code based upon a set of rules known as the compiler’s calling convention. These rules address the following issues:

• register preservation and usage
• parameter passing
• call and return mechanism

A compiler’s calling convention is of importance when interfacing to subroutines written in another language either assembly or high-level. Even when the high-level language and target processor are the same, different compilers may use different calling conventions. As a result, calling conventions are both processor and compiler dependent.

2.4. Memory Model¶

A processor may support any combination of memory models ranging from pure physical addressing to complex demand paged virtual memory systems. RTEMS supports a flat memory model which ranges contiguously over the processor’s allowable address space. RTEMS does not support segmentation or virtual memory of any kind. The appropriate memory model for RTEMS provided by the targeted processor and related characteristics of that model are described in this chapter.

2.5. Interrupt Processing¶

Different types of processors respond to the occurrence of an interrupt in its own unique fashion. In addition, each processor type provides a control mechanism to allow for the proper handling of an interrupt. The processor dependent response to the interrupt modifies the current execution state and results in a change in the execution stream. Most processors require that an interrupt handler utilize some special control mechanisms to return to the normal processing stream. Although RTEMS hides many of the processor dependent details of interrupt processing, it is important to understand how the RTEMS interrupt manager is mapped onto the processor’s unique architecture.

RTEMS supports a dedicated interrupt stack for all architectures. On architectures with hardware support for a dedicated interrupt stack, it will be initialized such that when an interrupt occurs, the processor automatically switches to this dedicated stack. On architectures without hardware support for a dedicated interrupt stack which is separate from those of the tasks, RTEMS will support switching to a dedicated stack for interrupt processing.

Without a dedicated interrupt stack, every task in the system MUST have enough stack space to accommodate the worst case stack usage of that particular task and the interrupt service routines COMBINED. By supporting a dedicated interrupt stack, RTEMS significantly lowers the stack requirements for each task.

A nested interrupt is processed similarly with the exception that since the CPU is already executing on the interrupt stack, there is no need to switch to the interrupt stack.

In some configurations, RTEMS allocates the interrupt stack from the Workspace Area. The amount of memory allocated for the interrupt stack is user configured and based upon the confdefs.h parameter CONFIGURE_INTERRUPT_STACK_SIZE. This parameter is described in detail in the Configuring a System chapter of the User’s Guide. On configurations in which RTEMS allocates the interrupt stack, during the initialization process, RTEMS will also install its interrupt stack. In other configurations, the interrupt stack is allocated and installed by the Board Support Package (BSP).

In each of the architecture specific chapters, this section discesses the interrupt response and control mechanisms of the architecture as they pertain to RTEMS.

2.6. Default Fatal Error Processing¶

Upon detection of a fatal error by either the application or RTEMS during initialization the rtems_fatal_error_occurred directive supplied by the Fatal Error Manager is invoked. The Fatal Error Manager will invoke the user-supplied fatal error handlers. If no user-supplied handlers are configured or all of them return without taking action to shutdown the processor or reset, a default fatal error handler is invoked.

Most of the action performed as part of processing the fatal error are described in detail in the Fatal Error Manager chapter in the User’s Guide. However, the if no user provided extension or BSP specific fatal error handler takes action, the final default action is to invoke a CPU architecture specific function. Typically this function disables interrupts and halts the processor.

In each of the architecture specific chapters, this describes the precise operations of the default CPU specific fatal error handler.

2.7. Symmetric Multiprocessing¶

This section contains information about the Symmetric Multiprocessing (SMP) status of a particular architecture.

2.8. Thread-Local Storage¶

In order to support thread-local storage (TLS) the CPU port must implement the facilities mandated by the application binary interface (ABI) of the CPU architecture. The CPU port must initialize the TLS area in the _CPU_Context_Initialize() function. There are support functions available via #include <rtems/score/tls.h> which implement Variants I and II according to Ulrich Drepper, ELF Handling For Thread-Local Storage.

_TLS_TCB_at_area_begin_initialize()

Uses Variant I, TLS offsets emitted by linker takes the TCB into account. For a reference implementation see cpukit/score/cpu/arm/cpu.c.

_TLS_TCB_before_TLS_block_initialize()

Uses Variant I, TLS offsets emitted by linker neglects the TCB. For a reference implementation see c/src/lib/libcpu/powerpc/new-exceptions/cpu.c.

_TLS_TCB_after_TLS_block_initialize()

Uses Variant II. For a reference implementation see cpukit/score/cpu/sparc/cpu.c.

The board support package (BSP) must provide the following sections and symbols in its linker command file:

.tdata : {
  _TLS_Data_begin = .;
  *(.tdata .tdata.* .gnu.linkonce.td.*)
  _TLS_Data_end = .;
}
.tbss : {
  _TLS_BSS_begin = .;
  *(.tbss .tbss.* .gnu.linkonce.tb.*) *(.tcommon)
  _TLS_BSS_end = .;
}
_TLS_Data_size = _TLS_Data_end - _TLS_Data_begin;
_TLS_Data_begin = _TLS_Data_size != 0 ? _TLS_Data_begin : _TLS_BSS_begin;
_TLS_Data_end = _TLS_Data_size != 0 ? _TLS_Data_end : _TLS_BSS_begin;
_TLS_BSS_size = _TLS_BSS_end - _TLS_BSS_begin;
_TLS_Size = _TLS_BSS_end - _TLS_Data_begin;
_TLS_Alignment = MAX (ALIGNOF (.tdata), ALIGNOF (.tbss));

2.9. CPU counter¶

The CPU support must implement the CPU counter interface. A CPU counter is some free-running counter. It ticks usually with a frequency close to the CPU or system bus clock. On some architectures the actual implementation is board support package dependent. The CPU counter is used for profiling of low-level functions. It is also used to implement two busy wait functions rtems_counter_delay_ticks() and rtems_counter_delay_nanoseconds() which may be used in device drivers. It may be also used as an entropy source for random number generators.

The CPU counter interface uses a CPU port specific unsigned integer type CPU_Counter_ticks to represent CPU counter values. The CPU port must provide the following two functions

• _CPU_Counter_read() to read the current CPU counter value, and
• _CPU_Counter_difference() to get the difference between two CPU counter values.

2.10. Interrupt Profiling¶

The RTEMS profiling needs support by the CPU port for the interrupt entry and exit times. In case profiling is enabled via the RTEMS build configuration option --enable-profiling (in this case the pre-processor symbol RTEMS_PROFILING is defined) the CPU port may provide data for the interrupt entry and exit times of the outer-most interrupt. The CPU port can feed interrupt entry and exit times with the _Profiling_Outer_most_interrupt_entry_and_exit() function (#include <rtems/score/profiling.h>). For an example please have a look at cpukit/score/cpu/arm/arm_exc_interrupt.S.

2.11. Board Support Packages¶

An RTEMS Board Support Package (BSP) must be designed to support a particular processor model and target board combination.

In each of the architecture specific chapters, this section will present a discussion of architecture specific BSP issues. For more information on developing a BSP, refer to BSP and Device Driver Development Guide and the chapter titled Board Support Packages in the RTEMS Applications User’s Guide.