bitmask_snprintf(9)
- NetBSD Manual Pages
BITMASK_SNPRINTF(9) NetBSD Kernel Developer's Manual BITMASK_SNPRINTF(9)
NAME
bitmask_snprintf -- bitmask output conversion
SYNOPSIS
#include <sys/systm.h>
char *
bitmask_snprintf(u_quad_t val, const char *fmt, char *buf,
size_t buflen);
DESCRIPTION
The bitmask_snprintf() 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-posi-
tion-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 char-
acters to print should the bit being described be set. Description
strings are delimited by the next bit position value character encoun-
tered (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\B Describes a bit position. The bit-position B indicates the corre-
sponding bit, as in the ``old'' format.
f\B\L Describes a multi-bit field beginning at bit-position 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.
F\B\L Describes a multi-bit field like `f', but just extracts the value
for use with the `=' and `:' formatting directives described
below.
=\V The field previously extracted by the last `f' or `F' operator is
compared to the byte `V' (for values 0 through 255). If they are
equal, `=' followed by the string following `V' is printed. This
and the `:' operator may be repeated to annotate multiple possible
values.
:\V Operates like the `=' operator, but omits the leading `='.
Finally, each field is delimited by a NUL (`\0') character. By conven-
tion, the format string has an additional NUL character at the end, fol-
lowing 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.
RETURN VALUES
The bitmask_snprintf() function returns the buffer buf. The returned
string is always NULL-terminated.
EXAMPLES
Two examples of the old formatting style:
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>"
ERRORS
If the buffer buf is too small to hold the formatted output,
bitmask_snprintf() will still return the buffer, containing a truncated
string.
SEE ALSO
printf(9)
CODE REFERENCES
sys/kern/subr_prf_bitmask.c
HISTORY
The bitmask_snprintf() function was originally implemented as a non-stan-
dard %b format string for the kernel printf() function in NetBSD 1.5 and
earlier releases.
AUTHORS
The ``new'' format was the invention of Chris Torek.
NetBSD 5.1.5 July 29, 2007 NetBSD 5.1.5
Powered by man-cgi (2024-03-20).
Maintained for NetBSD
by Kimmo Suominen.
Based on man-cgi by Panagiotis Christias.