char
*
bitmask_snprintf(
u_quad_t val
, const char *fmt
, char *buf
, size_t buflen
)
)
function formats a bitmask into a mnemonic form suitable for printing.
This conversion is useful for decoding bit fields in device registers.
It formats the integer
val
into the buffer
buf
,
of size
buflen
,
using a specified radix and an interpretation of
the bits within that integer as though they were flags.
The decoding directive string
fmt
describes how the bitfield is to be interpreted and displayed.
It follows two possible syntaxes, referred to as
``old''
and
``new''.
The main advantage of the
``new''
formatting is that it is capable of handling multi-bit fields.
The first character of
fmt
may be
\177
,
indicating that the remainder of the format string follows the
``new''
syntax.
The second character
(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
(in C escape-character format)
are
\10
(octal),
\12
(decimal),
and
\20
(hexadecimal).
The remaining characters in
fmt
are interpreted as a list of bit-position-description pairs.
From here the syntaxes diverge.
The ``old'' format syntax is series of bit-position-description 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 (octal 40, hexadecimal 20, the ASCII space character) describes the most significant bit.
The remaining characters in a bit-position-description pair are the characters to print should the bit being described be set. Description strings are delimited by the next bit position value character encountered (distinguishable by its value being 32), or the end of the decoding directive string itself.
For the ``new'' format syntax, a bit-position-description 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 ``old'' syntax where it is one.
B
indicates the corresponding bit, as in the
``old''
format.
B
and having a bit-length of
L
.
The remaining characters are printed as a description of the field
followed by
`='
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
fmt.
Finally, each field is delimited by a NUL (`\0') character. By convention, the format string has an additional NUL character at the end, following that delimiting the last bit-position-description pair.
The buffer
buf
passed to
bitmask_snprintf
must be at least
KPRINTF_BUFSIZE
bytes in length.
See the source code for the definition of this macro.
)
function returns the buffer
buf
.
The returned string is always NULL-terminated.
bitmask_snprintf(3, "\10\2BITTWO\1BITONE", buf, buflen)
=> "3<BITTWO,BITONE>"
bitmask_snprintf(0xe860,
"\20\x10NOTBOOT\x0fFPP\x0eSDVMA\x0cVIDEO"
"\x0bLORES\x0aFPA\x09DIAG\x07CACHE"
"\x06IOCACHE\x05LOOPBACK\x04DBGCACHE",
buf, buflen)
=> "e860<NOTBOOT,FPP,SDVMA,VIDEO,CACHE,IOCACHE>"
An example of the new formatting style:
bitmask_snprintf(0x800f0701,
"\177\020b\0LSB\0b\1_BITONE\0f\4\4NIBBLE2\0"
"f\x10\4BURST\0=\4FOUR\0=\xfSIXTEEN\0"
"b\x1fMSB\0\0",
buf, buflen)
=> "800f0701<LSB,NIBBLE2=0,BURST=f=SIXTEEN,MSB>"
buf
is too small to hold the formatted output,
bitmask_snprintf(
)
will still return the buffer, containing a truncated string.
sys/kern/subr_prf_bitmask.c
)
function was originally implemented as a non-standard
%b
format string for the kernel
printf(
)
function in
NetBSD1.5
and earlier releases.