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