Updated: 2021/Apr/14

BITS(3)                    Library Functions Manual                    BITS(3)

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

     #include <sys/param.h>
     #include <sys/cdefs.h>


     __BITS(m, n);

     __SHIFTIN(v, mask);

     __SHIFTOUT(v, mask);


     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:

                   Return a bitmask with bit n 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-

                            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).

     The following example demonstrates basic usage of the bits macros:

           uint32_t bits, mask, val;

           bits = __BITS(2, 3);                    /* 00001100 */
           mask = __BIT(2) | __BIT(3);             /* 00001100 */

           val = __SHIFTIN(0x03, mask);            /* 00001100 */
           val = __SHIFTOUT(0xf, mask);            /* 00000011 */

     bitops(3), cdefs(3)

     The bits macros first appeared in atw(4), with different names and
     implementation.  In their current form these macros appeared in
     NetBSD 4.0.

     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().

NetBSD 9.99                    November 6, 2016                    NetBSD 9.99