NetBSD/share/man/man3/bits.3

.\"	$NetBSD: bits.3,v 1.1 2006/08/31 19:24:37 dyoung Exp $
.\"
.\" Copyright (c) 2006 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.
.\" 3. The name of David Young may not be used to endorse or promote
.\"    products derived from this software without specific prior
.\"    written permission.
.\"
.\" 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 July 9, 2006
.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/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 __BIT and __BITS to define bitmasks:
.Pp
.Bl -tag -width __BITS -offset indent
.It Fn __BIT "n"
Return a bitmask with bit m 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 >
.Fa n or
.Fa m
<=
.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
.Bd -literal
/*
 * 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);
.Ed
.Sh HISTORY
The
.Nm bits
macros first appeared in
.Xr atw ,
with different names and implementation.
.Nm bits
macros appeared with their current names and implementation in
.Nx 4.0 .
.Sh BUGS
.Fn __BIT 
and
.Fn __BITS
can only express 32-bit bitmasks.
.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 .