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