July 9, 2006 BITS 3

### NAME

__BIT, __BITS, __SHIFTIN, __SHIFTOUT, __SHIFTOUT_MASK - macros for preparing bitmasks and operating on bit fields

### SYNOPSIS

```uint32_t` __BIT(```n`)
```uint32_t` __BITS(```m``, n`) __SHIFTIN(```v``, mask`) __SHIFTOUT(```v``, mask`) __SHIFTOUT_MASK(```mask`)

### DESCRIPTION

These macros prepare bitmasks, extract bitfields from words, and insert bitfields into words. A ``bitfield'' is a span of consecutive bits defined by a bitmask, where 1s select the bits in the bitfield.

Use __BIT and __BITS to define bitmasks:

__BIT(```n`)
  Return a bitmask with bit m set, where the least significant bit is bit 0.

__BITS(```m``, n`)
  Return a bitmask with bits ```m` through ```n`, inclusive, set. It does not matter whether ```m` >```n` or ```m` <=```n`. The least significant bit is bit 0.

__SHIFTIN(``), __SHIFTOUT(``), and __SHIFTOUT_MASK(``) help read and write bitfields from words:

__SHIFTIN(```v``, mask`)
  Left-shift bits ```v` into the bitfield defined by ```mask`, and return them. No side-effects.

__SHIFTOUT(```v``, mask`)
  Extract and return the bitfield selected by ```mask` from ```v`, right-shifting the bits so that the rightmost selected bit is at bit 0. No side-effects.

__SHIFTOUT_MASK(```mask`)
  Right-shift the bits in ```mask` so that the rightmost non-zero bit is at bit 0. This is useful for finding the greatest unsigned value that a bitfield can hold. No side-effects. Note that __SHIFTOUT_MASK(```m`) = __SHIFTOUT(```m``, m`).

### EXAMPLES

`

    /*
     * Register definitions taken from the RFMD RF3000 manual.
     */
    #define RF3000_GAINCTL          0x11            /* TX variable gain control */
    #define         RF3000_GAINCTL_TXVGC_MASK       __BITS(7, 2)
    #define         RF3000_GAINCTL_SCRAMBLER        __BIT(1)

    /*
     * Shift the transmit power into the transmit-power field of the
     * gain-control register and write it to the baseband processor.
     */
    atw_rf3000_write(sc, RF3000_GAINCTL,
        __SHIFTIN(txpower, RF3000_GAINCTL_TXVGC_MASK));

    /*
     * Register definitions taken from the ADMtek ADM8211 manual.
     *
     */
    #define ATW_RXSTAT_OWN  __BIT(31)               /* 1: NIC may fill descriptor */
    /* ... */
    #define ATW_RXSTAT_DA1  __BIT(17)               /* DA bit 1, admin'd address */
    #define ATW_RXSTAT_DA0          __BIT(16)       /* DA bit 0, group address */
    #define ATW_RXSTAT_RXDR_MASK    __BITS(15,12)   /* RX data rate */
    #define ATW_RXSTAT_FL_MASK      __BITS(11,0)    /* RX frame length, last
                                                     * descriptor only
                                                     */

    /* Extract the frame length from the Rx descriptor's
     * status field.
     */
    len = __SHIFTOUT(rxstat, ATW_RXSTAT_FL_MASK);

`

### HISTORY

The bits macros first appeared in atw(4), with different names and implementation. bits macros appeared with their current names and implementation in NetBSD4.0.

### AUTHORS

The bits macros were written by David Young <dyoung@NetBSD.org>
. Matt Thomas <matt@NetBSD.org>
suggested important improvements to the implementation, and contributed the macro names SHIFTIN(``) and SHIFTOUT(``).

### BUGS

__BIT(``) and __BITS(``) can only express 32-bit bitmasks.