Changeset b0f2977 in rtems-docs for porting


Ignore:
Timestamp:
Oct 28, 2016, 1:01:47 AM (3 years ago)
Author:
Joel Sherrill <joel@…>
Branches:
4.11, master
Children:
4cacea0
Parents:
f29b7c1c
Message:

porting: Fix code-block markup

Location:
porting
Files:
7 edited

Legend:

Unmodified
Added
Removed
  • porting/code_tuning.rst

    rf29b7c1c rb0f2977  
    2222which in turns calls _Thread_Dispatch.  If the enable dispatch is inlined,
    2323then one subroutine call is avoided entirely.]
    24 .. code:: c
     24.. code-block:: c
    2525
    2626    #define CPU_INLINE_ENABLE_DISPATCH       FALSE
     
    4545interrupt disable period in RTEMS.  So it is necessary to strike a balance
    4646when setting this parameter.
    47 .. code:: c
     47.. code-block:: c
    4848
    4949    #define CPU_UNROLL_ENQUEUE_PRIORITY      TRUE
     
    8080ports which require no special alignment for optimized access to data
    8181structures:
    82 .. code:: c
     82.. code-block:: c
    8383
    8484    #define CPU_STRUCTURE_ALIGNMENT
     
    9898is a basic C data type for this port which much be aligned to an 8 byte
    9999boundary.
    100 .. code:: c
     100.. code-block:: c
    101101
    102102    #define CPU_ALIGNMENT              8
     
    117117when the required alignment for elements from the heap is the same as the
    118118basic CPU alignment requirements.
    119 .. code:: c
     119.. code-block:: c
    120120
    121121    #define CPU_HEAP_ALIGNMENT         CPU_ALIGNMENT
     
    141141Manager is the same as the basic CPU alignment requirements.
    142142
    143 .. code:: c
     143.. code-block:: c
    144144
    145145    #define CPU_PARTITION_ALIGNMENT    CPU_ALIGNMENT
  • porting/cpu_init.rst

    rf29b7c1c rb0f2977  
    1717
    1818The _CPU_Initialize routine performs processor dependent initialization.
    19 .. code:: c
     19.. code-block:: c
    2020
    2121    void _CPU_Initialize(
     
    3333If you encounter this problem save the entry point in a CPU dependent
    3434variable as shown below:
    35 .. code:: c
     35.. code-block:: c
    3636
    3737    _CPU_Thread_dispatch_pointer = thread_dispatch;
  • porting/idle_thread.rst

    rf29b7c1c rb0f2977  
    2323
    2424The following illustrates how to set this macro:
    25 .. code:: c
     25.. code-block:: c
    2626
    2727    #define CPU_IDLE_TASK_IS_FP      FALSE
     
    5757
    5858The following illustrates setting the CPU_PROVIDES_IDLE_THREAD_BODY macro:
    59 .. code:: c
     59.. code-block:: c
    6060
    6161    #define CPU_PROVIDES_IDLE_THREAD_BODY    TRUE
     
    7272CPU_PROVIDES_IDLE_THREAD_BODY macro should be defined to TRUE.  This
    7373routine is prototyped as follows:
    74 .. code:: c
     74.. code-block:: c
    7575
    7676    void *_CPU_Thread_Idle_body( uintptr_t );
     
    8181independent algorithm is used.  This algorithm consists of a "branch to
    8282self" which is implemented in a routine as follows.
    83 .. code:: c
     83.. code-block:: c
    8484
    8585    void *_Thread_Idle_body( uintptr_t ignored )
     
    9292in an infinite loop as the CPU will have to reexecute this instruction
    9393each time the IDLE thread is dispatched.
    94 .. code:: c
     94.. code-block:: c
    9595
    9696    void *_CPU_Thread_Idle_body( uintptr_t ignored )
  • porting/interrupts.rst

    rf29b7c1c rb0f2977  
    2929family like the Intel i386 where the CPU itself only recognizes two
    3030interrupt levels - enabled and disabled.
    31 .. code:: c
     31.. code-block:: c
    3232
    3333    #define CPU_MODES_INTERRUPT_MASK   0x00000001
     
    3737
    3838The _CPU_ISR_Get_level function returns the current interrupt level.
    39 .. code:: c
     39.. code-block:: c
    4040
    4141    uint32_t _CPU_ISR_Get_level( void )
     
    5555
    5656The following is a dummy implementation of the _CPU_ISR_Set_level routine:
    57 .. code:: c
     57.. code-block:: c
    5858
    5959    #define _CPU_ISR_Set_level( new_level ) \\
     
    6262
    6363The following is the implementation from the Motorola M68K:
    64 .. code:: c
     64.. code-block:: c
    6565
    6666    XXX insert m68k implementation here
     
    8585_CPU_ISR_Get_level and _CPU_ISR_Set_level routines. The following is a
    8686dummy implementation that simply sets the previous level to 0.
    87 .. code:: c
     87.. code-block:: c
    8888
    8989    #define _CPU_ISR_Disable( _isr_cookie ) \\
     
    9393
    9494The following is the implementation from the Motorola M68K port:
    95 .. code:: c
     95.. code-block:: c
    9696
    9797    XXX insert m68k port here
     
    106106to.  The following illustrates a dummy implementation of the
    107107_CPU_ISR_Enable routine:
    108 .. code:: c
     108.. code-block:: c
    109109
    110110    #define _CPU_ISR_Enable( _isr_cookie )  \\
     
    113113
    114114The following is the implementation from the Motorola M68K port:
    115 .. code:: c
     115.. code-block:: c
    116116
    117117    XXX insert m68k version here
     
    127127
    128128The following is a dummy implementation of the _CPU_ISR_Flash routine:
    129 .. code:: c
     129.. code-block:: c
    130130
    131131    #define _CPU_ISR_Flash( _isr_cookie ) \\
     
    134134
    135135The following is the implementation from the Motorola M68K port:
    136 .. code:: c
     136.. code-block:: c
    137137
    138138    XXX insert m68k version here
     
    180180
    181181NOTE: This should be TRUE is CPU_HAS_SOFTWARE_INTERRUPT_STACK is TRUE.
    182 .. code:: c
     182.. code-block:: c
    183183
    184184    #define CPU_ALLOCATE_INTERRUPT_STACK TRUE
    185185
    186186If 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.
    187 .. code:: c
     187.. code-block:: c
    188188
    189189    SCORE_EXTERN void               *_CPU_Interrupt_stack_low;
     
    201201
    202202NOTE:  It need only be provided if CPU_HAS_HARDWARE_INTERRUPT_STAC is TRUE.
    203 .. code:: c
     203.. code-block:: c
    204204
    205205    void _CPU_Install_interrupt_stack( void )
     
    212212
    213213The _CPU_ISR_install_raw_handler XXX
    214 .. code:: c
     214.. code-block:: c
    215215
    216216    void _CPU_ISR_install_raw_handler(
     
    236236indicates the highest vector number which can be looked up in the table
    237237and mapped into a user provided handler.
    238 .. code:: c
     238.. code-block:: c
    239239
    240240    #define CPU_INTERRUPT_NUMBER_OF_VECTORS      32
     
    252252old_handler - former ISR for this vector number
    253253new_handler - replacement ISR for this vector number
    254 .. code:: c
     254.. code-block:: c
    255255
    256256    void _CPU_ISR_install_vector(
     
    260260    )
    261261
    262 .. code:: c
     262.. code-block:: c
    263263
    264264    *old_handler = _ISR_Vector_table[ vector ];
     
    267267then we need to install the appropriate RTEMS interrupt handler for this
    268268vector number.
    269 .. code:: c
     269.. code-block:: c
    270270
    271271    _CPU_ISR_install_raw_handler( vector, new_handler, old_handler );
     
    273273We put the actual user ISR address in _ISR_vector_table.  This will be
    274274used by the ``_ISR_Handler`` so the user gets control.
    275 .. code:: c
     275.. code-block:: c
    276276
    277277    _ISR_Vector_table[ vector ] = new_handler;
     
    291291define the ``CPU_Interrupt_frame`` structure so that application code can
    292292examine the saved state.
    293 .. code:: c
     293.. code-block:: c
    294294
    295295    typedef struct {
     
    302302
    303303The ``_ISR_Handler`` routine provides the RTEMS interrupt management.
    304 .. code:: c
     304.. code-block:: c
    305305
    306306    void _ISR_Handler()
     
    334334which somehow place the vector number in a known place (which is safe if
    335335another interrupt nests this one) and branches to ``_ISR_Handler``.
    336 .. code:: c
     336.. code-block:: c
    337337
    338338    save some or all context on stack
     
    373373Does the RTEMS invoke the user's ISR with the vector number and a pointer
    374374to the saved interrupt frame (1) or just the vector number (0)?
    375 .. code:: c
     375.. code-block:: c
    376376
    377377    #define CPU_ISR_PASSES_FRAME_POINTER 0
     
    391391invoke that routine at the end of the interrupt sequence (if a dispatch is
    392392necessary).
    393 .. code:: c
     393.. code-block:: c
    394394
    395395    void (*_CPU_Thread_dispatch_pointer)();
  • porting/miscellanous.rst

    rf29b7c1c rb0f2977  
    1111a register, optionally disables interrupts, and halts/stops the CPU.  It
    1212is prototyped as follows and is often implemented as a macro:
    13 .. code:: c
     13.. code-block:: c
    1414
    1515    void _CPU_Fatal_halt(
     
    2424the CPU port.  These two functions are only used for this test and have no
    2525other purpose.
    26 .. code:: c
     26.. code-block:: c
    2727
    2828    void _CPU_Context_volatile_clobber( uintptr_t pattern );
     
    7373same value.  The following example illustrates how these macros should be
    7474set on a processor family that is big endian.
    75 .. code:: c
     75.. code-block:: c
    7676
    7777    #define CPU_BIG_ENDIAN                           TRUE
     
    8383system the MPCI Receive Server Thread must be able to process all
    8484directives.
    85 .. code:: c
     85.. code-block:: c
    8686
    8787    #define CPU_MPCI_RECEIVE_SERVER_EXTRA_STACK 0
     
    109109work on any CPU.  It operates by breaking the unsigned thirty-two bit
    110110integer into four byte-wide quantities and reassemblying them.
    111 .. code:: c
     111.. code-block:: c
    112112
    113113    static inline unsigned int CPU_swap_u32(
     
    134134greatly improve the ``CPU_swap_u32`` routine.  The most common
    135135way to do this is to:
    136 .. code:: c
     136.. code-block:: c
    137137
    138138    swap least significant two bytes with 16-bit rotate
     
    151151routine.  Just as with the ``CPU_swap_u32`` routine, the porter
    152152should provide a better implementation if possible.
    153 .. code:: c
     153.. code-block:: c
    154154
    155155    #define CPU_swap_u16( value ) \\
  • porting/priority_bitmap.rst

    rf29b7c1c rb0f2977  
    5555The _CPU_Bitfield_Find_first_bit routine sets _output to the bit number of
    5656the first bit set in ``_value``.  ``_value`` is of CPU dependent type``Priority_bit_map_Control``.  A stub version of this routine is as follows:
    57 .. code:: c
     57.. code-block:: c
    5858
    5959    #define _CPU_Bitfield_Find_first_bit( _value, _output ) \
     
    101101- 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:
    102102
    103   .. code:: c
     103  .. code-block:: c
    104104
    105105      _number = 0 if _value > 0x00ff
     
    117117performance port.  This is perfectly acceptable during development and
    118118testing phases.
    119 .. code:: c
     119.. code-block:: c
    120120
    121121    #define CPU_USE_GENERIC_BITFIELD_CODE TRUE
     
    127127available on all models in the CPU family.  In this case, one might find
    128128something like this stub example did:
    129 .. code:: c
     129.. code-block:: c
    130130
    131131    #if (CPU_USE_GENERIC_BITFIELD_CODE == FALSE)
     
    145145The following is a typical implementation when the
    146146_CPU_Bitfield_Find_first_bit searches for the most significant bit set:
    147 .. code:: c
     147.. code-block:: c
    148148
    149149    #if (CPU_USE_GENERIC_BITFIELD_CODE == FALSE)
     
    170170into a normalized form that is easier to process and use
    171171as an index.
    172 .. code:: c
     172.. code-block:: c
    173173
    174174    #if (CPU_USE_GENERIC_BITFIELD_CODE == FALSE)
  • porting/task_context.rst

    rf29b7c1c rb0f2977  
    2424
    2525The following illustrates how the CPU_STACK_GROWS_UP macro is set:
    26 .. code:: c
     26.. code-block:: c
    2727
    2828    #define CPU_STACK_GROWS_UP               TRUE
     
    4646The following illustrates setting the minimum stack size to 4 kilobytes
    4747per task.
    48 .. code:: c
     48.. code-block:: c
    4949
    5050    #define CPU_STACK_MINIMUM_SIZE          (1024*4)
     
    6161The following illustrates how the CPU_STACK_ALIGNMENT macro should be set
    6262when there are no special requirements:
    63 .. code:: c
     63.. code-block:: c
    6464
    6565    #define CPU_STACK_ALIGNMENT        0
     
    8989Additionally, if the GNU debugger gdb is to be made aware of RTEMS tasks
    9090for this CPU, then care should be used in designing the context area.
    91 .. code:: c
     91.. code-block:: c
    9292
    9393    typedef struct {
     
    119119of elements results in the simplest, most efficient implementation of XXX.
    120120A typical implementation starts with a definition such as the following:
    121 .. code:: c
     121.. code-block:: c
    122122
    123123    typedef struct {
     
    147147context.  The state of the "general data" registers is undefined at task
    148148start time. The _CPU_Context_initialize routine is prototyped as follows:
    149 .. code:: c
     149.. code-block:: c
    150150
    151151    void _CPU_Context_Initialize(
     
    184184The _CPU_Context_switch performs a normal non-FP context switch from the
    185185context of the current executing thread to the context of the heir thread.
    186 .. code:: c
     186.. code-block:: c
    187187
    188188    void _CPU_Context_switch(
     
    223223occur writing over the context data.  The following is
    224224an example of an *INCORRECT* sequence:
    225 .. code:: c
     225.. code-block:: c
    226226
    227227    save part of context beyond current top of stack
     
    237237ports, it can simply be a label in _CPU_Context_switch. It may be
    238238unnecessary to reload some registers.
    239 .. code:: c
     239.. code-block:: c
    240240
    241241    void _CPU_Context_restore(
     
    256256The following is an implementation of _CPU_Context_Restart_self that can
    257257be used when no special handling is required for this case.
    258 .. code:: c
     258.. code-block:: c
    259259
    260260    #define _CPU_Context_Restart_self( _the_context ) \
     
    283283The following example illustrates how the CPU_HARDWARE_FP (XXX macro name
    284284is varying) macro is set based on the CPU family dependent macro.
    285 .. code:: c
     285.. code-block:: c
    286286
    287287    #if ( THIS_CPU_FAMILY_HAS_FPU == 1 ) /* where THIS_CPU_FAMILY */
     
    334334the PowerPC.  On this CPU family, this macro is set to TRUE if the CPU
    335335model has hardware floating point.
    336 .. code:: c
     336.. code-block:: c
    337337
    338338    #if (CPU_HARDWARE_FP == TRUE)
     
    383383a processor family such as the M68K or i386 which can use deferred
    384384floating point context switches.
    385 .. code:: c
     385.. code-block:: c
    386386
    387387    #define CPU_USE_DEFERRED_FP_SWITCH       TRUE
     
    405405information for RTEMS, it is probably not enough for a debugger such as
    406406gdb.  But that is another problem.
    407 .. code:: c
     407.. code-block:: c
    408408
    409409    typedef struct {
     
    424424operation and define the Context_Control_fp structure to be an area of
    425425bytes of the required size in this case.
    426 .. code:: c
     426.. code-block:: c
    427427
    428428    #define CPU_CONTEXT_FP_SIZE sizeof( Context_Control_fp )
     
    437437use this implementation since the floating point context is saved as a
    438438sequence of store operations.
    439 .. code:: c
     439.. code-block:: c
    440440
    441441    #define _CPU_Context_Fp_start( _base, _offset ) \
     
    446446_CPU_Context_Fp_start is used in that port:
    447447
    448 .. code:: c
     448.. code-block:: c
    449449
    450450    XXX insert m68k version here
     
    467467point context passed to it.  The following example implementation shows
    468468how to accomplish this:
    469 .. code:: c
     469.. code-block:: c
    470470
    471471    #define _CPU_Context_Initialize_fp( _destination ) \
     
    476476
    477477The _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:
    478 .. code:: c
     478.. code-block:: c
    479479
    480480    Context_Control_fp  _CPU_Null_fp_context;
     
    491491a (Context_Control_fp *).  The general rule on making this decision is to
    492492avoid writing assembly language.
    493 .. code:: c
     493.. code-block:: c
    494494
    495495    void _CPU_Context_save_fp(
     
    508508a (Context_Control_fp *).  The general rule on making this decision is to
    509509avoid writing assembly language.
    510 .. code:: c
     510.. code-block:: c
    511511
    512512    void _CPU_Context_restore_fp(
Note: See TracChangeset for help on using the changeset viewer.