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

Masami Hiramatsu
2019-06-21T16:19:16Z

Add a devicetree binding document for ftrace node.

Signed-off-by: Masami Hiramatsu <mhiramat@kernel.org>
---
.../devicetree/bindings/tracing/ftrace.yaml | 170 ++++++++++++++++++++
1 file changed, 170 insertions(+)
create mode 100644 Documentation/devicetree/bindings/tracing/ftrace.yaml

diff --git a/Documentation/devicetree/bindings/tracing/ftrace.yaml b/Documentation/devicetree/bindings/tracing/ftrace.yaml
new file mode 100644
index 000000000000..cbd7af986c38
--- /dev/null
+++ b/Documentation/devicetree/bindings/tracing/ftrace.yaml
@@ -0,0 +1,170 @@
+# 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@kernel.org>
+
+description: |
+ Boot-time ftrace tracing setting via devicetree. Users can use devicetree node
+ for programming ftrace boot-time tracing.
+
+properties:
+ compatible:
+ items:
+ - const: linux,ftrace
+
+ 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.
+
+ 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.
+
+ 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.
+
+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
+
+required:
+ - compatible
+
+examples:
+ - |
+ ftrace {
+ compatible = "linux,ftrace";
+ events = "initcall:*";
+ tp-printk;
+ buffer-size-kb = <0x400>;
+ event0 {
+ event = "task:task_newtask";
+ filter = "pid < 128";
+ enable;
+ };
+ 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)";
+ };
+
+ };