| blob | a973ed1ad6563eba477183f54563327e0a3b09cc |
1 .\" $NetBSD: snprintb.3,v 1.16 2013/08/07 23:22:28 pgoyette Exp $
2 .\"
3 .\" Copyright (c) 1998 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
5 .\"
6 .\" This code is derived from software contributed to The NetBSD Foundation
7 .\" by Jeremy Cooper.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28 .\" POSSIBILITY OF SUCH DAMAGE.
29 .\"
30 .Dd May 7, 2009
31 .Dt SNPRINTB 3
32 .Os
33 .Sh NAME
34 .Nm snprintb
35 .Nd bitmask output conversion
36 .Sh LIBRARY
37 .Lb libutil
38 .Sh SYNOPSIS
39 .In util.h
40 .Ft int
41 .Fn "snprintb" "char *buf" "size_t buflen" "const char *fmt" "uint64_t val"
42 .Ft int
43 .Fn "snprintb_m" "char *buf" "size_t buflen" "const char *fmt" "uint64_t val" \
44 "size_t max"
45 .Sh DESCRIPTION
46 The
47 .Fn snprintb
48 function formats a bitmask into a mnemonic form suitable for printing.
49 .Pp
50 This conversion is useful for decoding bit fields in device registers.
51 It formats the integer
52 .Fa val
53 into the buffer
54 .Fa buf ,
55 of size
56 .Fa buflen ,
57 using a specified radix and an interpretation of
58 the bits within that integer as though they were flags.
59 The buffer is always NUL-terminated.
60 If the buffer
61 .Fa buf
62 is too small to hold the formatted output,
63 .Fn snprintb
64 will fill as much as it can, and return the number of bytes
65 that would have written if the buffer was long enough excluding the
66 terminating NUL.
67 .Pp
68 The decoding directive string
69 .Fa fmt
70 describes how the bitfield is to be interpreted and displayed.
71 It follows two possible syntaxes, referred to as
72 .Dq old
73 and
74 .Dq new .
75 The main advantage of the
76 .Dq new
77 formatting is that it is capable of handling multi-bit fields.
78 .Pp
79 The first character of
80 .Fa fmt
81 may be
82 .Li \e177 ,
83 indicating that the remainder of the format string follows the
84 .Dq new
85 syntax.
86 The second character
87 .Pq the first for the old format
88 is a binary character representation of the
89 output numeral base in which the bitfield will be printed before it is decoded.
90 Recognized radix values
91 .Pq in C escape-character format
92 are
93 .Li \e10
94 .Pq octal ,
95 .Li \e12
96 .Pq decimal ,
97 and
98 .Li \e20
99 .Pq hexadecimal .
100 .Pp
101 The remaining characters in
102 .Fa fmt
103 are interpreted as a list of bit-position\(endescription pairs.
104 From here the syntaxes diverge.
105 .Pp
106 The
107 .Dq old
108 format syntax is series of bit-position\(endescription pairs.
109 Each begins with a binary character value that represents the position
110 of the bit being described.
111 A bit position value of one describes the least significant bit.
112 Whereas a position value of 32
113 .Pq octal 40, hexadecimal 20, the ASCII space character
114 describes the most significant bit.
115 .Pp
116 The remaining characters in a bit-position\(endescription pair are the
117 characters to print should the bit being described be set.
118 Description strings are delimited by the next bit position value character
119 encountered
120 .Pq distinguishable by its value being \*[Le] 32 ,
121 or the end of the decoding directive string itself.
122 .Pp
123 For the
124 .Dq new
125 format syntax, a bit-position\(endescription begins with a field type
126 followed by a binary bit-position and possibly a field length.
127 The least significant bit is bit-position zero, unlike the
128 .Dq old
129 syntax where it is one.
130 .Bl -tag -width "xxxxx"
131 .It Cm b\eB
132 Describes a bit position.
133 The bit-position
134 .Fa B
135 indicates the corresponding bit, as in the
136 .Dq old
137 format.
138 .It Cm f\eB\eL
139 Describes a multi-bit field beginning at bit-position
140 .Fa B
141 and having a bit-length of
142 .Fa L .
143 The remaining characters are printed as a description of the field
144 followed by
145 .Sq \&=
146 and the value of the field.
147 The value of the field is printed in the base specified as the second
148 character of the decoding directive string
149 .Ar fmt .
150 .It Cm F\eB\eL
151 Describes a multi-bit field like
152 .Sq f ,
153 but just extracts the value for use with the
154 .Sq \&=
155 and
156 .Sq \&:
157 formatting directives described below.
158 .It Cm \&=\eV
159 The field previously extracted by the last
160 .Sq f
161 or
162 .Sq F
163 operator is compared to the byte
164 .Sq Cm V
165 .Pq for values 0 through 255 .
166 If they are equal,
167 .Sq \&=
168 followed by the string following
169 .Sq Cm V
170 is printed.
171 This and the
172 .Sq \&:
173 operator may be repeated to annotate multiple possible values.
174 .It Cm :\eV
175 Operates like the
176 .Sq \&=
177 operator, but omits the leading
178 .Sq \&= .
179 .El
180 .Pp
181 Finally, each field is delimited by a NUL
182 .Pq Sq \e0
183 character.
184 By convention, the format string has an additional NUL character at
185 the end, following that delimiting the last bit-position\(endescription
186 pair.
187 .Pp
188 The
189 .Fn snprintb_m
190 function accepts an additional
191 .Fa max
192 argument.
193 If this argument is zero, the
194 .Fn snprintb_m
195 function returns exactly the same results in the
196 .Fa buf
197 as the
198 .Fn snprintb
199 function.
200 If the
201 .Fa max
202 argument is present and has a non-zero value, it represents the maximum
203 length of a formatted string.
204 If the formatted string would require more than
205 .Fa max
206 characters, the
207 .Fn snprintb_m
208 function returns multiple formatted strings in the output buffer
209 .Fa buf .
210 Each string is NUL-terminated, and the last string is followed by an
211 additional NUL character (or, if you prefer, a zero-length string).
212 .Sh RETURN VALUES
213 The
214 .Fn snprintb
215 and
216 .Fn snprintb_m
217 functions return the number of bytes that would have written to the buffer
218 if there was adequate space, excluding the final terminating NUL, or \-1 in
219 case an error occurred.
220 For
221 .Fn snprintb_m ,
222 the NUL characters terminating each individual string are included in the
223 total number of bytes.
224 .Sh EXAMPLES
225 Two examples of the old formatting style:
226 .Bd -literal -offset indent
227 snprintb(buf, buflen, "\e10\e2BITTWO\e1BITONE", 3)
228 \(rA "03<BITTWO,BITONE>"
230 snprintb(buf, buflen,
231 "\e20\ex10NOTBOOT\ex0f" "FPP\ex0eSDVMA\ex0cVIDEO"
232 "\ex0bLORES\ex0a" "FPA\ex09" "DIAG\ex07" "CACHE"
233 "\ex06IOCACHE\ex05LOOPBACK\ex04" "DBGCACHE",
234 0xe860)
235 \(rA "0xe860<NOTBOOT,FPP,SDVMA,VIDEO,CACHE,IOCACHE>"
236 .Ed
237 .Pp
238 An example of the new formatting style:
239 .Bd -literal -offset indent
240 snprintb(buf, buflen,
241 "\e177\e020b\e0LSB\e0b\e1_BITONE\e0f\e4\e4NIBBLE2\e0"
242 "f\ex10\e4BURST\e0=\e4FOUR\e0=\exfSIXTEEN\e0"
243 "b\ex1fMSB\e0\e0",
244 0x800f0701)
245 \(rA "0x800f0701<LSB,NIBBLE2=0x0,BURST=0xf=SIXTEEN,MSB>"
246 .Ed
247 .Pp
248 An example using snprintb_m:
249 .Bd -literal -offset indent
250 snprintb_m(buf, buflen,
251 "\e177\e020b\e0LSB\e0b\e1_BITONE\e0f\e4\e4NIBBLE2\e0"
252 "f\ex10\e4BURST\e0=\e4FOUR\e0=\exfSIXTEEN\e0"
253 "b\ex1fMSB\e0\e0",
254 0x800f0701, 34)
255 \(rA "0x800f0701<LSB,NIBBLE2=0x0>\e00x800f0701<BURST=0xf=SIXTEEN,MSB>\e0"
256 .Ed
257 .Sh ERRORS
258 .Fn snprintb
259 will fail if:
260 .Bl -tag -width Er
261 .It Bq Er EINVAL
262 The leading character does not describe a supported format,
263 or
264 .Fn snprintf
265 failed.
266 .El
267 .Sh SEE ALSO
268 .Xr printf 3 ,
269 .Xr snprintf 3
270 .Sh HISTORY
271 The
272 .Fn snprintb
273 function was originally implemented as a non-standard
274 .Li %b
275 format string for the kernel
276 .Fn printf
277 function in
278 .Nx 1.5
279 and earlier releases.
280 It was called
281 .Fn bitmask_snprintf
282 in
283 .Nx 5.0
284 and earlier releases.
285 .Sh AUTHORS
286 The
287 .Dq new
288 format was the invention of
289 .An Chris Torek .