change system file

hc

2024-10-09 244b2c5ca8b14627e4a17755e5922221e121c771

 kernel/Documentation/core-api/printk-formats.rst
..
..
@@ -2,6 +2,8 @@
2
2
 How to get printk format specifiers right
3
3
 =========================================
4
4
 
5
+.. _printk-specifiers:
6
+
5
7
 :Author: Randy Dunlap <rdunlap@infradead.org>
6
8
 :Author: Andrew Murray <amurray@mpc-data.co.uk>
7
9
 
..
..
@@ -13,6 +15,10 @@
13
15
 
14
16
 	If variable is of Type,		use printk format specifier:
15
17
 	------------------------------------------------------------
18
+		char			%d or %x
19
+		unsigned char		%u or %x
20
+		short int		%d or %x
21
+		unsigned short int	%u or %x
16
22
 		int			%d or %x
17
23
 		unsigned int		%u or %x
18
24
 		long			%ld or %lx
..
..
@@ -21,6 +27,10 @@
21
27
 		unsigned long long	%llu or %llx
22
28
 		size_t			%zu or %zx
23
29
 		ssize_t			%zd or %zx
30
+		s8			%d or %x
31
+		u8			%u or %x
32
+		s16			%d or %x
33
+		u16			%u or %x
24
34
 		s32			%d or %x
25
35
 		u32			%u or %x
26
36
 		s64			%lld or %llx
..
..
@@ -50,6 +60,14 @@
50
60
 before printing. The kernel also supports extended specifiers for printing
51
61
 pointers of different types.
52
62
 
63
+Some of the extended specifiers print the data on the given address instead
64
+of printing the address itself. In this case, the following error messages
65
+might be printed instead of the unreachable information::
66
+
67
+	(null)	 data on plain NULL address
68
+	(efault) data on invalid address
69
+	(einval) invalid data on a valid address
70
+
53
71
 Plain Pointers
54
72
 --------------
55
73
 
..
..
@@ -63,6 +81,18 @@
63
81
 the first 32 bits are zeroed. The kernel will print ``(ptrval)`` until it
64
82
 gathers enough entropy. If you *really* want the address see %px below.
65
83
 
84
+Error Pointers
85
+--------------
86
+
87
+::
88
+
89
+	%pe	-ENOSPC
90
+
91
+For printing error pointers (i.e. a pointer for which IS_ERR() is true)
92
+as a symbolic error name. Error values for which no symbolic name is
93
+known are printed in decimal, while a non-ERR_PTR passed as the
94
+argument to %pe gets treated as ordinary %p.
95
+
66
96
 Symbols/Function Pointers
67
97
 -------------------------
68
98
 
..
..
@@ -70,8 +100,6 @@
70
100
 
71
101
 	%pS	versatile_init+0x0/0x110
72
102
 	%ps	versatile_init
73
-	%pF	versatile_init+0x0/0x110
74
-	%pf	versatile_init
75
103
 	%pSR	versatile_init+0x9/0x110
76
104
 		(with __builtin_extract_return_addr() translation)
77
105
 	%pB	prev_fn_of_versatile_init+0x88/0x88
..
..
@@ -81,18 +109,24 @@
81
109
 format. They result in the symbol name with (S) or without (s)
82
110
 offsets. If KALLSYMS are disabled then the symbol address is printed instead.
83
111
 
84
-Note, that the ``F`` and ``f`` specifiers are identical to ``S`` (``s``)
85
-and thus deprecated. We have ``F`` and ``f`` because on ia64, ppc64 and
86
-parisc64 function pointers are indirect and, in fact, are function
87
-descriptors, which require additional dereferencing before we can lookup
88
-the symbol. As of now, ``S`` and ``s`` perform dereferencing on those
89
-platforms (when needed), so ``F`` and ``f`` exist for compatibility
90
-reasons only.
91
-
92
112
 The ``B`` specifier results in the symbol name with offsets and should be
93
113
 used when printing stack backtraces. The specifier takes into
94
114
 consideration the effect of compiler optimisations which may occur
95
115
 when tail-calls are used and marked with the noreturn GCC attribute.
116
+
117
+Probed Pointers from BPF / tracing
118
+----------------------------------
119
+
120
+::
121
+
122
+	%pks	kernel string
123
+	%pus	user string
124
+
125
+The ``k`` and ``u`` specifiers are used for printing prior probed memory from
126
+either kernel memory (k) or user memory (u). The subsequent ``s`` specifier
127
+results in printing a string. For direct use in regular vsnprintf() the (k)
128
+and (u) annotation is ignored, however, when used out of BPF's bpf_trace_printk(),
129
+for example, it reads the memory it is pointing to without faulting.
96
130
 
97
131
 Kernel Pointers
98
132
 ---------------
..
..
@@ -103,7 +137,7 @@
103
137
 
