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