[RFC PATCH v2 07/15] dt-bindings: tracing: Add ftrace binding document

From: Masami Hiramatsu
Date: Mon Jul 15 2019 - 01:12:31 EST


Add a devicetree binding document for ftrace node.

Signed-off-by: Masami Hiramatsu <mhiramat@xxxxxxxxxx>
---
Changes in v2:
- Add cpumask, ftrace-filters, ftrace-notraces, fgraph-filters,
fgraph-notraces, fgraph-max-depth and instance node.
- Remove compatible and move file to bindings/chosen/linux,ftrace.yaml
---
.../devicetree/bindings/chosen/linux,ftrace.yaml | 306 ++++++++++++++++++++
1 file changed, 306 insertions(+)
create mode 100644 Documentation/devicetree/bindings/chosen/linux,ftrace.yaml

diff --git a/Documentation/devicetree/bindings/chosen/linux,ftrace.yaml b/Documentation/devicetree/bindings/chosen/linux,ftrace.yaml
new file mode 100644
index 000000000000..a5c60ac2f66d
--- /dev/null
+++ b/Documentation/devicetree/bindings/chosen/linux,ftrace.yaml
@@ -0,0 +1,306 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright 2019 Linaro Ltd.
+%YAML 1.2
+---
+$id: "http://devicetree.org/schemas/tracing/ftrace.yaml#";
+$schema: "http://devicetree.org/meta-schemas/core.yaml#";
+
+title: Ftrace setting devicetree binding
+
+maintainers:
+ - Masami Hiramatsu <mhiramat@xxxxxxxxxx>
+
+description: |
+ Boot-time ftrace tracing setting via devicetree. Users can use devicetree node
+ for programming ftrace boot-time tracing. This node must be placed at
+ /chosen/linux,ftrace.
+
+properties:
+ dump-on-oops:
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/uint32
+ - enum: [0, 1, 2]
+ description: |
+ A neumerical flag to enable ftrace dump on Kernel Oops. 0 means no dump,
+ 1 means dump on the origin cpu of the oops, and means dump on all cpus.
+
+ traceoff-on-warning:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description: A flag to stop tracing on warning.
+
+ tp-printk:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description: A flag to send tracing output to printk buffer too.
+
+ alloc-snapshot:
+ $ref: /schemas/types.yaml#/definitions/flag
+ description: |
+ A flag to allocate snapshot buffer at boot. This will be required if you
+ use "snapshot" action on some events.
+
+ trace-clock:
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/string
+ - enum: [ global, local, counter, uptime, perf, mono, mono_raw, boot, ppc-tb, x86-tsc ]
+ description: Specify which clock method is used for trace-clock.
+
+ buffer-size-kb:
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/uint32
+ - minimum: 1
+ description: |
+ The size of per-cpu tracing buffer in KByte. Note that the size must be
+ larger than page size, and total size of buffers depends on the number
+ of CPUs.
+
+ events:
+ minItems: 1
+ $ref: /schemas/types.yaml#/definitions/string-array
+ description: |
+ A string array of enabling events (including wildcard patterns).
+ See Documentation/trace/events.rst for detail.
+
+ options:
+ minItems: 1
+ $ref: /schemas/types.yaml#/definitions/string-array
+ description: |
+ A string array of trace options for ftrace to control what gets printed
+ in the trace output or manipulate the tracers.
+ See Documentation/trace/ftrace.rst#trace_options for detail.
+
+ tracer:
+ default: nop
+ $ref: /schemas/types.yaml#/definitions/string
+ description: A string of the tracer to start up.
+
+ cpumask:
+ $ref: /schemas/types.yaml#/definitions/string
+ description: |
+ A hexadecimal number of the cpu-mask value which is given as a string.
+ This is because the number of cores can be bigger than 64.
+
+ ftrace-filters:
+ minItems: 1
+ $ref: /schemas/types.yaml#/definitions/string-array
+ description: |
+ A string array of the functions traced by the function tracer at boot
+ up. The function can be given with wildcards. This list can be
+ specified in each instance.
+
+ ftrace-notraces:
+ minItems: 1
+ $ref: /schemas/types.yaml#/definitions/string-array
+ description: |
+ A string array of the functions NOT traced by the function tracer at
+ boot up. The function can be given with wildcards. This list can be
+ specified in each instance.
+
+ fgraph-filters:
+ minItems: 1
+ $ref: /schemas/types.yaml#/definitions/string-array
+ description: |
+ A string array of the top level callers functions traced by the
+ function graph tracer at boot up. The function can be given with
+ wildcards. This list is not available in instance node.
+
+ fgraph-notraces:
+ minItems: 1
+ $ref: /schemas/types.yaml#/definitions/string-array
+ description: |
+ A string array of the top level callers functions NOT traced by the
+ function graph tracer at boot up. The function can be given with
+ wildcards. This list is not available in instance node.
+
+ fgraph-max-depth:
+ default: 0
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ This is the max depth, the function graph tracer will trace into
+ a function. 0 means no limit for the trace depth.
+
+patternProperties:
+ "event[0-9a-fA-F]+$":
+ type: object
+
+ description: |
+ event* properties are child nodes for per-event settings. It is also
+ able to define new kprobe events and synthetic events. Note that you
+ can not define both "probes" and "fields" properties on same event.
+
+ properties:
+ event:
+ $ref: /schemas/types.yaml#/definitions/string
+ description: |
+ Event name string formatted as "GROUP:EVENT". For synthetic event,
+ you must use "synthetic" for group name. For kprobe and synthetic
+ event, you can ommit the group name.
+
+ probes:
+ minItems: 1
+ $ref: /schemas/types.yaml#/definitions/string-array
+ description: |
+ A string array of kprobe event definitions, including location
+ (symbol+offset) and event arguments.
+ See Documentation/trace/kprobetrace.rst for detail.
+
+ fields:
+ minItems: 1
+ $ref: /schemas/types.yaml#/definitions/string-array
+ description: |
+ A string of synthetic event's fields definition. Note that you
+ don't need to repeat event name.
+
+ filter:
+ $ref: /schemas/types.yaml#/definitions/string
+ description: A string of event filter rule
+
+ actions:
+ minItems: 1
+ $ref: /schemas/types.yaml#/definitions/string-array
+ description: A string array of event trigger actions.
+
+ enable:
+ type: boolean
+ description: |
+ A flag to enable event. Note that the event is not enabled by
+ default. (But actions will set the event soft-disabled)
+
+ oneOf:
+ - required:
+ - event
+ - required:
+ - event
+ - probes
+ - required:
+ - event
+ - fields
+
+ "instance[0-9a-fA-F]+$":
+ type: object
+
+ description: |
+ instance* properties are child nodes for per-instance settings.
+ It is also able to have event nodes as linux,ftrace node does.
+
+ properties:
+ instance:
+ $ref: /schemas/types.yaml#/definitions/string
+ description: The name of new instance.
+
+ trace-clock:
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/string
+ - enum: [ global, local, counter, uptime, perf, mono, mono_raw, boot, ppc-tb, x86-tsc ]
+ description: Specify which clock method is used for trace-clock.
+
+ buffer-size-kb:
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/uint32
+ - minimum: 1
+ description: |
+ The size of per-cpu tracing buffer in KByte. Note that the size must be
+ larger than page size, and total size of buffers depends on the number
+ of CPUs.
+
+ events:
+ minItems: 1
+ $ref: /schemas/types.yaml#/definitions/string-array
+ description: |
+ A string array of enabling events (including wildcard patterns).
+ See Documentation/trace/events.rst for detail.
+
+ options:
+ minItems: 1
+ $ref: /schemas/types.yaml#/definitions/string-array
+ description: |
+ A string array of trace options for ftrace to control what gets printed
+ in the trace output or manipulate the tracers.
+ See Documentation/trace/ftrace.rst#trace_options for detail.
+
+ tracer:
+ default: nop
+ $ref: /schemas/types.yaml#/definitions/string
+ description: A string of the tracer to start up.
+
+ cpumask:
+ $ref: /schemas/types.yaml#/definitions/string
+ description: |
+ A hexadecimal number of the cpu-mask value which is given as a string.
+ This is because the number of cores can be bigger than 64.
+
+ ftrace-filters:
+ minItems: 1
+ $ref: /schemas/types.yaml#/definitions/string-array
+ description: |
+ A string array of the functions traced by the function tracer at boot
+ up. The function can be given with wildcards. This list can be
+ specified in each instance.
+
+ ftrace-notraces:
+ minItems: 1
+ $ref: /schemas/types.yaml#/definitions/string-array
+ description: |
+ A string array of the functions NOT traced by the function tracer at
+ boot up. The function can be given with wildcards. This list can be
+ specified in each instance.
+
+ fgraph-filters:
+ minItems: 1
+ $ref: /schemas/types.yaml#/definitions/string-array
+ description: |
+ A string array of the top level callers functions traced by the
+ function graph tracer at boot up. The function can be given with
+ wildcards. This list is not available in instance node.
+
+ fgraph-notraces:
+ minItems: 1
+ $ref: /schemas/types.yaml#/definitions/string-array
+ description: |
+ A string array of the top level callers functions NOT traced by the
+ function graph tracer at boot up. The function can be given with
+ wildcards. This list is not available in instance node.
+
+ fgraph-max-depth:
+ default: 0
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description: |
+ This is the max depth, the function graph tracer will trace into
+ a function. 0 means no limit for the trace depth.
+
+ required:
+ - instance
+
+examples:
+ - |
+ ftrace {
+ events = "initcall:*";
+ tp-printk;
+ buffer-size-kb = <0x400>;
+ event1 {
+ event = "kprobes:vfs_read";
+ probes = "vfs_read $arg1 $arg2";
+ filter = "common_pid < 200";
+ };
+ event2 {
+ event = "initcall_latency";
+ fields = "unsigned long func", "u64 lat";
+ actions = "hist:keys=func.sym,lat:vals=lat:sort=lat";
+ };
+ event3 {
+ event = "initcall:initcall_start";
+ actions = "hist:keys=func:ts0=common_timestamp.usecs";
+ };
+ event4 {
+ event = "initcall:initcall_finish";
+ actions = "hist:keys=func:lat=common_timestamp.usecs-$ts0:onmatch(initcall.initcall_start).initcall_latency(func,$lat)";
+ };
+ instance0 {
+ buffer-size-kb = <0x100>;
+ event5 {
+ event = "task:task_newtask";
+ filter = "pid < 128";
+ enable;
+ };
+ };
+
+ };