forked from Imagelibrary/rtems
171 lines
6.6 KiB
Perl
171 lines
6.6 KiB
Perl
@c
|
|
@c COPYRIGHT (c) 1988-1999.
|
|
@c On-Line Applications Research Corporation (OAR).
|
|
@c All rights reserved.
|
|
@c
|
|
@c $Id$
|
|
@c
|
|
|
|
@chapter Miscellaneous
|
|
|
|
@section 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:
|
|
|
|
@example
|
|
void _CPU_Fatal_halt(
|
|
unsigned32 _error
|
|
);
|
|
@end example
|
|
|
|
@section 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.
|
|
|
|
@subsection 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.
|
|
|
|
@example
|
|
#define CPU_BIG_ENDIAN TRUE
|
|
#define CPU_LITTLE_ENDIAN FALSE
|
|
@end example
|
|
|
|
@subsection Optional Endian Conversion Routines
|
|
|
|
In a networked environment, each program communicating must agree on the
|
|
format of data passed between the various systems in the networked
|
|
application. Routines such as ntohl() and htonl() are used to convert
|
|
between the common network format and the native format used on this
|
|
particular host system. Although RTEMS has a portable implementation of
|
|
these endian conversion routines, it is often possible to implement these
|
|
routines more efficiently in a processor specific fashion.
|
|
|
|
The CPU_HAS_OWN_HOST_TO_NETWORK_ROUTINES is set to TRUE when the port
|
|
provides its own implementation of the network to host and host to network
|
|
family of routines. This set of routines include the following:
|
|
|
|
@itemize @bullet
|
|
@item XXX list of routines in bullets
|
|
@end itemize
|
|
|
|
The following example illustrates how this macro should be set when the
|
|
generic, portable implementation of this family of routines is to be used
|
|
by this port:
|
|
|
|
@example
|
|
#define CPU_HAS_OWN_HOST_TO_NETWORK_ROUTINES FALSE
|
|
@end example
|
|
|
|
@section Extra Stack for MPCI Receive Thread
|
|
|
|
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.
|
|
|
|
@example
|
|
#define CPU_MPCI_RECEIVE_SERVER_EXTRA_STACK 0
|
|
@end example
|
|
|
|
@subsection 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.
|
|
|
|
@example
|
|
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 );
|
|
@}
|
|
@end example
|
|
|
|
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:
|
|
|
|
@example
|
|
swap least significant two bytes with 16-bit rotate
|
|
swap upper and lower 16-bits
|
|
swap most significant two bytes with 16-bit rotate
|
|
@end example
|
|
|
|
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.
|
|
|
|
@example
|
|
#define CPU_swap_u16( value ) \
|
|
(((value&0xff) << 8) | ((value >> 8)&0xff))
|
|
@end example
|
|
|
|
|