cpu.h File Reference

#include <rtems/score/no_cpu.h>
#include <rtems/score/types.h>

Include dependency graph for cpu.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct Context_Control

struct Context_Control_fp

struct CPU_Interrupt_frame

Defines

#define CPU_INLINE_ENABLE_DISPATCH   FALSE

#define CPU_UNROLL_ENQUEUE_PRIORITY   TRUE

#define CPU_HAS_SOFTWARE_INTERRUPT_STACK   FALSE

#define CPU_SIMPLE_VECTORED_INTERRUPTS   TRUE

#define CPU_HAS_HARDWARE_INTERRUPT_STACK   TRUE

#define CPU_ALLOCATE_INTERRUPT_STACK   TRUE

#define CPU_ISR_PASSES_FRAME_POINTER   0

#define CPU_HARDWARE_FP   FALSE

#define CPU_SOFTWARE_FP   FALSE

#define CPU_ALL_TASKS_ARE_FP   TRUE

#define CPU_IDLE_TASK_IS_FP   FALSE

#define CPU_USE_DEFERRED_FP_SWITCH   TRUE

#define CPU_PROVIDES_IDLE_THREAD_BODY   TRUE

#define CPU_STACK_GROWS_UP   TRUE

#define CPU_STRUCTURE_ALIGNMENT

#define CPU_BIG_ENDIAN   TRUE

#define CPU_LITTLE_ENDIAN   FALSE

#define CPU_MODES_INTERRUPT_MASK   0x00000001

#define _CPU_Context_Get_SP(_context)   (_context)->stack_pointer

#define CPU_CONTEXT_FP_SIZE   sizeof( Context_Control_fp )

#define CPU_MPCI_RECEIVE_SERVER_EXTRA_STACK   0

#define CPU_INTERRUPT_NUMBER_OF_VECTORS   32

#define CPU_INTERRUPT_MAXIMUM_VECTOR_NUMBER   (CPU_INTERRUPT_NUMBER_OF_VECTORS - 1)

#define CPU_PROVIDES_ISR_IS_IN_PROGRESS   FALSE

#define CPU_STACK_MINIMUM_SIZE   (1024*4)

#define CPU_ALIGNMENT   8

#define CPU_HEAP_ALIGNMENT   CPU_ALIGNMENT

#define CPU_PARTITION_ALIGNMENT   CPU_ALIGNMENT

#define CPU_STACK_ALIGNMENT   0

#define _CPU_Initialize_vectors()

#define _CPU_ISR_Disable(_isr_cookie)

#define _CPU_ISR_Enable(_isr_cookie)

#define _CPU_ISR_Flash(_isr_cookie)

#define _CPU_ISR_Set_level(new_level)

#define _CPU_Context_Initialize(_the_context, _stack_base, _size, _isr, _entry_point, _is_fp)

#define _CPU_Context_Restart_self(_the_context)   _CPU_Context_restore( (_the_context) );

#define _CPU_Context_Fp_start(_base, _offset)   ( (void *) _Addresses_Add_offset( (_base), (_offset) ) )

#define _CPU_Context_Initialize_fp(_destination)

#define _CPU_Fatal_halt(_error)

#define CPU_USE_GENERIC_BITFIELD_CODE   TRUE

#define CPU_USE_GENERIC_BITFIELD_DATA   TRUE

#define _CPU_Bitfield_Find_first_bit(_value, _output)

#define _CPU_Priority_Mask(_bit_number)   ( 1 << (_bit_number) )

#define _CPU_Priority_bits_index(_priority)   (_priority)

#define CPU_swap_u16(value)   (((value&0xff) << 8) | ((value >> 8)&0xff))

Functions

uint32_t _CPU_ISR_Get_level (void)

void _CPU_Initialize (void(*thread_dispatch))

void _CPU_ISR_install_raw_handler (uint32_t vector, proc_ptr new_handler, proc_ptr *old_handler)

void _CPU_ISR_install_vector (uint32_t vector, proc_ptr new_handler, proc_ptr *old_handler)

void _CPU_Install_interrupt_stack (void)

void * _CPU_Thread_Idle_body (uint32_t)

void _CPU_Context_switch (Context_Control *run, Context_Control *heir)

void _CPU_Context_restore (Context_Control *new_context)

void _CPU_Context_save_fp (Context_Control_fp **fp_context_ptr)

void _CPU_Context_restore_fp (Context_Control_fp **fp_context_ptr)

Variables

SCORE_EXTERN Context_Control_fp _CPU_Null_fp_context

SCORE_EXTERN void * _CPU_Interrupt_stack_low

