.\"	$NetBSD: bits.3,v 1.17.6.1 2019/09/02 16:39:22 martin 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 November 6, 2016
.Dt BITS 3
.Os
.Sh NAME
.Nm __BIT ,
.Nm __BITS ,
.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"
.Fn __SHIFTIN "v" "mask"
.Fn __SHIFTOUT "v" "mask"
.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
and
.Fn __BITS
to define bitmasks:
.Pp
.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.
.El
.Pp
.Fn __SHIFTIN ,
.Fn __SHIFTOUT ,
and
.Fn __SHIFTOUT_MASK
help read and write bitfields from words:
.Pp
.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 dyoung@NetBSD.org .
.An Matt Thomas Aq Mt matt@NetBSD.org
suggested important improvements to the implementation, and
contributed the macro names
.Fn SHIFTIN
and
.Fn SHIFTOUT .