[rtems commit] porting: Review and tidy up multiple formatting issues.
Joel Sherrill
joel at rtems.org
Fri Oct 28 20:57:48 UTC 2016
Module: rtems
Branch: master
Commit: 7497f5ed9a2cebe06619987e295cae529dde9fad
Changeset: http://git.rtems.org/rtems/commit/?id=7497f5ed9a2cebe06619987e295cae529dde9fad
Author: Joel Sherrill <joel at rtems.org>
Date: Fri Oct 28 15:57:11 2016 -0500
porting: Review and tidy up multiple formatting issues.
---
porting/code_tuning.rst | 30 +++++----
porting/cpu_init.rst | 15 ++---
porting/cpu_model_variations.rst | 14 ++--
porting/development_tools.rst | 11 ++--
porting/idle_thread.rst | 31 +++++----
porting/interrupts.rst | 49 ++++++++++----
porting/miscellanous.rst | 36 ++++++-----
porting/preface.rst | 11 ++--
porting/priority_bitmap.rst | 67 ++++++++++---------
porting/source_code_org.rst | 11 ++--
porting/task_context.rst | 135 +++++++++++++++++++++------------------
11 files changed, 223 insertions(+), 187 deletions(-)
diff --git a/porting/code_tuning.rst b/porting/code_tuning.rst
index 5fd664e..22544a1 100644
--- a/porting/code_tuning.rst
+++ b/porting/code_tuning.rst
@@ -1,5 +1,9 @@
.. comment SPDX-License-Identifier: CC-BY-SA-4.0
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
Code Tuning Parameters
######################
@@ -8,9 +12,9 @@ Inline Thread_Enable_dispatch
Should the calls to _Thread_Enable_dispatch be inlined?
-If TRUE, then they are inlined.
+- If ``TRUE``, then they are inlined.
-If FALSE, then a subroutine call is made.
+- If ``FALSE``, then a subroutine call is made.
Basically this is an example of the classic trade-off of size versus
speed. Inlining the call (TRUE) typically increases the size of RTEMS
@@ -21,6 +25,7 @@ unless you are in an interrupt handler and that interrupt handler invokes
the executive.] When not inlined something calls _Thread_Enable_dispatch
which in turns calls _Thread_Dispatch. If the enable dispatch is inlined,
then one subroutine call is avoided entirely.]
+
.. code-block:: c
#define CPU_INLINE_ENABLE_DISPATCH FALSE
@@ -33,9 +38,9 @@ unrolled one time? In unrolled each iteration of the loop examines two
"nodes" on the chain being searched. Otherwise, only one node is examined
per iteration.
-If TRUE, then the loops are unrolled.
-
-If FALSE, then the loops are not unrolled.
+- If ``TRUE``, then the loops are unrolled.
+
+- If ``FALSE``, then the loops are not unrolled.
The primary factor in making this decision is the cost of disabling and
enabling interrupts (_ISR_Flash) versus the cost of rest of the body of
@@ -44,6 +49,7 @@ the loop body. In this case, it might be desirable to unroll the loop.
It is important to note that on some CPUs, this code is the longest
interrupt disable period in RTEMS. So it is necessary to strike a balance
when setting this parameter.
+
.. code-block:: c
#define CPU_UNROLL_ENQUEUE_PRIORITY TRUE
@@ -69,7 +75,9 @@ For another toolset, the placement of this macro could be incorrect. For
example with GNU C, use the following definition of
CPU_STRUCTURE_ALIGNMENT to force a structures to a 32 byte boundary.
-#define CPU_STRUCTURE_ALIGNMENT __attribute__ ((aligned (32)))
+.. code-block:: c
+
+ #define CPU_STRUCTURE_ALIGNMENT __attribute__ ((aligned (32)))
To benefit from using this, the data must be heavily used so it will stay
in the cache and used frequently enough in the executive to justify
@@ -79,6 +87,7 @@ currently uses this feature.
The following illustrates how the CPU_STRUCTURE_ALIGNMENT is defined on
ports which require no special alignment for optimized access to data
structures:
+
.. code-block:: c
#define CPU_STRUCTURE_ALIGNMENT
@@ -97,6 +106,7 @@ account the requirements for the stack.
The following sets the CPU_ALIGNMENT macro to 8 which indicates that there
is a basic C data type for this port which much be aligned to an 8 byte
boundary.
+
.. code-block:: c
#define CPU_ALIGNMENT 8
@@ -116,6 +126,7 @@ use by high level language routines.
The following example illustrates how the CPU_HEAP_ALIGNMENT macro is set
when the required alignment for elements from the heap is the same as the
basic CPU alignment requirements.
+
.. code-block:: c
#define CPU_HEAP_ALIGNMENT CPU_ALIGNMENT
@@ -146,10 +157,3 @@ Manager is the same as the basic CPU alignment requirements.
NOTE: This does not have to be a power of 2. It does have to be greater
or equal to than CPU_ALIGNMENT.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
diff --git a/porting/cpu_init.rst b/porting/cpu_init.rst
index c4f7e7d..8e3d0da 100644
--- a/porting/cpu_init.rst
+++ b/porting/cpu_init.rst
@@ -1,5 +1,9 @@
.. comment SPDX-License-Identifier: CC-BY-SA-4.0
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
CPU Initialization
##################
@@ -16,10 +20,11 @@ Initializing the CPU
====================
The _CPU_Initialize routine performs processor dependent initialization.
+
.. code-block:: c
void _CPU_Initialize(
- void (*thread_dispatch) /* may be ignored */
+ void (*thread_dispatch) /* may be ignored */
)
The thread_dispatch argument is the address of the entry point for the
@@ -32,6 +37,7 @@ limitation on these systems.
If you encounter this problem save the entry point in a CPU dependent
variable as shown below:
+
.. code-block:: c
_CPU_Thread_dispatch_pointer = thread_dispatch;
@@ -44,10 +50,3 @@ FP context here and copy it to the task's during Context_Initialize. If
this technique is used to initialize the FP contexts, then it is important
to ensure that the state of the floating point unit is in a coherent,
initialized state.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
diff --git a/porting/cpu_model_variations.rst b/porting/cpu_model_variations.rst
index 5788d77..8c00dd7 100644
--- a/porting/cpu_model_variations.rst
+++ b/porting/cpu_model_variations.rst
@@ -1,11 +1,12 @@
.. comment SPDX-License-Identifier: CC-BY-SA-4.0
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
CPU Model Variations
####################
-XXX enhance using portability presentation from CS595 class. See
-general/portability.ppt.
-
Since the text in the next section was written, RTEMS view of
portability has grown to distinguish totally portable, CPU
family dependent, CPU model dependent, peripheral chip dependent
@@ -140,10 +141,3 @@ Coding Issues
XXX deal with this as it applies to score/cpu. Section name may
be bad.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
diff --git a/porting/development_tools.rst b/porting/development_tools.rst
index 3f0b7fc..13182a4 100644
--- a/porting/development_tools.rst
+++ b/porting/development_tools.rst
@@ -1,5 +1,9 @@
.. comment SPDX-License-Identifier: CC-BY-SA-4.0
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
Development Tools
#################
@@ -18,10 +22,3 @@ of the target object format.
Porting and retargetting the GNU tools is beyond the scope of this manual.
The best advice that can be offered is to look at the existing RTEMS
targets in the tool source and use that as a guideline.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
diff --git a/porting/idle_thread.rst b/porting/idle_thread.rst
index 317cf2a..767c320 100644
--- a/porting/idle_thread.rst
+++ b/porting/idle_thread.rst
@@ -1,5 +1,9 @@
.. comment SPDX-License-Identifier: CC-BY-SA-4.0
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
IDLE Thread
###########
@@ -7,10 +11,11 @@ Does Idle Thread Have a Floating Point Context?
===============================================
The setting of the macro CPU_IDLE_TASK_IS_FP is based on the answer to the
-question: Should the IDLE task have a floating point context? If the
-answer to this question is TRUE, then the IDLE task has a floating point
-context associated. This is equivalent to creating a task in the Classic
-API (using rtems_task_create) as a RTEMS_FLOATING_POINT task. If
+question: Should the IDLE task have a floating point context?
+
+If the answer to this question is TRUE, then the IDLE task has a floating
+point context associated. This is equivalent to creating a task in the
+Classic API (using rtems_task_create) as a RTEMS_FLOATING_POINT task. If
CPU_IDLE_TASK_IS_FP is set to TRUE, then a floating point context switch
occurs when the IDLE task is switched in and out. This adds to the
execution overhead of the system but is necessary on some ports.
@@ -22,6 +27,7 @@ required to preempt the IDLE task from an interrupt because the floating
point context must be saved as part of the preemption.
The following illustrates how to set this macro:
+
.. code-block:: c
#define CPU_IDLE_TASK_IS_FP FALSE
@@ -49,13 +55,14 @@ powered down when the processor is idle.
The order of precedence for selecting the IDLE thread body is:
-# BSP provided
+#. BSP provided
-# CPU dependent (if provided)
+#. CPU dependent (if provided)
-# generic (if no BSP and no CPU dependent)
+#. generic (if no BSP and no CPU dependent)
The following illustrates setting the CPU_PROVIDES_IDLE_THREAD_BODY macro:
+
.. code-block:: c
#define CPU_PROVIDES_IDLE_THREAD_BODY TRUE
@@ -71,6 +78,7 @@ wishes to include a CPU dependent IDLE thread body. If the port includes
a CPU dependent implementation of the IDLE thread body, then the
CPU_PROVIDES_IDLE_THREAD_BODY macro should be defined to TRUE. This
routine is prototyped as follows:
+
.. code-block:: c
void *_CPU_Thread_Idle_body( uintptr_t );
@@ -80,6 +88,7 @@ thread body be provided as part of the port. If
CPU_PROVIDES_IDLE_THREAD_BODY is defined to FALSE, then the CPU
independent algorithm is used. This algorithm consists of a "branch to
self" which is implemented in a routine as follows.
+
.. code-block:: c
void *_Thread_Idle_body( uintptr_t ignored )
@@ -91,6 +100,7 @@ If the CPU dependent IDLE thread body is implementation centers upon using
a "halt", "idle", or "shutdown" instruction, then don't forget to put it
in an infinite loop as the CPU will have to reexecute this instruction
each time the IDLE thread is dispatched.
+
.. code-block:: c
void *_CPU_Thread_Idle_body( uintptr_t ignored )
@@ -102,10 +112,3 @@ each time the IDLE thread is dispatched.
Be warned. Some processors with onboard DMA have been known to stop the
DMA if the CPU were put in IDLE mode. This might also be a problem with
other on-chip peripherals. So use this hook with caution.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
diff --git a/porting/interrupts.rst b/porting/interrupts.rst
index d8580ce..c95495d 100644
--- a/porting/interrupts.rst
+++ b/porting/interrupts.rst
@@ -1,5 +1,9 @@
.. comment SPDX-License-Identifier: CC-BY-SA-4.0
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
Interrupts
##########
@@ -28,6 +32,7 @@ The CPU_MODES_INTERRUPT_MASK macro defines the number of bits actually used in t
The following illustrates how the CPU_MODES_INTERRUPT_MASK is set on a CPU
family like the Intel i386 where the CPU itself only recognizes two
interrupt levels - enabled and disabled.
+
.. code-block:: c
#define CPU_MODES_INTERRUPT_MASK 0x00000001
@@ -36,6 +41,7 @@ Obtaining the Current Interrupt Level
-------------------------------------
The _CPU_ISR_Get_level function returns the current interrupt level.
+
.. code-block:: c
uint32_t _CPU_ISR_Get_level( void )
@@ -54,13 +60,15 @@ manage a programmable interrupt controller via the rtems_task_mode
directive.
The following is a dummy implementation of the _CPU_ISR_Set_level routine:
+
.. code-block:: c
- #define _CPU_ISR_Set_level( new_level ) \\
- { \\
+ #define _CPU_ISR_Set_level( new_level ) \
+ { \
}
The following is the implementation from the Motorola M68K:
+
.. code-block:: c
XXX insert m68k implementation here
@@ -84,14 +92,16 @@ manipulate. It is typically the contents of the processor status
register. It is NOT the same format as manipulated by the
_CPU_ISR_Get_level and _CPU_ISR_Set_level routines. The following is a
dummy implementation that simply sets the previous level to 0.
+
.. code-block:: c
- #define _CPU_ISR_Disable( _isr_cookie ) \\
+ #define _CPU_ISR_Disable( _isr_cookie ) \
{ \
(_isr_cookie) = 0; /* do something to prevent warnings */ \
}
The following is the implementation from the Motorola M68K port:
+
.. code-block:: c
XXX insert m68k port here
@@ -105,13 +115,15 @@ RTEMS critical section to reenable interrupts. The parameter _level is
not modified but indicates that level that interrupts should be enabled
to. The following illustrates a dummy implementation of the
_CPU_ISR_Enable routine:
+
.. code-block:: c
- #define _CPU_ISR_Enable( _isr_cookie ) \\
- { \\
+ #define _CPU_ISR_Enable( _isr_cookie ) \
+ { \
}
The following is the implementation from the Motorola M68K port:
+
.. code-block:: c
XXX insert m68k version here
@@ -126,13 +138,15 @@ preceded by a call to _CPU_ISR_Disable and followed by a call to
_CPU_ISR_Enable. The parameter _level is not modified.
The following is a dummy implementation of the _CPU_ISR_Flash routine:
+
.. code-block:: c
- #define _CPU_ISR_Flash( _isr_cookie ) \\
- { \\
+ #define _CPU_ISR_Flash( _isr_cookie ) \
+ { \
}
The following is the implementation from the Motorola M68K port:
+
.. code-block:: c
XXX insert m68k version here
@@ -179,11 +193,13 @@ in the Interrupt Manager, then the macro CPU_ALLOCATE_INTERRUPT_STACK
should be set to TRUE.
NOTE: This should be TRUE is CPU_HAS_SOFTWARE_INTERRUPT_STACK is TRUE.
+
.. code-block:: c
#define CPU_ALLOCATE_INTERRUPT_STACK TRUE
If the CPU_HAS_SOFTWARE_INTERRUPT_STACK macro is set to TRUE, then RTEMS automatically allocates the stack memory in the initialization of the Interrupt Manager and the switch to that stack is performed in ``_ISR_Handler`` on the outermost interrupt. The _CPU_Interrupt_stack_low and _CPU_Interrupt_stack_high variables contain the addresses of the the lowest and highest addresses of the memory allocated for the interrupt stack. Although technically only one of these addresses is required to switch to the interrupt stack, by always providing both addresses, the port has more options avaialble to it without requiring modifications to the portable parts of the executive. Whether the stack grows up or down, this give the CPU dependent code the option of picking the version it wants to use.
+
.. code-block:: c
SCORE_EXTERN void *_CPU_Interrupt_stack_low;
@@ -200,6 +216,7 @@ The _CPU_Install_interrupt_stack routine XXX
This routine installs the hardware interrupt stack pointer.
NOTE: It need only be provided if CPU_HAS_HARDWARE_INTERRUPT_STAC is TRUE.
+
.. code-block:: c
void _CPU_Install_interrupt_stack( void )
@@ -211,6 +228,7 @@ Install a Raw Interrupt Handler
-------------------------------
The _CPU_ISR_install_raw_handler XXX
+
.. code-block:: c
void _CPU_ISR_install_raw_handler(
@@ -235,10 +253,11 @@ by this CPU model. The second macro is the
CPU_INTERRUPT_MAXIMUM_VECTOR_NUMBER. Since the table is zero-based, this
indicates the highest vector number which can be looked up in the table
and mapped into a user provided handler.
+
.. code-block:: c
#define CPU_INTERRUPT_NUMBER_OF_VECTORS 32
- #define CPU_INTERRUPT_MAXIMUM_VECTOR_NUMBER \\
+ #define CPU_INTERRUPT_MAXIMUM_VECTOR_NUMBER \
(CPU_INTERRUPT_NUMBER_OF_VECTORS - 1)
Install RTEMS Interrupt Handler
@@ -251,6 +270,7 @@ XXX Input parameters:
vector - interrupt vector number
old_handler - former ISR for this vector number
new_handler - replacement ISR for this vector number
+
.. code-block:: c
void _CPU_ISR_install_vector(
@@ -266,12 +286,14 @@ new_handler - replacement ISR for this vector number
If the interrupt vector table is a table of pointer to isr entry points,
then we need to install the appropriate RTEMS interrupt handler for this
vector number.
+
.. code-block:: c
_CPU_ISR_install_raw_handler( vector, new_handler, old_handler );
We put the actual user ISR address in _ISR_vector_table. This will be
used by the ``_ISR_Handler`` so the user gets control.
+
.. code-block:: c
_ISR_Vector_table[ vector ] = new_handler;
@@ -290,6 +312,7 @@ results in the saving of registers which are NOT preserved across
subroutine calls as well as any special interrupt state. A port should
define the ``CPU_Interrupt_frame`` structure so that application code can
examine the saved state.
+
.. code-block:: c
typedef struct {
@@ -301,6 +324,7 @@ Interrupt Dispatching
---------------------
The ``_ISR_Handler`` routine provides the RTEMS interrupt management.
+
.. code-block:: c
void _ISR_Handler()
@@ -333,6 +357,7 @@ hardware does not provide this information, then the assembly portion of
RTEMS for this port will contain a set of distinct interrupt entry points
which somehow place the vector number in a known place (which is safe if
another interrupt nests this one) and branches to ``_ISR_Handler``.
+
.. code-block:: c
save some or all context on stack
@@ -372,6 +397,7 @@ ISR Invoked with Frame Pointer
Does the RTEMS invoke the user's ISR with the vector number and a pointer
to the saved interrupt frame (1) or just the vector number (0)?
+
.. code-block:: c
#define CPU_ISR_PASSES_FRAME_POINTER 0
@@ -390,13 +416,8 @@ variable can be optionally defined by the CPU porter and contains the
address of the routine _Thread_Dispatch. This can make it easier to
invoke that routine at the end of the interrupt sequence (if a dispatch is
necessary).
+
.. code-block:: c
void (*_CPU_Thread_dispatch_pointer)();
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
diff --git a/porting/miscellanous.rst b/porting/miscellanous.rst
index be208a4..863160e 100644
--- a/porting/miscellanous.rst
+++ b/porting/miscellanous.rst
@@ -10,10 +10,11 @@ The ``_CPU_Fatal_halt`` routine is the default fatal error handler. This
routine copies _error into a known place - typically a stack location or
a register, optionally disables interrupts, and halts/stops the CPU. It
is prototyped as follows and is often implemented as a macro:
+
.. code-block:: c
void _CPU_Fatal_halt(
- unsigned32 _error
+ unsigned32 _error
);
CPU Context Validation
@@ -23,6 +24,7 @@ The test case ``sptests/spcontext01`` ensures that the context switching and
interrupt processing works. This test uses two support functions provided by
the CPU port. These two functions are only used for this test and have no
other purpose.
+
.. code-block:: c
void _CPU_Context_volatile_clobber( uintptr_t pattern );
@@ -67,11 +69,11 @@ peripheral controllers.
Specifying Processor Endianness
-------------------------------
-The ``CPU_BIG_ENDIAN`` and ``CPU_LITTLE_ENDIAN`` are
-set to specify the endian
-format used by this microprocessor. These macros should not be set to the
-same value. The following example illustrates how these macros should be
-set on a processor family that is big endian.
+The ``CPU_BIG_ENDIAN`` and ``CPU_LITTLE_ENDIAN`` are set to specify
+the endian format used by this microprocessor. These macros should not
+be set to the same value. The following example illustrates how these
+macros should be set on a processor family that is big endian.
+
.. code-block:: c
#define CPU_BIG_ENDIAN TRUE
@@ -82,6 +84,7 @@ stack space above the minimum thread stack space required by the MPCI
Receive Server Thread. This macro is needed because in a multiprocessor
system the MPCI Receive Server Thread must be able to process all
directives.
+
.. code-block:: c
#define CPU_MPCI_RECEIVE_SERVER_EXTRA_STACK 0
@@ -108,19 +111,20 @@ code and data - so the code will be fetched incorrectly.
The following is an implementation of the ``CPU_swap_u32`` routine that will
work on any CPU. It operates by breaking the unsigned thirty-two bit
integer into four byte-wide quantities and reassemblying them.
+
.. code-block:: c
static inline unsigned int CPU_swap_u32(
- unsigned int value
+ unsigned int value
)
{
- unsigned32 byte1, byte2, byte3, byte4, swapped;
- byte4 = (value >> 24) & 0xff;
- byte3 = (value >> 16) & 0xff;
- byte2 = (value >> 8) & 0xff;
- byte1 = value & 0xff;
- swapped = (byte1 << 24) | (byte2 << 16) | (byte3 << 8) | byte4;
- return( swapped );
+ unsigned32 byte1, byte2, byte3, byte4, swapped;
+ byte4 = (value >> 24) & 0xff;
+ byte3 = (value >> 16) & 0xff;
+ byte2 = (value >> 8) & 0xff;
+ byte1 = value & 0xff;
+ swapped = (byte1 << 24) | (byte2 << 16) | (byte3 << 8) | byte4;
+ return( swapped );
}
Although the above implementation is portable, it is not particularly
@@ -133,6 +137,7 @@ family of routines.
Most microprocessor families have rotate instructions which can be used to
greatly improve the ``CPU_swap_u32`` routine. The most common
way to do this is to:
+
.. code-block:: c
swap least significant two bytes with 16-bit rotate
@@ -150,8 +155,9 @@ code and data - so the code will be fetched incorrectly.
Similarly, here is a portable implementation of the ``CPU_swap_u16``
routine. Just as with the ``CPU_swap_u32`` routine, the porter
should provide a better implementation if possible.
+
.. code-block:: c
#define CPU_swap_u16( value ) \\
- (((value&0xff) << 8) | ((value >> 8)&0xff))
+ (((value&0xff) << 8) | ((value >> 8)&0xff))
diff --git a/porting/preface.rst b/porting/preface.rst
index 8f23446..f0ceda2 100644
--- a/porting/preface.rst
+++ b/porting/preface.rst
@@ -1,5 +1,9 @@
.. comment SPDX-License-Identifier: CC-BY-SA-4.0
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
=======
Preface
=======
@@ -28,10 +32,3 @@ using RTEMS, the C programming language, and the target CPU architecture.
It is desirable to be familiar with the assembly language for the target
CPU family but since only a limited amount of assembly is required to port
RTEMS.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
diff --git a/porting/priority_bitmap.rst b/porting/priority_bitmap.rst
index 0a9a3f0..d5699c4 100644
--- a/porting/priority_bitmap.rst
+++ b/porting/priority_bitmap.rst
@@ -1,5 +1,9 @@
.. comment SPDX-License-Identifier: CC-BY-SA-4.0
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
Priority Bitmap Manipulation
############################
@@ -23,14 +27,15 @@ ready task at that priority. The bit array can be efficiently searched to
determine the highest priority ready task. This family of data type and
routines is used to maintain and search the bit map array.
-When manipulating the bitmap array, RTEMS internally divides the
-8 bits of the task priority into "major" and "minor" components.
-The most significant 4 bits are the major component, while the least
-significant are the minor component. The major component of a priority
-value is used to determine which 16-bit wide entry in the``_Priority_Bit_map`` array is associated with this priority.
-Each element in the ``_Priority_Bit_map`` array has a bit
-in the ``_Priority_Major_bit_map`` associated with it.
-That bit is cleared when all of the bits in a particular``_Priority_Bit_map`` array entry are zero.
+When manipulating the bitmap array, RTEMS internally divides the 8 bits
+of the task priority into "major" and "minor" components. The most
+significant 4 bits are the major component, while the least significant
+are the minor component. The major component of a priority value is
+used to determine which 16-bit wide entry in the``_Priority_Bit_map``
+array is associated with this priority. Each element in the
+``_Priority_Bit_map`` array has a bit in the ``_Priority_Major_bit_map``
+associated with it. That bit is cleared when all of the bits in a
+particular``_Priority_Bit_map`` array entry are zero.
The minor component of a priority is used to determine
specifically which bit in ``_Priority_Bit_map[major]``
@@ -54,6 +59,7 @@ Find First Bit Routine
The _CPU_Bitfield_Find_first_bit routine sets _output to the bit number of
the first bit set in ``_value``. ``_value`` is of CPU dependent type``Priority_bit_map_Control``. A stub version of this routine is as follows:
+
.. code-block:: c
#define _CPU_Bitfield_Find_first_bit( _value, _output ) \
@@ -64,13 +70,13 @@ the first bit set in ``_value``. ``_value`` is of CPU dependent type``Priority_
There are a number of variables in using a "find first bit" type
instruction.
-# What happens when run on a value of zero?
+#. What happens when run on a value of zero?
-# Bits may be numbered from MSB to LSB or vice-versa.
+#. Bits may be numbered from MSB to LSB or vice-versa.
-# The numbering may be zero or one based.
+#. The numbering may be zero or one based.
-# The "find first bit" instruction may search from MSB or LSB.
+#. The "find first bit" instruction may search from MSB or LSB.
RTEMS guarantees that (1) will never happen so it is not a concern.
Cases (2),(3), (4) are handled by the macros _CPU_Priority_mask() and
@@ -98,7 +104,9 @@ in software:
- a "binary search using if's"
-- the following algorithm based upon a 16 entry lookup table. In this pseudo-code, bit_set_table[16] has values which indicate the first bit set:
+- the following algorithm based upon a 16 entry lookup table. In this
+ pseudo-code, bit_set_table[16] has values which indicate the first
+ bit set:
.. code-block:: c
@@ -106,9 +114,9 @@ in software:
_value >>=8
_number = 8;
if _value > 0x0000f
- _value >=8
- _number += 4
- _number += bit_set_table[ _value ]
+ _value >=8
+ _number += 4
+ _number += bit_set_table[ _value ]
The following illustrates how the CPU_USE_GENERIC_BITFIELD_CODE macro may
be so the port can use the generic implementation of this bitfield code.
@@ -116,6 +124,7 @@ This can be used temporarily during the porting process to avoid writing
these routines until the end. This results in a functional although lower
performance port. This is perfectly acceptable during development and
testing phases.
+
.. code-block:: c
#define CPU_USE_GENERIC_BITFIELD_CODE TRUE
@@ -126,13 +135,14 @@ written since they dramatically impact the performance of blocking
operations. However they may take advantage of instructions which are not
available on all models in the CPU family. In this case, one might find
something like this stub example did:
+
.. code-block:: c
#if (CPU_USE_GENERIC_BITFIELD_CODE == FALSE)
- #define _CPU_Bitfield_Find_first_bit( _value, _output ) \
- { \
- (_output) = 0; /* do something to prevent warnings */ \
- }
+ #define _CPU_Bitfield_Find_first_bit( _value, _output ) \
+ { \
+ (_output) = 0; /* do something to prevent warnings */ \
+ }
#endif
Build Bit Field Mask
@@ -144,11 +154,12 @@ that routine for more details.
The following is a typical implementation when the
_CPU_Bitfield_Find_first_bit searches for the most significant bit set:
+
.. code-block:: c
#if (CPU_USE_GENERIC_BITFIELD_CODE == FALSE)
- #define _CPU_Priority_Mask( _bit_number ) \\
- ( 1 << (_bit_number) )
+ #define _CPU_Priority_Mask( _bit_number ) \
+ ( 1 << (_bit_number) )
#endif
Bit Scan Support
@@ -169,16 +180,10 @@ would be bit 16 or 17.
This routine allows that unwieldy form to be converted
into a normalized form that is easier to process and use
as an index.
+
.. code-block:: c
#if (CPU_USE_GENERIC_BITFIELD_CODE == FALSE)
- #define _CPU_Priority_bits_index( _priority ) \\
- (_priority)
+ #define _CPU_Priority_bits_index( _priority ) \
+ (_priority)
#endif
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
diff --git a/porting/source_code_org.rst b/porting/source_code_org.rst
index ddad561..1210251 100644
--- a/porting/source_code_org.rst
+++ b/porting/source_code_org.rst
@@ -1,5 +1,9 @@
.. comment SPDX-License-Identifier: CC-BY-SA-4.0
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
Source Code Organization
########################
@@ -16,10 +20,3 @@ dependent code which may be reused across multiple Board Support Packages
is found in c/src/lib/libcpu.
XXX list the files and directories here
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
diff --git a/porting/task_context.rst b/porting/task_context.rst
index 9b8dec2..c70f2b0 100644
--- a/porting/task_context.rst
+++ b/porting/task_context.rst
@@ -1,5 +1,9 @@
.. comment SPDX-License-Identifier: CC-BY-SA-4.0
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
Task Context Management
#######################
@@ -23,6 +27,7 @@ should be set to TRUE. Otherwise, it should be set to FALSE to indicate
that the stack grows downward toward smaller addresses.
The following illustrates how the CPU_STACK_GROWS_UP macro is set:
+
.. code-block:: c
#define CPU_STACK_GROWS_UP TRUE
@@ -45,6 +50,7 @@ tend to require larger stacks as do Ada tasks.
The following illustrates setting the minimum stack size to 4 kilobytes
per task.
+
.. code-block:: c
#define CPU_STACK_MINIMUM_SIZE (1024*4)
@@ -60,6 +66,7 @@ CPU_ALIGNMENT is strict enough for the stack, then this should be set to
The following illustrates how the CPU_STACK_ALIGNMENT macro should be set
when there are no special requirements:
+
.. code-block:: c
#define CPU_STACK_ALIGNMENT 0
@@ -88,10 +95,11 @@ interrupt level context structure is discussed in the XXX.
Additionally, if the GNU debugger gdb is to be made aware of RTEMS tasks
for this CPU, then care should be used in designing the context area.
+
.. code-block:: c
typedef struct {
- unsigned32 special_interrupt_register;
+ unsigned32 special_interrupt_register;
} CPU_Interrupt_frame;
Basic Context Data Structure
@@ -118,12 +126,13 @@ entry as for tasks in this case.
The Context_Control data structure should be defined such that the order
of elements results in the simplest, most efficient implementation of XXX.
A typical implementation starts with a definition such as the following:
+
.. code-block:: c
typedef struct {
- unsigned32 some_integer_register;
- unsigned32 another_integer_register;
- unsigned32 some_system_register;
+ unsigned32 some_integer_register;
+ unsigned32 another_integer_register;
+ unsigned32 some_system_register;
} Context_Control;
Initializing a Context
@@ -146,6 +155,7 @@ Generally, this involves:
This routine generally does not set any unnecessary register in the
context. The state of the "general data" registers is undefined at task
start time. The _CPU_Context_initialize routine is prototyped as follows:
+
.. code-block:: c
void _CPU_Context_Initialize(
@@ -165,12 +175,14 @@ non-floating point task is unable to access the FPU. This guarantees that
a deferred floating point context switch is safe.
The ``_stack_base`` parameter is the base address of the memory area
-allocated for use as the task stack. It is critical to understand that``_stack_base`` may not be the starting stack pointer for this task.
+allocated for use as the task stack. It is critical to understand that
+``_stack_base`` may not be the starting stack pointer for this task.
On CPU families where the stack grows from high addresses to lower ones,
(i.e. ``CPU_STACK_GROWS_UP`` is FALSE) the starting stack point
-will be near the end of the stack memory area or close to``_stack_base`` + ``_size``. Even on CPU families where the stack
-grows from low to higher addresses, there may be some required
-outermost stack frame that must be put at the address ``_stack_base``.
+will be near the end of the stack memory area or close to ``_stack_base``
++ ``_size``. Even on CPU families where the stack grows from low to
+higher addresses, there may be some required outermost stack frame that
+must be put at the address ``_stack_base``.
The ``_size`` parameter is the requested size in bytes of the stack for
this task. It is assumed that the memory area ``_stack_base``
@@ -183,45 +195,41 @@ Performing a Context Switch
The _CPU_Context_switch performs a normal non-FP context switch from the
context of the current executing thread to the context of the heir thread.
+
.. code-block:: c
void _CPU_Context_switch(
- Context_Control *run,
- Context_Control *heir
+ Context_Control *run,
+ Context_Control *heir
);
-This routine begins by saving the current state of the
-CPU (i.e. the context) in the context area at ``run``.
-Then the routine should load the CPU context pointed to
-by ``heir``. Loading the new context will cause a
-branch to its task code, so the task that invoked``_CPU_Context_switch`` will not run for a while.
-When, eventually, a context switch is made to load
-context from ``*run`` again, this task will resume
-and ``_CPU_Context_switch`` will return to its caller.
-
-Care should be exercise when writing this routine. All
-registers assumed to be preserved across subroutine calls
-must be preserved. These registers may be saved in
-the task's context area or on its stack. However, the
-stack pointer and address to resume executing the task
-at must be included in the context (normally the subroutine
-return address to the caller of ``_Thread_Dispatch``.
-The decision of where to store the task's context is based
-on numerous factors including the capabilities of
-the CPU architecture itself and simplicity as well
-as external considerations such as debuggers wishing
-to examine a task's context. In this case, it is
-often simpler to save all data in the context area.
-
-Also there may be special considerations
-when loading the stack pointers or interrupt level of the
-incoming task. Independent of CPU specific considerations,
-if some context is saved on the task stack, then the porter
-must ensure that the stack pointer is adjusted *BEFORE*
-to make room for this context information before the
-information is written. Otherwise, an interrupt could
-occur writing over the context data. The following is
-an example of an *INCORRECT* sequence:
+This routine begins by saving the current state of the CPU (i.e. the
+context) in the context area at ``run``. Then the routine should load the
+CPU context pointed to by ``heir``. Loading the new context will cause a
+branch to its task code, so the task that invoked ``_CPU_Context_switch``
+will not run for a while. When, eventually, a context switch is
+made to load context from ``*run`` again, this task will resume and
+``_CPU_Context_switch`` will return to its caller.
+
+Care should be exercise when writing this routine. All registers
+assumed to be preserved across subroutine calls must be preserved.
+These registers may be saved in the task's context area or on its stack.
+However, the stack pointer and address to resume executing the task at
+must be included in the context (normally the subroutine return address to
+the caller of ``_Thread_Dispatch``. The decision of where to store the
+task's context is based on numerous factors including the capabilities
+of the CPU architecture itself and simplicity as well as external
+considerations such as debuggers wishing to examine a task's context.
+In this case, it is often simpler to save all data in the context area.
+
+Also there may be special considerations when loading the stack pointers
+or interrupt level of the incoming task. Independent of CPU specific
+considerations, if some context is saved on the task stack, then the
+porter must ensure that the stack pointer is adjusted *BEFORE* to make
+room for this context information before the information is written.
+Otherwise, an interrupt could occur writing over the context data.
+The following is an example of an *INCORRECT* sequence:
+
.. code-block:: c
save part of context beyond current top of stack
@@ -236,6 +244,7 @@ The _CPU_Context_restore routine is generally used only to restart the
currently executing thread (i.e. self) in an efficient manner. In many
ports, it can simply be a label in _CPU_Context_switch. It may be
unnecessary to reload some registers.
+
.. code-block:: c
void _CPU_Context_restore(
@@ -255,6 +264,7 @@ self conflicts with the stack frame assumptions of restoring a context.
The following is an implementation of _CPU_Context_Restart_self that can
be used when no special handling is required for this case.
+
.. code-block:: c
#define _CPU_Context_Restart_self( _the_context ) \
@@ -282,6 +292,7 @@ determines whether every POSIX thread has a floating point context.
The following example illustrates how the CPU_HARDWARE_FP (XXX macro name
is varying) macro is set based on the CPU family dependent macro.
+
.. code-block:: c
#if ( THIS_CPU_FAMILY_HAS_FPU == 1 ) /* where THIS_CPU_FAMILY */
@@ -333,12 +344,13 @@ port would not have to have this option set to TRUE.
The following example illustrates how the CPU_ALL_TASKS_ARE_FP is set on
the PowerPC. On this CPU family, this macro is set to TRUE if the CPU
model has hardware floating point.
+
.. code-block:: c
#if (CPU_HARDWARE_FP == TRUE)
- #define CPU_ALL_TASKS_ARE_FP TRUE
+ #define CPU_ALL_TASKS_ARE_FP TRUE
#else
- #define CPU_ALL_TASKS_ARE_FP FALSE
+ #define CPU_ALL_TASKS_ARE_FP FALSE
#endif
NOTE: If CPU_HARDWARE_FP is FALSE, then this should be FALSE as well.
@@ -382,6 +394,7 @@ task, the FP context will never be saved or restored.
The following illustrates setting the CPU_USE_DEFERRED_FP_SWITCH macro on
a processor family such as the M68K or i386 which can use deferred
floating point context switches.
+
.. code-block:: c
#define CPU_USE_DEFERRED_FP_SWITCH TRUE
@@ -404,10 +417,11 @@ context switch routines. In this case, there is no need to figure out the
exact format - only the size. Of course, although this is enough
information for RTEMS, it is probably not enough for a debugger such as
gdb. But that is another problem.
+
.. code-block:: c
typedef struct {
- double some_float_register;
+ double some_float_register;
} Context_Control_fp;
On some CPUs with hardware floating point support, the Context_Control_fp
@@ -423,6 +437,7 @@ usually on CPUs with a "floating point save context" instruction. In
general, though it is easier to define the structure as a "sizeof"
operation and define the Context_Control_fp structure to be an area of
bytes of the required size in this case.
+
.. code-block:: c
#define CPU_CONTEXT_FP_SIZE sizeof( Context_Control_fp )
@@ -436,6 +451,7 @@ This is a common implementation of the _CPU_Context_Fp_start routine which
is suitable for many processors. In particular, RISC processors tend to
use this implementation since the floating point context is saved as a
sequence of store operations.
+
.. code-block:: c
#define _CPU_Context_Fp_start( _base, _offset ) \
@@ -466,15 +482,17 @@ _CPU_Null_fp_context. Then all that is required to initialize a floating
point context is to copy _CPU_Null_fp_context to the destination floating
point context passed to it. The following example implementation shows
how to accomplish this:
+
.. code-block:: c
#define _CPU_Context_Initialize_fp( _destination ) \
{ \
- *((Context_Control_fp *) *((void **) _destination)) = \\
- _CPU_Null_fp_context; \\
+ *((Context_Control_fp *) *((void **) _destination)) = \
+ _CPU_Null_fp_context; \
}
The _CPU_Null_fp_context is optional. A port need only include this variable when it uses the above mechanism to initialize a floating point context. This is typically done on CPUs where it is difficult to generate an "uninitialized" FP context. If the port requires this variable, then it is declared as follows:
+
.. code-block:: c
Context_Control_fp _CPU_Null_fp_context;
@@ -483,13 +501,14 @@ Saving a Floating Point Context
-------------------------------
The _CPU_Context_save_fp_context routine is responsible for saving the FP
-context at *fp_context_ptr. If the point to load the FP context from is
+context at ``*fp_context_ptr``. If the point to load the FP context from is
changed then the pointer is modified by this routine.
Sometimes a macro implementation of this is in cpu.h which dereferences
-the ** and a similarly named routine in this file is passed something like
-a (Context_Control_fp *). The general rule on making this decision is to
+the ``**`` and a similarly named routine in this file is passed something like
+a ``(Context_Control_fp *)``. The general rule on making this decision is to
avoid writing assembly language.
+
.. code-block:: c
void _CPU_Context_save_fp(
@@ -500,22 +519,16 @@ Restoring a Floating Point Context
----------------------------------
The _CPU_Context_restore_fp_context is responsible for restoring the FP
-context at *fp_context_ptr. If the point to load the FP context from is
+context at ``*fp_context_ptr``. If the point to load the FP context from is
changed then the pointer is modified by this routine.
Sometimes a macro implementation of this is in cpu.h which dereferences
-the ** and a similarly named routine in this file is passed something like
-a (Context_Control_fp *). The general rule on making this decision is to
+the ``**`` and a similarly named routine in this file is passed something like
+a ``(Context_Control_fp *)``. The general rule on making this decision is to
avoid writing assembly language.
+
.. code-block:: c
void _CPU_Context_restore_fp(
- void **fp_context_ptr
+ void **fp_context_ptr
);
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
More information about the vc
mailing list