forked from ~ljy/RK356X_SDK_RELEASE

blame | history | patch | commit | commitdiff
hc
2024-10-12 a5969cabbb4660eab42b6ef0412cbbd1200cf14d 
 kernel/Documentation/core-api/printk-formats.rst
....@@ -2,6 +2,8 @@
22 How to get printk format specifiers right
33 =========================================
44 
5
+.. _printk-specifiers:
6
+
57 :Author: Randy Dunlap <rdunlap@infradead.org>
68 :Author: Andrew Murray <amurray@mpc-data.co.uk>
79 
....@@ -13,6 +15,10 @@
1315 
1416 	If variable is of Type,		use printk format specifier:
1517 	------------------------------------------------------------
18
+		char			%d or %x
19
+		unsigned char		%u or %x
20
+		short int		%d or %x
21
+		unsigned short int	%u or %x
1622 		int			%d or %x
1723 		unsigned int		%u or %x
1824 		long			%ld or %lx
....@@ -21,6 +27,10 @@
2127 		unsigned long long	%llu or %llx
2228 		size_t			%zu or %zx
2329 		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
2434 		s32			%d or %x
2535 		u32			%u or %x
2636 		s64			%lld or %llx
....@@ -50,6 +60,14 @@
5060 before printing. The kernel also supports extended specifiers for printing
5161 pointers of different types.
5262 
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
+
5371 Plain Pointers
5472 --------------
5573 
....@@ -63,6 +81,18 @@
6381 the first 32 bits are zeroed. The kernel will print ``(ptrval)`` until it
6482 gathers enough entropy. If you *really* want the address see %px below.
6583 
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
+
6696 Symbols/Function Pointers
6797 -------------------------
6898 
....@@ -70,8 +100,6 @@
70100 
71101 	%pS	versatile_init+0x0/0x110
72102 	%ps	versatile_init
73
-	%pF	versatile_init+0x0/0x110
74
-	%pf	versatile_init
75103 	%pSR	versatile_init+0x9/0x110
76104 		(with __builtin_extract_return_addr() translation)
77105 	%pB	prev_fn_of_versatile_init+0x88/0x88
....@@ -81,18 +109,24 @@
81109 format. They result in the symbol name with (S) or without (s)
82110 offsets. If KALLSYMS are disabled then the symbol address is printed instead.
83111 
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
-
92112 The ``B`` specifier results in the symbol name with offsets and should be
93113 used when printing stack backtraces. The specifier takes into
94114 consideration the effect of compiler optimisations which may occur
95115 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.
96130 
97131 Kernel Pointers
98132 ---------------
....@@ -103,7 +137,7 @@
103137 
104138 For printing kernel pointers which should be hidden from unprivileged
105139 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.
107141 
108142 Unmodified Addresses
109143 --------------------
....@@ -118,6 +152,20 @@
118152 equivalent to %lx (or %lu). %px is preferred because it is more uniquely
119153 grep'able. If in the future we need to modify the way the kernel handles
120154 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);
121169 
122170 Struct Resources
123171 ----------------
....@@ -269,7 +317,7 @@
269317 
270318 The additional ``c`` specifier can be used with the ``I`` specifier to
271319 print a compressed IPv6 address as described by
272
-http://tools.ietf.org/html/rfc5952
320
+https://tools.ietf.org/html/rfc5952
273321 
274322 Passed by reference.
275323 
....@@ -293,7 +341,7 @@
293341 flowinfo a ``/`` and scope a ``%``, each followed by the actual value.
294342 
295343 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
297345 specifier ``c`` is given. The IPv6 address is surrounded by ``[``, ``]`` in
298346 case of additional specifiers ``p``, ``f`` or ``s`` as suggested by
299347 https://tools.ietf.org/html/draft-ietf-6man-text-addr-representation-07
....@@ -376,15 +424,15 @@
376424 
377425 Passed by reference.
378426 
379
-kobjects
380
---------
427
+Device tree nodes
428
+-----------------
381429 
382430 ::
383431 
384432 	%pOF[fnpPcCF]
385433 
386434 
387
-For printing kobject based structs (device nodes). Default behaviour is
435
+For printing device tree node structures. Default behaviour is
388436 equivalent to %pOFf.
389437 
390438 	- f - device node full_name
....@@ -412,6 +460,52 @@
412460 
413461 Passed by reference.
414462 
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
+
415509 struct clk
416510 ----------
417511 
....@@ -420,9 +514,8 @@
420514 	%pC	pll1
421515 	%pCn	pll1
422516 
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).
426519 
427520 Passed by reference.
428521