BSP Developer's Guide

5
Driver Guidelines
To fix this situation, create a new macro that is the value of the argument. Define it
at the head of the file in its proper place, then refer to it at the proper place in the
code. This results in a subroutine that is much easier to understand at first sight.
For example:
/* A better way */
#ifdef INCL_FOO
# define THE_FOO myFoo
#else
# define THE_FOO yourFoo
#endif
. . .
fooReset (&THE_FOO, arg2, arg3, arg4);
5
The general rule shall be to use conditional compilation if it really changes the flow
of execution within the routine. If only argument values, variable names, or
subroutine names are changed then use the technique above to define an
intermediate macro.
Be careful with macro names, neither too simple nor too complex. Both of the
following examples are unsatisfactory:
SIO_READ
NS16550_CONTROL_REGISTER_BIT_7_CLEAR
Do not use structures to declare hardware registers, or memory control blocks. Use
macros for offset constants or to convert a base address into a register address.
Structures are inherently non-portable. This is the single greatest source of failure
when porting drivers across architectures. Even using the same toolchain, the
default structure creation can vary from architecture to architecture. The C
language specification does not specify a standard for structure element
alignments.
typedef struct { /* I8250_DEV */
char CSR;
char DATA;
char MBR;
} I8250_DEV;
/* A better way */
#define I8250_CSR 0
#define I8250_DATA 1
#define I8250_MBR 2
99