The following code tests to see whether bit 3 is set in the timer status register using the & operator:

if (*pTimerStatus & 0x08)
{
    /* Do something here... */
}

In this case, we’ll imagine that the value in the timer status register, contained in the variable pTimerStatus, is 0x4C; the & operator performs an AND operation with 0x08. The operation looks like this:

        0 1 0 0 1 1 0 0 (0x4C)
AND (&)
        0 0 0 0 1 0 0 0 (0x08)
       =======================
        0 0 0 0 1 0 0 0 (0x08)

Because the proper bit is set in the register, the code enters the if statement.

To set bit 4, the | operator is used as shown in the following code:

*pTimerStatus |= 0x10;

resulting in:

        0 1 0 0 1 1 0 0  (0x4C)
OR (|)
        0 0 0 1 0 0 0 0  (0x10)
       =================
        0 1 0 1 1 1 0 0  (0x5C)

The code to clear bit 2 uses the & and ~ operators as follows:

*pTimerStatus &= ~(0x04);

For this operation, the inverse of 0x04 equals 0xFB. The &= operator sets bit 2 of the timer status register to 0, while leaving all other bits unchanged. The operation looks like this:

        0 1 0 1 1 1 0 0  (0x5C)
AND (&)
NOT (~) 1 1 1 1 1 0 1 1  (0xFB)
       =================
        0 1 0 1 1 0 0 0  (0x58)

Note that all bits in the register remain the same except for the bit we want to clear.

It is sometimes useful to change a bit back and forth. For instance, you may want to blink an LED on and off. You may also want to toggle a bit back and forth, without having to check it first, and explicitly set or clear it. Toggling is done in C with the ^ operator. Here is the code to toggle bit 7 in the timer status register:

*pTimerStatus ^= 0x80;

This results in the following operation:

        0 1 0 1 1 0 0 0  (0x58)
XOR (^)
        1 0 0 0 0 0 0 0  (0x80)
       =================
        1 1 0 1 1 0 0 0  (0xD8)

Another type of useful bitwise operation is a shift. For example, consider what happens to the value of the 8-bit unsigned integer bitCount that contains 0xAC and is shifted right by 1 bit. Code demonstrating a right shift follows:

bitCount >>= 1;

This results in:

        1 0 1 0 1 1 0 0  (0xAC)
>> by 1
       =================
        0 1 0 1 0 1 1 0  (0x56)

In this case, a 0 is shifted in from the left. However, the C standard also allows the most significant bit to be repeated when the variable is signed. We recommend you use unsigned integers for variables on which you perform bit operations so that you will not have to worry about the different results on different compilers.

Assume the value of the 8-bit unsigned integer bitCount is again 0xAC and is shifted left by 2 bits:

bitCount <<= 2;

This results in:

        1 0 1 0 1 1 0 0  (0xAC)
<< by 2
       =================
        1 0 1 1 0 0 0 0  (0xB0)

One reason to use a shift is if you want to perform an operation on each bit of a register in turn; you can create a bitmask (discussed in the next section) with 1 bit set or clear and shift it so you can operate on the individual bits of the register.

A bitmask is a constant often used along with bitwise operators to manipulate one or more bits in a larger integer field. A bitmask is a constant binary pattern, such as the 16-bit hexadecimal literal 0x00FF, that can be used to mask specific bits. Bitmasks can be used with bitwise operators in order to set, test, clear, and toggle bits. Following are example bitmasks for the timer status register:

#define TIMER_COMPLETE              (0x08)
#define TIMER_ENABLE                (0xC0)

