Add documentation for the two newly introduced options for the
function_graph tracer. The new option funcgraph-retval is used to
control whether or not to display the return value. The new option
graph_retval_hex is used to control the display format of the return
value.
Signed-off-by: Donglin Peng <pengdonglin@sangfor.com.cn>
---
v5:
- Describe the limitations of funcgraph-retval
---
Documentation/trace/ftrace.rst | 75 ++++++++++++++++++++++++++++++++++
1 file changed, 75 insertions(+)
diff --git a/Documentation/trace/ftrace.rst b/Documentation/trace/ftrace.rst
index b927fb2b94dc..797841d15da9 100644
--- a/Documentation/trace/ftrace.rst
+++ b/Documentation/trace/ftrace.rst
@@ -1328,6 +1328,19 @@ Options for function_graph tracer:
only a closing curly bracket "}" is displayed for
the return of a function.
+ funcgraph-retval
+ When set, the return event will include the function and
+ its return value. Note that even if the function return
+ type is void, a return value will also be printed, you
+ should ignore it. This option is off by default.
+
+ graph_retval_hex
+ Depend on function-retval. When set, the function return
+ value will be printed in hexadecimal format. If this is not
+ set and the return value looks like an error code, it will
+ be printed in signed decimal format, else in hexadecimal
+ format. This option is off by default.
+
sleep-time
When running function graph tracer, to include
the time a task schedules out in its function.
@@ -2673,6 +2686,68 @@ It is default disabled.
0) 1.757 us | } /* kmem_cache_free() */
0) 2.861 us | } /* putname() */
+The return value of each traced function can be displayed. This
+feature can be very useful when you encounter system call failures
+and want to locate the function that return errors firstly.
+
+ - hide: echo nofuncgraph-retval > trace_options
+ - show: echo funcgraph-retval > trace_options
+
+ Example with funcgraph-retval::
+
+ 1) | cgroup_migrate() {
+ 1) 0.651 us | cgroup_migrate_add_task(); /* = 0xffff93fcfd346c00 */
+ 1) | cgroup_migrate_execute() {
+ 1) | cpu_cgroup_can_attach() {
+ 1) | cgroup_taskset_first() {
+ 1) 0.732 us | cgroup_taskset_next(); /* = 0xffff93fc8fb20000 */
+ 1) 1.232 us | } /* cgroup_taskset_first = 0xffff93fc8fb20000 */
+ 1) 0.380 us | sched_rt_can_attach(); /* = 0x0 */
+ 1) 2.335 us | } /* cpu_cgroup_can_attach = -22 */
+ 1) 4.369 us | } /* cgroup_migrate_execute = -22 */
+ 1) 7.143 us | } /* cgroup_migrate = -22 */
+
+The above example shows that the cgroup function cpu_cgroup_can_attach
+returned the error code -22 firstly, then we can read the code of this
+function to get the root cause.
+
+If the option graph_retval_hex is not set and the return value looks
+like an error code, it will be printed in signed decimal format. In
+other cases, it will be printed in hexadecimal format.
+
+ - hexadecimal or signed decimal: echo nograph_retval_hex > trace_options
+ - hexadecimal: echo graph_retval_hex > trace_options
+
+ Example with graph_retval_hex::
+
+ 1) | cgroup_migrate() {
+ 1) 0.651 us | cgroup_migrate_add_task(); /* = 0xffff93fcfd346c00 */
+ 1) | cgroup_migrate_execute() {
+ 1) | cpu_cgroup_can_attach() {
+ 1) | cgroup_taskset_first() {
+ 1) 0.732 us | cgroup_taskset_next(); /* = 0xffff93fc8fb20000 */
+ 1) 1.232 us | } /* cgroup_taskset_first = 0xffff93fc8fb20000 */
+ 1) 0.380 us | sched_rt_can_attach(); /* = 0x0 */
+ 1) 2.335 us | } /* cpu_cgroup_can_attach = 0xffffffea */
+ 1) 4.369 us | } /* cgroup_migrate_execute = 0xffffffea */
+ 1) 7.143 us | } /* cgroup_migrate = 0xffffffea */
+
+There are some limitations when using the funcgraph-retval currently:
+
+- Even if the function return type is void, a return value will still
+ be printed, and you can just ignore it.
+
+- Even if the return value is not an error code actually, it may be
+ displayed as an error code. You should read the code to check.
+ For example, both 0xfe and 0xfffe are be interpreted as -2.
+
+- Only the value of the first return register will be recorded and
+ printed even if the return values may be stored in two registers
+ actually. For example, both the eax and edx are used to store a
+ 64 bit return value in the x86 architecture, and the eax stores
+ the low 32 bit, the edx stores the high 32 bit, however only the
+ value stored in eax will be recorded and printed.
+
You can put some comments on specific functions by using
trace_printk() For example, if you want to put a comment inside
the __might_sleep() function, you just have to include
--
2.25.1On 2023/3/20 21:16, Donglin Peng wrote: > +There are some limitations when using the funcgraph-retval currently: > + > +- Even if the function return type is void, a return value will still > + be printed, and you can just ignore it. > + > +- Even if the return value is not an error code actually, it may be > + displayed as an error code. You should read the code to check. > + For example, both 0xfe and 0xfffe are be interpreted as -2. For char and short types, displaying as signed decimal may be not appropriate, because they are rarely used to store error code. So in "smart" mode (graph_retval_hex=0), I suggest just smart convert error value stored in int or pointer to signed decimal. > +- Only the value of the first return register will be recorded and > + printed even if the return values may be stored in two registers > + actually. For example, both the eax and edx are used to store a > + 64 bit return value in the x86 architecture, and the eax stores > + the low 32 bit, the edx stores the high 32 bit, however only the > + value stored in eax will be recorded and printed. > + > You can put some comments on specific functions by using > trace_printk() For example, if you want to put a comment inside > the __might_sleep() function, you just have to include -- Thanks, - Ding Hui
On 2023/3/21 10:31, Ding Hui wrote: > On 2023/3/20 21:16, Donglin Peng wrote: > >> +There are some limitations when using the funcgraph-retval currently: >> + >> +- Even if the function return type is void, a return value will still >> + be printed, and you can just ignore it. >> + >> +- Even if the return value is not an error code actually, it may be >> + displayed as an error code. You should read the code to check. >> + For example, both 0xfe and 0xfffe are be interpreted as -2. > > For char and short types, displaying as signed decimal may be not > appropriate, because they are rarely used to store error code. > > So in "smart" mode (graph_retval_hex=0), I suggest just smart convert > error value stored in int or pointer to signed decimal. Yeah, I will remove the return value conversion for char and short types in the "smart" mode. > >> +- Only the value of the first return register will be recorded and >> + printed even if the return values may be stored in two registers >> + actually. For example, both the eax and edx are used to store a >> + 64 bit return value in the x86 architecture, and the eax stores >> + the low 32 bit, the edx stores the high 32 bit, however only the >> + value stored in eax will be recorded and printed. >> + >> You can put some comments on specific functions by using >> trace_printk() For example, if you want to put a comment inside >> the __might_sleep() function, you just have to include >
© 2016 - 2026 Red Hat, Inc.