BITS(3)

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

SYNOPSIS
#include <sys/cdefs.h>
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 NetBSD 4.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.