From 8ef6ea80ef8f8e9ac5a0dfa11687329101e7bb67 Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Wed, 27 Jan 2016 17:50:19 +1100 Subject: Clean ups. --- c_user/board_support_packages.rst | 370 +++++++++++++++++--------------------- 1 file changed, 167 insertions(+), 203 deletions(-) (limited to 'c_user/board_support_packages.rst') diff --git a/c_user/board_support_packages.rst b/c_user/board_support_packages.rst index 9b5b932..6b63aae 100644 --- a/c_user/board_support_packages.rst +++ b/c_user/board_support_packages.rst @@ -1,3 +1,7 @@ +.. COMMENT: COPYRIGHT (c) 1988-2008. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + Board Support Packages ###################### @@ -8,87 +12,80 @@ Introduction ============ .. index:: BSP, definition -A board support package (BSP) is a collection of -user-provided facilities which interface RTEMS and an -application with a specific hardware platform. These facilities -may include hardware initialization, device drivers, user -extensions, and a Multiprocessor Communications Interface -(MPCI). However, a minimal BSP need only support processor -reset and initialization and, if needed, a clock tick. +A board support package (BSP) is a collection of user-provided facilities which +interface RTEMS and an application with a specific hardware platform. These +facilities may include hardware initialization, device drivers, user +extensions, and a Multiprocessor Communications Interface (MPCI). However, a +minimal BSP need only support processor reset and initialization and, if +needed, a clock tick. Reset and Initialization ======================== -An RTEMS based application is initiated or -re-initiated when the processor is reset. This initialization -code is responsible for preparing the target platform for the -RTEMS application. Although the exact actions performed by the -initialization code are highly processor and target dependent, -the logical functionality of these actions are similar across a -variety of processors and target platforms. - -Normally, the BSP and some of the application initialization is -intertwined in the RTEMS initialization sequence controlled by -the shared function ``boot_card()``. - -The reset application initialization code is executed -first when the processor is reset. All of the hardware must be -initialized to a quiescent state by this software before -initializing RTEMS. When in quiescent state, devices do not -generate any interrupts or require any servicing by the -application. Some of the hardware components may be initialized -in this code as well as any application initialization that does -not involve calls to RTEMS directives. - -The processor's Interrupt Vector Table which will be used by the -application may need to be set to the required value by the reset -application initialization code. Because interrupts are enabled -automatically by RTEMS as part of the context switch to the first task, -the Interrupt Vector Table MUST be set before this directive is invoked -to ensure correct interrupt vectoring. The processor's Interrupt Vector -Table must be accessible by RTEMS as it will be modified by the when -installing user Interrupt Service Routines (ISRs) On some CPUs, RTEMS -installs it's own Interrupt Vector Table as part of initialization and -thus these requirements are met automatically. The reset code which is -executed before the call to any RTEMS initialization routines has the -following requirements: +An RTEMS based application is initiated or re-initiated when the processor is +reset. This initialization code is responsible for preparing the target +platform for the RTEMS application. Although the exact actions performed by +the initialization code are highly processor and target dependent, the logical +functionality of these actions are similar across a variety of processors and +target platforms. + +Normally, the BSP and some of the application initialization is intertwined in +the RTEMS initialization sequence controlled by the shared function +``boot_card()``. + +The reset application initialization code is executed first when the processor +is reset. All of the hardware must be initialized to a quiescent state by this +software before initializing RTEMS. When in quiescent state, devices do not +generate any interrupts or require any servicing by the application. Some of +the hardware components may be initialized in this code as well as any +application initialization that does not involve calls to RTEMS directives. + +The processor's Interrupt Vector Table which will be used by the application +may need to be set to the required value by the reset application +initialization code. Because interrupts are enabled automatically by RTEMS as +part of the context switch to the first task, the Interrupt Vector Table MUST +be set before this directive is invoked to ensure correct interrupt vectoring. +The processor's Interrupt Vector Table must be accessible by RTEMS as it will +be modified by the when installing user Interrupt Service Routines (ISRs) On +some CPUs, RTEMS installs it's own Interrupt Vector Table as part of +initialization and thus these requirements are met automatically. The reset +code which is executed before the call to any RTEMS initialization routines has +the following requirements: - Must not make any blocking RTEMS directive calls. -- If the processor supports multiple privilege levels, must leave - the processor in the most privileged, or supervisory, state. +- If the processor supports multiple privilege levels, must leave the processor + in the most privileged, or supervisory, state. -- Must allocate a stack of sufficient size to execute the initialization - and shutdown of the system. This stack area will NOT be used by any task - once the system is initialized. This stack is often reserved via the - linker script or in the assembly language start up file. +- Must allocate a stack of sufficient size to execute the initialization and + shutdown of the system. This stack area will NOT be used by any task once + the system is initialized. This stack is often reserved via the linker + script or in the assembly language start up file. -- Must initialize the stack pointer for the initialization process to - that allocated. +- Must initialize the stack pointer for the initialization process to that + allocated. - Must initialize the processor's Interrupt Vector Table. - Must disable all maskable interrupts. -- If the processor supports a separate interrupt stack, must allocate - the interrupt stack and initialize the interrupt stack pointer. +- If the processor supports a separate interrupt stack, must allocate the + interrupt stack and initialize the interrupt stack pointer. -At the end of the initialization sequence, RTEMS does not return to the -BSP initialization code, but instead context switches to the highest -priority task to begin application execution. This task is typically -a User Initialization Task which is responsible for performing both -local and global application initialization which is dependent on RTEMS -facilities. It is also responsible for initializing any higher level -RTEMS services the application uses such as networking and blocking -device drivers. +At the end of the initialization sequence, RTEMS does not return to the BSP +initialization code, but instead context switches to the highest priority task +to begin application execution. This task is typically a User Initialization +Task which is responsible for performing both local and global application +initialization which is dependent on RTEMS facilities. It is also responsible +for initializing any higher level RTEMS services the application uses such as +networking and blocking device drivers. Interrupt Stack Requirements ---------------------------- -The worst-case stack usage by interrupt service -routines must be taken into account when designing an -application. If the processor supports interrupt nesting, the -stack usage must include the deepest nest level. The worst-case +The worst-case stack usage by interrupt service routines must be taken into +account when designing an application. If the processor supports interrupt +nesting, the stack usage must include the deepest nest level. The worst-case stack usage must account for the following requirements: - Processor's interrupt stack frame @@ -101,51 +98,47 @@ stack usage must account for the following requirements: - Application subroutine calls -The size of the interrupt stack must be greater than or equal to the -confugured minimum stack size. +The size of the interrupt stack must be greater than or equal to the confugured +minimum stack size. Processors with a Separate Interrupt Stack ------------------------------------------ -Some processors support a separate stack for interrupts. When an -interrupt is vectored and the interrupt is not nested, the processor -will automatically switch from the current stack to the interrupt stack. -The size of this stack is based solely on the worst-case stack usage by -interrupt service routines. +Some processors support a separate stack for interrupts. When an interrupt is +vectored and the interrupt is not nested, the processor will automatically +switch from the current stack to the interrupt stack. The size of this stack +is based solely on the worst-case stack usage by interrupt service routines. -The dedicated interrupt stack for the entire application on some -architectures is supplied and initialized by the reset and initialization -code of the user's Board Support Package. Whether allocated and -initialized by the BSP or RTEMS, since all ISRs use this stack, the -stack size must take into account the worst case stack usage by any -combination of nested ISRs. +The dedicated interrupt stack for the entire application on some architectures +is supplied and initialized by the reset and initialization code of the user's +Board Support Package. Whether allocated and initialized by the BSP or RTEMS, +since all ISRs use this stack, the stack size must take into account the worst +case stack usage by any combination of nested ISRs. Processors Without a Separate Interrupt Stack --------------------------------------------- -Some processors do not support a separate stack for interrupts. In this -case, without special assistance every task's stack must include -enough space to handle the task's worst-case stack usage as well as -the worst-case interrupt stack usage. This is necessary because the -worst-case interrupt nesting could occur while any task is executing. +Some processors do not support a separate stack for interrupts. In this case, +without special assistance every task's stack must include enough space to +handle the task's worst-case stack usage as well as the worst-case interrupt +stack usage. This is necessary because the worst-case interrupt nesting could +occur while any task is executing. -On many processors without dedicated hardware managed interrupt stacks, -RTEMS manages a dedicated interrupt stack in software. If this capability -is supported on a CPU, then it is logically equivalent to the processor -supporting a separate interrupt stack in hardware. +On many processors without dedicated hardware managed interrupt stacks, RTEMS +manages a dedicated interrupt stack in software. If this capability is +supported on a CPU, then it is logically equivalent to the processor supporting +a separate interrupt stack in hardware. Device Drivers ============== -Device drivers consist of control software for -special peripheral devices and provide a logical interface for -the application developer. The RTEMS I/O manager provides -directives which allow applications to access these device -drivers in a consistent fashion. A Board Support Package may -include device drivers to access the hardware on the target -platform. These devices typically include serial and parallel -ports, counter/timer peripherals, real-time clocks, disk -interfaces, and network controllers. +Device drivers consist of control software for special peripheral devices and +provide a logical interface for the application developer. The RTEMS I/O +manager provides directives which allow applications to access these device +drivers in a consistent fashion. A Board Support Package may include device +drivers to access the hardware on the target platform. These devices typically +include serial and parallel ports, counter/timer peripherals, real-time clocks, +disk interfaces, and network controllers. For more information on device drivers, refer to the I/O Manager chapter. @@ -153,42 +146,37 @@ I/O Manager chapter. Clock Tick Device Driver ------------------------ -Most RTEMS applications will include a clock tick -device driver which invokes the ``rtems_clock_tick`` -directive at regular intervals. The clock tick is necessary if -the application is to utilize timeslicing, the clock manager, the +Most RTEMS applications will include a clock tick device driver which invokes +the ``rtems_clock_tick`` directive at regular intervals. The clock tick is +necessary if the application is to utilize timeslicing, the clock manager, the timer manager, the rate monotonic manager, or the timeout option on blocking directives. -The clock tick is usually provided as an interrupt from a counter/timer -or a real-time clock device. When a counter/timer is used to provide the -clock tick, the device is typically programmed to operate in continuous -mode. This mode selection causes the device to automatically reload the -initial count and continue the countdown without programmer intervention. -This reduces the overhead required to manipulate the counter/timer in -the clock tick ISR and increases the accuracy of tick occurrences. -The initial count can be based on the microseconds_per_tick field -in the RTEMS Configuration Table. An alternate approach is to set -the initial count for a fixed time period (such as one millisecond) -and have the ISR invoke ``rtems_clock_tick`` on the -configured ``microseconds_per_tick`` boundaries. Obviously, this -can induce some error if the configured ``microseconds_per_tick`` -is not evenly divisible by the chosen clock interrupt quantum. - -It is important to note that the interval between -clock ticks directly impacts the granularity of RTEMS timing -operations. In addition, the frequency of clock ticks is an -important factor in the overall level of system overhead. A -high clock tick frequency results in less processor time being -available for task execution due to the increased number of -clock tick ISRs. +The clock tick is usually provided as an interrupt from a counter/timer or a +real-time clock device. When a counter/timer is used to provide the clock +tick, the device is typically programmed to operate in continuous mode. This +mode selection causes the device to automatically reload the initial count and +continue the countdown without programmer intervention. This reduces the +overhead required to manipulate the counter/timer in the clock tick ISR and +increases the accuracy of tick occurrences. The initial count can be based on +the microseconds_per_tick field in the RTEMS Configuration Table. An alternate +approach is to set the initial count for a fixed time period (such as one +millisecond) and have the ISR invoke ``rtems_clock_tick`` on the configured +``microseconds_per_tick`` boundaries. Obviously, this can induce some error if +the configured ``microseconds_per_tick`` is not evenly divisible by the chosen +clock interrupt quantum. + +It is important to note that the interval between clock ticks directly impacts +the granularity of RTEMS timing operations. In addition, the frequency of +clock ticks is an important factor in the overall level of system overhead. A +high clock tick frequency results in less processor time being available for +task execution due to the increased number of clock tick ISRs. User Extensions =============== -RTEMS allows the application developer to augment -selected features by invoking user-supplied extension routines -when the following system events occur: +RTEMS allows the application developer to augment selected features by invoking +user-supplied extension routines when the following system events occur: - Task creation @@ -208,109 +196,85 @@ when the following system events occur: - Fatal error detection -User extensions can be used to implement a wide variety of -functions including execution profiling, non-standard -coprocessor support, debug support, and error detection and -recovery. For example, the context of a non-standard numeric -coprocessor may be maintained via the user extensions. In this -example, the task creation and deletion extensions are -responsible for allocating and deallocating the context area, -the task initiation and reinitiation extensions would be -responsible for priming the context area, and the task context -switch extension would save and restore the context of the -device. +User extensions can be used to implement a wide variety of functions including +execution profiling, non-standard coprocessor support, debug support, and error +detection and recovery. For example, the context of a non-standard numeric +coprocessor may be maintained via the user extensions. In this example, the +task creation and deletion extensions are responsible for allocating and +deallocating the context area, the task initiation and reinitiation extensions +would be responsible for priming the context area, and the task context switch +extension would save and restore the context of the device. For more information on user extensions, refer to `User Extensions Manager`_. Multiprocessor Communications Interface (MPCI) ============================================== -RTEMS requires that an MPCI layer be provided when a -multiple node application is developed. This MPCI layer must -provide an efficient and reliable communications mechanism -between the multiple nodes. Tasks on different nodes -communicate and synchronize with one another via the MPCI. Each -MPCI layer must be tailored to support the architecture of the -target platform. +RTEMS requires that an MPCI layer be provided when a multiple node application +is developed. This MPCI layer must provide an efficient and reliable +communications mechanism between the multiple nodes. Tasks on different nodes +communicate and synchronize with one another via the MPCI. Each MPCI layer +must be tailored to support the architecture of the target platform. -For more information on the MPCI, refer to the -Multiprocessing Manager chapter. +For more information on the MPCI, refer to the Multiprocessing Manager chapter. Tightly-Coupled Systems ----------------------- -A tightly-coupled system is a multiprocessor -configuration in which the processors communicate solely via -shared global memory. The MPCI can simply place the RTEMS -packets in the shared memory space. The two primary -considerations when designing an MPCI for a tightly-coupled -system are data consistency and informing another node of a -packet. - -The data consistency problem may be solved using -atomic "test and set" operations to provide a "lock" in the -shared memory. It is important to minimize the length of time -any particular processor locks a shared data structure. - -The problem of informing another node of a packet can -be addressed using one of two techniques. The first technique -is to use an interprocessor interrupt capability to cause an -interrupt on the receiving node. This technique requires that -special support hardware be provided by either the processor -itself or the target platform. The second technique is to have -a node poll for arrival of packets. The drawback to this -technique is the overhead associated with polling. +A tightly-coupled system is a multiprocessor configuration in which the +processors communicate solely via shared global memory. The MPCI can simply +place the RTEMS packets in the shared memory space. The two primary +considerations when designing an MPCI for a tightly-coupled system are data +consistency and informing another node of a packet. + +The data consistency problem may be solved using atomic "test and set" +operations to provide a "lock" in the shared memory. It is important to +minimize the length of time any particular processor locks a shared data +structure. + +The problem of informing another node of a packet can be addressed using one of +two techniques. The first technique is to use an interprocessor interrupt +capability to cause an interrupt on the receiving node. This technique +requires that special support hardware be provided by either the processor +itself or the target platform. The second technique is to have a node poll for +arrival of packets. The drawback to this technique is the overhead associated +with polling. Loosely-Coupled Systems ----------------------- -A loosely-coupled system is a multiprocessor -configuration in which the processors communicate via some type -of communications link which is not shared global memory. The -MPCI sends the RTEMS packets across the communications link to -the destination node. The characteristics of the communications -link vary widely and have a significant impact on the MPCI -layer. For example, the bandwidth of the communications link -has an obvious impact on the maximum MPCI throughput. +A loosely-coupled system is a multiprocessor configuration in which the +processors communicate via some type of communications link which is not shared +global memory. The MPCI sends the RTEMS packets across the communications link +to the destination node. The characteristics of the communications link vary +widely and have a significant impact on the MPCI layer. For example, the +bandwidth of the communications link has an obvious impact on the maximum MPCI +throughput. -The characteristics of a shared network, such as -Ethernet, lend themselves to supporting an MPCI layer. These -networks provide both the point-to-point and broadcast -capabilities which are expected by RTEMS. +The characteristics of a shared network, such as Ethernet, lend themselves to +supporting an MPCI layer. These networks provide both the point-to-point and +broadcast capabilities which are expected by RTEMS. Systems with Mixed Coupling --------------------------- -A mixed-coupling system is a multiprocessor -configuration in which the processors communicate via both -shared memory and communications links. A unique characteristic -of mixed-coupling systems is that a node may not have access to -all communication methods. There may be multiple shared memory -areas and communication links. Therefore, one of the primary -functions of the MPCI layer is to efficiently route RTEMS -packets between nodes. This routing may be based on numerous -algorithms. In addition, the router may provide alternate -communications paths in the event of an overload or a partial -failure. +A mixed-coupling system is a multiprocessor configuration in which the +processors communicate via both shared memory and communications links. A +unique characteristic of mixed-coupling systems is that a node may not have +access to all communication methods. There may be multiple shared memory areas +and communication links. Therefore, one of the primary functions of the MPCI +layer is to efficiently route RTEMS packets between nodes. This routing may be +based on numerous algorithms. In addition, the router may provide alternate +communications paths in the event of an overload or a partial failure. Heterogeneous Systems --------------------- -Designing an MPCI layer for a heterogeneous system -requires special considerations by the developer. RTEMS is -designed to eliminate many of the problems associated with -sharing data in a heterogeneous environment. The MPCI layer -need only address the representation of thirty-two (32) bit -unsigned quantities. - -For more information on supporting a heterogeneous -system, refer the Supporting Heterogeneous Environments in the -Multiprocessing Manager chapter. - -.. COMMENT: COPYRIGHT (c) 1988-2002. - -.. COMMENT: On-Line Applications Research Corporation (OAR). - -.. COMMENT: All rights reserved. - +Designing an MPCI layer for a heterogeneous system requires special +considerations by the developer. RTEMS is designed to eliminate many of the +problems associated with sharing data in a heterogeneous environment. The MPCI +layer need only address the representation of thirty-two (32) bit unsigned +quantities. +For more information on supporting a heterogeneous system, refer the Supporting +Heterogeneous Environments in the Multiprocessing Manager chapter. -- cgit v1.2.3