share/man/man3/bits.3

   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 .\"
  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
  48 These macros prepare bitmasks, extract bitfields from words, and
  49 insert bitfields into words.
  50 A
  51 .Dq bitfield
  52 is a span of consecutive bits defined by a bitmask, where 1s select
  53 the bits in the bitfield.
  54 .Pp
  55 Use __BIT and __BITS to define bitmasks:
  56 .Pp
  57 .Bl -tag -width __BITS -offset indent
  58 .It Fn __BIT "n"
  59 Return a bitmask with bit m set, where the least significant bit is bit 0.
  60 .It Fn __BITS "m" "n"
  61 Return a bitmask with bits
  62 .Fa m
  63 through
  64 .Fa n ,
  65 inclusive, set.
  66 It does not matter whether
  67 .Fa m No \*[Gt] Fa n
  68 or
  69 .Fa m No \*[Lt]= Fa n .
  70 The least significant bit is bit 0.
  71 .El
  72 .Pp
  73 .Fn __SHIFTIN ,
  74 .Fn __SHIFTOUT ,
  75 and
  76 .Fn __SHIFTOUT_MASK
  77 help read and write bitfields from words:
  78 .Pp
  79 .Bl -tag -width __SHIFTOUT_MASK -offset indent
  80 .It Fn __SHIFTIN "v" "mask"
  81 Left-shift bits
  82 .Fa v
  83 into the bitfield defined by
  84 .Fa mask ,
  85 and return them.
  86 No side-effects.
  87 .It Fn __SHIFTOUT "v" "mask"
  88 Extract and return the bitfield selected by
  89 .Fa mask
  90 from
  91 .Fa v ,
  92 right-shifting the bits so that the rightmost selected bit is at
  93 bit 0.
  94 No side-effects.
  95 .It Fn __SHIFTOUT_MASK "mask"
  96 Right-shift the bits in
  97 .Fa mask
  98 so that the rightmost non-zero bit is at bit 0.
  99 This is useful for finding the greatest unsigned value that a
 100 bitfield can hold.
 101 No side-effects.
 102 Note 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  */
 120 atw_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  */
 139 len = __SHIFTOUT(rxstat, ATW_RXSTAT_FL_MASK);
 140 .Ed
 141 .Sh HISTORY
 142 The
 143 .Nm bits
 144 macros first appeared in
 145 .Xr atw 4 ,
 146 with different names and implementation.
 147 .Nm bits
 148 macros appeared with their current names and implementation in
 149 .Nx 4.0 .
 150 .Sh AUTHORS
 151 The
 152 .Nm bits
 153 macros were written by
 154 .An David Young Aq dyoung@NetBSD.org .
 155 .An Matt Thomas Aq matt@NetBSD.org
 156 suggested important improvements to the implementation, and
 157 contributed the macro names
 158 .Fn SHIFTIN
 159 and
 160 .Fn SHIFTOUT .
 161 .Sh BUGS
 162 .Fn __BIT
 163 and
 164 .Fn __BITS
 165 can only express 32-bit bitmasks.