lkml.org 
[lkml]   [2020]   [Jan]   [14]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    Date
    From
    Subject[for-next][PATCH 25/26] Documentation: tracing: Add boot-time tracing document
    From: Masami Hiramatsu <mhiramat@kernel.org>

    Add a documentation about boot-time tracing options in
    boot config.

    Link: http://lkml.kernel.org/r/157867246028.17873.8047384554383977870.stgit@devnote2

    Signed-off-by: Masami Hiramatsu <mhiramat@kernel.org>
    Signed-off-by: Steven Rostedt (VMware) <rostedt@goodmis.org>
    ---
    Documentation/admin-guide/bootconfig.rst | 2 +
    Documentation/trace/boottime-trace.rst | 184 +++++++++++++++++++++++
    Documentation/trace/index.rst | 1 +
    3 files changed, 187 insertions(+)
    create mode 100644 Documentation/trace/boottime-trace.rst

    diff --git a/Documentation/admin-guide/bootconfig.rst b/Documentation/admin-guide/bootconfig.rst
    index f7475df2a718..c8f7cd4cf44e 100644
    --- a/Documentation/admin-guide/bootconfig.rst
    +++ b/Documentation/admin-guide/bootconfig.rst
    @@ -1,5 +1,7 @@
    .. SPDX-License-Identifier: GPL-2.0

    +.. _bootconfig:
    +
    ==================
    Boot Configuration
    ==================
    diff --git a/Documentation/trace/boottime-trace.rst b/Documentation/trace/boottime-trace.rst
    new file mode 100644
    index 000000000000..1d10fdebf1b2
    --- /dev/null
    +++ b/Documentation/trace/boottime-trace.rst
    @@ -0,0 +1,184 @@
    +.. SPDX-License-Identifier: GPL-2.0
    +
    +=================
    +Boot-time tracing
    +=================
    +
    +:Author: Masami Hiramatsu <mhiramat@kernel.org>
    +
    +Overview
    +========
    +
    +Boot-time tracing allows users to trace boot-time process including
    +device initialization with full features of ftrace including per-event
    +filter and actions, histograms, kprobe-events and synthetic-events,
    +and trace instances.
    +Since kernel cmdline is not enough to control these complex features,
    +this uses bootconfig file to describe tracing feature programming.
    +
    +Options in the Boot Config
    +==========================
    +
    +Here is the list of available options list for boot time tracing in
    +boot config file [1]_. All options are under "ftrace." or "kernel."
    +refix. See kernel parameters for the options which starts
    +with "kernel." prefix [2]_.
    +
    +.. [1] See :ref:`Documentation/admin-guide/bootconfig.rst <bootconfig>`
    +.. [2] See :ref:`Documentation/admin-guide/kernel-parameters.rst <kernelparameters>`
    +
    +Ftrace Global Options
    +---------------------
    +
    +Ftrace global options have "kernel." prefix in boot config, which means
    +these options are passed as a part of kernel legacy command line.
    +
    +kernel.tp_printk
    + Output trace-event data on printk buffer too.
    +
    +kernel.dump_on_oops [= MODE]
    + Dump ftrace on Oops. If MODE = 1 or omitted, dump trace buffer
    + on all CPUs. If MODE = 2, dump a buffer on a CPU which kicks Oops.
    +
    +kernel.traceoff_on_warning
    + Stop tracing if WARN_ON() occurs.
    +
    +kernel.fgraph_max_depth = MAX_DEPTH
    + Set MAX_DEPTH to maximum depth of fgraph tracer.
    +
    +kernel.fgraph_filters = FILTER[, FILTER2...]
    + Add fgraph tracing function filters.
    +
    +kernel.fgraph_notraces = FILTER[, FILTER2...]
    + Add fgraph non tracing function filters.
    +
    +
    +Ftrace Per-instance Options
    +---------------------------
    +
    +These options can be used for each instance including global ftrace node.
    +
    +ftrace.[instance.INSTANCE.]options = OPT1[, OPT2[...]]
    + Enable given ftrace options.
    +
    +ftrace.[instance.INSTANCE.]trace_clock = CLOCK
    + Set given CLOCK to ftrace's trace_clock.
    +
    +ftrace.[instance.INSTANCE.]buffer_size = SIZE
    + Configure ftrace buffer size to SIZE. You can use "KB" or "MB"
    + for that SIZE.
    +
    +ftrace.[instance.INSTANCE.]alloc_snapshot
    + Allocate snapshot buffer.
    +
    +ftrace.[instance.INSTANCE.]cpumask = CPUMASK
    + Set CPUMASK as trace cpu-mask.
    +
    +ftrace.[instance.INSTANCE.]events = EVENT[, EVENT2[...]]
    + Enable given events on boot. You can use a wild card in EVENT.
    +
    +ftrace.[instance.INSTANCE.]tracer = TRACER
    + Set TRACER to current tracer on boot. (e.g. function)
    +
    +ftrace.[instance.INSTANCE.]ftrace.filters
    + This will take an array of tracing function filter rules
    +
    +ftrace.[instance.INSTANCE.]ftrace.notraces
    + This will take an array of NON-tracing function filter rules
    +
    +
    +Ftrace Per-Event Options
    +------------------------
    +
    +These options are setting per-event options.
    +
    +ftrace.[instance.INSTANCE.]event.GROUP.EVENT.enable
    + Enables GROUP:EVENT tracing.
    +
    +ftrace.[instance.INSTANCE.]event.GROUP.EVENT.filter = FILTER
    + Set FILTER rule to the GROUP:EVENT.
    +
    +ftrace.[instance.INSTANCE.]event.GROUP.EVENT.actions = ACTION[, ACTION2[...]]
    + Set ACTIONs to the GROUP:EVENT.
    +
    +ftrace.[instance.INSTANCE.]event.kprobes.EVENT.probes = PROBE[, PROBE2[...]]
    + Defines new kprobe event based on PROBEs. It is able to define
    + multiple probes on one event, but those must have same type of
    + arguments. This option is available only for the event which
    + group name is "kprobes".
    +
    +ftrace.[instance.INSTANCE.]event.synthetic.EVENT.fields = FIELD[, FIELD2[...]]
    + Defines new synthetic event with FIELDs. Each field should be
    + "type varname".
    +
    +Note that kprobe and synthetic event definitions can be written under
    +instance node, but those are also visible from other instances. So please
    +take care for event name conflict.
    +
    +
    +Examples
    +========
    +
    +For example, to add filter and actions for each event, define kprobe
    +events, and synthetic events with histogram, write a boot config like
    +below::
    +
    + ftrace.event {
    + task.task_newtask {
    + filter = "pid < 128"
    + enable
    + }
    + kprobes.vfs_read {
    + probes = "vfs_read $arg1 $arg2"
    + filter = "common_pid < 200"
    + enable
    + }
    + synthetic.initcall_latency {
    + fields = "unsigned long func", "u64 lat"
    + actions = "hist:keys=func.sym,lat:vals=lat:sort=lat"
    + }
    + initcall.initcall_start {
    + actions = "hist:keys=func:ts0=common_timestamp.usecs"
    + }
    + initcall.initcall_finish {
    + actions = "hist:keys=func:lat=common_timestamp.usecs-$ts0:onmatch(initcall.initcall_start).initcall_latency(func,$lat)"
    + }
    + }
    +
    +Also, boottime tracing supports "instance" node, which allows us to run
    +several tracers for different purpose at once. For example, one tracer
    +is for tracing functions start with "user\_", and others tracing "kernel\_"
    +functions, you can write boot config as below::
    +
    + ftrace.instance {
    + foo {
    + tracer = "function"
    + ftrace.filters = "user_*"
    + }
    + bar {
    + tracer = "function"
    + ftrace.filters = "kernel_*"
    + }
    + }
    +
    +The instance node also accepts event nodes so that each instance
    +can customize its event tracing.
    +
    +This boot-time tracing also supports ftrace kernel parameters via boot
    +config.
    +For example, following kernel parameters::
    +
    + trace_options=sym-addr trace_event=initcall:* tp_printk trace_buf_size=1M ftrace=function ftrace_filter="vfs*"
    +
    +This can be written in boot config like below::
    +
    + kernel {
    + trace_options = sym-addr
    + trace_event = "initcall:*"
    + tp_printk
    + trace_buf_size = 1M
    + ftrace = function
    + ftrace_filter = "vfs*"
    + }
    +
    +Note that parameters start with "kernel" prefix instead of "ftrace".
    diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst
    index 04acd277c5f6..fa9e1c730f6a 100644
    --- a/Documentation/trace/index.rst
    +++ b/Documentation/trace/index.rst
    @@ -19,6 +19,7 @@ Linux Tracing Technologies
    events-msr
    mmiotrace
    histogram
    + boottime-trace
    hwlat_detector
    intel_th
    stm
    --
    2.24.1

    \
     
     \ /
      Last update: 2020-01-14 22:05    [W:4.234 / U:0.012 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site