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 @code{_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 @code{CPU_BIG_ENDIAN} and @code{CPU_LITTLE_ENDIAN} are |
---|
50 | set to specify the endian |
---|
51 | format used by this microprocessor. These macros should not be set to the |
---|
52 | same value. The following example illustrates how these macros should be |
---|
53 | set on a processor family that is big endian. |
---|
54 | |
---|
55 | @example |
---|
56 | #define CPU_BIG_ENDIAN TRUE |
---|
57 | #define CPU_LITTLE_ENDIAN FALSE |
---|
58 | @end example |
---|
59 | |
---|
60 | @subsection Optional Endian Conversion Routines |
---|
61 | |
---|
62 | In a networked environment, each program communicating must agree on the |
---|
63 | format of data passed between the various systems in the networked |
---|
64 | application. Routines such as @code{ntohl()} |
---|
65 | and @code{htonl()} are used to convert |
---|
66 | between the common network format and the native format used on this |
---|
67 | particular host system. Although RTEMS has a portable implementation of |
---|
68 | these endian conversion routines, it is often possible to implement these |
---|
69 | routines more efficiently in a processor specific fashion. |
---|
70 | |
---|
71 | The @code{CPU_HAS_OWN_HOST_TO_NETWORK_ROUTINES} is set to TRUE when the port |
---|
72 | provides its own implementation of the network to host and host to network |
---|
73 | family of routines. This set of routines include the following: |
---|
74 | |
---|
75 | @itemize @bullet |
---|
76 | @item @code{ntohl()} |
---|
77 | @item @code{ntohs()} |
---|
78 | @item @code{htonl()} |
---|
79 | @item @code{htons()} |
---|
80 | @end itemize |
---|
81 | |
---|
82 | The following example illustrates how this macro should be set when the |
---|
83 | generic, portable implementation of this family of routines is to be used |
---|
84 | by this port: |
---|
85 | |
---|
86 | @example |
---|
87 | #define CPU_HAS_OWN_HOST_TO_NETWORK_ROUTINES FALSE |
---|
88 | @end example |
---|
89 | |
---|
90 | @section Extra Stack for MPCI Receive Thread |
---|
91 | |
---|
92 | The @code{CPU_MPCI_RECEIVE_SERVER_EXTRA_STACK} macro is set to the amount of |
---|
93 | stack space above the minimum thread stack space required by the MPCI |
---|
94 | Receive Server Thread. This macro is needed because in a multiprocessor |
---|
95 | system the MPCI Receive Server Thread must be able to process all |
---|
96 | directives. |
---|
97 | |
---|
98 | @example |
---|
99 | #define CPU_MPCI_RECEIVE_SERVER_EXTRA_STACK 0 |
---|
100 | @end example |
---|
101 | |
---|
102 | @subsection Endian Swap Unsigned Integers |
---|
103 | |
---|
104 | The port should provide routines to swap sixteen (@code{CPU_swap_u16}) and |
---|
105 | thirty-bit (@code{CPU_swap_u32}) unsigned integers. These are primarily used in |
---|
106 | two areas of RTEMS - multiprocessing support and the network endian swap |
---|
107 | routines. The @code{CPU_swap_u32} routine must be implemented as a static |
---|
108 | routine rather than a macro because its address is taken and used |
---|
109 | indirectly. On the other hand, the @code{CPU_swap_u16} routine may be |
---|
110 | implemented as a macro. |
---|
111 | |
---|
112 | Some CPUs have special instructions that swap a 32-bit quantity in a |
---|
113 | single instruction (e.g. i486). It is probably best to avoid an "endian |
---|
114 | swapping control bit" in the CPU. One good reason is that interrupts |
---|
115 | would probably have to be disabled to insure that an interrupt does not |
---|
116 | try to access the same "chunk" with the wrong endian. Another good reason |
---|
117 | is that on some CPUs, the endian bit endianness for ALL fetches -- both |
---|
118 | code and data -- so the code will be fetched incorrectly. |
---|
119 | |
---|
120 | The following is an implementation of the @code{CPU_swap_u32} routine that will |
---|
121 | work on any CPU. It operates by breaking the unsigned thirty-two bit |
---|
122 | integer into four byte-wide quantities and reassemblying them. |
---|
123 | |
---|
124 | @example |
---|
125 | static inline unsigned int CPU_swap_u32( |
---|
126 | unsigned int value |
---|
127 | ) |
---|
128 | @{ |
---|
129 | unsigned32 byte1, byte2, byte3, byte4, swapped; |
---|
130 | |
---|
131 | byte4 = (value >> 24) & 0xff; |
---|
132 | byte3 = (value >> 16) & 0xff; |
---|
133 | byte2 = (value >> 8) & 0xff; |
---|
134 | byte1 = value & 0xff; |
---|
135 | |
---|
136 | swapped = (byte1 << 24) | (byte2 << 16) | (byte3 << 8) | byte4; |
---|
137 | return( swapped ); |
---|
138 | @} |
---|
139 | @end example |
---|
140 | |
---|
141 | Although the above implementation is portable, it is not particularly |
---|
142 | efficient. So if there is a better way to implement this on a particular |
---|
143 | CPU family or model, please do so. The efficiency of this routine has |
---|
144 | significant impact on the efficiency of the multiprocessing support code |
---|
145 | in the shared memory driver and in network applications using the ntohl() |
---|
146 | family of routines. |
---|
147 | |
---|
148 | Most microprocessor families have rotate instructions which can be used to |
---|
149 | greatly improve the @code{CPU_swap_u32} routine. The most common |
---|
150 | way to do this is to: |
---|
151 | |
---|
152 | @example |
---|
153 | swap least significant two bytes with 16-bit rotate |
---|
154 | swap upper and lower 16-bits |
---|
155 | swap most significant two bytes with 16-bit rotate |
---|
156 | @end example |
---|
157 | |
---|
158 | Some CPUs have special instructions that swap a 32-bit quantity in a |
---|
159 | single instruction (e.g. i486). It is probably best to avoid an "endian |
---|
160 | swapping control bit" in the CPU. One good reason is that interrupts |
---|
161 | would probably have to be disabled to insure that an interrupt does not |
---|
162 | try to access the same "chunk" with the wrong endian. Another good reason |
---|
163 | is that on some CPUs, the endian bit endianness for ALL fetches -- both |
---|
164 | code and data -- so the code will be fetched incorrectly. |
---|
165 | |
---|
166 | Similarly, here is a portable implementation of the @code{CPU_swap_u16} |
---|
167 | routine. Just as with the @code{CPU_swap_u32} routine, the porter |
---|
168 | should provide a better implementation if possible. |
---|
169 | |
---|
170 | @example |
---|
171 | #define CPU_swap_u16( value ) \ |
---|
172 | (((value&0xff) << 8) | ((value >> 8)&0xff)) |
---|
173 | @end example |
---|
174 | |
---|
175 | |
---|