SCORE_EXTERN void * _CPU_Interrupt_stack_high

SCORE_EXTERN void(* _CPU_Thread_dispatch_pointer )()

Detailed Description

Define Documentation

#define _CPU_Context_Initialize_fp ( _destination )

Value:

{ \
   *(*(_destination)) = _CPU_Null_fp_context; \
  }

This routine initializes the FP context area passed to it to. There are a few standard ways in which to initialize the floating point context. The code included for this macro assumes that this is a CPU in which a "initial" FP context was saved into _CPU_Null_fp_context and it simply copies it to the destination context passed to it.

Other floating point context save/restore models include:

not doing anything, and
putting a "null FP status word" in the correct place in the FP context.

Parameters:

[in] _destination is the floating point context area

Port Specific Information:

XXX document implementation including references if appropriate

#define _CPU_Context_Restart_self ( _the_context ) _CPU_Context_restore( (_the_context) );

This routine is responsible for somehow restarting the currently executing task. If you are lucky, then all that is necessary is restoring the context. Otherwise, there will need to be a special assembly routine which does something special in this case. For many ports, simply adding a label to the restore path of _CPU_Context_switch will work. On other ports, it may be possibly to load a few arguments and jump to the restore path. It will not work if restarting self conflicts with the stack frame assumptions of restoring a context.

Port Specific Information:

XXX document implementation including references if appropriate

Referenced by _Thread_Restart_self().

#define _CPU_Fatal_halt ( _error )

Value:

{ \
  }

This routine copies _error into a known place -- typically a stack location or a register, optionally disables interrupts, and halts/stops the CPU.

Port Specific Information:

XXX document implementation including references if appropriate

#define _CPU_Priority_Mask ( _bit_number ) ( 1 << (_bit_number) )

This routine builds the mask which corresponds to the bit fields as searched by _CPU_Bitfield_Find_first_bit. See the discussion for that routine.

Port Specific Information:

XXX document implementation including references if appropriate

#define CPU_ALIGNMENT 8

CPU's worst alignment requirement for data types on a byte boundary. This alignment does not take into account the requirements for the stack.

Port Specific Information:

XXX document implementation including references if appropriate

Referenced by _Addresses_Is_aligned().

#define CPU_ALL_TASKS_ARE_FP TRUE

Are all tasks RTEMS_FLOATING_POINT tasks implicitly?

If TRUE, then the RTEMS_FLOATING_POINT task attribute is assumed. If FALSE, then the RTEMS_FLOATING_POINT task attribute is followed.

So far, the only CPUs in which this option has been used are the HP PA-RISC and PowerPC. On the PA-RISC, The HP C compiler and gcc both implicitly used the floating point registers to perform integer multiplies. Similarly, the PowerPC port of gcc has been seen to allocate floating point local variables and touch the FPU even when the flow through a subroutine (like vfprintf()) might not use floating point formats.

If a function which you would not think utilize the FP unit DOES, then one can not easily predict which tasks will use the FP hardware. In this case, this option should be TRUE.

If CPU_HARDWARE_FP is FALSE, then this should be FALSE as well.

Port Specific Information:

XXX document implementation including references if appropriate

#define CPU_ALLOCATE_INTERRUPT_STACK TRUE

Does RTEMS allocate a dedicated interrupt stack in the Interrupt Manager?

If TRUE, then the memory is allocated during initialization. If FALSE, then the memory is allocated during initialization.

This should be TRUE is CPU_HAS_SOFTWARE_INTERRUPT_STACK is TRUE.

Port Specific Information:

XXX document implementation including references if appropriate

#define CPU_HARDWARE_FP FALSE

Does the CPU have hardware floating point?

If TRUE, then the RTEMS_FLOATING_POINT task attribute is supported. If FALSE, then the RTEMS_FLOATING_POINT task attribute is ignored.

If there is a FP coprocessor such as the i387 or mc68881, then the answer is TRUE.

The macro name "NO_CPU_HAS_FPU" should be made CPU specific. It indicates whether or not this CPU model has FP support. For example, it would be possible to have an i386_nofp CPU model which set this to false to indicate that you have an i386 without an i387 and wish to leave floating point support out of RTEMS.

#define CPU_HAS_HARDWARE_INTERRUPT_STACK TRUE

Does this CPU have hardware support for a dedicated interrupt stack?

If TRUE, then it must be installed during initialization. If FALSE, then no installation is performed.

If this is TRUE, CPU_ALLOCATE_INTERRUPT_STACK should also be TRUE.

