[PATCH 05/54] dt-bindings: Convert Reserved Memory binding to a schema

[Rob Herring]

On Wed, Aug 18, 2021 at 5:00 AM Maxime Ripard <maxime at cerno.tech> wrote:
>
> Hi Rob,
>
> On Wed, Jul 21, 2021 at 08:30:43AM -0600, Rob Herring wrote:
> > > +%YAML 1.2
> > > +---
> > > +$id: http://devicetree.org/schemas/reserved-memory/reserved-memory.yaml#
> > > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > > +
> > > +title: /reserved-memory Node
> > > +
> > > +maintainers:
> > > +  - Devicetree Specification Mailing List <devicetree-spec at vger.kernel.org>
> > > +
> > > +description: >
> > > +  Reserved memory is specified as a node under the /reserved-memory node. The
> > > +  operating system shall exclude reserved memory from normal usage one can
> > > +  create child nodes describing particular reserved (excluded from normal use)
> > > +  memory regions. Such memory regions are usually designed for the special
> > > +  usage by various device drivers.
> > > +
> > > +properties:
> > > +  $nodename:
> > > +    const: reserved-memory
> > > +
> > > +  "#address-cells": true
> > > +  "#size-cells": true
> > > +  ranges: true
> > > +
> > > +patternProperties:
> > > +  "^(?!(ranges))[a-z,-]*(@[0-9]+)?$":
> >
> > Note that you could drop this and put under 'additionalProperties'.
> > You would lose some node name checking, but there's really little
> > standard on these nodes.
>
> I didn't realise it could be used that way too, I'll change it.
>
> > > +    type: object
> > > +
> > > +    description: >
> > > +      Each child of the reserved-memory node specifies one or more regions of
> > > +      reserved memory. Each child node may either use a 'reg' property to
> > > +      specify a specific range of reserved memory, or a 'size' property with
> > > +      optional constraints to request a dynamically allocated block of memory.
> > > +
> > > +      Following the generic-names recommended practice, node names should
> > > +      reflect the purpose of the node (ie. "framebuffer" or "dma-pool"). Unit
> > > +      address (@<address>) should be appended to the name if the node is a
> > > +      static allocation.
> > > +
> > > +    properties:
> > > +      reg: true
> > > +
> > > +      size:
> > > +        $ref: /schemas/types.yaml#/definitions/uint32-array
> > > +        description: >
> > > +          Length based on parent's \#size-cells. Size in bytes of memory to
> > > +          reserve.
> > > +
> > > +      alignment:
> > > +        $ref: /schemas/types.yaml#/definitions/uint32-array
> > > +        description: >
> > > +          Length based on parent's \#size-cells. Address boundary for
> > > +          alignment of allocation.
> > > +
> > > +      alloc-ranges:
> > > +        $ref: /schemas/types.yaml#/definitions/uint32-array
> > > +        description: >
> > > +          Address and Length pairs. Specifies regions of memory that are
> > > +          acceptable to allocate from.
> > > +
> > > +      compatible:
> > > +        oneOf:
> > > +          - const: shared-dma-pool
> > > +            description: >
> > > +              This indicates a region of memory meant to be used as a shared
> > > +              pool of DMA buffers for a set of devices. It can be used by an
> > > +              operating system to instantiate the necessary pool management
> > > +              subsystem if necessary.
> > > +
> > > +          # Vendor-specific compatibles in the form <vendor>,[<device>-]<usage>
> > > +          - const: mediatek,trustzone-bootinfo
> >
> > I think these should be separate schema files. At least, we're going
> > to need to support separate files because I don't think we want ones
> > adding custom properties here. This would fail unless we add every
> > compatible here. We could also be a bit more exact as to which
> > properties below apply (e.g. linux,.*-default is only valid for
> > shared-dma-pool).
>
> I'm not entirely sure how we can just ignore the vendor compatibles
> without raising a warning. Do you have any suggestion?

You need 1 schema file with all the common (child) properties and then
1 schema file for each compatible (maybe some can be grouped) that
references the common schema.

You'd lose checking that the child nodes are actually children of
/reserved-memory, but I'm not too worried about that.

Rob