[PATCH 2/4] dt-bindings: arm: fsl: add imx-se-fw binding doc

[Rob Herring]

On Fri, May 10, 2024 at 06:57:28PM +0530, Pankaj Gupta wrote:
> The NXP security hardware IP(s) like: i.MX EdgeLock Enclave, V2X etc.,
> creates an embedded secure enclave within the SoC boundary to enable
> features like:
> - HSM
> - SHE
> - V2X
> 
> Secure-Enclave(s) communication interface are typically via message
> unit, i.e., based on mailbox linux kernel driver. This driver enables
> communication ensuring well defined message sequence protocol between
> Application Core and enclave's firmware.
> 
> Driver configures multiple misc-device on the MU, for multiple
> user-space applications, to be able to communicate over single MU.
> 
> It exists on some i.MX processors. e.g. i.MX8ULP, i.MX93 etc.
> 
> Signed-off-by: Pankaj Gupta <pankaj.gupta at nxp.com>
> ---
>  .../devicetree/bindings/firmware/fsl,imx-se.yaml   | 186 +++++++++++++++++++++
>  1 file changed, 186 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/firmware/fsl,imx-se.yaml b/Documentation/devicetree/bindings/firmware/fsl,imx-se.yaml
> new file mode 100644
> index 000000000000..a858ef6965cb
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/firmware/fsl,imx-se.yaml
> @@ -0,0 +1,186 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/firmware/fsl,imx-se.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: NXP i.MX HW Secure Enclave(s) EdgeLock Enclave
> +
> +maintainers:
> +  - Pankaj Gupta <pankaj.gupta at nxp.com>
> +
> +description: |
> +  NXP's SoC may contain one or multiple embedded secure-enclave HW
> +  IP(s) like i.MX EdgeLock Enclave, V2X etc. These NXP's HW IP(s)
> +  enables features like
> +    - Hardware Security Module (HSM),
> +    - Security Hardware Extension (SHE), and
> +    - Vehicular to Anything (V2X)
> +
> +  Communication interface to the secure-enclaves is based on the
> +  messaging unit(s).
> +
> +properties:
> +  '#address-cells':
> +    const: 1
> +
> +  '#size-cells':
> +    const: 0
> +
> +  compatible:
> +    enum:
> +      - fsl,imx8ulp-ele
> +      - fsl,imx93-ele

You basically have 0 properties in the parent node. What's the point of 
it? Either just get rid of it and define the child nodes independently 
or make the parent contain all the resources.

> +
> +patternProperties:
> +  "^[0-9a-z]*-if@[0-9]+$":

unit-addresses are hex. 

> +    type: object
> +    description:
> +      Communication interface to secure-enclave node, that defines hardware
> +      properties to required to establish the communication. There can be
> +      multiple interfaces to the same secure-enclave. Each interface is
> +      enumerated with reg property. It optionally defines properties
> +      depending on the compatible string and interface enum identifier.
> +
> +    properties:
> +      reg:
> +        maxItems: 1
> +        description: Identifier of the communication interface to secure-enclave.

What are the identifiers based on? Is the value significant to s/w? Kind 
of looks like you just made up indices.

How many child nodes do you have? Is it fixed per SoC?

> +
> +      mboxes:
> +        description: contain a list of phandles to mailboxes.
> +        items:
> +          - description: Specify the mailbox used to send message to se firmware
> +          - description: Specify the mailbox used to receive message from se firmware
> +
> +      mbox-names:
> +        items:
> +          - const: tx
> +          - const: rx
> +          - const: txdb
> +          - const: rxdb
> +        minItems: 2
> +
> +      memory-region:
> +        description: contains a list of phandles to reserved external memory.
> +        items:
> +          - description: It is used by secure-enclave firmware. It is an optional
> +              property based on compatible and identifier to communication interface.
> +              (see bindings/reserved-memory/reserved-memory.txt)
> +
> +      sram:
> +        description: contains a list of phandles to sram.
> +        $ref: /schemas/types.yaml#/definitions/phandle-array
> +        items:
> +          - description: Phandle to the device SRAM. It is an optional property
> +              based on compatible and identifier to communication interface.
> +
> +    required:
> +      - reg
> +      - mboxes
> +      - mbox-names
> +
> +allOf:
> +  # memory-region
> +  - if:
> +      properties:
> +        compatible:
> +          contains:
> +            enum:
> +              - fsl,imx8ulp-ele
> +              - fsl,imx93-ele

What else would they contain? Those are the only compatibles defined 
here.

> +    then:
> +      patternProperties:
> +        "^[0-9a-z]*-if@[0-9]+$":
> +          allOf:
> +            - if:

These conditionals are hard to follow. Probably a sign some of this 
needs to be separate or simplified.

> +                properties:
> +                  reg:
> +                    items:
> +                      - enum:
> +                          - 0
> +              then:
> +                required:
> +                  - memory-region
> +              else:
> +                not:
> +                  required:
> +                    - memory-region
> +  # sram
> +  - if:
> +      properties:
> +        compatible:
> +          contains:
> +            enum:
> +              - fsl,imx8ulp-ele
> +    then:
> +      patternProperties:
> +        "^[0-9a-z]*-if@[0-9]+$":
> +          allOf:
> +            - if:
> +                properties:
> +                  reg:
> +                    items:
> +                      - enum:
> +                          - 0
> +              then:
> +                required:
> +                  - sram
> +              else:
> +                not:
> +                  required:
> +                    - sram
> +
> +additionalProperties: false