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