diff options
Diffstat (limited to 'Documentation/printk-formats.txt')
| -rw-r--r-- | Documentation/printk-formats.txt | 207 |
1 files changed, 198 insertions, 9 deletions
diff --git a/Documentation/printk-formats.txt b/Documentation/printk-formats.txt index 1b5a5ddbc3e..b4498218c47 100644 --- a/Documentation/printk-formats.txt +++ b/Documentation/printk-formats.txt @@ -9,20 +9,208 @@ If variable is of Type, use printk format specifier: size_t %zu or %zx ssize_t %zd or %zx -Raw pointer value SHOULD be printed with %p. +Raw pointer value SHOULD be printed with %p. The kernel supports +the following extended format specifiers for pointer types: -u64 SHOULD be printed with %llu/%llx, (unsigned long long): +Symbols/Function Pointers: - printk("%llu", (unsigned long long)u64_var); + %pF versatile_init+0x0/0x110 + %pf versatile_init + %pS versatile_init+0x0/0x110 + %pSR versatile_init+0x9/0x110 + (with __builtin_extract_return_addr() translation) + %ps versatile_init + %pB prev_fn_of_versatile_init+0x88/0x88 -s64 SHOULD be printed with %lld/%llx, (long long): + For printing symbols and function pointers. The 'S' and 's' specifiers + result in the symbol name with ('S') or without ('s') offsets. Where + this is used on a kernel without KALLSYMS - the symbol address is + printed instead. - printk("%lld", (long long)s64_var); + The 'B' specifier results in the symbol name with offsets and should be + used when printing stack backtraces. The specifier takes into + consideration the effect of compiler optimisations which may occur + when tail-call's are used and marked with the noreturn GCC attribute. + + On ia64, ppc64 and parisc64 architectures function pointers are + actually function descriptors which must first be resolved. The 'F' and + 'f' specifiers perform this resolution and then provide the same + functionality as the 'S' and 's' specifiers. + +Kernel Pointers: + + %pK 0x01234567 or 0x0123456789abcdef + + For printing kernel pointers which should be hidden from unprivileged + users. The behaviour of %pK depends on the kptr_restrict sysctl - see + Documentation/sysctl/kernel.txt for more details. + +Struct Resources: + + %pr [mem 0x60000000-0x6fffffff flags 0x2200] or + [mem 0x0000000060000000-0x000000006fffffff flags 0x2200] + %pR [mem 0x60000000-0x6fffffff pref] or + [mem 0x0000000060000000-0x000000006fffffff pref] + + For printing struct resources. The 'R' and 'r' specifiers result in a + printed resource with ('R') or without ('r') a decoded flags member. + +Physical addresses types phys_addr_t: + + %pa[p] 0x01234567 or 0x0123456789abcdef + + For printing a phys_addr_t type (and its derivatives, such as + resource_size_t) which can vary based on build options, regardless of + the width of the CPU data path. Passed by reference. + +DMA addresses types dma_addr_t: + + %pad 0x01234567 or 0x0123456789abcdef + + For printing a dma_addr_t type which can vary based on build options, + regardless of the width of the CPU data path. Passed by reference. + +Raw buffer as a hex string: + %*ph 00 01 02 ... 3f + %*phC 00:01:02: ... :3f + %*phD 00-01-02- ... -3f + %*phN 000102 ... 3f + + For printing a small buffers (up to 64 bytes long) as a hex string with + certain separator. For the larger buffers consider to use + print_hex_dump(). + +MAC/FDDI addresses: + + %pM 00:01:02:03:04:05 + %pMR 05:04:03:02:01:00 + %pMF 00-01-02-03-04-05 + %pm 000102030405 + %pmR 050403020100 + + For printing 6-byte MAC/FDDI addresses in hex notation. The 'M' and 'm' + specifiers result in a printed address with ('M') or without ('m') byte + separators. The default byte separator is the colon (':'). + + Where FDDI addresses are concerned the 'F' specifier can be used after + the 'M' specifier to use dash ('-') separators instead of the default + separator. + + For Bluetooth addresses the 'R' specifier shall be used after the 'M' + specifier to use reversed byte order suitable for visual interpretation + of Bluetooth addresses which are in the little endian order. + +IPv4 addresses: + + %pI4 1.2.3.4 + %pi4 001.002.003.004 + %p[Ii]4[hnbl] + + For printing IPv4 dot-separated decimal addresses. The 'I4' and 'i4' + specifiers result in a printed address with ('i4') or without ('I4') + leading zeros. + + The additional 'h', 'n', 'b', and 'l' specifiers are used to specify + host, network, big or little endian order addresses respectively. Where + no specifier is provided the default network/big endian order is used. + +IPv6 addresses: + + %pI6 0001:0002:0003:0004:0005:0006:0007:0008 + %pi6 00010002000300040005000600070008 + %pI6c 1:2:3:4:5:6:7:8 + + For printing IPv6 network-order 16-bit hex addresses. The 'I6' and 'i6' + specifiers result in a printed address with ('I6') or without ('i6') + colon-separators. Leading zeros are always used. + + The additional 'c' specifier can be used with the 'I' specifier to + print a compressed IPv6 address as described by + http://tools.ietf.org/html/rfc5952 + +IPv4/IPv6 addresses (generic, with port, flowinfo, scope): + + %pIS 1.2.3.4 or 0001:0002:0003:0004:0005:0006:0007:0008 + %piS 001.002.003.004 or 00010002000300040005000600070008 + %pISc 1.2.3.4 or 1:2:3:4:5:6:7:8 + %pISpc 1.2.3.4:12345 or [1:2:3:4:5:6:7:8]:12345 + %p[Ii]S[pfschnbl] + + For printing an IP address without the need to distinguish whether it's + of type AF_INET or AF_INET6, a pointer to a valid 'struct sockaddr', + specified through 'IS' or 'iS', can be passed to this format specifier. + + The additional 'p', 'f', and 's' specifiers are used to specify port + (IPv4, IPv6), flowinfo (IPv6) and scope (IPv6). Ports have a ':' prefix, + flowinfo a '/' and scope a '%', each followed by the actual value. + + In case of an IPv6 address the compressed IPv6 address as described by + http://tools.ietf.org/html/rfc5952 is being used if the additional + specifier 'c' is given. The IPv6 address is surrounded by '[', ']' in + case of additional specifiers 'p', 'f' or 's' as suggested by + https://tools.ietf.org/html/draft-ietf-6man-text-addr-representation-07 + + In case of IPv4 addresses, the additional 'h', 'n', 'b', and 'l' + specifiers can be used as well and are ignored in case of an IPv6 + address. + + Further examples: + + %pISfc 1.2.3.4 or [1:2:3:4:5:6:7:8]/123456789 + %pISsc 1.2.3.4 or [1:2:3:4:5:6:7:8]%1234567890 + %pISpfc 1.2.3.4:12345 or [1:2:3:4:5:6:7:8]:12345/123456789 + +UUID/GUID addresses: + + %pUb 00010203-0405-0607-0809-0a0b0c0d0e0f + %pUB 00010203-0405-0607-0809-0A0B0C0D0E0F + %pUl 03020100-0504-0706-0809-0a0b0c0e0e0f + %pUL 03020100-0504-0706-0809-0A0B0C0E0E0F + + For printing 16-byte UUID/GUIDs addresses. The additional 'l', 'L', + 'b' and 'B' specifiers are used to specify a little endian order in + lower ('l') or upper case ('L') hex characters - and big endian order + in lower ('b') or upper case ('B') hex characters. + + Where no additional specifiers are used the default little endian + order with lower case hex characters will be printed. + +dentry names: + %pd{,2,3,4} + %pD{,2,3,4} + + For printing dentry name; if we race with d_move(), the name might be + a mix of old and new ones, but it won't oops. %pd dentry is a safer + equivalent of %s dentry->d_name.name we used to use, %pd<n> prints + n last components. %pD does the same thing for struct file. + +struct va_format: + + %pV + + For printing struct va_format structures. These contain a format string + and va_list as follows: + + struct va_format { + const char *fmt; + va_list *va; + }; + + Do not use this feature without some mechanism to verify the + correctness of the format string and va_list arguments. + +u64 SHOULD be printed with %llu/%llx: + + printk("%llu", u64_var); + +s64 SHOULD be printed with %lld/%llx: + + printk("%lld", s64_var); If <type> is dependent on a config option for its size (e.g., sector_t, -blkcnt_t, phys_addr_t, resource_size_t) or is architecture-dependent -for its size (e.g., tcflag_t), use a format specifier of its largest -possible type and explicitly cast to it. Example: +blkcnt_t) or is architecture-dependent for its size (e.g., tcflag_t), use a +format specifier of its largest possible type and explicitly cast to it. +Example: printk("test: sector number/total blocks: %llu/%llu\n", (unsigned long long)sector, (unsigned long long)blockcount); @@ -32,4 +220,5 @@ Reminder: sizeof() result is of type size_t. Thank you for your cooperation and attention. -By Randy Dunlap <rdunlap@xenotime.net> +By Randy Dunlap <rdunlap@infradead.org> and +Andrew Murray <amurray@mpc-data.co.uk> |