Only one of CPU_HAS_SOFTWARE_INTERRUPT_STACK and CPU_HAS_HARDWARE_INTERRUPT_STACK should be set to TRUE. It is possible that both are FALSE for a particular CPU. Although it is unclear what that would imply about the interrupt processing procedure on that CPU.

Port Specific Information:

XXX document implementation including references if appropriate

#define CPU_HAS_SOFTWARE_INTERRUPT_STACK FALSE

Does RTEMS manage a dedicated interrupt stack in software?

If TRUE, then a stack is allocated in _ISR_Handler_initialization. If FALSE, nothing is done.

If the CPU supports a dedicated interrupt stack in hardware, then it is generally the responsibility of the BSP to allocate it and set it up.

If the CPU does not support a dedicated interrupt stack, then the porter has two options: (1) execute interrupts on the stack of the interrupted task, and (2) have RTEMS manage a dedicated interrupt stack.

If this is TRUE, CPU_ALLOCATE_INTERRUPT_STACK should also be TRUE.

Only one of CPU_HAS_SOFTWARE_INTERRUPT_STACK and CPU_HAS_HARDWARE_INTERRUPT_STACK should be set to TRUE. It is possible that both are FALSE for a particular CPU. Although it is unclear what that would imply about the interrupt processing procedure on that CPU.

Port Specific Information:

XXX document implementation including references if appropriate

#define CPU_HEAP_ALIGNMENT CPU_ALIGNMENT

This number corresponds to the byte alignment requirement for the heap handler. This alignment requirement may be stricter than that for the data types alignment specified by CPU_ALIGNMENT. It is common for the heap to follow the same alignment requirement as CPU_ALIGNMENT. If the CPU_ALIGNMENT is strict enough for the heap, then this should be set to CPU_ALIGNMENT.

Note:: This does not have to be a power of 2 although it should be a multiple of 2 greater than or equal to 2. The requirement to be a multiple of 2 is because the heap uses the least significant field of the front and back flags to indicate that a block is in use or free. So you do not want any odd length blocks really putting length data in that bit.

On byte oriented architectures, CPU_HEAP_ALIGNMENT normally will have to be greater or equal to than CPU_ALIGNMENT to ensure that elements allocated from the heap meet all restrictions.

Port Specific Information:

XXX document implementation including references if appropriate

#define CPU_IDLE_TASK_IS_FP FALSE

Should the IDLE task have a floating point context?

If TRUE, then the IDLE task is created as a RTEMS_FLOATING_POINT task and it has a floating point context which is switched in and out. If FALSE, then the IDLE task does not have a floating point context.

Setting this to TRUE negatively impacts the time required to preempt the IDLE task from an interrupt because the floating point context must be saved as part of the preemption.

Port Specific Information:

XXX document implementation including references if appropriate

#define CPU_INLINE_ENABLE_DISPATCH FALSE

Should the calls to _Thread_Enable_dispatch be inlined?

If TRUE, then they are inlined. If FALSE, then a subroutine call is made.

This conditional is an example of the classic trade-off of size versus speed. Inlining the call (TRUE) typically increases the size of RTEMS while speeding up the enabling of dispatching.

Note:: In general, the _Thread_Dispatch_disable_level will only be 0 or 1 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.

Port Specific Information:

XXX document implementation including references if appropriate

#define CPU_ISR_PASSES_FRAME_POINTER 0

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)?

Port Specific Information:

XXX document implementation including references if appropriate

#define CPU_MPCI_RECEIVE_SERVER_EXTRA_STACK 0

Amount of extra stack (above minimum stack size) required by MPCI receive server thread. Remember that in a multiprocessor system this thread must exist and be able to process all directives.

Port Specific Information:

XXX document implementation including references if appropriate

#define CPU_PARTITION_ALIGNMENT CPU_ALIGNMENT

This number corresponds to the byte alignment requirement for memory buffers allocated by the partition manager. This alignment requirement may be stricter than that for the data types alignment specified by CPU_ALIGNMENT. It is common for the partition to follow the same alignment requirement as CPU_ALIGNMENT. If the CPU_ALIGNMENT is strict enough for the partition, then this should be set to CPU_ALIGNMENT.

Note:: This does not have to be a power of 2. It does have to be greater or equal to than CPU_ALIGNMENT.

Port Specific Information:

XXX document implementation including references if appropriate

#define CPU_PROVIDES_IDLE_THREAD_BODY TRUE

Does this port provide a CPU dependent IDLE task implementation?

If TRUE, then the routine _CPU_Thread_Idle_body must be provided and is the default IDLE thread body instead of _CPU_Thread_Idle_body.

If FALSE, then use the generic IDLE thread body if the BSP does not provide one.

