1.\" $NetBSD: bits.3,v 1.9 2010/08/27 09:13:38 jruoho Exp $ 2.\" 3.\" Copyright (c) 2006, 2010 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 August 27, 2010 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/param.h 40.In sys/cdefs.h 41.Ft uint32_t 42.Fn __BIT "n" 43.Ft uint32_t 44.Fn __BITS "m" "n" 45.Fn __SHIFTIN "v" "mask" 46.Fn __SHIFTOUT "v" "mask" 47.Fn __SHIFTOUT_MASK "mask" 48.Sh DESCRIPTION 49These macros prepare bitmasks, extract bitfields from words, and 50insert bitfields into words. 51A 52.Dq bitfield 53is a span of consecutive bits defined by a bitmask, where 1s select 54the bits in the bitfield. 55.Pp 56Use 57.Fn __BIT 58and 59.Fn __BITS 60to define bitmasks: 61.Pp 62.Bl -tag -width __BITS -offset indent 63.It Fn __BIT "n" 64Return a bitmask with bit m set, where the least significant bit is bit 0. 65.It Fn __BITS "m" "n" 66Return a bitmask with bits 67.Fa m 68through 69.Fa n , 70inclusive, set. 71It does not matter whether 72.Fa m No \*[Gt] Fa n 73or 74.Fa m No \*[Lt]= Fa n . 75The least significant bit is bit 0. 76.El 77.Pp 78.Fn __SHIFTIN , 79.Fn __SHIFTOUT , 80and 81.Fn __SHIFTOUT_MASK 82help read and write bitfields from words: 83.Pp 84.Bl -tag -width __SHIFTOUT_MASK -offset indent 85.It Fn __SHIFTIN "v" "mask" 86Left-shift bits 87.Fa v 88into the bitfield defined by 89.Fa mask , 90and return them. 91No side-effects. 92.It Fn __SHIFTOUT "v" "mask" 93Extract and return the bitfield selected by 94.Fa mask 95from 96.Fa v , 97right-shifting the bits so that the rightmost selected bit is at 98bit 0. 99No side-effects. 100.It Fn __SHIFTOUT_MASK "mask" 101Right-shift the bits in 102.Fa mask 103so that the rightmost non-zero bit is at bit 0. 104This is useful for finding the greatest unsigned value that a 105bitfield can hold. 106No side-effects. 107Note that 108.Fn __SHIFTOUT_MASK "m" 109= 110.Fn __SHIFTOUT "m" "m" . 111.El 112.Sh EXAMPLES 113The following example demonstrates basic usage of the 114.Nm bits 115macros: 116.Bd -literal -offset indent 117uint32_t bits, mask, val; 118 119bits = __BITS(2, 3); /* 00001100 */ 120mask = __BIT(2) | __BIT(3); /* 00001100 */ 121 122val = __SHIFTIN(0x03, mask); /* 00001100 */ 123val = __SHIFTOUT(0xf, mask); /* 00000011 */ 124.Ed 125.Sh HISTORY 126The 127.Nm bits 128macros first appeared in 129.Xr atw 4 , 130with different names and implementation. 131In their current form these macros appeared in 132.Nx 4.0 . 133.Sh AUTHORS 134The 135.Nm bits 136macros were written by 137.An David Young Aq dyoung@NetBSD.org . 138.An Matt Thomas Aq matt@NetBSD.org 139suggested important improvements to the implementation, and 140contributed the macro names 141.Fn SHIFTIN 142and 143.Fn SHIFTOUT . 144.Sh BUGS 145.Fn __BIT 146and 147.Fn __BITS 148can only express 32-bit bitmasks. 149