1.\" $NetBSD: bits.3,v 1.3 2008/08/19 22:54:53 jnemeth Exp $ 2.\" 3.\" Copyright (c) 2006 David Young. All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or 6.\" without modification, are permitted provided that the following 7.\" conditions are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above 11.\" copyright notice, this list of conditions and the following 12.\" disclaimer in the documentation and/or other materials 13.\" provided with the distribution. 14.\" 3. The name of David Young may not be used to endorse or promote 15.\" products derived from this software without specific prior 16.\" written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY DAVID YOUNG ``AS IS'' AND ANY 19.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 20.\" THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 21.\" PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL DAVID 22.\" YOUNG BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 23.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED 24.\" TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 25.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 26.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 27.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 29.\" POSSIBILITY OF SUCH DAMAGE. 30.\" 31.Dd July 9, 2006 32.Dt BITS 3 33.Os 34.Sh NAME 35.Nm __BIT , 36.Nm __BITS , 37.Nm __SHIFTIN , 38.Nm __SHIFTOUT , 39.Nm __SHIFTOUT_MASK 40.Nd "macros for preparing bitmasks and operating on bit fields" 41.Sh SYNOPSIS 42.In sys/cdefs.h 43.Ft uint32_t 44.Fn __BIT "n" 45.Ft uint32_t 46.Fn __BITS "m" "n" 47.Fn __SHIFTIN "v" "mask" 48.Fn __SHIFTOUT "v" "mask" 49.Fn __SHIFTOUT_MASK "mask" 50.Sh DESCRIPTION 51These macros prepare bitmasks, extract bitfields from words, and 52insert bitfields into words. 53A 54.Dq bitfield 55is a span of consecutive bits defined by a bitmask, where 1s select 56the bits in the bitfield. 57.Pp 58Use __BIT and __BITS to define bitmasks: 59.Pp 60.Bl -tag -width __BITS -offset indent 61.It Fn __BIT "n" 62Return a bitmask with bit m set, where the least significant bit is bit 0. 63.It Fn __BITS "m" "n" 64Return a bitmask with bits 65.Fa m 66through 67.Fa n , 68inclusive, set. 69It does not matter whether 70.Fa m No \*[Gt] Fa n 71or 72.Fa m No \*[Lt]= Fa n . 73The least significant bit is bit 0. 74.El 75.Pp 76.Fn __SHIFTIN , 77.Fn __SHIFTOUT , 78and 79.Fn __SHIFTOUT_MASK 80help read and write bitfields from words: 81.Pp 82.Bl -tag -width __SHIFTOUT_MASK -offset indent 83.It Fn __SHIFTIN "v" "mask" 84Left-shift bits 85.Fa v 86into the bitfield defined by 87.Fa mask , 88and return them. 89No side-effects. 90.It Fn __SHIFTOUT "v" "mask" 91Extract and return the bitfield selected by 92.Fa mask 93from 94.Fa v , 95right-shifting the bits so that the rightmost selected bit is at 96bit 0. 97No side-effects. 98.It Fn __SHIFTOUT_MASK "mask" 99Right-shift the bits in 100.Fa mask 101so that the rightmost non-zero bit is at bit 0. 102This is useful for finding the greatest unsigned value that a 103bitfield can hold. 104No side-effects. 105Note that 106.Fn __SHIFTOUT_MASK "m" 107= 108.Fn __SHIFTOUT "m" "m" . 109.El 110.Sh EXAMPLES 111.Bd -literal 112/* 113 * Register definitions taken from the RFMD RF3000 manual. 114 */ 115#define RF3000_GAINCTL 0x11 /* TX variable gain control */ 116#define RF3000_GAINCTL_TXVGC_MASK __BITS(7, 2) 117#define RF3000_GAINCTL_SCRAMBLER __BIT(1) 118 119/* 120 * Shift the transmit power into the transmit-power field of the 121 * gain-control register and write it to the baseband processor. 122 */ 123atw_rf3000_write(sc, RF3000_GAINCTL, 124 __SHIFTIN(txpower, RF3000_GAINCTL_TXVGC_MASK)); 125 126/* 127 * Register definitions taken from the ADMtek ADM8211 manual. 128 * 129 */ 130#define ATW_RXSTAT_OWN __BIT(31) /* 1: NIC may fill descriptor */ 131/* ... */ 132#define ATW_RXSTAT_DA1 __BIT(17) /* DA bit 1, admin'd address */ 133#define ATW_RXSTAT_DA0 __BIT(16) /* DA bit 0, group address */ 134#define ATW_RXSTAT_RXDR_MASK __BITS(15,12) /* RX data rate */ 135#define ATW_RXSTAT_FL_MASK __BITS(11,0) /* RX frame length, last 136 * descriptor only 137 */ 138 139/* Extract the frame length from the Rx descriptor's 140 * status field. 141 */ 142len = __SHIFTOUT(rxstat, ATW_RXSTAT_FL_MASK); 143.Ed 144.Sh HISTORY 145The 146.Nm bits 147macros first appeared in 148.Xr atw 4 , 149with different names and implementation. 150.Nm bits 151macros appeared with their current names and implementation in 152.Nx 4.0 . 153.Sh AUTHORS 154The 155.Nm bits 156macros were written by 157.An David Young Aq dyoung@NetBSD.org . 158.An Matt Thomas Aq matt@NetBSD.org 159suggested important improvements to the implementation, and 160contributed the macro names 161.Fn SHIFTIN 162and 163.Fn SHIFTOUT . 164.Sh BUGS 165.Fn __BIT 166and 167.Fn __BITS 168can only express 32-bit bitmasks. 169