169 lines
4.7 KiB
Groff
169 lines
4.7 KiB
Groff
.\" $NetBSD: bits.3,v 1.3 2008/08/19 22:54:53 jnemeth 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 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
|
|
.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 4 ,
|
|
with different names and implementation.
|
|
.Nm bits
|
|
macros appeared with their current names and implementation 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.
|