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