This is intended to allow for supporting processors which have a low power or idle mode. When the IDLE thread is executed, then the CPU can be powered down.

The order of precedence for selecting the IDLE thread body is:

BSP provided
CPU dependent (if provided)
generic (if no BSP and no CPU dependent)

Port Specific Information:

XXX document implementation including references if appropriate

#define CPU_SIMPLE_VECTORED_INTERRUPTS TRUE

Does the CPU follow the simple vectored interrupt model?

If TRUE, then RTEMS allocates the vector table it internally manages. If FALSE, then the BSP is assumed to allocate and manage the vector table

Port Specific Information:

XXX document implementation including references if appropriate

#define CPU_SOFTWARE_FP FALSE

Does the CPU have no hardware floating point and GCC provides a software floating point implementation which must be context switched?

This feature conditional is used to indicate whether or not there is software implemented floating point that must be context switched. The determination of whether or not this applies is very tool specific and the state saved/restored is also compiler specific.

Port Specific Information:

XXX document implementation including references if appropriate

#define CPU_STACK_ALIGNMENT 0

This number corresponds to the byte alignment requirement for the stack. This alignment requirement may be stricter than that for the data types alignment specified by CPU_ALIGNMENT. If the CPU_ALIGNMENT is strict enough for the stack, then this should be set to 0.

Note:: This must be a power of 2 either 0 or greater than CPU_ALIGNMENT.

Port Specific Information:

XXX document implementation including references if appropriate

Referenced by _Stack_Adjust_size().

#define CPU_STACK_GROWS_UP TRUE

Does the stack grow up (toward higher addresses) or down (toward lower addresses)?

If TRUE, then the grows upward. If FALSE, then the grows toward smaller addresses.

Port Specific Information:

XXX document implementation including references if appropriate

#define CPU_STRUCTURE_ALIGNMENT

The following is the variable attribute used to force alignment of critical RTEMS structures. On some processors it may make sense to have these aligned on tighter boundaries than the minimum requirements of the compiler in order to have as much of the critical data area as possible in a cache line.

The placement of this macro in the declaration of the variables is based on the syntactically requirements of the GNU C "__attribute__" extension. For example with GNU C, use the following to force a structures to a 32 byte boundary.

__attribute__ ((aligned (32)))

Note:: Currently only the Priority Bit Map table uses this feature. 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 turning this on.

Port Specific Information:

XXX document implementation including references if appropriate

#define CPU_UNROLL_ENQUEUE_PRIORITY TRUE

Should the body of the search loops in _Thread_queue_Enqueue_priority be 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.

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 the loop. On some CPUs, the flash is more expensive than one iteration of 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.

Port Specific Information:

XXX document implementation including references if appropriate

#define CPU_USE_DEFERRED_FP_SWITCH TRUE

Should the saving of the floating point registers be deferred until a context switch is made to another different floating point task?

If TRUE, then the floating point context will not be stored until necessary. It will remain in the floating point registers and not disturned until another floating point task is switched to.

If FALSE, then the floating point context is saved when a floating point task is switched out and restored when the next floating point task is restored. The state of the floating point registers between those two operations is not specified.

If the floating point context does NOT have to be saved as part of interrupt dispatching, then it should be safe to set this to TRUE.

Setting this flag to TRUE results in using a different algorithm for deciding when to save and restore the floating point context. The deferred FP switch algorithm minimizes the number of times the FP context is saved and restored. The FP context is not saved until a context switch is made to another, different FP task. Thus in a system with only one FP task, the FP context will never be saved or restored.

Port Specific Information:

XXX document implementation including references if appropriate

Function Documentation

void _CPU_Initialize ( void * thread_dispatch )

This routine performs CPU dependent initialization.

Parameters:

[in] thread_dispatch is the address of _Thread_Dispatch

Port Specific Information:

XXX document implementation including references if appropriate

void* _CPU_Thread_Idle_body ( uint32_t )

This routine is the CPU dependent IDLE thread body.

Note:: It need only be provided if CPU_PROVIDES_IDLE_THREAD_BODY is TRUE.

Port Specific Information:

XXX document implementation including references if appropriate

Variable Documentation

SCORE_EXTERN Context_Control_fp _CPU_Null_fp_context

This variable is optional. It is used on CPUs on which it is difficult to generate an "uninitialized" FP context. It is filled in by _CPU_Initialize and copied into the task's FP context area during _CPU_Context_Initialize.

Port Specific Information:

XXX document implementation including references if appropriate


