parisc: pci memory bar assignment fails with 64bit kernels on dino/cujo
[karo-tx-linux.git] / Documentation / printk-formats.txt
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                 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
24                 s32                     %d or %x
25                 u32                     %u or %x
26                 s64                     %lld or %llx
27                 u64                     %llu or %llx
28
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::
34
35         printk("test: sector number/total blocks: %llu/%llu\n",
36                 (unsigned long long)sector, (unsigned long long)blockcount);
37
38 Reminder: ``sizeof()`` result is of type ``size_t``.
39
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
42 unsupported specifier or length qualifier results in a WARN and early
43 return from vsnprintf.
44
45 Raw pointer value SHOULD be printed with %p. The kernel supports
46 the following extended format specifiers for pointer types:
47
48 Symbols/Function Pointers
49 =========================
50
51 ::
52
53         %pF     versatile_init+0x0/0x110
54         %pf     versatile_init
55         %pS     versatile_init+0x0/0x110
56         %pSR    versatile_init+0x9/0x110
57                 (with __builtin_extract_return_addr() translation)
58         %ps     versatile_init
59         %pB     prev_fn_of_versatile_init+0x88/0x88
60
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.
70
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.
75
76 Kernel Pointers
77 ===============
78
79 ::
80
81         %pK     0x01234567 or 0x0123456789abcdef
82
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 ================
89
90 ::
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
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 ========================================
103
104 ::
105
106         %pa[p]  0x01234567 or 0x0123456789abcdef
107
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.
111
112 DMA addresses types ``dma_addr_t``
113 ==================================
114
115 ::
116
117         %pad    0x01234567 or 0x0123456789abcdef
118
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 ===============================
124
125 ::
126
127         %*pE[achnops]
128
129 For printing raw buffer as an escaped string. For the following buffer::
130
131                 1b 62 20 5c 43 07 22 90 0d 5d
132
133 few examples show how the conversion would be done (the result string
134 without surrounding quotes)::
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
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
151
152 By default ESCAPE_ANY_NP is used.
153
154 ESCAPE_ANY_NP is the sane choice for many cases, in particularly for
155 printing SSIDs.
156
157 If field width is omitted the 1 byte only will be escaped.
158
159 Raw buffer as a hex string
160 ==========================
161
162 ::
163
164         %*ph    00 01 02  ...  3f
165         %*phC   00:01:02: ... :3f
166         %*phD   00-01-02- ... -3f
167         %*phN   000102 ... 3f
168
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 ==================
175
176 ::
177
178         %pM     00:01:02:03:04:05
179         %pMR    05:04:03:02:01:00
180         %pMF    00-01-02-03-04-05
181         %pm     000102030405
182         %pmR    050403020100
183
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 (``:``).
187
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.
191
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.
195
196 Passed by reference.
197
198 IPv4 addresses
199 ==============
200
201 ::
202
203         %pI4    1.2.3.4
204         %pi4    001.002.003.004
205         %p[Ii]4[hnbl]
206
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.
210
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.
214
215 Passed by reference.
216
217 IPv6 addresses
218 ==============
219
220 ::
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
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.
229
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
233
234 Passed by reference.
235
236 IPv4/IPv6 addresses (generic, with port, flowinfo, scope)
237 =========================================================
238
239 ::
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
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.
250
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.
254
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
260
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.
264
265 Passed by reference.
266
267 Further examples::
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
273 UUID/GUID addresses
274 ===================
275
276 ::
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
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.
287
288 Where no additional specifiers are used the default big endian
289 order with lower case hex characters will be printed.
290
291 Passed by reference.
292
293 dentry names
294 ============
295
296 ::
297
298         %pd{,2,3,4}
299         %pD{,2,3,4}
300
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.
305
306 Passed by reference.
307
308 block_device names
309 ==================
310
311 ::
312
313         %pg     sda, sda1 or loop0p1
314
315 For printing name of block_device pointers.
316
317 struct va_format
318 ================
319
320 ::
321
322         %pV
323
324 For printing struct va_format structures. These contain a format string
325 and va_list as follows::
326
327         struct va_format {
328                 const char *fmt;
329                 va_list *va;
330         };
331
332 Implements a "recursive vsnprintf".
333
334 Do not use this feature without some mechanism to verify the
335 correctness of the format string and va_list arguments.
336
337 Passed by reference.
338
339 kobjects
340 ========
341
342 ::
343
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
379
380 struct clk
381 ==========
382
383 ::
384
385         %pC     pll1
386         %pCn    pll1
387         %pCr    1560000000
388
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.
392
393 Passed by reference.
394
395 bitmap and its derivatives such as cpumask and nodemask
396 =======================================================
397
398 ::
399
400         %*pb    0779
401         %*pbl   0,3-6,8-10
402
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.
406
407 Passed by reference.
408
409 Flags bitfields such as page flags, gfp_flags
410 =============================================
411
412 ::
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
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.
423
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>.
427
428 Passed by reference.
429
430 Network device features
431 =======================
432
433 ::
434
435         %pNF    0x000000000000c000
436
437 For printing netdev_features_t.
438
439 Passed by reference.
440
441 If you add other ``%p`` extensions, please extend lib/test_printf.c with
442 one or more test cases, if at all feasible.
443
444
445 Thank you for your cooperation and attention.