Merge tag 'armsoc-dt' of git://git.kernel.org/pub/scm/linux/kernel/git/soc/soc
[sfrench/cifs-2.6.git] / Documentation / core-api / printk-formats.rst
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         ------------------------------------------------------------
16                 char                    %hhd or %hhx
17                 unsigned char           %hhu or %hhx
18                 short int               %hd or %hx
19                 unsigned short int      %hu or %hx
20                 int                     %d or %x
21                 unsigned int            %u or %x
22                 long                    %ld or %lx
23                 unsigned long           %lu or %lx
24                 long long               %lld or %llx
25                 unsigned long long      %llu or %llx
26                 size_t                  %zu or %zx
27                 ssize_t                 %zd or %zx
28                 s8                      %hhd or %hhx
29                 u8                      %hhu or %hhx
30                 s16                     %hd or %hx
31                 u16                     %hu or %hx
32                 s32                     %d or %x
33                 u32                     %u or %x
34                 s64                     %lld or %llx
35                 u64                     %llu or %llx
36
37
38 If <type> is dependent on a config option for its size (e.g., sector_t,
39 blkcnt_t) or is architecture-dependent for its size (e.g., tcflag_t), use a
40 format specifier of its largest possible type and explicitly cast to it.
41
42 Example::
43
44         printk("test: sector number/total blocks: %llu/%llu\n",
45                 (unsigned long long)sector, (unsigned long long)blockcount);
46
47 Reminder: sizeof() returns type size_t.
48
49 The kernel's printf does not support %n. Floating point formats (%e, %f,
50 %g, %a) are also not recognized, for obvious reasons. Use of any
51 unsupported specifier or length qualifier results in a WARN and early
52 return from vsnprintf().
53
54 Pointer types
55 =============
56
57 A raw pointer value may be printed with %p which will hash the address
58 before printing. The kernel also supports extended specifiers for printing
59 pointers of different types.
60
61 Some of the extended specifiers print the data on the given address instead
62 of printing the address itself. In this case, the following error messages
63 might be printed instead of the unreachable information::
64
65         (null)   data on plain NULL address
66         (efault) data on invalid address
67         (einval) invalid data on a valid address
68
69 Plain Pointers
70 --------------
71
72 ::
73
74         %p      abcdef12 or 00000000abcdef12
75
76 Pointers printed without a specifier extension (i.e unadorned %p) are
77 hashed to prevent leaking information about the kernel memory layout. This
78 has the added benefit of providing a unique identifier. On 64-bit machines
79 the first 32 bits are zeroed. The kernel will print ``(ptrval)`` until it
80 gathers enough entropy. If you *really* want the address see %px below.
81
82 Symbols/Function Pointers
83 -------------------------
84
85 ::
86
87         %pS     versatile_init+0x0/0x110
88         %ps     versatile_init
89         %pF     versatile_init+0x0/0x110
90         %pf     versatile_init
91         %pSR    versatile_init+0x9/0x110
92                 (with __builtin_extract_return_addr() translation)
93         %pB     prev_fn_of_versatile_init+0x88/0x88
94
95
96 The ``S`` and ``s`` specifiers are used for printing a pointer in symbolic
97 format. They result in the symbol name with (S) or without (s)
98 offsets. If KALLSYMS are disabled then the symbol address is printed instead.
99
100 Note, that the ``F`` and ``f`` specifiers are identical to ``S`` (``s``)
101 and thus deprecated. We have ``F`` and ``f`` because on ia64, ppc64 and
102 parisc64 function pointers are indirect and, in fact, are function
103 descriptors, which require additional dereferencing before we can lookup
104 the symbol. As of now, ``S`` and ``s`` perform dereferencing on those
105 platforms (when needed), so ``F`` and ``f`` exist for compatibility
106 reasons only.
107
108 The ``B`` specifier results in the symbol name with offsets and should be
109 used when printing stack backtraces. The specifier takes into
110 consideration the effect of compiler optimisations which may occur
111 when tail-calls are used and marked with the noreturn GCC attribute.
112
113 Kernel Pointers
114 ---------------
115
116 ::
117
118         %pK     01234567 or 0123456789abcdef
119
120 For printing kernel pointers which should be hidden from unprivileged
121 users. The behaviour of %pK depends on the kptr_restrict sysctl - see
122 Documentation/sysctl/kernel.txt for more details.
123
124 Unmodified Addresses
125 --------------------
126
127 ::
128
129         %px     01234567 or 0123456789abcdef
130
131 For printing pointers when you *really* want to print the address. Please
132 consider whether or not you are leaking sensitive information about the
133 kernel memory layout before printing pointers with %px. %px is functionally
134 equivalent to %lx (or %lu). %px is preferred because it is more uniquely
135 grep'able. If in the future we need to modify the way the kernel handles
136 printing pointers we will be better equipped to find the call sites.
137
138 Struct Resources
139 ----------------
140
141 ::
142
143         %pr     [mem 0x60000000-0x6fffffff flags 0x2200] or
144                 [mem 0x0000000060000000-0x000000006fffffff flags 0x2200]
145         %pR     [mem 0x60000000-0x6fffffff pref] or
146                 [mem 0x0000000060000000-0x000000006fffffff pref]
147
148 For printing struct resources. The ``R`` and ``r`` specifiers result in a
149 printed resource with (R) or without (r) a decoded flags member.
150
151 Passed by reference.
152
153 Physical address types phys_addr_t
154 ----------------------------------
155
156 ::
157
158         %pa[p]  0x01234567 or 0x0123456789abcdef
159
160 For printing a phys_addr_t type (and its derivatives, such as
161 resource_size_t) which can vary based on build options, regardless of the
162 width of the CPU data path.
163
164 Passed by reference.
165
166 DMA address types dma_addr_t
167 ----------------------------
168
169 ::
170
171         %pad    0x01234567 or 0x0123456789abcdef
172
173 For printing a dma_addr_t type which can vary based on build options,
174 regardless of the width of the CPU data path.
175
176 Passed by reference.
177
178 Raw buffer as an escaped string
179 -------------------------------
180
181 ::
182
183         %*pE[achnops]
184
185 For printing raw buffer as an escaped string. For the following buffer::
186
187                 1b 62 20 5c 43 07 22 90 0d 5d
188
189 A few examples show how the conversion would be done (excluding surrounding
190 quotes)::
191
192                 %*pE            "\eb \C\a"\220\r]"
193                 %*pEhp          "\x1bb \C\x07"\x90\x0d]"
194                 %*pEa           "\e\142\040\\\103\a\042\220\r\135"
195
196 The conversion rules are applied according to an optional combination
197 of flags (see :c:func:`string_escape_mem` kernel documentation for the
198 details):
199
200         - a - ESCAPE_ANY
201         - c - ESCAPE_SPECIAL
202         - h - ESCAPE_HEX
203         - n - ESCAPE_NULL
204         - o - ESCAPE_OCTAL
205         - p - ESCAPE_NP
206         - s - ESCAPE_SPACE
207
208 By default ESCAPE_ANY_NP is used.
209
210 ESCAPE_ANY_NP is the sane choice for many cases, in particularly for
211 printing SSIDs.
212
213 If field width is omitted then 1 byte only will be escaped.
214
215 Raw buffer as a hex string
216 --------------------------
217
218 ::
219
220         %*ph    00 01 02  ...  3f
221         %*phC   00:01:02: ... :3f
222         %*phD   00-01-02- ... -3f
223         %*phN   000102 ... 3f
224
225 For printing small buffers (up to 64 bytes long) as a hex string with a
226 certain separator. For larger buffers consider using
227 :c:func:`print_hex_dump`.
228
229 MAC/FDDI addresses
230 ------------------
231
232 ::
233
234         %pM     00:01:02:03:04:05
235         %pMR    05:04:03:02:01:00
236         %pMF    00-01-02-03-04-05
237         %pm     000102030405
238         %pmR    050403020100
239
240 For printing 6-byte MAC/FDDI addresses in hex notation. The ``M`` and ``m``
241 specifiers result in a printed address with (M) or without (m) byte
242 separators. The default byte separator is the colon (:).
243
244 Where FDDI addresses are concerned the ``F`` specifier can be used after
245 the ``M`` specifier to use dash (-) separators instead of the default
246 separator.
247
248 For Bluetooth addresses the ``R`` specifier shall be used after the ``M``
249 specifier to use reversed byte order suitable for visual interpretation
250 of Bluetooth addresses which are in the little endian order.
251
252 Passed by reference.
253
254 IPv4 addresses
255 --------------
256
257 ::
258
259         %pI4    1.2.3.4
260         %pi4    001.002.003.004
261         %p[Ii]4[hnbl]
262
263 For printing IPv4 dot-separated decimal addresses. The ``I4`` and ``i4``
264 specifiers result in a printed address with (i4) or without (I4) leading
265 zeros.
266
267 The additional ``h``, ``n``, ``b``, and ``l`` specifiers are used to specify
268 host, network, big or little endian order addresses respectively. Where
269 no specifier is provided the default network/big endian order is used.
270
271 Passed by reference.
272
273 IPv6 addresses
274 --------------
275
276 ::
277
278         %pI6    0001:0002:0003:0004:0005:0006:0007:0008
279         %pi6    00010002000300040005000600070008
280         %pI6c   1:2:3:4:5:6:7:8
281
282 For printing IPv6 network-order 16-bit hex addresses. The ``I6`` and ``i6``
283 specifiers result in a printed address with (I6) or without (i6)
284 colon-separators. Leading zeros are always used.
285
286 The additional ``c`` specifier can be used with the ``I`` specifier to
287 print a compressed IPv6 address as described by
288 http://tools.ietf.org/html/rfc5952
289
290 Passed by reference.
291
292 IPv4/IPv6 addresses (generic, with port, flowinfo, scope)
293 ---------------------------------------------------------
294
295 ::
296
297         %pIS    1.2.3.4         or 0001:0002:0003:0004:0005:0006:0007:0008
298         %piS    001.002.003.004 or 00010002000300040005000600070008
299         %pISc   1.2.3.4         or 1:2:3:4:5:6:7:8
300         %pISpc  1.2.3.4:12345   or [1:2:3:4:5:6:7:8]:12345
301         %p[Ii]S[pfschnbl]
302
303 For printing an IP address without the need to distinguish whether it's of
304 type AF_INET or AF_INET6. A pointer to a valid struct sockaddr,
305 specified through ``IS`` or ``iS``, can be passed to this format specifier.
306
307 The additional ``p``, ``f``, and ``s`` specifiers are used to specify port
308 (IPv4, IPv6), flowinfo (IPv6) and scope (IPv6). Ports have a ``:`` prefix,
309 flowinfo a ``/`` and scope a ``%``, each followed by the actual value.
310
311 In case of an IPv6 address the compressed IPv6 address as described by
312 http://tools.ietf.org/html/rfc5952 is being used if the additional
313 specifier ``c`` is given. The IPv6 address is surrounded by ``[``, ``]`` in
314 case of additional specifiers ``p``, ``f`` or ``s`` as suggested by
315 https://tools.ietf.org/html/draft-ietf-6man-text-addr-representation-07
316
317 In case of IPv4 addresses, the additional ``h``, ``n``, ``b``, and ``l``
318 specifiers can be used as well and are ignored in case of an IPv6
319 address.
320
321 Passed by reference.
322
323 Further examples::
324
325         %pISfc          1.2.3.4         or [1:2:3:4:5:6:7:8]/123456789
326         %pISsc          1.2.3.4         or [1:2:3:4:5:6:7:8]%1234567890
327         %pISpfc         1.2.3.4:12345   or [1:2:3:4:5:6:7:8]:12345/123456789
328
329 UUID/GUID addresses
330 -------------------
331
332 ::
333
334         %pUb    00010203-0405-0607-0809-0a0b0c0d0e0f
335         %pUB    00010203-0405-0607-0809-0A0B0C0D0E0F
336         %pUl    03020100-0504-0706-0809-0a0b0c0e0e0f
337         %pUL    03020100-0504-0706-0809-0A0B0C0E0E0F
338
339 For printing 16-byte UUID/GUIDs addresses. The additional ``l``, ``L``,
340 ``b`` and ``B`` specifiers are used to specify a little endian order in
341 lower (l) or upper case (L) hex notation - and big endian order in lower (b)
342 or upper case (B) hex notation.
343
344 Where no additional specifiers are used the default big endian
345 order with lower case hex notation will be printed.
346
347 Passed by reference.
348
349 dentry names
350 ------------
351
352 ::
353
354         %pd{,2,3,4}
355         %pD{,2,3,4}
356
357 For printing dentry name; if we race with :c:func:`d_move`, the name might
358 be a mix of old and new ones, but it won't oops.  %pd dentry is a safer
359 equivalent of %s dentry->d_name.name we used to use, %pd<n> prints ``n``
360 last components.  %pD does the same thing for struct file.
361
362 Passed by reference.
363
364 block_device names
365 ------------------
366
367 ::
368
369         %pg     sda, sda1 or loop0p1
370
371 For printing name of block_device pointers.
372
373 struct va_format
374 ----------------
375
376 ::
377
378         %pV
379
380 For printing struct va_format structures. These contain a format string
381 and va_list as follows::
382
383         struct va_format {
384                 const char *fmt;
385                 va_list *va;
386         };
387
388 Implements a "recursive vsnprintf".
389
390 Do not use this feature without some mechanism to verify the
391 correctness of the format string and va_list arguments.
392
393 Passed by reference.
394
395 Device tree nodes
396 -----------------
397
398 ::
399
400         %pOF[fnpPcCF]
401
402
403 For printing device tree node structures. Default behaviour is
404 equivalent to %pOFf.
405
406         - f - device node full_name
407         - n - device node name
408         - p - device node phandle
409         - P - device node path spec (name + @unit)
410         - F - device node flags
411         - c - major compatible string
412         - C - full compatible string
413
414 The separator when using multiple arguments is ':'
415
416 Examples::
417
418         %pOF    /foo/bar@0                      - Node full name
419         %pOFf   /foo/bar@0                      - Same as above
420         %pOFfp  /foo/bar@0:10                   - Node full name + phandle
421         %pOFfcF /foo/bar@0:foo,device:--P-      - Node full name +
422                                                   major compatible string +
423                                                   node flags
424                                                         D - dynamic
425                                                         d - detached
426                                                         P - Populated
427                                                         B - Populated bus
428
429 Passed by reference.
430
431 Time and date (struct rtc_time)
432 -------------------------------
433
434 ::
435
436         %ptR            YYYY-mm-ddTHH:MM:SS
437         %ptRd           YYYY-mm-dd
438         %ptRt           HH:MM:SS
439         %ptR[dt][r]
440
441 For printing date and time as represented by struct rtc_time structure in
442 human readable format.
443
444 By default year will be incremented by 1900 and month by 1. Use %ptRr (raw)
445 to suppress this behaviour.
446
447 Passed by reference.
448
449 struct clk
450 ----------
451
452 ::
453
454         %pC     pll1
455         %pCn    pll1
456
457 For printing struct clk structures. %pC and %pCn print the name of the clock
458 (Common Clock Framework) or a unique 32-bit ID (legacy clock framework).
459
460 Passed by reference.
461
462 bitmap and its derivatives such as cpumask and nodemask
463 -------------------------------------------------------
464
465 ::
466
467         %*pb    0779
468         %*pbl   0,3-6,8-10
469
470 For printing bitmap and its derivatives such as cpumask and nodemask,
471 %*pb outputs the bitmap with field width as the number of bits and %*pbl
472 output the bitmap as range list with field width as the number of bits.
473
474 Passed by reference.
475
476 Flags bitfields such as page flags, gfp_flags
477 ---------------------------------------------
478
479 ::
480
481         %pGp    referenced|uptodate|lru|active|private
482         %pGg    GFP_USER|GFP_DMA32|GFP_NOWARN
483         %pGv    read|exec|mayread|maywrite|mayexec|denywrite
484
485 For printing flags bitfields as a collection of symbolic constants that
486 would construct the value. The type of flags is given by the third
487 character. Currently supported are [p]age flags, [v]ma_flags (both
488 expect ``unsigned long *``) and [g]fp_flags (expects ``gfp_t *``). The flag
489 names and print order depends on the particular type.
490
491 Note that this format should not be used directly in the
492 :c:func:`TP_printk()` part of a tracepoint. Instead, use the show_*_flags()
493 functions from <trace/events/mmflags.h>.
494
495 Passed by reference.
496
497 Network device features
498 -----------------------
499
500 ::
501
502         %pNF    0x000000000000c000
503
504 For printing netdev_features_t.
505
506 Passed by reference.
507
508 Thanks
509 ======
510
511 If you add other %p extensions, please extend <lib/test_printf.c> with
512 one or more test cases, if at all feasible.
513
514 Thank you for your cooperation and attention.