104
138
 For printing kernel pointers which should be hidden from unprivileged
105
139
 users. The behaviour of %pK depends on the kptr_restrict sysctl - see
106
-Documentation/sysctl/kernel.txt for more details.
140
+Documentation/admin-guide/sysctl/kernel.rst for more details.
107
141
 
108
142
 Unmodified Addresses
109
143
 --------------------
..
..
@@ -118,6 +152,20 @@
118
152
 equivalent to %lx (or %lu). %px is preferred because it is more uniquely
119
153
 grep'able. If in the future we need to modify the way the kernel handles
120
154
 printing pointers we will be better equipped to find the call sites.
155
+
156
+Pointer Differences
157
+-------------------
158
+
159
+::
160
+
161
+	%td	2560
162
+	%tx	a00
163
+
164
+For printing the pointer differences, use the %t modifier for ptrdiff_t.
165
+
166
+Example::
167
+
168
+	printk("test: difference between pointers: %td\n", ptr2 - ptr1);
121
169
 
122
170
 Struct Resources
123
171
 ----------------
..
..
@@ -269,7 +317,7 @@
269
317
 
270
318
 The additional ``c`` specifier can be used with the ``I`` specifier to
271
319
 print a compressed IPv6 address as described by
272
-http://tools.ietf.org/html/rfc5952
320
+https://tools.ietf.org/html/rfc5952
273
321
 
274
322
 Passed by reference.
275
323
 
..
..
@@ -293,7 +341,7 @@
293
341
 flowinfo a ``/`` and scope a ``%``, each followed by the actual value.
294
342
 
295
343
 In case of an IPv6 address the compressed IPv6 address as described by
296
-http://tools.ietf.org/html/rfc5952 is being used if the additional
344
+https://tools.ietf.org/html/rfc5952 is being used if the additional
297
345
 specifier ``c`` is given. The IPv6 address is surrounded by ``[``, ``]`` in
298
346
 case of additional specifiers ``p``, ``f`` or ``s`` as suggested by
299
347
 https://tools.ietf.org/html/draft-ietf-6man-text-addr-representation-07
..
..
@@ -376,15 +424,15 @@
376
424
 
377
425
 Passed by reference.
378
426
 
379
-kobjects
380
---------
427
+Device tree nodes
428
+-----------------
381
429
 
382
430
 ::
383
431
 
384
432
 	%pOF[fnpPcCF]
385
433
 
386
434
 
387
-For printing kobject based structs (device nodes). Default behaviour is
435
+For printing device tree node structures. Default behaviour is
388
436
 equivalent to %pOFf.
389
437
 
390
438
 	- f - device node full_name
..
..
@@ -412,6 +460,52 @@
412
460
 
413
461
 Passed by reference.
414
462
 
463
+Fwnode handles
464
+--------------
465
+
466
+::
467
+
468
+	%pfw[fP]
469
+
470
+For printing information on fwnode handles. The default is to print the full
471
+node name, including the path. The modifiers are functionally equivalent to
472
+%pOF above.
473
+
474
+	- f - full name of the node, including the path
475
+	- P - the name of the node including an address (if there is one)
476
+
477
+Examples (ACPI)::
478
+
479
+	%pfwf	\_SB.PCI0.CIO2.port@1.endpoint@0	- Full node name
480
+	%pfwP	endpoint@0				- Node name
481
+
482
+Examples (OF)::
483
+
484
+	%pfwf	/ocp@68000000/i2c@48072000/camera@10/port/endpoint - Full name
485
+	%pfwP	endpoint				- Node name
486
+
487
+Time and date
488
+-------------
489
+
490
+::
491
+
492
+	%pt[RT]			YYYY-mm-ddTHH:MM:SS
493
+	%pt[RT]d		YYYY-mm-dd
494
+	%pt[RT]t		HH:MM:SS
495
+	%pt[RT][dt][r]
496
+
497
+For printing date and time as represented by::
498
+
499
+	R  struct rtc_time structure
500
+	T  time64_t type
501
+
502
+in human readable format.
503
+
504
+By default year will be incremented by 1900 and month by 1.
505
+Use %pt[RT]r (raw) to suppress this behaviour.
506
+
507
+Passed by reference.
508
+
415
509
 struct clk
416
510
 ----------
417
511
 
..
..
@@ -420,9 +514,8 @@
420
514
 	%pC	pll1
421
515
 	%pCn	pll1
422
516
 
423
-For printing struct clk structures. %pC and %pCn print the name
424
-(Common Clock Framework) or address (legacy clock framework) of the
425
-structure.
517
+For printing struct clk structures. %pC and %pCn print the name of the clock
518
+(Common Clock Framework) or a unique 32-bit ID (legacy clock framework).
426
519
 
427
520
 Passed by reference.
428
521