154 lines
3.9 KiB
Groff
154 lines
3.9 KiB
Groff
.\" $NetBSD: bits.3,v 1.12 2011/04/30 19:34:10 jym 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 April 8, 2011
|
|
.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 uint32_t
|
|
.Fn __BIT "n"
|
|
.Ft uint32_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 \*[Gt] Fa n
|
|
or
|
|
.Fa m No \*[Lt]= 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 dyoung@NetBSD.org .
|
|
.An Matt Thomas Aq matt@NetBSD.org
|
|
suggested important improvements to the implementation, and
|
|
contributed the macro names
|
|
.Fn SHIFTIN
|
|
and
|
|
.Fn SHIFTOUT .
|
|
.Sh BUGS
|
|
.Fn __BIT
|
|
and
|
|
.Fn __BITS
|
|
can only express 32-bit bitmasks.
|