Re: [PATCH] schemas: Add schema for firmware logs

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Hi Peter,

On Sat, 4 Feb 2023 at 02:36, Peter Robinson <pbrobinson@xxxxxxxxx> wrote:
>
> Hi Simon,
>
> Does it make sense to devise something that is compatible with the
> kernel's pstore [1] mechanism?

Possibly...can you please be a little more specific?

Regards,
Simon

>
> Peter
>
> [1] https://lwn.net/Articles/434821/
>
> On Sat, Feb 4, 2023 at 12:20 AM Simon Glass <sjg@xxxxxxxxxxxx> wrote:
> >
> > A common way to detect problems in firmware is to collect logs from
> > the firmware, then pass them to the OS for storage and analysis.
> >
> > Logs can take the form of simple text output, or structured logs where the
> > filename and line number, etc. are provided. Timestamps can sometimes be
> > useful, too.
> >
> > Ideally the log can be displayed as simple ASCII without always needing
> > a special program to read it.
> >
> > The firmware consists of various boot phases, any of which can contribute
> > log information. It is assumed that these logs are not interleaved, i.e.
> > that the phases run one after the other.
> >
> > The final boot phase (before the OS) is responsible for collecting the
> > logs, e.g. from a Transfer List, and placing them in the devicetree.
> >
> > This binding collects the logs as individual log@n subnodes within a
> > /chosen/logs node.
> >
> > If firmware phases use the devicetree to pass logs between each other,
> > then the /chosen node should still be used. The /options node is not
> > supported. Subsequent phases must be sure to use the next numbered
> > log@n node.
> >
> > If the log data is sitting in memory somewhere, it is possible to point
> > to it, rather than copying the data into a property. For large logs this
> > may be more efficient. It must end with a NUL character, so the total
> > space for actual log data is one byte less than the allocated size.
> >
> > If something goes wrong and an incomplete log record is emitted, then the
> > next record may appear to be part of it, since there is no LF or ETX
> > character at the end of the previous record.
> >
> > The intent with this binding is to provide a Linux driver which can
> > provide access to the log data after booting is complete.
> >
> > Other things not considered:
> > - signalling overflow of a log buffer
> > - circular log buffers
> > - a single unified log buffer with inline ASCII characters to indicate the
> >   phase and project
> > - log records that contain multiple lines of text
> >
> > Signed-off-by: Simon Glass <sjg@xxxxxxxxxxxx>
> > ---
> >
> >  dtschema/schemas/chosen.yaml |   3 +
> >  dtschema/schemas/log.yaml    | 176 +++++++++++++++++++++++++++++++++++
> >  dtschema/schemas/logs.yaml   |  30 ++++++
> >  test/logs.dts                |  47 ++++++++++
> >  4 files changed, 256 insertions(+)
> >  create mode 100644 dtschema/schemas/log.yaml
> >  create mode 100644 dtschema/schemas/logs.yaml
> >  create mode 100644 test/logs.dts
> >
> > diff --git a/dtschema/schemas/chosen.yaml b/dtschema/schemas/chosen.yaml
> > index 86194dd..46cc9fb 100644
> > --- a/dtschema/schemas/chosen.yaml
> > +++ b/dtschema/schemas/chosen.yaml
> > @@ -236,6 +236,9 @@ properties:
> >        system.
> >
> >  patternProperties:
> > +  '^logs$':
> > +    $ref: logs.yaml#
> > +
> >    "^framebuffer": true
> >
> >  additionalProperties: false
> > diff --git a/dtschema/schemas/log.yaml b/dtschema/schemas/log.yaml
> > new file mode 100644
> > index 0000000..5218234
> > --- /dev/null
> > +++ b/dtschema/schemas/log.yaml
> > @@ -0,0 +1,176 @@
> > +# SPDX-License-Identifier: BSD-2-Clause
> > +# Copyright 2023 Google LLC
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/log.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Log-output binding
> > +
> > +maintainers:
> > +  - Simon Glass <sjg@xxxxxxxxxxxx>
> > +
> > +description:
> > +  This holds a log file or console dump created by a single phase of the boot.
> > +  It typically consists of plain ASCII text, but it is also possible to
> > +  add metadata like files and line numbers.
> > +
> > +  Each log node has a hex unit address which indicates the order of progress
> > +  through the boot phases. The first node must be log@0, followed by
> > +  log@1, etc.
> > +
> > +select: false
> > +
> > +properties:
> > +  reg:
> > +    description:
> > +      Defines a unique log ID for the log represented by the log node.
> > +
> > +  boot-phase:
> > +    $ref: types.yaml#/definitions/string
> > +    description: |
> > +      Indicates the phase of boot which produced this log:
> > +
> > +        - pre-sram: Before SRAM is available
> > +        - verify: Verification step, which decides which of the available images
> > +          should be run next
> > +        - pre-ram: Sets up SDRAM
> > +        - some-ram: After SDRAM is working but before all of it is available.
> > +          Some RAM is available but it is limited (e.g. it may be split into
> > +          two pieces by the location of the running program) because the
> > +          program code is not yet relocated out of the way.
> > +        - loader: OS loader, typically the final firmware step
> > +
> > +    pattern: "^pre-sram|verify|pre-ram|some-ram|loader$"
> > +
> > +  project:
> > +    $ref: types.yaml#/definitions/string
> > +    description:
> > +      Indicates the name of the project which produced this log
> > +
> > +    pattern: "^U-Boot|TF-A"
> > +
> > +  time-format:
> > +    $ref: types.yaml#/definitions/string
> > +    description: |
> > +      Indicates the time format used by the log. Options are:
> > +
> > +        usec - a integer number of microseconds since reset was released,
> > +               expressed in ASCII, e.g. "123"
> > +
> > +    pattern: "^usec$"
> > +
> > +  text-start:
> > +    oneOf:
> > +      - $ref: types.yaml#/definitions/uint32
> > +      - $ref: types.yaml#/definitions/uint64
> > +    description:
> > +      These properties hold the physical start and end address of the log text
> > +      if the 'text' property is not used.
> > +
> > +      Note that text-start is inclusive, but text-end is exclusive.
> > +
> > +      The text must be terminated with a NUL character.
> > +
> > +  text-end:
> > +    oneOf:
> > +      - $ref: types.yaml#/definitions/uint32
> > +      - $ref: types.yaml#/definitions/uint64
> > +    description:
> > +      These properties hold the physical start and end address of the log text
> > +      if the 'text' property is not used.
> > +
> > +      Note that text-start is inclusive, but text-end is exclusive.
> > +
> > +      The text must be terminated with a NUL character.
> > +
> > +  text:
> > +    $ref: types.yaml#/definitions/string
> > +    description: |
> > +      Contains the log text, if it is not referred to by text-start / text-end.
> > +
> > +      The format is ASCII with US and SOT used to indicate optional fields:
> > +
> > +        [timestamp<US>][level[:category[:filename[:line[:function]]]]]<SOT>]message[<LF>|<ETX>]
> > +
> > +      where:
> > +
> > +        timestamp is the timestamp, according to time-format
> > +
> > +        level is the single-digit log level:
> > +           0 - emergency (program is unstable)
> > +           1 - alert (action must be taken immediately)
> > +           2 - crit (critical conditions)
> > +           3 - err (error that prevents something from working
> > +           4 - warning (may prevent optimal operation)
> > +           5 - notice (normal but significant condition, printf())
> > +           6 - info (general information message)
> > +           7 - debug (basic debug-level message)
> > +           8 - debug content (debug message showing full message content)
> > +           9 - debug I/O (debug message showing hardware I/O access)
> > +
> > +        category is the category name which is project-dependent
> > +
> > +        filename is the relative filename (__FILE__ in C)
> > +
> > +        line is the line number starting from 1 (__LINE__ in C)
> > +
> > +        function is the function name (__func__ in C)
> > +
> > +        message is the message string, which may not contain control
> > +        characters (beyond those listed above) except for HT and LF. DEL and CR
> > +        are not permitted.
> > +
> > +      The timestamp is present only if US is in the string.
> > +
> > +      The fields before <SOT> are all optional, but must be listed in order.
> > +      To omit a field in the middle, use an empty string between two colons.
> > +      To omit a field at the end, just leave it out along with the colon before
> > +      it.
> > +
> > +      Typically LF is used as a line delimiter, but if a record does not
> > +      end with a newline, ETX can be used. This indicates that it is a new
> > +      log record but without a newline between them. Often (but not always)
> > +      the 'continuation' does not include the US and SOT information.
> > +
> > +      A log record without a LF or ETX terminator is considered invalid, even
> > +      if it is the final record.
> > +
> > +      Examples:
> > +
> > +         123<US>5:tpm:lib/tpm.c:334:tpm_init<SOT>TPM starting...<LF>
> > +         23<US>Hello<LF>
> > +         2:boot:lib/panic.c:84:panic<SOT>Memory training failed<LF>
> > +         7:mmc:::mmc_bind<SOT>Cannot create block device<LF>
> > +         Net:   eth0: host_lo, eth1: host_enp1s0<ETX>
> > +
> > +      ASCII characters:
> > +
> > +        SOT - 0x2  - indicates the start of the message. This is optional if
> > +                     the record has nothing but a message
> > +        ETX - 0x3  - indicates the end of a log record (without new line)
> > +        LF  - 0xa  - indicates the end of a log record (and new line)
> > +        US  - 0x1f - indicates the end of the timestamp (and that it is present
> > +                     in the record)
> > +
> > +      The above format is intended to be unambiguous, while still being fairly
> > +      readable it just shown on a terminal with all control characters except
> > +      LF dropped. The CR character is not permitted since it is not needed to
> > +      signal an end of line and it avoids worrying about what <CR><LF> actually
> > +      means.
> > +
> > +      The text size is determined by the property size. The last byte must be
> > +      a NUL character.
> > +
> > +required:
> > +  - boot-phase
> > +  - project
> > +
> > +anyOf:
> > +  - required:
> > +    - text
> > +  - required:
> > +    - text-start
> > +    - text-end
> > +
> > +additionalProperties: false
> > diff --git a/dtschema/schemas/logs.yaml b/dtschema/schemas/logs.yaml
> > new file mode 100644
> > index 0000000..76ba2b0
> > --- /dev/null
> > +++ b/dtschema/schemas/logs.yaml
> > @@ -0,0 +1,30 @@
> > +# SPDX-License-Identifier: BSD-2-Clause
> > +# Copyright 2023 Google LLC
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/logs.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Log information collected during firmware execution
> > +
> > +maintainers:
> > +  - Simon Glass <sjg@xxxxxxxxxxxx>
> > +
> > +description:
> > +  This holds a set of logs build up during booting of the machine. The
> > +  collection of logs is described in the "/logs" node.  This node in turn
> > +  contains a number of subnodes representing individual log output from
> > +  different boot phases.
> > +
> > +properties:
> > +  '#address-cells':
> > +    const: 1
> > +
> > +  '#size-cells':
> > +    const: 0
> > +
> > +patternProperties:
> > +  '^log@[0-9a-f]+$':
> > +    $ref: log.yaml#
> > +
> > +additionalProperties: false
> > diff --git a/test/logs.dts b/test/logs.dts
> > new file mode 100644
> > index 0000000..7d044df
> > --- /dev/null
> > +++ b/test/logs.dts
> > @@ -0,0 +1,47 @@
> > +// SPDX-License-Identifier: BSD-2-Clause
> > +// Copyright 2023 Google LLC
> > +
> > +// Used to validate the "logs" node and its child "log" nodes
> > +
> > +// dtc -O dtb -o test.dtb test/bootphases.dts && tools/dt-validate -s test/schemas -m test.dtb
> > +
> > +
> > +/dts-v1/;
> > +
> > +/ {
> > +       model = "none";
> > +       compatible = "foo";
> > +
> > +       #address-cells = <1>;
> > +       #size-cells = <1>;
> > +
> > +       chosen {
> > +               logs {
> > +                       #address-cells = <1>;
> > +                       #size-cells = <0>;
> > +
> > +                       log@0 {
> > +                               reg = <0>;
> > +                               boot-phase = "pre-ram";
> > +                               project = "U-Boot";
> > +                               text = "\nU-Boot SPL 2023.01 (Feb 03 2023 - 14:45:39 -0700)\nTrying to boot from sandbox_image\nTrying to boot from sandbox_file\n";
> > +                       };
> > +
> > +                       log@1 {
> > +                               reg = <1>;
> > +                               boot-phase = "loader";
> > +                               project = "U-Boot";
> > +                               time-format = "usec";
> > +                               text = "\n\n123\x1f2:boot:lib/display_options.c:43:display_options\x02U-Boot 2023.01 (Feb 03 2023 - 14:45:39 -0700)\n\nReset Status: COLD\nModel: sandbox\nDRAM:  256 MiB\n";
> > +                       };
> > +
> > +                       log@2 {
> > +                               reg = <2>;
> > +                               boot-phase = "pre-ram";
> > +                               project = "TF-A";
> > +                               text-start = <0x103000>;
> > +                               text-end = <0x107000>;
> > +                       };
> > +               };
> > +       };
> > +};
> > --
> > 2.39.1.519.gcb327c4b5f-goog
> >



[Index of Archives]     [Device Tree Compilter]     [Device Tree Spec]     [Linux Driver Backports]     [Video for Linux]     [Linux USB Devel]     [Linux PCI Devel]     [Linux Audio Users]     [Linux Kernel]     [Linux SCSI]     [XFree86]     [Yosemite Backpacking]


  Powered by Linux