BITS(3)                 NetBSD Library Functions Manual                BITS(3)

NAME
     __BIT, __BITS, __SHIFTIN, __SHIFTOUT, __SHIFTOUT_MASK -- macros for pre-
     paring 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 signifi-
                   cant 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 signif-
                   icant bit is bit 0.

     __SHIFTIN(), __SHIFTOUT(), and __SHIFTOUT_MASK() help read and write bit-
     fields 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 right-
                            most 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 bit-
                            field 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 imple-
     mentation.  bits macros appeared with their current names and implementa-
     tion 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.

NetBSD 5.0_STABLE                July 9, 2006                NetBSD 5.0_STABLE
