1 | Miscellaneous |
---|
2 | ############# |
---|
3 | |
---|
4 | Fatal Error Default Handler |
---|
5 | =========================== |
---|
6 | |
---|
7 | The ``_CPU_Fatal_halt`` routine is the default fatal error handler. This |
---|
8 | routine copies _error into a known place â typically a stack location or |
---|
9 | a register, optionally disables interrupts, and halts/stops the CPU. It |
---|
10 | is prototyped as follows and is often implemented as a macro: |
---|
11 | .. code:: c |
---|
12 | |
---|
13 | void _CPU_Fatal_halt( |
---|
14 | unsigned32 _error |
---|
15 | ); |
---|
16 | |
---|
17 | CPU Context Validation |
---|
18 | ====================== |
---|
19 | |
---|
20 | The test case ``sptests/spcontext01`` ensures that the context switching and |
---|
21 | interrupt processing works. This test uses two support functions provided by |
---|
22 | the CPU port. These two functions are only used for this test and have no |
---|
23 | other purpose. |
---|
24 | .. code:: c |
---|
25 | |
---|
26 | void _CPU_Context_volatile_clobber( uintptr_t pattern ); |
---|
27 | void _CPU_Context_validate( uintptr_t pattern ); |
---|
28 | |
---|
29 | The ``_CPU_Context_volatile_clobber()`` function clobbers all volatile |
---|
30 | registers with values derived from the pattern parameter. This makes sure that |
---|
31 | the interrupt prologue code restores all volatile registers of the interrupted |
---|
32 | context. |
---|
33 | |
---|
34 | The ``_CPU_Context_validate()`` function initializes and validates the CPU |
---|
35 | context with values derived from the pattern parameter. This function will not |
---|
36 | return if the CPU context remains consistent. In case this function returns |
---|
37 | the CPU port is broken. The test uses two threads which concurrently validate |
---|
38 | the CPU context with a different patterns for each thread. This ensures that |
---|
39 | the context switching code works. |
---|
40 | |
---|
41 | Processor Endianness |
---|
42 | ==================== |
---|
43 | |
---|
44 | Endianness refers to the order in which numeric values are stored in |
---|
45 | memory by the microprocessor. Big endian architectures store the most |
---|
46 | significant byte of a multi-byte numeric value in the byte with the lowest |
---|
47 | address. This results in the hexadecimal value 0x12345678 being stored as |
---|
48 | 0x12345678 with 0x12 in the byte at offset zero, 0x34 in the byte at |
---|
49 | offset one, etc.. The Motorola M68K and numerous RISC processor families |
---|
50 | is big endian. Conversely, little endian architectures store the least |
---|
51 | significant byte of a multi-byte numeric value in the byte with the lowest |
---|
52 | address. This results in the hexadecimal value 0x12345678 being stored as |
---|
53 | 0x78563412 with 0x78 in the byte at offset zero, 0x56 in the byte at |
---|
54 | offset one, etc.. The Intel ix86 family is little endian. |
---|
55 | Interestingly, some CPU models within the PowerPC and MIPS architectures |
---|
56 | can be switched between big and little endian modes. Most embedded |
---|
57 | systems use these families strictly in big endian mode. |
---|
58 | |
---|
59 | RTEMS must be informed of the byte ordering for this microprocessor family |
---|
60 | and, optionally, endian conversion routines may be provided as part of the |
---|
61 | port. Conversion between endian formats is often necessary in |
---|
62 | multiprocessor environments and sometimes needed when interfacing with |
---|
63 | peripheral controllers. |
---|
64 | |
---|
65 | Specifying Processor Endianness |
---|
66 | ------------------------------- |
---|
67 | |
---|
68 | The ``CPU_BIG_ENDIAN`` and ``CPU_LITTLE_ENDIAN`` are |
---|
69 | set to specify the endian |
---|
70 | format used by this microprocessor. These macros should not be set to the |
---|
71 | same value. The following example illustrates how these macros should be |
---|
72 | set on a processor family that is big endian. |
---|
73 | .. code:: c |
---|
74 | |
---|
75 | #define CPU_BIG_ENDIAN TRUE |
---|
76 | #define CPU_LITTLE_ENDIAN FALSE |
---|
77 | |
---|
78 | The ``CPU_MPCI_RECEIVE_SERVER_EXTRA_STACK`` macro is set to the amount of |
---|
79 | stack space above the minimum thread stack space required by the MPCI |
---|
80 | Receive Server Thread. This macro is needed because in a multiprocessor |
---|
81 | system the MPCI Receive Server Thread must be able to process all |
---|
82 | directives. |
---|
83 | .. code:: c |
---|
84 | |
---|
85 | #define CPU_MPCI_RECEIVE_SERVER_EXTRA_STACK 0 |
---|
86 | |
---|
87 | Endian Swap Unsigned Integers |
---|
88 | ----------------------------- |
---|
89 | |
---|
90 | The port should provide routines to swap sixteen (``CPU_swap_u16``) and |
---|
91 | thirty-bit (``CPU_swap_u32``) unsigned integers. These are primarily used in |
---|
92 | two areas of RTEMS - multiprocessing support and the network endian swap |
---|
93 | routines. The ``CPU_swap_u32`` routine must be implemented as a static |
---|
94 | routine rather than a macro because its address is taken and used |
---|
95 | indirectly. On the other hand, the ``CPU_swap_u16`` routine may be |
---|
96 | implemented as a macro. |
---|
97 | |
---|
98 | Some CPUs have special instructions that swap a 32-bit quantity in a |
---|
99 | single instruction (e.g. i486). It is probably best to avoid an "endian |
---|
100 | swapping control bit" in the CPU. One good reason is that interrupts |
---|
101 | would probably have to be disabled to insure that an interrupt does not |
---|
102 | try to access the same "chunk" with the wrong endian. Another good reason |
---|
103 | is that on some CPUs, the endian bit endianness for ALL fetches â both |
---|
104 | code and data â so the code will be fetched incorrectly. |
---|
105 | |
---|
106 | The following is an implementation of the ``CPU_swap_u32`` routine that will |
---|
107 | work on any CPU. It operates by breaking the unsigned thirty-two bit |
---|
108 | integer into four byte-wide quantities and reassemblying them. |
---|
109 | .. code:: c |
---|
110 | |
---|
111 | static inline unsigned int CPU_swap_u32( |
---|
112 | unsigned int value |
---|
113 | ) |
---|
114 | { |
---|
115 | unsigned32 byte1, byte2, byte3, byte4, swapped; |
---|
116 | byte4 = (value >> 24) & 0xff; |
---|
117 | byte3 = (value >> 16) & 0xff; |
---|
118 | byte2 = (value >> 8) & 0xff; |
---|
119 | byte1 = value & 0xff; |
---|
120 | swapped = (byte1 << 24) | (byte2 << 16) | (byte3 << 8) | byte4; |
---|
121 | return( swapped ); |
---|
122 | } |
---|
123 | |
---|
124 | Although the above implementation is portable, it is not particularly |
---|
125 | efficient. So if there is a better way to implement this on a particular |
---|
126 | CPU family or model, please do so. The efficiency of this routine has |
---|
127 | significant impact on the efficiency of the multiprocessing support code |
---|
128 | in the shared memory driver and in network applications using the ntohl() |
---|
129 | family of routines. |
---|
130 | |
---|
131 | Most microprocessor families have rotate instructions which can be used to |
---|
132 | greatly improve the ``CPU_swap_u32`` routine. The most common |
---|
133 | way to do this is to: |
---|
134 | .. code:: c |
---|
135 | |
---|
136 | swap least significant two bytes with 16-bit rotate |
---|
137 | swap upper and lower 16-bits |
---|
138 | swap most significant two bytes with 16-bit rotate |
---|
139 | |
---|
140 | Some CPUs have special instructions that swap a 32-bit quantity in a |
---|
141 | single instruction (e.g. i486). It is probably best to avoid an "endian |
---|
142 | swapping control bit" in the CPU. One good reason is that interrupts |
---|
143 | would probably have to be disabled to insure that an interrupt does not |
---|
144 | try to access the same "chunk" with the wrong endian. Another good reason |
---|
145 | is that on some CPUs, the endian bit endianness for ALL fetches â both |
---|
146 | code and data â so the code will be fetched incorrectly. |
---|
147 | |
---|
148 | Similarly, here is a portable implementation of the ``CPU_swap_u16`` |
---|
149 | routine. Just as with the ``CPU_swap_u32`` routine, the porter |
---|
150 | should provide a better implementation if possible. |
---|
151 | .. code:: c |
---|
152 | |
---|
153 | #define CPU_swap_u16( value ) \\ |
---|
154 | (((value&0xff) << 8) | ((value >> 8)&0xff)) |
---|
155 | |
---|