The bitmasks TIMER_COMPLETE and TIMER_ENABLE are descriptive names that correspond to specific bits in a peripheral’s register. Using a symbolic (e.g., #define) bitmask allows you to write code that is more descriptive and almost self-commented. By replacing hexadecimal literals with words, the definition makes it easier for you (or someone else) to understand the code at a later time. Here is an example of a bitwise operation involving a bitmask:

if (*pTimerStatus & TIMER_COMPLETE)
{
    /* Do something here... */
}

#define BIT(X)                      (1 << (X))

#define TIMER_STATUS             BIT(22)

A bitfield is a field of one or more bits within a larger integer value. Bitfields are useful for bit manipulations and are supported within a struct by C language compilers.

struct
{
    uint8_t  bit0   : 1;
    uint8_t  bit1   : 1;
    uint8_t  bit2   : 1;
    uint8_t  bit3   : 1;
    uint8_t  nibble : 4;
} foo;

Bits within a bitfield can be individually set, tested, cleared, and toggled without affecting the state of the other bits outside the bitfield.

To test bits using the bitfield, use code such as the following:

if (foo.bit0)
{
    /* Do other stuff. */
}

Here’s how to test a wider field (such as two bits) using a bitfield:

if (foo.nibble == 0x03)
{
    /* Do other stuff. */
}

To set a bit using a bitfield, use this code:

foo.bit1 = 1;

And use code such as the following to set multiple bits in a bitfield:

foo.nibble = 0xC;

To clear a bit using the bitfield, use this code:

foo.bit2 = 0;

And to toggle a bit using the bitfield, use this:

foo.bit3 = ~foo.bit3; /* or !foo.bit3 */

There are some issues you must be aware of should you decide to use bitfields. Bitfields are not portable; some compilers start from the least significant bit, while others start from the most significant bit. In some cases, the compiler may require enclosing the bitfield within a union; doing this makes the bitfield code portable across ANSI C compilers.

In the following example, we use a union to contain the bitfield. In addition to making the bitfield code portable, the union provides wider register access.

union
{
    uint8_t byte;
    struct
    {
        uint8_t  bit0   : 1;
        uint8_t  bit1   : 1;
        uint8_t  bit2   : 1;
        uint8_t  bit3   : 1;
        uint8_t  nibble : 4;
    } bits;
} foo;

Instead of accessing only individual bits, the register can be written to as a whole. For example, the bitfield union, along with bitmasks, can be useful when initializing a register, as shown here:

foo.byte = (TIMER_COMPLETE | TIMER_ENABLE);

while individual bits are still accessible, as shown here:

foo.bits.bit2 = 1;

Bitmasks are more efficient than bitfields in certain instances. Specifically, a bitmask is usually a better way to initialize several bits in a register. For example, the following code initializes the timer status register by setting the two bits denoted by the macros and clearing all others:

*pTimerStatus = (TIMER_COMPLETE | TIMER_ENABLE);

Setting and clearing bits using a bitfield is no faster than using a bitmask; with some compilers, it can be slower to use a bitfield. One benefit of using bitfields is that individual bitfields may be declared volatile or const. This is useful when a register is writeable but contains a few read-only bits.

/* Initialize timer write-only register. */
timerRegValue = TIMER_INTERRUPT;
*pTimerReg = timerRegValue;

timerRegValue |= TIMER_ENABLE;
*pTimerReg = timerRegValue;

The first step for the serial device driver is to define the register interface. For this example, we use a struct overlay for the UART registers, which are memory-mapped. The struct overlay, uart_t, is shown here:

typedef struct
{
    uint32_t data;
    uint32_t interruptEnable;
    uint32_t interruptStatus;
    uint32_t uartConfig;
    uint32_t pinConfig;
    uint32_t uartStatus;
    uint32_t pinStatus;
} volatile uart_t;

The variable pSerialPort is used to access the UART registers at address 0x40100000 and is defined as:

uart_t *pSerialPort = (uart_t *)(0x40100000);

Next, we define variables to track the current state of the hardware. A struct of serial driver parameters called serialparams_t is defined. The global variable gSerialParams is used in the serial device driver to encapsulate and help organize the configuration parameters.

The variable bInitialized is used in the serial initialization routine to keep track of the hardware configuration state. You may notice that in the following code, enumerated types are defined for the parity (parity_t), data bits (databits_t), and stop bits (stopbits_t). The enumerators are set to bitmask values in the UART configuration register. The enumerations simplify the UART configuration programming and help make the code more readable.

/* UART Config Register (LCR) Bit Descriptions */
#define DATABITS_LENGTH_0           (0x01)
#define DATABITS_LENGTH_1           (0x02)
#define STOP_BITS                   (0x04)
#define PARITY_ENABLE               (0x08)
#define EVEN_PARITY_ENABLE          (0x10)

typedef enum {PARITY_NONE, PARITY_ODD = PARITY_ENABLE,
              PARITY_EVEN = (PARITY_ENABLE | EVEN_PARITY_ENABLE)} parity_t;

typedef enum {DATA_5, DATA_6 = DATABITS_LENGTH_0, DATA_7 = DATABITS_LENGTH_1,
              DATA_8 = (DATABITS_LENGTH_0 | DATABITS_LENGTH_1)} databits_t;

typedef enum {STOP_1, STOP_2 = STOP_BITS} stopbits_t;

typedef struct
{
    uint32_t dataBits;
    uint32_t stopBits;
    uint32_t baudRate;
    parity_t parity;
} serialparams_t;

serialparams_t gSerialParams;

The initialization routine serialInit sets up the default communication parameters for the serial device driver. The UART registers are programmed in the routine serialConfig, which gets passed in the gSerialParams variable. The variable bInitialized is used to ensure that the serial port is configured only once.

/**********************************************************************
 *
 * Function:    serialInit
 *
 * Description: Initialize the serial port UART.
 * 
 * Notes:       This function is specific to the Arcom board.
 *              Default communication parameters are set in
 *              this function.
 *
 * Returns:     None.
 *
 **********************************************************************/
void serialInit(void)
{
    static int bInitialized = FALSE;

    /* Initialize the UART only once. */
    if (bInitialized == FALSE)
    {
        /* Set the communication parameters. */
        gSerialParams.baudRate = 115200;
        gSerialParams.dataBits = DATA_8;
        gSerialParams.parity = PARITY_NONE;
        gSerialParams.stopBits = STOP_1;

        serialConfig(&gSerialParams);

        bInitialized = TRUE;
    }
}

Now additional functionality can be added by defining other serial device driver API functions. A serial device driver API should have functions to send and receive characters. For sending characters, the function serialPutChar is used; for receiving characters, serialGetChar is used.

The serial device driver API function serialPutChar waits until the transmitter is ready and then sends a single character via the serial port. Transmitting is done by writing to the UART data register. The following code shows the serialPutChar function.

#define TRANSMITTER_EMPTY           (0x40)

/**********************************************************************
 *
 * Function:    serialPutChar
 *
 * Description: Send a character via the serial port.
 * 
 * Notes:       This function is specific to the Arcom board.
 *
 * Returns:     None.
 *
 **********************************************************************/
void serialPutChar(char outputChar)
{
    /* Wait until the transmitter is ready for the next character. */
    while ((pSerialPort->uartStatus & TRANSMITTER_EMPTY) == 0)
        ;

    /* Send the character via the serial port. */
    pSerialPort->data = outputChar;
}

The serial device driver API function serialGetChar waits until a character is received and then reads the character from the serial port. To determine whether a character has been received, the data ready bit is checked in the UART status register. The character received is returned to the calling function. Here is the serialGetChar function:

#define DATA_READY                  (0x01)

/**********************************************************************
 *
 * Function:    serialGetChar
 *
 * Description: Get a character from the serial port.
 * 
 * Notes:       This function is specific to the Arcom board.
 *
 * Returns:     The character received from the serial port.
 *
 **********************************************************************/
char serialGetChar(void)
{
    /* Wait for the next character to arrive. */
    while ((pSerialPort->uartStatus & DATA_READY) == 0)
        ;

    return pSerialPort->data;
}

Because this serial device driver does not use interrupts, the final step in the device driver philosophy—implementing device driver interrupt service routines—is skipped.