source: rtems-docs/c-user/board_support_packages.rst @ 12dccfe

5
Last change on this file since 12dccfe was 12dccfe, checked in by Sebastian Huber <sebastian.huber@…>, on 01/09/19 at 15:14:05

Remove superfluous "All rights reserved."

  • Property mode set to 100644
File size: 12.5 KB
Line 
1.. comment SPDX-License-Identifier: CC-BY-SA-4.0
2
3.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
4
5.. index:: Board Support Packages
6.. index:: BSPs
7.. index:: BSP, definition
8
9Board Support Packages
10**********************
11
12Introduction
13============
14
15A board support package (BSP) is a collection of user-provided facilities which
16interface RTEMS and an application with a specific hardware platform.  These
17facilities may include hardware initialization, device drivers, user
18extensions, and a Multiprocessor Communications Interface (MPCI).  However, a
19minimal BSP need only support processor reset and initialization and, if
20needed, a clock tick.
21
22Reset and Initialization
23========================
24
25An RTEMS based application is initiated or re-initiated when the processor is
26reset.  This initialization code is responsible for preparing the target
27platform for the RTEMS application.  Although the exact actions performed by
28the initialization code are highly processor and target dependent, the logical
29functionality of these actions are similar across a variety of processors and
30target platforms.
31
32Normally, the BSP and some of the application initialization is intertwined in
33the RTEMS initialization sequence controlled by the shared function
34``boot_card()``.
35
36The reset application initialization code is executed first when the processor
37is reset.  All of the hardware must be initialized to a quiescent state by this
38software before initializing RTEMS.  When in quiescent state, devices do not
39generate any interrupts or require any servicing by the application.  Some of
40the hardware components may be initialized in this code as well as any
41application initialization that does not involve calls to RTEMS directives.
42
43The processor's Interrupt Vector Table which will be used by the application
44may need to be set to the required value by the reset application
45initialization code.  Because interrupts are enabled automatically by RTEMS as
46part of the context switch to the first task, the Interrupt Vector Table MUST
47be set before this directive is invoked to ensure correct interrupt vectoring.
48The processor's Interrupt Vector Table must be accessible by RTEMS as it will
49be modified by the when installing user Interrupt Service Routines (ISRs) On
50some CPUs, RTEMS installs it's own Interrupt Vector Table as part of
51initialization and thus these requirements are met automatically.  The reset
52code which is executed before the call to any RTEMS initialization routines has
53the following requirements:
54
55- Must not make any blocking RTEMS directive calls.
56
57- If the processor supports multiple privilege levels, must leave the processor
58  in the most privileged, or supervisory, state.
59
60- Must allocate a stack of sufficient size to execute the initialization and
61  shutdown of the system.  This stack area will NOT be used by any task once
62  the system is initialized.  This stack is often reserved via the linker
63  script or in the assembly language start up file.
64
65- Must initialize the stack pointer for the initialization process to that
66  allocated.
67
68- Must initialize the processor's Interrupt Vector Table.
69
70- Must disable all maskable interrupts.
71
72- If the processor supports a separate interrupt stack, must allocate the
73  interrupt stack and initialize the interrupt stack pointer.
74
75At the end of the initialization sequence, RTEMS does not return to the BSP
76initialization code, but instead context switches to the highest priority task
77to begin application execution.  This task is typically a User Initialization
78Task which is responsible for performing both local and global application
79initialization which is dependent on RTEMS facilities.  It is also responsible
80for initializing any higher level RTEMS services the application uses such as
81networking and blocking device drivers.
82
83Interrupt Stack Requirements
84----------------------------
85
86The worst-case stack usage by interrupt service routines must be taken into
87account when designing an application.  If the processor supports interrupt
88nesting, the stack usage must include the deepest nest level.  The worst-case
89stack usage must account for the following requirements:
90
91- Processor's interrupt stack frame
92
93- Processor's subroutine call stack frame
94
95- RTEMS system calls
96
97- Registers saved on stack
98
99- Application subroutine calls
100
101The size of the interrupt stack must be greater than or equal to the confugured
102minimum stack size.
103
104Processors with a Separate Interrupt Stack
105------------------------------------------
106
107Some processors support a separate stack for interrupts.  When an interrupt is
108vectored and the interrupt is not nested, the processor will automatically
109switch from the current stack to the interrupt stack.  The size of this stack
110is based solely on the worst-case stack usage by interrupt service routines.
111
112The dedicated interrupt stack for the entire application on some architectures
113is supplied and initialized by the reset and initialization code of the user's
114Board Support Package.  Whether allocated and initialized by the BSP or RTEMS,
115since all ISRs use this stack, the stack size must take into account the worst
116case stack usage by any combination of nested ISRs.
117
118Processors Without a Separate Interrupt Stack
119---------------------------------------------
120
121Some processors do not support a separate stack for interrupts.  In this case,
122without special assistance every task's stack must include enough space to
123handle the task's worst-case stack usage as well as the worst-case interrupt
124stack usage.  This is necessary because the worst-case interrupt nesting could
125occur while any task is executing.
126
127On many processors without dedicated hardware managed interrupt stacks, RTEMS
128manages a dedicated interrupt stack in software.  If this capability is
129supported on a CPU, then it is logically equivalent to the processor supporting
130a separate interrupt stack in hardware.
131
132Device Drivers
133==============
134
135Device drivers consist of control software for special peripheral devices and
136provide a logical interface for the application developer.  The RTEMS I/O
137manager provides directives which allow applications to access these device
138drivers in a consistent fashion.  A Board Support Package may include device
139drivers to access the hardware on the target platform.  These devices typically
140include serial and parallel ports, counter/timer peripherals, real-time clocks,
141disk interfaces, and network controllers.
142
143For more information on device drivers, refer to the
144I/O Manager chapter.
145
146Clock Tick Device Driver
147------------------------
148
149Most RTEMS applications will include a clock tick device driver which invokes
150a clock tick directive at regular intervals.  The clock tick is
151necessary if the application is to utilize timeslicing, the clock manager, the
152timer manager, the rate monotonic manager, or the timeout option on blocking
153directives.
154
155The clock tick is usually provided as an interrupt from a counter/timer or a
156real-time clock device.  When a counter/timer is used to provide the clock
157tick, the device is typically programmed to operate in continuous mode.  This
158mode selection causes the device to automatically reload the initial count and
159continue the countdown without programmer intervention.  This reduces the
160overhead required to manipulate the counter/timer in the clock tick ISR and
161increases the accuracy of tick occurrences.  The initial count can be based on
162the microseconds_per_tick field in the RTEMS Configuration Table.  An alternate
163approach is to set the initial count for a fixed time period (such as one
164millisecond) and have the ISR invoke a clock tick directive on the configured
165``microseconds_per_tick`` boundaries.  Obviously, this can induce some error if
166the configured ``microseconds_per_tick`` is not evenly divisible by the chosen
167clock interrupt quantum.
168
169It is important to note that the interval between clock ticks directly impacts
170the granularity of RTEMS timing operations.  In addition, the frequency of
171clock ticks is an important factor in the overall level of system overhead.  A
172high clock tick frequency results in less processor time being available for
173task execution due to the increased number of clock tick ISRs.
174
175User Extensions
176===============
177
178RTEMS allows the application developer to augment selected features by invoking
179user-supplied extension routines when the following system events occur:
180
181- Task creation
182
183- Task initiation
184
185- Task reinitiation
186
187- Task deletion
188
189- Task context switch
190
191- Post task context switch
192
193- Task begin
194
195- Task exits
196
197- Fatal error detection
198
199User extensions can be used to implement a wide variety of functions including
200execution profiling, non-standard coprocessor support, debug support, and error
201detection and recovery.  For example, the context of a non-standard numeric
202coprocessor may be maintained via the user extensions.  In this example, the
203task creation and deletion extensions are responsible for allocating and
204deallocating the context area, the task initiation and reinitiation extensions
205would be responsible for priming the context area, and the task context switch
206extension would save and restore the context of the device.
207
208For more information on user extensions, refer to :ref:`User Extensions Manager`.
209
210Multiprocessor Communications Interface (MPCI)
211==============================================
212
213RTEMS requires that an MPCI layer be provided when a multiple node application
214is developed.  This MPCI layer must provide an efficient and reliable
215communications mechanism between the multiple nodes.  Tasks on different nodes
216communicate and synchronize with one another via the MPCI.  Each MPCI layer
217must be tailored to support the architecture of the target platform.
218
219For more information on the MPCI, refer to the Multiprocessing Manager chapter.
220
221Tightly-Coupled Systems
222-----------------------
223
224A tightly-coupled system is a multiprocessor configuration in which the
225processors communicate solely via shared global memory.  The MPCI can simply
226place the RTEMS packets in the shared memory space.  The two primary
227considerations when designing an MPCI for a tightly-coupled system are data
228consistency and informing another node of a packet.
229
230The data consistency problem may be solved using atomic "test and set"
231operations to provide a "lock" in the shared memory.  It is important to
232minimize the length of time any particular processor locks a shared data
233structure.
234
235The problem of informing another node of a packet can be addressed using one of
236two techniques.  The first technique is to use an interprocessor interrupt
237capability to cause an interrupt on the receiving node.  This technique
238requires that special support hardware be provided by either the processor
239itself or the target platform.  The second technique is to have a node poll for
240arrival of packets.  The drawback to this technique is the overhead associated
241with polling.
242
243Loosely-Coupled Systems
244-----------------------
245
246A loosely-coupled system is a multiprocessor configuration in which the
247processors communicate via some type of communications link which is not shared
248global memory.  The MPCI sends the RTEMS packets across the communications link
249to the destination node.  The characteristics of the communications link vary
250widely and have a significant impact on the MPCI layer.  For example, the
251bandwidth of the communications link has an obvious impact on the maximum MPCI
252throughput.
253
254The characteristics of a shared network, such as Ethernet, lend themselves to
255supporting an MPCI layer.  These networks provide both the point-to-point and
256broadcast capabilities which are expected by RTEMS.
257
258Systems with Mixed Coupling
259---------------------------
260
261A mixed-coupling system is a multiprocessor configuration in which the
262processors communicate via both shared memory and communications links.  A
263unique characteristic of mixed-coupling systems is that a node may not have
264access to all communication methods.  There may be multiple shared memory areas
265and communication links.  Therefore, one of the primary functions of the MPCI
266layer is to efficiently route RTEMS packets between nodes.  This routing may be
267based on numerous algorithms. In addition, the router may provide alternate
268communications paths in the event of an overload or a partial failure.
269
270Heterogeneous Systems
271---------------------
272
273Designing an MPCI layer for a heterogeneous system requires special
274considerations by the developer.  RTEMS is designed to eliminate many of the
275problems associated with sharing data in a heterogeneous environment.  The MPCI
276layer need only address the representation of thirty-two (32) bit unsigned
277quantities.
278
279For more information on supporting a heterogeneous system, refer the Supporting
280Heterogeneous Environments in the Multiprocessing Manager chapter.
Note: See TracBrowser for help on using the repository browser.