Data Structures
struct	Context_Control
struct	Context_Control_fp
struct	CPU_Interrupt_frame
Defines
#define	CPU_INLINE_ENABLE_DISPATCH FALSE
#define	CPU_UNROLL_ENQUEUE_PRIORITY TRUE
#define	CPU_HAS_SOFTWARE_INTERRUPT_STACK FALSE
#define	CPU_SIMPLE_VECTORED_INTERRUPTS TRUE
#define	CPU_HAS_HARDWARE_INTERRUPT_STACK TRUE
#define	CPU_ALLOCATE_INTERRUPT_STACK TRUE
#define	CPU_ISR_PASSES_FRAME_POINTER 0
#define	CPU_HARDWARE_FP FALSE
#define	CPU_SOFTWARE_FP FALSE
#define	CPU_ALL_TASKS_ARE_FP TRUE
#define	CPU_IDLE_TASK_IS_FP FALSE
#define	CPU_USE_DEFERRED_FP_SWITCH TRUE
#define	CPU_PROVIDES_IDLE_THREAD_BODY TRUE
#define	CPU_STACK_GROWS_UP TRUE
#define	CPU_STRUCTURE_ALIGNMENT
#define	CPU_BIG_ENDIAN TRUE
#define	CPU_LITTLE_ENDIAN FALSE
#define	CPU_MODES_INTERRUPT_MASK 0x00000001
#define	_CPU_Context_Get_SP(_context) (_context)->stack_pointer
#define	CPU_CONTEXT_FP_SIZE sizeof( Context_Control_fp )
#define	CPU_MPCI_RECEIVE_SERVER_EXTRA_STACK 0
#define	CPU_INTERRUPT_NUMBER_OF_VECTORS 32
#define	CPU_INTERRUPT_MAXIMUM_VECTOR_NUMBER (CPU_INTERRUPT_NUMBER_OF_VECTORS - 1)
#define	CPU_PROVIDES_ISR_IS_IN_PROGRESS FALSE
#define	CPU_STACK_MINIMUM_SIZE (1024*4)
#define	CPU_ALIGNMENT 8
#define	CPU_HEAP_ALIGNMENT CPU_ALIGNMENT
#define	CPU_PARTITION_ALIGNMENT CPU_ALIGNMENT
#define	CPU_STACK_ALIGNMENT 0
#define	_CPU_Initialize_vectors()
#define	_CPU_ISR_Disable(_isr_cookie)
#define	_CPU_ISR_Enable(_isr_cookie)
#define	_CPU_ISR_Flash(_isr_cookie)
#define	_CPU_ISR_Set_level(new_level)
#define	_CPU_Context_Initialize(_the_context, _stack_base, _size, _isr, _entry_point, _is_fp)
#define	_CPU_Context_Restart_self(_the_context) _CPU_Context_restore( (_the_context) );
#define	_CPU_Context_Fp_start(_base, _offset) ( (void *) _Addresses_Add_offset( (_base), (_offset) ) )
#define	_CPU_Context_Initialize_fp(_destination)
#define	_CPU_Fatal_halt(_error)
#define	CPU_USE_GENERIC_BITFIELD_CODE TRUE
#define	CPU_USE_GENERIC_BITFIELD_DATA TRUE
#define	_CPU_Bitfield_Find_first_bit(_value, _output)
#define	_CPU_Priority_Mask(_bit_number) ( 1 << (_bit_number) )
#define	_CPU_Priority_bits_index(_priority) (_priority)
#define	CPU_swap_u16(value) (((value&0xff) << 8) \| ((value >> 8)&0xff))
Functions
uint32_t	_CPU_ISR_Get_level (void)
void	_CPU_Initialize (void(*thread_dispatch))
void	_CPU_ISR_install_raw_handler (uint32_t vector, proc_ptr new_handler, proc_ptr *old_handler)
void	_CPU_ISR_install_vector (uint32_t vector, proc_ptr new_handler, proc_ptr *old_handler)
void	_CPU_Install_interrupt_stack (void)
void *	_CPU_Thread_Idle_body (uint32_t)
void	_CPU_Context_switch (Context_Control run, Context_Control heir)
void	_CPU_Context_restore (Context_Control *new_context)
void	_CPU_Context_save_fp (Context_Control_fp **fp_context_ptr)
void	_CPU_Context_restore_fp (Context_Control_fp **fp_context_ptr)
Variables
SCORE_EXTERN Context_Control_fp	_CPU_Null_fp_context
SCORE_EXTERN void *	_CPU_Interrupt_stack_low
SCORE_EXTERN void *	_CPU_Interrupt_stack_high
SCORE_EXTERN void(*	_CPU_Thread_dispatch_pointer )()