[PATCH v3 17/17] Documentation: KHO: Add ftrace bindings

[Alexander Graf]

We introduced KHO into Linux: A framework that allows Linux to pass
metadata and memory across kexec from Linux to Linux. KHO reuses fdt
as file format and shares a lot of the same properties of firmware-to-
Linux boot formats: It needs a stable, documented ABI that allows for
forward and backward compatibility as well as versioning.

As first user of KHO, we introduced ftrace which can now preserve
trace contents across kexec, so you can use the post-kexec kernel to
read traces from the pre-kexec kernel.

This patch adds ftrace schemas similar to "device" device tree ones to
a new kho bindings directory. This allows us to force contributors to
document the data that moves across KHO kexecs and catch breaking change
during review.

Signed-off-by: Alexander Graf <graf at amazon.com>

---

v2 -> v3:

  - Fix make dt_binding_check
  - Add descriptions for each object
  - s/trace_flags/trace-flags/
  - s/global_trace/global-trace/
  - Make all additionalProperties false
  - Change subject to reflect subsysten (dt-bindings)
  - Fix indentation
  - Remove superfluous examples
  - Convert to 64bit syntax
  - Move to kho directory
---
 .../kho/bindings/ftrace/ftrace-array.yaml     | 38 ++++++++++++
 .../kho/bindings/ftrace/ftrace-cpu.yaml       | 43 +++++++++++++
 Documentation/kho/bindings/ftrace/ftrace.yaml | 62 +++++++++++++++++++
 3 files changed, 143 insertions(+)
 create mode 100644 Documentation/kho/bindings/ftrace/ftrace-array.yaml
 create mode 100644 Documentation/kho/bindings/ftrace/ftrace-cpu.yaml
 create mode 100644 Documentation/kho/bindings/ftrace/ftrace.yaml

diff --git a/Documentation/kho/bindings/ftrace/ftrace-array.yaml b/Documentation/kho/bindings/ftrace/ftrace-array.yaml
new file mode 100644
index 000000000000..aa0007595b95
--- /dev/null
+++ b/Documentation/kho/bindings/ftrace/ftrace-array.yaml
@@ -0,0 +1,38 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/kho/ftrace/ftrace-array.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Ftrace trace array
+
+maintainers:
+  - Alexander Graf <graf at amazon.com>
+
+description: |
+  Ftrace can create and expose multiple different trace instances, see
+  https://docs.kernel.org/trace/ftrace.html#instances. Each instance is
+  backed by a single trace array which contains all information about where
+  the corresponding trace buffers are located and how they are configured.
+
+properties:
+  compatible:
+    enum:
+      - ftrace,array-v1
+
+  trace-flags:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    description: |
+      Bitmap of all the trace flags that were enabled in the trace array at the
+      point of serialization.
+
+patternProperties:
+  cpu[0-9a-f]*:
+    $ref: ftrace-cpu.yaml#
+    description: Trace buffer location for each CPU
+
+required:
+  - compatible
+  - trace-flags
+
+additionalProperties: false
diff --git a/Documentation/kho/bindings/ftrace/ftrace-cpu.yaml b/Documentation/kho/bindings/ftrace/ftrace-cpu.yaml
new file mode 100644
index 000000000000..95dec1c94fc3
--- /dev/null
+++ b/Documentation/kho/bindings/ftrace/ftrace-cpu.yaml
@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/kho/ftrace/ftrace-cpu.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Ftrace per-CPU ring buffer contents
+
+maintainers:
+  - Alexander Graf <graf at amazon.com>
+
+description: |
+  An ftrace trace array contains a ring buffers for each CPU. This
+  object describes the buffers of such a single CPU. It describes which
+  CPU it was used in and which memory was backing the ring buffer.
+
+properties:
+  compatible:
+    enum:
+      - ftrace,cpu-v1
+
+  cpu:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    description: |
+      CPU number of the CPU that this ring buffer belonged to when it was
+      serialized.
+
+  mem:
+    $ref: /schemas/types.yaml#/definitions/uint32-array
+    description: |
+      Array of { u64 phys_addr, u64 len } elements that describe a list of ring
+      buffer pages. Each page consists of two elements. The first element
+      describes the location of the struct buffer_page that contains metadata
+      for a given ring buffer page, such as the ring's head indicator. The
+      second element points to the ring buffer data page which contains the raw
+      trace data.
+
+required:
+  - compatible
+  - cpu
+  - mem
+
+additionalProperties: false
diff --git a/Documentation/kho/bindings/ftrace/ftrace.yaml b/Documentation/kho/bindings/ftrace/ftrace.yaml
new file mode 100644
index 000000000000..4a7308be8dbf
--- /dev/null
+++ b/Documentation/kho/bindings/ftrace/ftrace.yaml
@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/kho/ftrace/ftrace.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Ftrace core data
+
+maintainers:
+  - Alexander Graf <graf at amazon.com>
+
+description: |
+  Ftrace can serialize its current trace buffers across kexec through KHO.
+  For each instance, it preserves the backing ring buffers. It also
+  preserves event ID associations. The post-KHO kernel can then consume
+  these bits to reassemble trace data (not configuration!) for each trace
+  instance and that way expose pre-KHO traces in post-KHO ftrace files.
+
+properties:
+  compatible:
+    enum:
+      - ftrace-v1
+
+  events:
+    $ref: /schemas/types.yaml#/definitions/uint32-array
+    description:
+      Array of { u32 crc, u32 type } elements. Each element contains a unique
+      identifier for an event, followed by the identifier that this event had
+      in the previous kernel's trace buffers.
+
+# Every subnode has to be a trace array
+patternProperties:
+  ^(?!compatible|events)$:
+    $ref: ftrace-array.yaml#
+    description: Trace array description for each trace instance
+
+required:
+  - compatible
+  - events
+
+additionalProperties: true
+
+examples:
+  - |
+    ftrace {
+      compatible = "ftrace-v1";
+      events = < 1 1 2 2 3 3 >;
+
+      global-trace {
+        compatible = "ftrace,array-v1";
+        trace-flags = < 0x3354601 >;
+
+        cpu0 {
+          compatible = "ftrace,cpu-v1";
+          cpu = < 0x00 >;
+          mem = /bits/ 64 < 0x101000000 0x38
+	                    0x101000100 0x1000
+	                    0x101000038 0x38
+	                    0x101002000 0x1000 >;
+        };
+      };
+    };
-- 
2.40.1




Amazon Development Center Germany GmbH
Krausenstr. 38
10117 Berlin
Geschaeftsfuehrung: Christian Schlaeger, Jonathan Weiss
Eingetragen am Amtsgericht Charlottenburg unter HRB 149173 B
Sitz: Berlin
Ust-ID: DE 289 237 879