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