1.. include:: ../disclaimer-zh_CN.rst 2 3:Original: Documentation/core-api/printk-formats.rst 4:Translator: Yanteng Si <siyanteng@loongson.cn> 5 6.. _cn_printk-formats.rst: 7 8 9============================== 10如何获得正确的printk格式占位符 11============================== 12 13 14 15:作者: Randy Dunlap <rdunlap@infradead.org> 16:作者: Andrew Murray <amurray@mpc-data.co.uk> 17 18 19整数类型 20======== 21 22:: 23 24 若变量类型是Type,则使用printk格式占位符。 25 ------------------------------------------- 26 char %d 或 %x 27 unsigned char %u 或 %x 28 short int %d 或 %x 29 unsigned short int %u 或 %x 30 int %d 或 %x 31 unsigned int %u 或 %x 32 long %ld 或 %lx 33 unsigned long %lu 或 %lx 34 long long %lld 或 %llx 35 unsigned long long %llu 或 %llx 36 size_t %zu 或 %zx 37 ssize_t %zd 或 %zx 38 s8 %d 或 %x 39 u8 %u 或 %x 40 s16 %d 或 %x 41 u16 %u 或 %x 42 s32 %d 或 %x 43 u32 %u 或 %x 44 s64 %lld 或 %llx 45 u64 %llu 或 %llx 46 47 48如果 <type> 的大小依赖于配置选项 (例如 sector_t, blkcnt_t) 或其大小依赖于架构 49(例如 tcflag_t),则使用其可能的最大类型的格式占位符并显式强制转换为它。 50 51例如 52 53:: 54 55 printk("test: sector number/total blocks: %llu/%llu\n", 56 (unsigned long long)sector, (unsigned long long)blockcount); 57 58提醒:sizeof()返回类型为size_t。 59 60内核的printf不支持%n。显而易见,浮点格式(%e, %f, %g, %a)也不被识别。使用任何不 61支持的占位符或长度限定符都会导致一个WARN并且终止vsnprintf()执行。 62 63指针类型 64======== 65 66一个原始指针值可以用%p打印,它将在打印前对地址进行哈希处理。内核也支持扩展占位符来打印 67不同类型的指针。 68 69一些扩展占位符会打印给定地址上的数据,而不是打印地址本身。在这种情况下,以下错误消息可能 70会被打印出来,而不是无法访问的消息:: 71 72 (null) data on plain NULL address 73 (efault) data on invalid address 74 (einval) invalid data on a valid address 75 76普通指针 77---------- 78 79:: 80 81 %p abcdef12 or 00000000abcdef12 82 83没有指定扩展名的指针(即没有修饰符的%p)被哈希(hash),以防止内核内存布局消息的泄露。这 84样还有一个额外的好处,就是提供一个唯一的标识符。在64位机器上,前32位被清零。当没有足够的 85熵进行散列处理时,内核将打印(ptrval)代替 86 87如果可能的话,使用专门的修饰符,如%pS或%pB(如下所述),以避免打印一个必须事后解释的非哈 88希地址。如果不可能,而且打印地址的目的是为调试提供更多的消息,使用%p,并在调试过程中 89用 ``no_hash_pointers`` 参数启动内核,这将打印所有未修改的%p地址。如果你 *真的* 想知 90道未修改的地址,请看下面的%px。 91 92如果(也只有在)你将地址作为虚拟文件的内容打印出来,例如在procfs或sysfs中(使用 93seq_printf(),而不是printk())由用户空间进程读取,使用下面描述的%pK修饰符,不 94要用%p或%px。 95 96 97错误指针 98-------- 99 100:: 101 102 %pe -ENOSPC 103 104用于打印错误指针(即IS_ERR()为真的指针)的符号错误名。不知道符号名的错误值会以十进制打印, 105而作为%pe参数传递的非ERR_PTR会被视为普通的%p。 106 107符号/函数指针 108------------- 109 110:: 111 112 %pS versatile_init+0x0/0x110 113 %ps versatile_init 114 %pSR versatile_init+0x9/0x110 115 (with __builtin_extract_return_addr() translation) 116 %pB prev_fn_of_versatile_init+0x88/0x88 117 118 119``S`` 和 ``s`` 占位符用于打印符号格式的指针。它们的结果是符号名称带有(S)或不带有(s)偏移 120量。如果禁用KALLSYMS,则打印符号地址。 121 122``B`` 占位符的结果是带有偏移量的符号名,在打印堆栈回溯时应该使用。占位符将考虑编译器优化 123的影响,当使用尾部调用并使用noreturn GCC属性标记时,可能会发生这种优化。 124 125如果指针在一个模块内,模块名称和可选的构建ID将被打印在符号名称之后,并在说明符的末尾添加 126一个额外的 ``b`` 。 127 128:: 129 130 %pS versatile_init+0x0/0x110 [module_name] 131 %pSb versatile_init+0x0/0x110 [module_name ed5019fdf5e53be37cb1ba7899292d7e143b259e] 132 %pSRb versatile_init+0x9/0x110 [module_name ed5019fdf5e53be37cb1ba7899292d7e143b259e] 133 (with __builtin_extract_return_addr() translation) 134 %pBb prev_fn_of_versatile_init+0x88/0x88 [module_name ed5019fdf5e53be37cb1ba7899292d7e143b259e] 135 136来自BPF / tracing追踪的探查指针 137---------------------------------- 138 139:: 140 141 %pks kernel string 142 %pus user string 143 144``k`` 和 ``u`` 指定符用于打印来自内核内存(k)或用户内存(u)的先前探测的内存。后面的 ``s`` 指 145定符的结果是打印一个字符串。对于直接在常规的vsnprintf()中使用时,(k)和(u)注释被忽略,但是,当 146在BPF的bpf_trace_printk()之外使用时,它会读取它所指向的内存,不会出现错误。 147 148内核指针 149-------- 150 151:: 152 153 %pK 01234567 or 0123456789abcdef 154 155用于打印应该对非特权用户隐藏的内核指针。%pK的行为取决于kptr_restrict sysctl——详见 156Documentation/admin-guide/sysctl/kernel.rst。 157 158未经修改的地址 159-------------- 160 161:: 162 163 %px 01234567 or 0123456789abcdef 164 165对于打印指针,当你 *真的* 想打印地址时。在用%px打印指针之前,请考虑你是否泄露了内核内 166存布局的敏感消息。%px在功能上等同于%lx(或%lu)。%px是首选,因为它在grep查找时更唯一。 167如果将来我们需要修改内核处理打印指针的方式,我们将能更好地找到调用点。 168 169在使用%px之前,请考虑使用%p并在调试过程中启用' ' no_hash_pointer ' '内核参数是否足 170够(参见上面的%p描述)。%px的一个有效场景可能是在panic发生之前立即打印消息,这样无论如何 171都可以防止任何敏感消息被利用,使用%px就不需要用no_hash_pointer来重现panic。 172 173指针差异 174-------- 175 176:: 177 178 %td 2560 179 %tx a00 180 181为了打印指针的差异,使用ptrdiff_t的%t修饰符。 182 183例如:: 184 185 printk("test: difference between pointers: %td\n", ptr2 - ptr1); 186 187结构体资源(Resources) 188----------------------- 189 190:: 191 192 %pr [mem 0x60000000-0x6fffffff flags 0x2200] or 193 [mem 0x0000000060000000-0x000000006fffffff flags 0x2200] 194 %pR [mem 0x60000000-0x6fffffff pref] or 195 [mem 0x0000000060000000-0x000000006fffffff pref] 196 197用于打印结构体资源。 ``R`` 和 ``r`` 占位符的结果是打印出的资源带有(R)或不带有(r)解码标志 198成员。 199 200通过引用传递。 201 202物理地址类型 phys_addr_t 203------------------------ 204 205:: 206 207 %pa[p] 0x01234567 or 0x0123456789abcdef 208 209用于打印phys_addr_t类型(以及它的衍生物,如resource_size_t),该类型可以根据构建选项而 210变化,无论CPU数据真实物理地址宽度如何。 211 212通过引用传递。 213 214DMA地址类型dma_addr_t 215--------------------- 216 217:: 218 219 %pad 0x01234567 or 0x0123456789abcdef 220 221用于打印dma_addr_t类型,该类型可以根据构建选项而变化,而不考虑CPU数据路径的宽度。 222 223通过引用传递。 224 225原始缓冲区为转义字符串 226---------------------- 227 228:: 229 230 %*pE[achnops] 231 232用于将原始缓冲区打印成转义字符串。对于以下缓冲区:: 233 234 1b 62 20 5c 43 07 22 90 0d 5d 235 236几个例子展示了如何进行转换(不包括两端的引号)。:: 237 238 %*pE "\eb \C\a"\220\r]" 239 %*pEhp "\x1bb \C\x07"\x90\x0d]" 240 %*pEa "\e\142\040\\\103\a\042\220\r\135" 241 242转换规则是根据可选的标志组合来应用的(详见:c:func:`string_escape_mem` 内核文档): 243 244 - a - ESCAPE_ANY 245 - c - ESCAPE_SPECIAL 246 - h - ESCAPE_HEX 247 - n - ESCAPE_NULL 248 - o - ESCAPE_OCTAL 249 - p - ESCAPE_NP 250 - s - ESCAPE_SPACE 251 252默认情况下,使用 ESCAPE_ANY_NP。 253 254ESCAPE_ANY_NP是许多情况下的明智选择,特别是对于打印SSID。 255 256如果字段宽度被省略,那么将只转义1个字节。 257 258原始缓冲区为十六进制字符串 259-------------------------- 260 261:: 262 263 %*ph 00 01 02 ... 3f 264 %*phC 00:01:02: ... :3f 265 %*phD 00-01-02- ... -3f 266 %*phN 000102 ... 3f 267 268对于打印小的缓冲区(最长64个字节),可以用一定的分隔符作为一个 269十六进制字符串。对于较大的缓冲区,可以考虑使用 270:c:func:`print_hex_dump` 。 271 272MAC/FDDI地址 273------------ 274 275:: 276 277 %pM 00:01:02:03:04:05 278 %pMR 05:04:03:02:01:00 279 %pMF 00-01-02-03-04-05 280 %pm 000102030405 281 %pmR 050403020100 282 283用于打印以十六进制表示的6字节MAC/FDDI地址。 ``M`` 和 ``m`` 占位符导致打印的 284地址有(M)或没有(m)字节分隔符。默认的字节分隔符是冒号(:)。 285 286对于FDDI地址,可以在 ``M`` 占位符之后使用 ``F`` 说明,以使用破折号(——)分隔符 287代替默认的分隔符。 288 289对于蓝牙地址, ``R`` 占位符应使用在 ``M`` 占位符之后,以使用反转的字节顺序,适 290合于以小尾端顺序的蓝牙地址的肉眼可见的解析。 291 292通过引用传递。 293 294IPv4地址 295-------- 296 297:: 298 299 %pI4 1.2.3.4 300 %pi4 001.002.003.004 301 %p[Ii]4[hnbl] 302 303用于打印IPv4点分隔的十进制地址。 ``I4`` 和 ``i4`` 占位符的结果是打印的地址 304有(i4)或没有(I4)前导零。 305 306附加的 ``h`` 、 ``n`` 、 ``b`` 和 ``l`` 占位符分别用于指定主机、网络、大 307尾端或小尾端地址。如果没有提供占位符,则使用默认的网络/大尾端顺序。 308 309通过引用传递。 310 311IPv6 地址 312--------- 313 314:: 315 316 %pI6 0001:0002:0003:0004:0005:0006:0007:0008 317 %pi6 00010002000300040005000600070008 318 %pI6c 1:2:3:4:5:6:7:8 319 320用于打印IPv6网络顺序的16位十六进制地址。 ``I6`` 和 ``i6`` 占位符的结果是 321打印的地址有(I6)或没有(i6)分号。始终使用前导零。 322 323额外的 ``c`` 占位符可与 ``I`` 占位符一起使用,以打印压缩的IPv6地址,如 324https://tools.ietf.org/html/rfc5952 所述 325 326通过引用传递。 327 328IPv4/IPv6地址(generic, with port, flowinfo, scope) 329-------------------------------------------------- 330 331:: 332 333 %pIS 1.2.3.4 or 0001:0002:0003:0004:0005:0006:0007:0008 334 %piS 001.002.003.004 or 00010002000300040005000600070008 335 %pISc 1.2.3.4 or 1:2:3:4:5:6:7:8 336 %pISpc 1.2.3.4:12345 or [1:2:3:4:5:6:7:8]:12345 337 %p[Ii]S[pfschnbl] 338 339用于打印一个IP地址,不需要区分它的类型是AF_INET还是AF_INET6。一个指向有效结构 340体sockaddr的指针,通过 ``IS`` 或 ``IS`` 指定,可以传递给这个格式占位符。 341 342附加的 ``p`` 、 ``f`` 和 ``s`` 占位符用于指定port(IPv4, IPv6)、 343flowinfo (IPv6)和sope(IPv6)。port有一个 ``:`` 前缀,flowinfo是 ``/`` 和 344范围是 ``%`` ,每个后面都跟着实际的值。 345 346对于IPv6地址,如果指定了额外的指定符 ``c`` ,则使用 347https://tools.ietf.org/html/rfc5952 描述的压缩IPv6地址。 348如https://tools.ietf.org/html/draft-ietf-6man-text-addr-representation-07 349所建议的,IPv6地址由'[',']'包围,以防止出现额外的占位符 ``p`` , ``f`` 或 ``s`` 。 350 351对于IPv4地址,也可以使用额外的 ``h`` , ``n`` , ``b`` 和 ``l`` 说 352明符,但对于IPv6地址则忽略。 353 354通过引用传递。 355 356更多例子:: 357 358 %pISfc 1.2.3.4 or [1:2:3:4:5:6:7:8]/123456789 359 %pISsc 1.2.3.4 or [1:2:3:4:5:6:7:8]%1234567890 360 %pISpfc 1.2.3.4:12345 or [1:2:3:4:5:6:7:8]:12345/123456789 361 362UUID/GUID地址 363------------- 364 365:: 366 367 %pUb 00010203-0405-0607-0809-0a0b0c0d0e0f 368 %pUB 00010203-0405-0607-0809-0A0B0C0D0E0F 369 %pUl 03020100-0504-0706-0809-0a0b0c0e0e0f 370 %pUL 03020100-0504-0706-0809-0A0B0C0E0E0F 371 372用于打印16字节的UUID/GUIDs地址。附加的 ``l`` , ``L`` , ``b`` 和 ``B`` 占位符用 373于指定小写(l)或大写(L)十六进制表示法中的小尾端顺序,以及小写(b)或大写(B)十六进制表 374示法中的大尾端顺序。 375 376如果没有使用额外的占位符,则将打印带有小写十六进制表示法的默认大端顺序。 377 378通过引用传递。 379 380目录项(dentry)的名称 381---------------------- 382 383:: 384 385 %pd{,2,3,4} 386 %pD{,2,3,4} 387 388用于打印dentry名称;如果我们用 :c:func:`d_move` 和它比较,名称可能是新旧混合的,但 389不会oops。 %pd dentry比较安全,其相当于我们以前用的%s dentry->d_name.name,%pd<n>打 390印 ``n`` 最后的组件。 %pD对结构文件做同样的事情。 391 392 393通过引用传递。 394 395块设备(block_device)名称 396-------------------------- 397 398:: 399 400 %pg sda, sda1 or loop0p1 401 402用于打印block_device指针的名称。 403 404va_format结构体 405--------------- 406 407:: 408 409 %pV 410 411用于打印结构体va_format。这些结构包含一个格式字符串 412和va_list如下 413 414:: 415 416 struct va_format { 417 const char *fmt; 418 va_list *va; 419 }; 420 421实现 "递归vsnprintf"。 422 423如果没有一些机制来验证格式字符串和va_list参数的正确性,请不要使用这个功能。 424 425通过引用传递。 426 427设备树节点 428---------- 429 430:: 431 432 %pOF[fnpPcCF] 433 434 435用于打印设备树节点结构。默认行为相当于%pOFf。 436 437 - f - 设备节点全称 438 - n - 设备节点名 439 - p - 设备节点句柄 440 - P - 设备节点路径规范(名称+@单位) 441 - F - 设备节点标志 442 - c - 主要兼容字符串 443 - C - 全兼容字符串 444 445当使用多个参数时,分隔符是':'。 446 447例如 448 449:: 450 451 %pOF /foo/bar@0 - Node full name 452 %pOFf /foo/bar@0 - Same as above 453 %pOFfp /foo/bar@0:10 - Node full name + phandle 454 %pOFfcF /foo/bar@0:foo,device:--P- - Node full name + 455 major compatible string + 456 node flags 457 D - dynamic 458 d - detached 459 P - Populated 460 B - Populated bus 461 462通过引用传递。 463 464Fwnode handles 465-------------- 466 467:: 468 469 %pfw[fP] 470 471用于打印fwnode_handles的消息。默认情况下是打印完整的节点名称,包括路径。 472这些修饰符在功能上等同于上面的%pOF。 473 474 - f - 节点的全名,包括路径。 475 - P - 节点名称,包括地址(如果有的话)。 476 477例如 (ACPI) 478 479:: 480 481 %pfwf \_SB.PCI0.CIO2.port@1.endpoint@0 - Full node name 482 %pfwP endpoint@0 - Node name 483 484例如 (OF) 485 486:: 487 488 %pfwf /ocp@68000000/i2c@48072000/camera@10/port/endpoint - Full name 489 %pfwP endpoint - Node name 490 491时间和日期 492---------- 493 494:: 495 496 %pt[RT] YYYY-mm-ddTHH:MM:SS 497 %pt[RT]s YYYY-mm-dd HH:MM:SS 498 %pt[RT]d YYYY-mm-dd 499 %pt[RT]t HH:MM:SS 500 %pt[RT][dt][r][s] 501 502用于打印日期和时间:: 503 504 R struct rtc_time structure 505 T time64_t type 506 507以我们(人类)可读的格式。 508 509默认情况下,年将以1900为单位递增,月将以1为单位递增。 使用%pt[RT]r (raw) 510来抑制这种行为。 511 512%pt[RT]s(空格)将覆盖ISO 8601的分隔符,在日期和时间之间使用''(空格)而 513不是'T'(大写T)。当日期或时间被省略时,它不会有任何影响。 514 515通过引用传递。 516 517clk结构体 518--------- 519 520:: 521 522 %pC pll1 523 %pCn pll1 524 525用于打印clk结构。%pC 和 %pCn 打印时钟的名称(通用时钟框架)或唯一的32位 526ID(传统时钟框架)。 527 528通过引用传递。 529 530位图及其衍生物,如cpumask和nodemask 531----------------------------------- 532 533:: 534 535 %*pb 0779 536 %*pbl 0,3-6,8-10 537 538对于打印位图(bitmap)及其派生的cpumask和nodemask,%*pb输出以字段宽度为位数的位图, 539%*pbl输出以字段宽度为位数的范围列表。 540 541字段宽度用值传递,位图用引用传递。可以使用辅助宏cpumask_pr_args()和 542nodemask_pr_args()来方便打印cpumask和nodemask。 543 544标志位字段,如页标志、gfp_flags 545------------------------------- 546 547:: 548 549 %pGp referenced|uptodate|lru|active|private|node=0|zone=2|lastcpupid=0x1fffff 550 %pGg GFP_USER|GFP_DMA32|GFP_NOWARN 551 %pGv read|exec|mayread|maywrite|mayexec|denywrite 552 553将flags位字段打印为构造值的符号常量集合。标志的类型由第三个字符给出。目前支持的 554是[p]age flags, [v]ma_flags(都期望 ``unsigned long *`` )和 555[g]fp_flags(期望 ``gfp_t *`` )。标志名称和打印顺序取决于特定的类型。 556 557注意,这种格式不应该直接用于跟踪点的:c:func:`TP_printk()` 部分。相反,应使 558用 <trace/events/mmflags.h>中的show_*_flags()函数。 559 560通过引用传递。 561 562网络设备特性 563------------ 564 565:: 566 567 %pNF 0x000000000000c000 568 569用于打印netdev_features_t。 570 571通过引用传递。 572 573V4L2和DRM FourCC代码(像素格式) 574------------------------------ 575 576:: 577 578 %p4cc 579 580打印V4L2或DRM使用的FourCC代码,包括格式端序及其十六进制的数值。 581 582通过引用传递。 583 584例如:: 585 586 %p4cc BG12 little-endian (0x32314742) 587 %p4cc Y10 little-endian (0x20303159) 588 %p4cc NV12 big-endian (0xb231564e) 589 590谢谢 591==== 592 593如果您添加了其他%p扩展,请在可行的情况下,用一个或多个测试用例扩展<lib/test_printf.c>。 594 595谢谢你的合作和关注。 596