Document Chris Torek's (the "new" format) bitmask format string.

share/man/man9/bitmask_snprintf.9

@@ -1,4 +1,4 @@
-.\"     $NetBSD: bitmask_snprintf.9,v 1.5 2004/10/17 04:09:23 heas Exp $
+.\"     $NetBSD: bitmask_snprintf.9,v 1.6 2004/10/26 20:58:10 heas Exp $
 .\"
 .\" Copyright (c) 1998 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -34,7 +34,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd October 16, 2004
+.Dd October 26, 2004
 .Dt BITMASK_SNPRINTF 9
 .Os
 .Sh NAME
@@ -62,8 +62,23 @@ the bits within that integer as though they were flags.
 The decoding directive string
 .Fa fmt
 describes how the bitfield is to be interpreted and displayed.
+It follows two possible syntaxes, referred to as
+.Dq old
+and
+.Dq new .
+The main advantage of the
+.Dq new
+formating being that it is capable of handling multi-bit fields.
+.Pp
 The first character of
 .Fa fmt
+may be
+.Li \e177 ,
+indicating that the remainder of the format string follows the
+.Dq new
+syntax.
+The second character
+.Pq "the first for the old format"
 is a binary character representation of the
 output numeral base in which the bitfield will be printed before it is decoded.
 Recognized radix values
@@ -80,8 +95,13 @@ and
 The remaining characters in
 .Fa fmt
 are interpreted as a list of bit-position\(endescription pairs.
-A bit-position\(endescription pair begins with a binary character value
-that represents the position of the bit being described.
+From here the syntaxes diverge.
+.Pp
+The
+.Dq old
+format syntax is series of bit-position\(endescription pairs.
+Each begins with a binary character value that represents the position
+of the bit being described.
 A bit position value of one describes the least significant bit.
 Whereas a position value of 32
 .Pq "octal 40, hexadecimal 20, the ASCII space character"
@@ -93,6 +113,80 @@ Description strings are delimited by the next bit position value character
 encountered
 .Pq "distinguishable by its value being \*[Le] 32" ,
 or the end of the decoding directive string itself.
+.Pp
+For the
+.Dq new
+format syntax, a bit-position\(endescription begins with a field type
+followed by a binary bit-position and possibly a field length.
+The least significant bit is bit-position zero, unlike the
+.Dq old
+syntax where it is one.
+.Bl -tag -width "xxxxx"
+.It Cm b\eB
+Describes a bit position.
+The bit-position 
+.Fa B
+indicates the corresponding bit, as in the
+.Dq old
+format.
+.It Cm f\eB\eL
+Describes a multi-bit field beginning at bit-position
+.Fa B
+and having a bit-length of
+.Fa L .
+The remaining characters are printed as a description of the field
+followed by
+.Sq \&=
+and the value of the field.
+The value of the field is printed in the base specified as the second
+character of the decoding directive string
+.Ar fmt .
+.It Cm F\eB\eL
+Describes a multi-bit field like
+.Sq f ,
+but just extracts the value for use with the
+.Sq \&=
+and 
+.Sq \&:
+formatting directives described below.
+.It Cm \&=\eV
+The field previously extracted by the last
+.Sq f
+or
+.Sq F
+operator is compared to the byte
+.Sq Cm V
+.Pq "for values 0 through 255" .
+If they are equal,
+.Sq \&=
+followed by the string following
+.Sq Cm V
+is printed.
+This and the
+.Sq \&:
+operator may be repeated to annotate multiple possible values.
+.It Cm :\eV
+Operates like the
+.Sq \&=
+operator, but omits the leading
+.Sq \&= .
+.El
+.Pp
+Finally, each field is delimited by a NULL
+.Pq "\e0"
+character.
+By convention, the format string has an additional NULL character at
+the end, following that delimiting the last bit-position\(endescription
+pair.
+.Pp
+The buffer
+.Fa buf
+passed to
+.Nm
+must be at least
+.Dv KPRINTF_BUFSIZE
+bytes in length.
+See the source code for the definition of this macro.
 .Sh RETURN VALUES
 The
 .Fn bitmask_snprintf
@@ -112,6 +206,16 @@ bitmask_snprintf(0xe860,
         buf, buflen)
 \(rA "e860\*[Lt]NOTBOOT,FPP,SDVMA,VIDEO,CACHE,IOCACHE\*[Gt]"
 .Ed
+.Pp
+An example of the new formatting style:
+.Bd -literal -offset indent
+bitmask_snprintf(0x800f0701,
+       "\e177\e020b\e0LSB\e0b\e1_BITONE\e0f\e4\e4NIBBLE2\e0"
+       "f\ex10\e4BURST\e0=\e4FOUR\e0=\exfSIXTEEN\e0"
+       "b\ex1fMSB\e0\e0",
+        buf, buflen)
+\(rA "800f0701\*[Lt]LSB,NIBBLE2=0,BURST=f=SIXTEEN,MSB\*[Gt]"
+.Ed
 .Sh ERRORS
 If the buffer
 .Fa buf
@@ -132,7 +236,8 @@ format string for the kernel
 function in
 .Nx 1.5
 and earlier releases.
-.Sh BUGS
-.Fn bitmask_snprintf
-supports a new extended form of formatting string, which is not yet
-described here.
+.Sh AUTHORS
+The
+.Dq new
+format was the invention of
+.An "Chris Torek" .