\"      $NetBSD: bits.3,v 1.22 2022/01/22 09:22:41 wiz Exp $
\"
\" Copyright (c) 2006, 2010 David Young.  All rights reserved.
\"
\" Redistribution and use in source and binary forms, with or
\" without modification, are permitted provided that the following
\" conditions are met:
\" 1. Redistributions of source code must retain the above copyright
\"    notice, this list of conditions and the following disclaimer.
\" 2. Redistributions in binary form must reproduce the above
\"    copyright notice, this list of conditions and the following
\"    disclaimer in the documentation and/or other materials
\"    provided with the distribution.
\"
\" THIS SOFTWARE IS PROVIDED BY DAVID YOUNG ``AS IS'' AND ANY
\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
\" THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
\" PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL DAVID
\" YOUNG BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
\" TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
\" POSSIBILITY OF SUCH DAMAGE.
\"
Dd January 22, 2022
Dt BITS 3
Os
Sh NAME
Nm __BIT ,
Nm __BITS ,
Nm __MASK ,
Nm __SHIFTIN ,
Nm __SHIFTOUT ,
Nm __SHIFTOUT_MASK
Nd "macros for preparing bitmasks and operating on bit fields"
Sh SYNOPSIS
In sys/param.h
In sys/cdefs.h
Ft uintmax_t
Fn __BIT "n"
Ft uintmax_t
Fn __BITS "m" "n"
Ft uintmax_t
Fn __MASK "n"
Ft uintmax_t
Fn __SHIFTIN "v" "mask"
Ft uintmax_t
Fn __SHIFTOUT "v" "mask"
Ft uintmax_t
Fn __SHIFTOUT_MASK "mask"
Sh DESCRIPTION
These macros prepare bitmasks, extract bitfields from words, and
insert bitfields into words.
A
Dq bitfield
is a span of consecutive bits defined by a bitmask, where 1s select
the bits in the bitfield.
Pp
Use
Fn __BIT ,
Fn __BITS ,
and
Fn __MASK
to define bitmasks:
Bl -tag -width __BITS -offset indent
It Fn __BIT "n"
Return a bitmask with bit
Fa n
set, where the least significant bit is bit 0.
It Fn __BITS "m" "n"
Return a bitmask with bits
Fa m
through
Fa n ,
inclusive, set.
It does not matter whether
Fa m No > Fa n
or
Fa m No <= Fa n .
The least significant bit is bit 0.
It Fn __MASK "n"
Return a bitmask with the first
Fa n
bits set.
That is, bits 0 through
Fa n
- 1, inclusive, set.
El
Pp
Fn __SHIFTIN ,
Fn __SHIFTOUT ,
and
Fn __SHIFTOUT_MASK
help read and write bitfields from words:
Bl -tag -width __SHIFTOUT_MASK -offset indent
It Fn __SHIFTIN "v" "mask"
Left-shift bits
Fa v
into the bitfield defined by
Fa mask ,
and return them.
No side-effects.
It Fn __SHIFTOUT "v" "mask"
Extract and return the bitfield selected by
Fa mask
from
Fa v ,
right-shifting the bits so that the rightmost selected bit is at
bit 0.
No side-effects.
It Fn __SHIFTOUT_MASK "mask"
Right-shift the bits in
Fa 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
Fn __SHIFTOUT_MASK "m"
=
Fn __SHIFTOUT "m" "m" .
El
Sh EXAMPLES
The following example demonstrates basic usage of the
Nm bits
macros:
Bd -literal -offset indent
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 */
Ed
Sh SEE ALSO
Xr bitops 3 ,
Xr cdefs 3
Sh HISTORY
The
Nm bits
macros first appeared in
Xr atw 4 ,
with different names and implementation.
In their current form these macros appeared in
Nx 4.0 .
Sh AUTHORS
The
Nm bits
macros were written by
An David Young Aq Mt [email protected] .
An Matt Thomas Aq Mt [email protected]
suggested important improvements to the implementation, and
contributed the macro names
Fn SHIFTIN
and
Fn SHIFTOUT .