]>
Commit | Line | Data |
---|---|---|
3b033380 MCC |
1 | ========================================= |
2 | How to get printk format specifiers right | |
3 | ========================================= | |
4 | ||
5 | :Author: Randy Dunlap <rdunlap@infradead.org> | |
6 | :Author: Andrew Murray <amurray@mpc-data.co.uk> | |
7 | ||
8 | ||
9 | Integer types | |
10 | ============= | |
11 | ||
12 | :: | |
13 | ||
14 | If variable is of Type, use printk format specifier: | |
15 | ------------------------------------------------------------ | |
b67ad18b RD |
16 | int %d or %x |
17 | unsigned int %u or %x | |
18 | long %ld or %lx | |
19 | unsigned long %lu or %lx | |
20 | long long %lld or %llx | |
21 | unsigned long long %llu or %llx | |
22 | size_t %zu or %zx | |
23 | ssize_t %zd or %zx | |
e8a7ba5f GU |
24 | s32 %d or %x |
25 | u32 %u or %x | |
26 | s64 %lld or %llx | |
27 | u64 %llu or %llx | |
28 | ||
3b033380 MCC |
29 | If <type> is dependent on a config option for its size (e.g., ``sector_t``, |
30 | ``blkcnt_t``) or is architecture-dependent for its size (e.g., ``tcflag_t``), | |
31 | use a format specifier of its largest possible type and explicitly cast to it. | |
32 | ||
33 | Example:: | |
e8a7ba5f GU |
34 | |
35 | printk("test: sector number/total blocks: %llu/%llu\n", | |
36 | (unsigned long long)sector, (unsigned long long)blockcount); | |
37 | ||
3b033380 | 38 | Reminder: ``sizeof()`` result is of type ``size_t``. |
e8a7ba5f | 39 | |
3b033380 MCC |
40 | The kernel's printf does not support ``%n``. For obvious reasons, floating |
41 | point formats (``%e, %f, %g, %a``) are also not recognized. Use of any | |
d7ec9a05 RV |
42 | unsupported specifier or length qualifier results in a WARN and early |
43 | return from vsnprintf. | |
b67ad18b | 44 | |
04c55715 AM |
45 | Raw pointer value SHOULD be printed with %p. The kernel supports |
46 | the following extended format specifiers for pointer types: | |
47 | ||
3b033380 MCC |
48 | Symbols/Function Pointers |
49 | ========================= | |
50 | ||
51 | :: | |
04c55715 AM |
52 | |
53 | %pF versatile_init+0x0/0x110 | |
54 | %pf versatile_init | |
55 | %pS versatile_init+0x0/0x110 | |
b0d33c2b JP |
56 | %pSR versatile_init+0x9/0x110 |
57 | (with __builtin_extract_return_addr() translation) | |
04c55715 AM |
58 | %ps versatile_init |
59 | %pB prev_fn_of_versatile_init+0x88/0x88 | |
60 | ||
d6957f33 HD |
61 | The ``F`` and ``f`` specifiers are for printing function pointers, |
62 | for example, f->func, &gettimeofday. They have the same result as | |
63 | ``S`` and ``s`` specifiers. But they do an extra conversion on | |
64 | ia64, ppc64 and parisc64 architectures where the function pointers | |
65 | are actually function descriptors. | |
66 | ||
67 | The ``S`` and ``s`` specifiers can be used for printing symbols | |
68 | from direct addresses, for example, __builtin_return_address(0), | |
69 | (void *)regs->ip. They result in the symbol name with (``S``) or | |
70 | without (``s``) offsets. If KALLSYMS are disabled then the symbol | |
71 | address is printed instead. | |
3b033380 MCC |
72 | |
73 | The ``B`` specifier results in the symbol name with offsets and should be | |
74 | used when printing stack backtraces. The specifier takes into | |
75 | consideration the effect of compiler optimisations which may occur | |
76 | when tail-call``s are used and marked with the noreturn GCC attribute. | |
04c55715 | 77 | |
04c55715 | 78 | |
3b033380 MCC |
79 | Kernel Pointers |
80 | =============== | |
04c55715 | 81 | |
3b033380 | 82 | :: |
04c55715 AM |
83 | |
84 | %pK 0x01234567 or 0x0123456789abcdef | |
85 | ||
3b033380 MCC |
86 | For printing kernel pointers which should be hidden from unprivileged |
87 | users. The behaviour of ``%pK`` depends on the ``kptr_restrict sysctl`` - see | |
88 | Documentation/sysctl/kernel.txt for more details. | |
89 | ||
90 | Struct Resources | |
91 | ================ | |
04c55715 | 92 | |
3b033380 | 93 | :: |
04c55715 AM |
94 | |
95 | %pr [mem 0x60000000-0x6fffffff flags 0x2200] or | |
96 | [mem 0x0000000060000000-0x000000006fffffff flags 0x2200] | |
97 | %pR [mem 0x60000000-0x6fffffff pref] or | |
98 | [mem 0x0000000060000000-0x000000006fffffff pref] | |
99 | ||
3b033380 MCC |
100 | For printing struct resources. The ``R`` and ``r`` specifiers result in a |
101 | printed resource with (``R``) or without (``r``) a decoded flags member. | |
102 | Passed by reference. | |
103 | ||
104 | Physical addresses types ``phys_addr_t`` | |
105 | ======================================== | |
04c55715 | 106 | |
3b033380 | 107 | :: |
7d799210 | 108 | |
aaf07621 | 109 | %pa[p] 0x01234567 or 0x0123456789abcdef |
7d799210 | 110 | |
3b033380 MCC |
111 | For printing a ``phys_addr_t`` type (and its derivatives, such as |
112 | ``resource_size_t``) which can vary based on build options, regardless of | |
113 | the width of the CPU data path. Passed by reference. | |
7d799210 | 114 | |
3b033380 MCC |
115 | DMA addresses types ``dma_addr_t`` |
116 | ================================== | |
117 | ||
118 | :: | |
aaf07621 JP |
119 | |
120 | %pad 0x01234567 or 0x0123456789abcdef | |
121 | ||
3b033380 MCC |
122 | For printing a ``dma_addr_t`` type which can vary based on build options, |
123 | regardless of the width of the CPU data path. Passed by reference. | |
124 | ||
125 | Raw buffer as an escaped string | |
126 | =============================== | |
aaf07621 | 127 | |
3b033380 | 128 | :: |
71dca95d AS |
129 | |
130 | %*pE[achnops] | |
131 | ||
3b033380 | 132 | For printing raw buffer as an escaped string. For the following buffer:: |
71dca95d AS |
133 | |
134 | 1b 62 20 5c 43 07 22 90 0d 5d | |
135 | ||
3b033380 MCC |
136 | few examples show how the conversion would be done (the result string |
137 | without surrounding quotes):: | |
71dca95d AS |
138 | |
139 | %*pE "\eb \C\a"\220\r]" | |
140 | %*pEhp "\x1bb \C\x07"\x90\x0d]" | |
141 | %*pEa "\e\142\040\\\103\a\042\220\r\135" | |
142 | ||
3b033380 MCC |
143 | The conversion rules are applied according to an optional combination |
144 | of flags (see :c:func:`string_escape_mem` kernel documentation for the | |
145 | details): | |
146 | ||
147 | - ``a`` - ESCAPE_ANY | |
148 | - ``c`` - ESCAPE_SPECIAL | |
149 | - ``h`` - ESCAPE_HEX | |
150 | - ``n`` - ESCAPE_NULL | |
151 | - ``o`` - ESCAPE_OCTAL | |
152 | - ``p`` - ESCAPE_NP | |
153 | - ``s`` - ESCAPE_SPACE | |
71dca95d | 154 | |
3b033380 | 155 | By default ESCAPE_ANY_NP is used. |
71dca95d | 156 | |
3b033380 MCC |
157 | ESCAPE_ANY_NP is the sane choice for many cases, in particularly for |
158 | printing SSIDs. | |
71dca95d | 159 | |
3b033380 MCC |
160 | If field width is omitted the 1 byte only will be escaped. |
161 | ||
162 | Raw buffer as a hex string | |
163 | ========================== | |
164 | ||
165 | :: | |
5e4ee7b1 | 166 | |
31550a16 AS |
167 | %*ph 00 01 02 ... 3f |
168 | %*phC 00:01:02: ... :3f | |
169 | %*phD 00-01-02- ... -3f | |
170 | %*phN 000102 ... 3f | |
171 | ||
3b033380 MCC |
172 | For printing a small buffers (up to 64 bytes long) as a hex string with |
173 | certain separator. For the larger buffers consider to use | |
174 | :c:func:`print_hex_dump`. | |
175 | ||
176 | MAC/FDDI addresses | |
177 | ================== | |
31550a16 | 178 | |
3b033380 | 179 | :: |
04c55715 AM |
180 | |
181 | %pM 00:01:02:03:04:05 | |
76597ff9 | 182 | %pMR 05:04:03:02:01:00 |
04c55715 AM |
183 | %pMF 00-01-02-03-04-05 |
184 | %pm 000102030405 | |
7c59154e | 185 | %pmR 050403020100 |
04c55715 | 186 | |
3b033380 MCC |
187 | For printing 6-byte MAC/FDDI addresses in hex notation. The ``M`` and ``m`` |
188 | specifiers result in a printed address with (``M``) or without (``m``) byte | |
189 | separators. The default byte separator is the colon (``:``). | |
04c55715 | 190 | |
3b033380 MCC |
191 | Where FDDI addresses are concerned the ``F`` specifier can be used after |
192 | the ``M`` specifier to use dash (``-``) separators instead of the default | |
193 | separator. | |
04c55715 | 194 | |
3b033380 MCC |
195 | For Bluetooth addresses the ``R`` specifier shall be used after the ``M`` |
196 | specifier to use reversed byte order suitable for visual interpretation | |
197 | of Bluetooth addresses which are in the little endian order. | |
76597ff9 | 198 | |
3b033380 MCC |
199 | Passed by reference. |
200 | ||
201 | IPv4 addresses | |
202 | ============== | |
7330660e | 203 | |
3b033380 | 204 | :: |
04c55715 AM |
205 | |
206 | %pI4 1.2.3.4 | |
207 | %pi4 001.002.003.004 | |
8ecada16 | 208 | %p[Ii]4[hnbl] |
04c55715 | 209 | |
3b033380 MCC |
210 | For printing IPv4 dot-separated decimal addresses. The ``I4`` and ``i4`` |
211 | specifiers result in a printed address with (``i4``) or without (``I4``) | |
212 | leading zeros. | |
04c55715 | 213 | |
3b033380 MCC |
214 | The additional ``h``, ``n``, ``b``, and ``l`` specifiers are used to specify |
215 | host, network, big or little endian order addresses respectively. Where | |
216 | no specifier is provided the default network/big endian order is used. | |
04c55715 | 217 | |
3b033380 | 218 | Passed by reference. |
7330660e | 219 | |
3b033380 MCC |
220 | IPv6 addresses |
221 | ============== | |
222 | ||
223 | :: | |
04c55715 AM |
224 | |
225 | %pI6 0001:0002:0003:0004:0005:0006:0007:0008 | |
226 | %pi6 00010002000300040005000600070008 | |
227 | %pI6c 1:2:3:4:5:6:7:8 | |
228 | ||
3b033380 MCC |
229 | For printing IPv6 network-order 16-bit hex addresses. The ``I6`` and ``i6`` |
230 | specifiers result in a printed address with (``I6``) or without (``i6``) | |
231 | colon-separators. Leading zeros are always used. | |
04c55715 | 232 | |
3b033380 MCC |
233 | The additional ``c`` specifier can be used with the ``I`` specifier to |
234 | print a compressed IPv6 address as described by | |
235 | http://tools.ietf.org/html/rfc5952 | |
04c55715 | 236 | |
3b033380 | 237 | Passed by reference. |
7330660e | 238 | |
3b033380 MCC |
239 | IPv4/IPv6 addresses (generic, with port, flowinfo, scope) |
240 | ========================================================= | |
241 | ||
242 | :: | |
10679643 DB |
243 | |
244 | %pIS 1.2.3.4 or 0001:0002:0003:0004:0005:0006:0007:0008 | |
245 | %piS 001.002.003.004 or 00010002000300040005000600070008 | |
246 | %pISc 1.2.3.4 or 1:2:3:4:5:6:7:8 | |
247 | %pISpc 1.2.3.4:12345 or [1:2:3:4:5:6:7:8]:12345 | |
248 | %p[Ii]S[pfschnbl] | |
249 | ||
3b033380 MCC |
250 | For printing an IP address without the need to distinguish whether it``s |
251 | of type AF_INET or AF_INET6, a pointer to a valid ``struct sockaddr``, | |
252 | specified through ``IS`` or ``iS``, can be passed to this format specifier. | |
10679643 | 253 | |
3b033380 MCC |
254 | The additional ``p``, ``f``, and ``s`` specifiers are used to specify port |
255 | (IPv4, IPv6), flowinfo (IPv6) and scope (IPv6). Ports have a ``:`` prefix, | |
256 | flowinfo a ``/`` and scope a ``%``, each followed by the actual value. | |
10679643 | 257 | |
3b033380 MCC |
258 | In case of an IPv6 address the compressed IPv6 address as described by |
259 | http://tools.ietf.org/html/rfc5952 is being used if the additional | |
260 | specifier ``c`` is given. The IPv6 address is surrounded by ``[``, ``]`` in | |
261 | case of additional specifiers ``p``, ``f`` or ``s`` as suggested by | |
262 | https://tools.ietf.org/html/draft-ietf-6man-text-addr-representation-07 | |
10679643 | 263 | |
3b033380 MCC |
264 | In case of IPv4 addresses, the additional ``h``, ``n``, ``b``, and ``l`` |
265 | specifiers can be used as well and are ignored in case of an IPv6 | |
266 | address. | |
10679643 | 267 | |
3b033380 | 268 | Passed by reference. |
7330660e | 269 | |
3b033380 | 270 | Further examples:: |
10679643 DB |
271 | |
272 | %pISfc 1.2.3.4 or [1:2:3:4:5:6:7:8]/123456789 | |
273 | %pISsc 1.2.3.4 or [1:2:3:4:5:6:7:8]%1234567890 | |
274 | %pISpfc 1.2.3.4:12345 or [1:2:3:4:5:6:7:8]:12345/123456789 | |
275 | ||
3b033380 MCC |
276 | UUID/GUID addresses |
277 | =================== | |
278 | ||
279 | :: | |
04c55715 AM |
280 | |
281 | %pUb 00010203-0405-0607-0809-0a0b0c0d0e0f | |
282 | %pUB 00010203-0405-0607-0809-0A0B0C0D0E0F | |
283 | %pUl 03020100-0504-0706-0809-0a0b0c0e0e0f | |
284 | %pUL 03020100-0504-0706-0809-0A0B0C0E0E0F | |
285 | ||
3b033380 MCC |
286 | For printing 16-byte UUID/GUIDs addresses. The additional 'l', 'L', |
287 | 'b' and 'B' specifiers are used to specify a little endian order in | |
288 | lower ('l') or upper case ('L') hex characters - and big endian order | |
289 | in lower ('b') or upper case ('B') hex characters. | |
04c55715 | 290 | |
3b033380 MCC |
291 | Where no additional specifiers are used the default big endian |
292 | order with lower case hex characters will be printed. | |
04c55715 | 293 | |
3b033380 MCC |
294 | Passed by reference. |
295 | ||
296 | dentry names | |
297 | ============ | |
7330660e | 298 | |
3b033380 | 299 | :: |
5e4ee7b1 | 300 | |
4b6ccca7 AV |
301 | %pd{,2,3,4} |
302 | %pD{,2,3,4} | |
303 | ||
3b033380 MCC |
304 | For printing dentry name; if we race with :c:func:`d_move`, the name might be |
305 | a mix of old and new ones, but it won't oops. ``%pd`` dentry is a safer | |
306 | equivalent of ``%s`` ``dentry->d_name.name`` we used to use, ``%pd<n>`` prints | |
307 | ``n`` last components. ``%pD`` does the same thing for struct file. | |
4b6ccca7 | 308 | |
3b033380 | 309 | Passed by reference. |
7330660e | 310 | |
3b033380 MCC |
311 | block_device names |
312 | ================== | |
313 | ||
314 | :: | |
1031bc58 DM |
315 | |
316 | %pg sda, sda1 or loop0p1 | |
317 | ||
3b033380 MCC |
318 | For printing name of block_device pointers. |
319 | ||
320 | struct va_format | |
321 | ================ | |
1031bc58 | 322 | |
3b033380 | 323 | :: |
04c55715 AM |
324 | |
325 | %pV | |
326 | ||
3b033380 MCC |
327 | For printing struct va_format structures. These contain a format string |
328 | and va_list as follows:: | |
04c55715 AM |
329 | |
330 | struct va_format { | |
331 | const char *fmt; | |
332 | va_list *va; | |
333 | }; | |
334 | ||
3b033380 | 335 | Implements a "recursive vsnprintf". |
5e4ee7b1 | 336 | |
3b033380 MCC |
337 | Do not use this feature without some mechanism to verify the |
338 | correctness of the format string and va_list arguments. | |
b67ad18b | 339 | |
3b033380 MCC |
340 | Passed by reference. |
341 | ||
342 | kobjects | |
343 | ======== | |
344 | ||
345 | :: | |
7330660e | 346 | |
ce4fecf1 PA |
347 | %pO |
348 | ||
349 | Base specifier for kobject based structs. Must be followed with | |
350 | character for specific type of kobject as listed below: | |
351 | ||
352 | Device tree nodes: | |
353 | ||
354 | %pOF[fnpPcCF] | |
355 | ||
356 | For printing device tree nodes. The optional arguments are: | |
357 | f device node full_name | |
358 | n device node name | |
359 | p device node phandle | |
360 | P device node path spec (name + @unit) | |
361 | F device node flags | |
362 | c major compatible string | |
363 | C full compatible string | |
364 | Without any arguments prints full_name (same as %pOFf) | |
365 | The separator when using multiple arguments is ':' | |
366 | ||
367 | Examples: | |
368 | ||
369 | %pOF /foo/bar@0 - Node full name | |
370 | %pOFf /foo/bar@0 - Same as above | |
371 | %pOFfp /foo/bar@0:10 - Node full name + phandle | |
372 | %pOFfcF /foo/bar@0:foo,device:--P- - Node full name + | |
373 | major compatible string + | |
374 | node flags | |
375 | D - dynamic | |
376 | d - detached | |
377 | P - Populated | |
378 | B - Populated bus | |
379 | ||
380 | Passed by reference. | |
381 | ||
3b033380 MCC |
382 | |
383 | struct clk | |
384 | ========== | |
385 | ||
386 | :: | |
900cca29 GU |
387 | |
388 | %pC pll1 | |
389 | %pCn pll1 | |
390 | %pCr 1560000000 | |
391 | ||
3b033380 MCC |
392 | For printing struct clk structures. ``%pC`` and ``%pCn`` print the name |
393 | (Common Clock Framework) or address (legacy clock framework) of the | |
394 | structure; ``%pCr`` prints the current clock rate. | |
900cca29 | 395 | |
3b033380 | 396 | Passed by reference. |
900cca29 | 397 | |
3b033380 MCC |
398 | bitmap and its derivatives such as cpumask and nodemask |
399 | ======================================================= | |
400 | ||
401 | :: | |
d0724961 WL |
402 | |
403 | %*pb 0779 | |
404 | %*pbl 0,3-6,8-10 | |
405 | ||
3b033380 MCC |
406 | For printing bitmap and its derivatives such as cpumask and nodemask, |
407 | ``%*pb`` output the bitmap with field width as the number of bits and ``%*pbl`` | |
408 | output the bitmap as range list with field width as the number of bits. | |
d0724961 | 409 | |
3b033380 MCC |
410 | Passed by reference. |
411 | ||
412 | Flags bitfields such as page flags, gfp_flags | |
413 | ============================================= | |
b67ad18b | 414 | |
3b033380 | 415 | :: |
edf14cdb VB |
416 | |
417 | %pGp referenced|uptodate|lru|active|private | |
418 | %pGg GFP_USER|GFP_DMA32|GFP_NOWARN | |
419 | %pGv read|exec|mayread|maywrite|mayexec|denywrite | |
420 | ||
3b033380 MCC |
421 | For printing flags bitfields as a collection of symbolic constants that |
422 | would construct the value. The type of flags is given by the third | |
423 | character. Currently supported are [p]age flags, [v]ma_flags (both | |
424 | expect ``unsigned long *``) and [g]fp_flags (expects ``gfp_t *``). The flag | |
425 | names and print order depends on the particular type. | |
edf14cdb | 426 | |
3b033380 MCC |
427 | Note that this format should not be used directly in :c:func:`TP_printk()` part |
428 | of a tracepoint. Instead, use the ``show_*_flags()`` functions from | |
429 | <trace/events/mmflags.h>. | |
edf14cdb | 430 | |
3b033380 MCC |
431 | Passed by reference. |
432 | ||
433 | Network device features | |
434 | ======================= | |
edf14cdb | 435 | |
3b033380 | 436 | :: |
5e4ee7b1 MK |
437 | |
438 | %pNF 0x000000000000c000 | |
439 | ||
3b033380 | 440 | For printing netdev_features_t. |
5e4ee7b1 | 441 | |
3b033380 | 442 | Passed by reference. |
5e4ee7b1 | 443 | |
3b033380 | 444 | If you add other ``%p`` extensions, please extend lib/test_printf.c with |
d7ec9a05 | 445 | one or more test cases, if at all feasible. |
5e4ee7b1 | 446 | |
5e4ee7b1 | 447 | |
b67ad18b | 448 | Thank you for your cooperation and attention. |