diff options
author | Amar Takhar <amar@rtems.org> | 2016-01-16 19:08:48 -0500 |
---|---|---|
committer | Amar Takhar <verm@darkbeer.org> | 2016-05-02 20:51:23 -0400 |
commit | 6733466adf26030f781c2779747472150238cadd (patch) | |
tree | 3d04d21658ddf18562cefa4d9c8f18dd1d6b4459 /porting/miscellanous.rst | |
parent | Fix markup (diff) | |
download | rtems-docs-6733466adf26030f781c2779747472150238cadd.tar.bz2 |
Split document into seperate files by section.
Diffstat (limited to 'porting/miscellanous.rst')
-rw-r--r-- | porting/miscellanous.rst | 155 |
1 files changed, 155 insertions, 0 deletions
diff --git a/porting/miscellanous.rst b/porting/miscellanous.rst new file mode 100644 index 0000000..9bbd712 --- /dev/null +++ b/porting/miscellanous.rst @@ -0,0 +1,155 @@ +Miscellaneous +############# + +Fatal Error Default Handler +=========================== + +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:: c + + void _CPU_Fatal_halt( + unsigned32 _error + ); + +CPU Context Validation +====================== + +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:: c + + void _CPU_Context_volatile_clobber( uintptr_t pattern ); + void _CPU_Context_validate( uintptr_t pattern ); + +The ``_CPU_Context_volatile_clobber()`` function clobbers all volatile +registers with values derived from the pattern parameter. This makes sure that +the interrupt prologue code restores all volatile registers of the interrupted +context. + +The ``_CPU_Context_validate()`` function initializes and validates the CPU +context with values derived from the pattern parameter. This function will not +return if the CPU context remains consistent. In case this function returns +the CPU port is broken. The test uses two threads which concurrently validate +the CPU context with a different patterns for each thread. This ensures that +the context switching code works. + +Processor Endianness +==================== + +Endianness refers to the order in which numeric values are stored in +memory by the microprocessor. Big endian architectures store the most +significant byte of a multi-byte numeric value in the byte with the lowest +address. This results in the hexadecimal value 0x12345678 being stored as +0x12345678 with 0x12 in the byte at offset zero, 0x34 in the byte at +offset one, etc.. The Motorola M68K and numerous RISC processor families +is big endian. Conversely, little endian architectures store the least +significant byte of a multi-byte numeric value in the byte with the lowest +address. This results in the hexadecimal value 0x12345678 being stored as +0x78563412 with 0x78 in the byte at offset zero, 0x56 in the byte at +offset one, etc.. The Intel ix86 family is little endian. +Interestingly, some CPU models within the PowerPC and MIPS architectures +can be switched between big and little endian modes. Most embedded +systems use these families strictly in big endian mode. + +RTEMS must be informed of the byte ordering for this microprocessor family +and, optionally, endian conversion routines may be provided as part of the +port. Conversion between endian formats is often necessary in +multiprocessor environments and sometimes needed when interfacing with +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. +.. code:: c + + #define CPU_BIG_ENDIAN TRUE + #define CPU_LITTLE_ENDIAN FALSE + +The ``CPU_MPCI_RECEIVE_SERVER_EXTRA_STACK`` macro is set to the amount of +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:: c + + #define CPU_MPCI_RECEIVE_SERVER_EXTRA_STACK 0 + +Endian Swap Unsigned Integers +----------------------------- + +The port should provide routines to swap sixteen (``CPU_swap_u16``) and +thirty-bit (``CPU_swap_u32``) unsigned integers. These are primarily used in +two areas of RTEMS - multiprocessing support and the network endian swap +routines. The ``CPU_swap_u32`` routine must be implemented as a static +routine rather than a macro because its address is taken and used +indirectly. On the other hand, the ``CPU_swap_u16`` routine may be +implemented as a macro. + +Some CPUs have special instructions that swap a 32-bit quantity in a +single instruction (e.g. i486). It is probably best to avoid an "endian +swapping control bit" in the CPU. One good reason is that interrupts +would probably have to be disabled to insure that an interrupt does not +try to access the same "chunk" with the wrong endian. Another good reason +is that on some CPUs, the endian bit endianness for ALL fetches – both +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:: c + + static inline unsigned int CPU_swap_u32( + 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 ); + } + +Although the above implementation is portable, it is not particularly +efficient. So if there is a better way to implement this on a particular +CPU family or model, please do so. The efficiency of this routine has +significant impact on the efficiency of the multiprocessing support code +in the shared memory driver and in network applications using the ntohl() +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:: c + + swap least significant two bytes with 16-bit rotate + swap upper and lower 16-bits + swap most significant two bytes with 16-bit rotate + +Some CPUs have special instructions that swap a 32-bit quantity in a +single instruction (e.g. i486). It is probably best to avoid an "endian +swapping control bit" in the CPU. One good reason is that interrupts +would probably have to be disabled to insure that an interrupt does not +try to access the same "chunk" with the wrong endian. Another good reason +is that on some CPUs, the endian bit endianness for ALL fetches – both +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:: c + + #define CPU_swap_u16( value ) \\ + (((value&0xff) << 8) | ((value >> 8)&0xff)) + |