source: rtems-docs/cpu-supplement/port.rst @ f067ba3

5am
Last change on this file since f067ba3 was efd581f, checked in by Sebastian Huber <sebastian.huber@…>, on Jul 18, 2018 at 6:14:09 AM

cpu-supplement: Update interrupt stack paragraph

Close #3459.

  • Property mode set to 100644
File size: 19.6 KB
RevLine 
[489740f]1.. comment SPDX-License-Identifier: CC-BY-SA-4.0
2
[f233256]3.. COMMENT: COPYRIGHT (c) 1988-2002.
4.. COMMENT: On-Line Applications Research Corporation (OAR).
5.. COMMENT: All rights reserved.
6
[d755cbd]7Port Specific Information
[6916004]8*************************
[d755cbd]9
[f233256]10This chaper provides a general description of the type of architecture specific
11information which is in each of the architecture specific chapters that follow.
12The outline of this chapter is identical to that of the architecture specific
13chapters.
[d755cbd]14
[f233256]15In each of the architecture specific chapters, this introductory section will
16provide an overview of the architecture:
[d755cbd]17
18**Architecture Documents**
19
[f233256]20In each of the architecture specific chapters, this section will provide
21pointers on where to obtain documentation.
[d755cbd]22
23CPU Model Dependent Features
24============================
25
[f233256]26Microprocessors are generally classified into families with a variety of CPU
27models or implementations within that family.  Within a processor family, there
28is a high level of binary compatibility.  This family may be based on either an
29architectural specification or on maintaining compatibility with a popular
30processor.  Recent microprocessor families such as the SPARC or PowerPC are
31based on an architectural specification which is independent or any particular
32CPU model or implementation.  Older families such as the Motorola 68000 and the
33Intel x86 evolved as the manufacturer strived to produce higher performance
34processor models which maintained binary compatibility with older models.
35
36RTEMS takes advantage of the similarity of the various models within a CPU
37family.  Although the models do vary in significant ways, the high level of
38compatibility makes it possible to share the bulk of the CPU dependent
39executive code across the entire family.  Each processor family supported by
40RTEMS has a list of features which vary between CPU models within a family.
41For example, the most common model dependent feature regardless of CPU family
42is the presence or absence of a floating point unit or coprocessor.  When
43defining the list of features present on a particular CPU model, one simply
44notes that floating point hardware is or is not present and defines a single
45constant appropriately.  Conditional compilation is utilized to include the
46appropriate source code for this CPU model's feature set.  It is important to
47note that this means that RTEMS is thus compiled using the appropriate feature
48set and compilation flags optimal for this CPU model used.  The alternative
49would be to generate a binary which would execute on all family members using
50only the features which were always present.
51
52The set of CPU model feature macros are defined in the
53:file:`cpukit/score/cpu/CPU/rtems/score/cpu.h` based upon the GNU tools
54multilib variant that is appropriate for the particular CPU model defined on
55the compilation command line.
56
57In each of the architecture specific chapters, this section presents the set of
58features which vary across various implementations of the architecture that may
59be of importance to RTEMS application developers.
60
61The subsections will vary amongst the target architecture chapters as the
62specific features may vary.  However, each port will include a few common
63features such as the CPU Model Name and presence of a hardware Floating Point
64Unit.  The common features are described here.
[d755cbd]65
66CPU Model Name
67--------------
68
[f233256]69The macro ``CPU_MODEL_NAME`` is a string which designates the name of this CPU
70model.  For example, for the MC68020 processor model from the m68k
71architecture, this macro is set to the string "mc68020".
[d755cbd]72
73Floating Point Unit
74-------------------
75
[f233256]76In most architectures, the presence of a floating point unit is an option.  It
77does not matter whether the hardware floating point support is incorporated
78on-chip or is an external coprocessor as long as it appears an FPU per the ISA.
79However, if a hardware FPU is not present, it is possible that the floating
80point emulation library for this CPU is not reentrant and thus context switched
81by RTEMS.
[d755cbd]82
83RTEMS provides two feature macros to indicate the FPU configuration:
84
85- CPU_HARDWARE_FP
86  is set to TRUE to indicate that a hardware FPU is present.
87
88- CPU_SOFTWARE_FP
[f233256]89  is set to TRUE to indicate that a hardware FPU is not present and that the FP
90  software emulation will be context switched.
[d755cbd]91
92Multilibs
93=========
94
[f233256]95Newlib and GCC provide several target libraries like the :file:`libc.a`,
96:file:`libm.a` and :file:`libgcc.a`.  These libraries are artifacts of the GCC
[d755cbd]97build process.  Newlib is built together with GCC.  To provide optimal support
98for various chip derivatives and instruction set revisions multiple variants of
99these libraries are available for each architecture.  For example one set may
100use software floating point support and another set may use hardware floating
101point instructions.  These sets of libraries are called *multilibs*.  Each
102library set corresponds to an application binary interface (ABI) and
103instruction set.
104
105A multilib variant can be usually detected via built-in compiler defines at
106compile-time.  This mechanism is used by RTEMS to select for example the
107context switch support for a particular BSP.  The built-in compiler defines
108corresponding to multilibs are the only architecture specific defines allowed
109in the ``cpukit`` area of the RTEMS sources.
110
111Invoking the GCC with the ``-print-multi-lib`` option lists the available
112multilibs.  Each line of the output describes one multilib variant.  The
[f233256]113default variant is denoted by ``.`` which is selected when no or contradicting
114GCC machine options are selected.  The multilib selection for a target is
115specified by target makefile fragments (see file :file:`t-rtems` in the GCC
116sources and section *The Target Makefile Fragment*
117(https://gcc.gnu.org/onlinedocs/gccint/Target-Fragment.html#Target-Fragment)
118in the *GCC Internals Manual* (https://gcc.gnu.org/onlinedocs/gccint/).
[d755cbd]119
120Calling Conventions
121===================
122
[f233256]123Each high-level language compiler generates subroutine entry and exit code
124based upon a set of rules known as the compiler's calling convention.  These
125rules address the following issues:
[d755cbd]126
127- register preservation and usage
128
129- parameter passing
130
131- call and return mechanism
132
[f233256]133A compiler's calling convention is of importance when interfacing to
134subroutines written in another language either assembly or high-level.  Even
135when the high-level language and target processor are the same, different
136compilers may use different calling conventions.  As a result, calling
137conventions are both processor and compiler dependent.
[d755cbd]138
139Calling Mechanism
140-----------------
141
[f233256]142In each of the architecture specific chapters, this subsection will describe
143the instruction(s) used to perform a *normal* subroutine invocation.  All RTEMS
144directives are invoked as *normal* C language functions so it is important to
145the user application to understand the call and return mechanism.
[d755cbd]146
147Register Usage
148--------------
149
[f233256]150In each of the architecture specific chapters, this subsection will detail the
151set of registers which are *NOT* preserved across subroutine invocations.  The
152registers which are not preserved are assumed to be available for use as
153scratch registers.  Therefore, the contents of these registers should not be
154assumed upon return from any RTEMS directive.
[d755cbd]155
156In some architectures, there may be a set of registers made available
[f233256]157automatically as a side-effect of the subroutine invocation mechanism.
[d755cbd]158
159Parameter Passing
160-----------------
161
[f233256]162In each of the architecture specific chapters, this subsection will describe
163the mechanism by which the parameters or arguments are passed by the caller to
164a subroutine.  In some architectures, all parameters are passed on the stack
165while in others some are passed in registers.
[d755cbd]166
167User-Provided Routines
168----------------------
169
[f233256]170All user-provided routines invoked by RTEMS, such as user extensions, device
171drivers, and MPCI routines, must also adhere to these calling conventions.
[d755cbd]172
173Memory Model
174============
175
[f233256]176A processor may support any combination of memory models ranging from pure
177physical addressing to complex demand paged virtual memory systems.  RTEMS
178supports a flat memory model which ranges contiguously over the processor's
179allowable address space.  RTEMS does not support segmentation or virtual memory
180of any kind.  The appropriate memory model for RTEMS provided by the targeted
181processor and related characteristics of that model are described in this
182chapter.
[d755cbd]183
184Flat Memory Model
185-----------------
186
187Most RTEMS target processors can be initialized to support a flat address
[f233256]188space.  Although the size of addresses varies between architectures, on most
189RTEMS targets, an address is 32-bits wide which defines addresses ranging from
1900x00000000 to 0xFFFFFFFF (4 gigabytes).  Each address is represented by a
19132-bit value and is byte addressable.  The address may be used to reference a
192single byte, word (2-bytes), or long word (4 bytes).  Memory accesses within
193this address space may be performed in little or big endian fashion.
194
195On smaller CPU architectures supported by RTEMS, the address space may only be
19620 or 24 bits wide.
197
198If the CPU model has support for virtual memory or segmentation, it is the
199responsibility of the Board Support Package (BSP) to initialize the MMU
200hardware to perform address translations which correspond to flat memory model.
201
202In each of the architecture specific chapters, this subsection will describe
203any architecture characteristics that differ from this general description.
[d755cbd]204
205Interrupt Processing
206====================
207
[f233256]208Different types of processors respond to the occurrence of an interrupt in its
209own unique fashion. In addition, each processor type provides a control
210mechanism to allow for the proper handling of an interrupt.  The processor
211dependent response to the interrupt modifies the current execution state and
212results in a change in the execution stream.  Most processors require that an
213interrupt handler utilize some special control mechanisms to return to the
214normal processing stream.  Although RTEMS hides many of the processor dependent
215details of interrupt processing, it is important to understand how the RTEMS
216interrupt manager is mapped onto the processor's unique architecture.
217
218RTEMS supports a dedicated interrupt stack for all architectures.  On
219architectures with hardware support for a dedicated interrupt stack, it will be
220initialized such that when an interrupt occurs, the processor automatically
221switches to this dedicated stack.  On architectures without hardware support
222for a dedicated interrupt stack which is separate from those of the tasks,
223RTEMS will support switching to a dedicated stack for interrupt processing.
224
[efd581f]225Without a dedicated interrupt stack, every task in the system must have enough
[f233256]226stack space to accommodate the worst case stack usage of that particular task
[efd581f]227and the interrupt service routines combined.  By supporting a dedicated
[f233256]228interrupt stack, RTEMS significantly lowers the stack requirements for each
229task.
230
231A nested interrupt is processed similarly with the exception that since the CPU
232is already executing on the interrupt stack, there is no need to switch to the
233interrupt stack.
234
[efd581f]235The interrupt stacks (one for each configured processor) are statically
236allocated by the application configuration via ``<rtems/confdefs.h>`` in the
237special section ``.rtemsstack``.  This enables an optimal placement of the
238interrupt stacks by the Board Support Package (BSP), e.g. a fast on-chip
239memory.  The amount of memory allocated for each interrupt stack is user
240configured and based upon the ``<rtems/confdefs.h>`` parameter
[f233256]241``CONFIGURE_INTERRUPT_STACK_SIZE``.  This parameter is described in detail in
[efd581f]242the Configuring a System chapter of the User's Guide.  Since interrupts are
243disabled during the sequential system initialization and the
244``_Thread_Start_multitasking()`` function does not return to the caller each
245interrupt stack may be used for the initialization stack on the corresponding
246processor.
[f233256]247
[efd581f]248In each of the architecture specific chapters, this section discusses the
[f233256]249interrupt response and control mechanisms of the architecture as they pertain
250to RTEMS.
[d755cbd]251
252Vectoring of an Interrupt Handler
253---------------------------------
254
[f233256]255In each of the architecture specific chapters, this subsection will describe
256the architecture specific details of the interrupt vectoring process.  In
257particular, it should include a description of the Interrupt Stack Frame (ISF).
[d755cbd]258
259Interrupt Levels
260----------------
261
[f233256]262In each of the architecture specific chapters, this subsection will describe
263how the interrupt levels available on this particular architecture are mapped
264onto the 255 reserved in the task mode.  The interrupt level value of zero (0)
265should always mean that interrupts are enabled.
[d755cbd]266
[f233256]267Any use of an interrupt level that is is not undefined on a particular
[d755cbd]268architecture may result in behavior that is unpredictable.
269
270Disabling of Interrupts by RTEMS
271--------------------------------
272
[f233256]273During the execution of directive calls, critical sections of code may be
274executed.  When these sections are encountered, RTEMS disables all external
275interrupts before the execution of this section and restores them to the
276previous level upon completion of the section.  RTEMS has been optimized to
277ensure that interrupts are disabled for the shortest number of instructions
278possible.  Since the precise number of instructions and their execution time
279varies based upon target CPU family, CPU model, board memory speed, compiler
280version, and optimization level, it is not practical to provide the precise
281number for all possible RTEMS configurations.
282
283Historically, the measurements were made by hand analyzing and counting the
284execution time of instruction sequences during interrupt disable critical
285sections.  For reference purposes, on a 16 Mhz Motorola MC68020, the maximum
286interrupt disable period was typically approximately ten (10) to thirteen (13)
287microseconds.  This architecture was memory bound and had a slow bit scan
288instruction.  In contrast, during the same period a 14 Mhz SPARC would have a
289worst case disable time of approximately two (2) to three (3) microseconds
290because it had a single cycle bit scan instruction and used fewer cycles for
291memory accesses.
292
293If you are interested in knowing the worst case execution time for a particular
294version of RTEMS, please contact OAR Corporation and we will be happy to
295product the results as a consulting service.
296
297Non-maskable interrupts (NMI) cannot be disabled, and ISRs which execute at
298this level MUST NEVER issue RTEMS system calls.  If a directive is invoked,
299unpredictable results may occur due to the inability of RTEMS to protect its
300critical sections.  However, ISRs that make no system calls may safely execute
301as non-maskable interrupts.
[d755cbd]302
303Default Fatal Error Processing
304==============================
305
306Upon detection of a fatal error by either the application or RTEMS during
[f233256]307initialization the ``rtems_fatal_error_occurred`` directive supplied by the
308Fatal Error Manager is invoked.  The Fatal Error Manager will invoke the
309user-supplied fatal error handlers.  If no user-supplied handlers are
310configured or all of them return without taking action to shutdown the
311processor or reset, a default fatal error handler is invoked.
[d755cbd]312
313Most of the action performed as part of processing the fatal error are
[f233256]314described in detail in the Fatal Error Manager chapter in the User's Guide.
315However, the if no user provided extension or BSP specific fatal error handler
316takes action, the final default action is to invoke a CPU architecture specific
317function.  Typically this function disables interrupts and halts the processor.
[d755cbd]318
319In each of the architecture specific chapters, this describes the precise
320operations of the default CPU specific fatal error handler.
321
322Symmetric Multiprocessing
323=========================
324
325This section contains information about the Symmetric Multiprocessing (SMP)
326status of a particular architecture.
327
328Thread-Local Storage
329====================
330
331In order to support thread-local storage (TLS) the CPU port must implement the
332facilities mandated by the application binary interface (ABI) of the CPU
[f233256]333architecture.  The CPU port must initialize the TLS area in the
334``_CPU_Context_Initialize()`` function.  There are support functions available
[d755cbd]335via ``#include <rtems/score/tls.h>`` which implement Variants I and II
[97e1553]336according to :cite:`Drepper:2013:TLS`.
[d755cbd]337
338``_TLS_TCB_at_area_begin_initialize()``
[f233256]339    Uses Variant I, TLS offsets emitted by linker takes the TCB into account.
340    For a reference implementation see :file:`cpukit/score/cpu/arm/cpu.c`.
[d755cbd]341
342``_TLS_TCB_before_TLS_block_initialize()``
343    Uses Variant I, TLS offsets emitted by linker neglects the TCB.  For a
[f233256]344    reference implementation see
345    :file:`c/src/lib/libcpu/powerpc/new-exceptions/cpu.c`.
[d755cbd]346
347``_TLS_TCB_after_TLS_block_initialize()``
[f233256]348    Uses Variant II.  For a reference implementation see
349    :file:`cpukit/score/cpu/sparc/cpu.c`.
[d755cbd]350
351The board support package (BSP) must provide the following sections and symbols
352in its linker command file:
[f233256]353
354.. code-block:: c
[d755cbd]355
356    .tdata : {
[f233256]357      _TLS_Data_begin = .;
358      *(.tdata .tdata.* .gnu.linkonce.td.*)
359      _TLS_Data_end = .;
[d755cbd]360    }
361    .tbss : {
[f233256]362      _TLS_BSS_begin = .;
363      *(.tbss .tbss.* .gnu.linkonce.tb.*) *(.tcommon)
364      _TLS_BSS_end = .;
[d755cbd]365    }
366    _TLS_Data_size = _TLS_Data_end - _TLS_Data_begin;
367    _TLS_Data_begin = _TLS_Data_size != 0 ? _TLS_Data_begin : _TLS_BSS_begin;
368    _TLS_Data_end = _TLS_Data_size != 0 ? _TLS_Data_end : _TLS_BSS_begin;
369    _TLS_BSS_size = _TLS_BSS_end - _TLS_BSS_begin;
370    _TLS_Size = _TLS_BSS_end - _TLS_Data_begin;
371    _TLS_Alignment = MAX (ALIGNOF (.tdata), ALIGNOF (.tbss));
372
373CPU counter
374===========
375
376The CPU support must implement the CPU counter interface.  A CPU counter is
377some free-running counter.  It ticks usually with a frequency close to the CPU
378or system bus clock.  On some architectures the actual implementation is board
379support package dependent.  The CPU counter is used for profiling of low-level
[f233256]380functions.  It is also used to implement two busy wait functions
381``rtems_counter_delay_ticks()`` and ``rtems_counter_delay_nanoseconds()`` which
382may be used in device drivers.  It may be also used as an entropy source for
383random number generators.
[d755cbd]384
[f233256]385The CPU counter interface uses a CPU port specific unsigned integer type
386``CPU_Counter_ticks`` to represent CPU counter values.  The CPU port must
[d755cbd]387provide the following two functions
388
389- ``_CPU_Counter_read()`` to read the current CPU counter value, and
390
391- ``_CPU_Counter_difference()`` to get the difference between two CPU
392  counter values.
393
394Interrupt Profiling
395===================
396
397The RTEMS profiling needs support by the CPU port for the interrupt entry and
398exit times.  In case profiling is enabled via the RTEMS build configuration
[f233256]399option ``--enable-profiling`` (in this case the pre-processor symbol
400``RTEMS_PROFILING`` is defined) the CPU port may provide data for the interrupt
401entry and exit times of the outer-most interrupt.  The CPU port can feed
402interrupt entry and exit times with the
403``_Profiling_Outer_most_interrupt_entry_and_exit()`` function (``#include
404<rtems/score/profiling.h>``).  For an example please have a look at
405:file:`cpukit/score/cpu/arm/arm_exc_interrupt.S`.
[d755cbd]406
407Board Support Packages
408======================
409
[f233256]410An RTEMS Board Support Package (BSP) must be designed to support a particular
411processor model and target board combination.
[d755cbd]412
[f233256]413In each of the architecture specific chapters, this section will present a
414discussion of architecture specific BSP issues.  For more information on
[c6f8e51]415developing a BSP, refer to *RTEMS BSP and Driver Guide* chapter titled
416``Board Support Packages`` in the *RTEMS Classic API Guide*.
[d755cbd]417
418System Reset
419------------
420
[f233256]421An RTEMS based application is initiated or re-initiated when the processor is
422reset or transfer is passed to it from a boot monitor or ROM monitor.
[d755cbd]423
[f233256]424In each of the architecture specific chapters, this subsection describes the
[c6f8e51]425actions that the BSP must take assuming the application gets control
426when the microprocessor is reset.
Note: See TracBrowser for help on using the repository browser.