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