From bf99826f239edf9e9471a25a62e3ed00a0f28c8c Mon Sep 17 00:00:00 2001 From: Maxime Ripard Date: Wed, 1 Sep 2021 11:18:05 +0200 Subject: [PATCH] dt-bindings: Convert Reserved Memory binding to a schema Convert the reserved memory bindings to DT schema format. The bindings are split into schemas for clients, common reserved memory node properties and a specific binding for shared-dma-pool. Cc: devicetree-spec@vger.kernel.org Signed-off-by: Maxime Ripard Signed-off-by: Rob Herring Link: https://lore.kernel.org/r/20210901091852.479202-6-maxime@cerno.tech --- .../bindings/reserved-memory/memory-region.yaml | 40 +++++ .../bindings/reserved-memory/reserved-memory.txt | 172 +-------------------- .../bindings/reserved-memory/reserved-memory.yaml | 100 ++++++++++++ .../bindings/reserved-memory/shared-dma-pool.yaml | 87 +++++++++++ 4 files changed, 228 insertions(+), 171 deletions(-) create mode 100644 Documentation/devicetree/bindings/reserved-memory/memory-region.yaml create mode 100644 Documentation/devicetree/bindings/reserved-memory/reserved-memory.yaml create mode 100644 Documentation/devicetree/bindings/reserved-memory/shared-dma-pool.yaml diff --git a/Documentation/devicetree/bindings/reserved-memory/memory-region.yaml b/Documentation/devicetree/bindings/reserved-memory/memory-region.yaml new file mode 100644 index 0000000..83dfe49 --- /dev/null +++ b/Documentation/devicetree/bindings/reserved-memory/memory-region.yaml @@ -0,0 +1,40 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/reserved-memory/memory-region.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Reserved Memory Region Device Tree Binding + +maintainers: + - devicetree-spec@vger.kernel.org + +description: | + Regions in the /reserved-memory node may be referenced by other device + nodes by adding a memory-region property to the device node. + +select: true + +properties: + memory-region: + $ref: /schemas/types.yaml#/definitions/phandle-array + description: > + Phandle to a /reserved-memory child node assigned to the device. + + memory-region-names: + $ref: /schemas/types.yaml#/definitions/string-array + description: > + A list of names, one for each corresponding entry in the + memory-region property + +additionalProperties: true + +examples: + - | + fb0: video@12300000 { + /* ... */ + reg = <0x12300000 0x1000>; + memory-region = <&display_reserved>; + }; + +... diff --git a/Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt b/Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt index 39b5f4c..1810701 100644 --- a/Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt +++ b/Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt @@ -1,171 +1 @@ -*** Reserved memory regions *** - -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. - -Parameters for each memory region can be encoded into the device tree -with the following nodes: - -/reserved-memory node ---------------------- -#address-cells, #size-cells (required) - standard definition - - Should use the same values as the root node -ranges (required) - standard definition - - Should be empty - -/reserved-memory/ child nodes ------------------------------ -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 (@
) should be appended to the name if the node is a -static allocation. - -Properties: -Requires either a) or b) below. -a) static allocation - reg (required) - standard definition -b) dynamic allocation - size (required) - length based on parent's #size-cells - - Size in bytes of memory to reserve. - alignment (optional) - length based on parent's #size-cells - - Address boundary for alignment of allocation. - alloc-ranges (optional) - prop-encoded-array (address, length pairs). - - Specifies regions of memory that are - acceptable to allocate from. - -If both reg and size are present, then the reg property takes precedence -and size is ignored. - -Additional properties: -compatible (optional) - standard definition - - may contain the following strings: - - shared-dma-pool: 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. - - restricted-dma-pool: This indicates a region of memory meant to be - used as a pool of restricted DMA buffers for a set of devices. The - memory region would be the only region accessible to those devices. - When using this, the no-map and reusable properties must not be set, - so the operating system can create a virtual mapping that will be used - for synchronization. The main purpose for restricted DMA is to - mitigate the lack of DMA access control on systems without an IOMMU, - which could result in the DMA accessing the system memory at - unexpected times and/or unexpected addresses, possibly leading to data - leakage or corruption. The feature on its own provides a basic level - of protection against the DMA overwriting buffer contents at - unexpected times. However, to protect against general data leakage and - system memory corruption, the system needs to provide way to lock down - the memory access, e.g., MPU. Note that since coherent allocation - needs remapping, one must set up another device coherent pool by - shared-dma-pool and use dma_alloc_from_dev_coherent instead for atomic - coherent allocation. - - vendor specific string in the form ,[-] -no-map (optional) - empty property - - Indicates the operating system must not create a virtual mapping - of the region as part of its standard mapping of system memory, - nor permit speculative access to it under any circumstances other - than under the control of the device driver using the region. -reusable (optional) - empty property - - The operating system can use the memory in this region with the - limitation that the device driver(s) owning the region need to be - able to reclaim it back. Typically that means that the operating - system can use that region to store volatile or cached data that - can be otherwise regenerated or migrated elsewhere. - -A node must not carry both the no-map and the reusable property as these are -logically contradictory. - -Linux implementation note: -- If a "linux,cma-default" property is present, then Linux will use the - region for the default pool of the contiguous memory allocator. - -- If a "linux,dma-default" property is present, then Linux will use the - region for the default pool of the consistent DMA allocator. - -Device node references to reserved memory ------------------------------------------ -Regions in the /reserved-memory node may be referenced by other device -nodes by adding a memory-region property to the device node. - -memory-region (optional) - phandle, specifier pairs to children of /reserved-memory -memory-region-names (optional) - a list of names, one for each corresponding - entry in the memory-region property - -Example -------- -This example defines 4 contiguous regions for Linux kernel: -one default of all device drivers (named linux,cma@72000000 and 64MiB in size), -one dedicated to the framebuffer device (named framebuffer@78000000, 8MiB), -one for multimedia processing (named multimedia-memory@77000000, 64MiB), and -one for restricted dma pool (named restricted_dma_reserved@0x50000000, 64MiB). - -/ { - #address-cells = <1>; - #size-cells = <1>; - - memory { - reg = <0x40000000 0x40000000>; - }; - - reserved-memory { - #address-cells = <1>; - #size-cells = <1>; - ranges; - - /* global autoconfigured region for contiguous allocations */ - linux,cma { - compatible = "shared-dma-pool"; - reusable; - size = <0x4000000>; - alignment = <0x2000>; - linux,cma-default; - }; - - display_reserved: framebuffer@78000000 { - reg = <0x78000000 0x800000>; - }; - - multimedia_reserved: multimedia@77000000 { - compatible = "acme,multimedia-memory"; - reg = <0x77000000 0x4000000>; - }; - - restricted_dma_reserved: restricted_dma_reserved { - compatible = "restricted-dma-pool"; - reg = <0x50000000 0x4000000>; - }; - }; - - /* ... */ - - fb0: video@12300000 { - memory-region = <&display_reserved>; - /* ... */ - }; - - scaler: scaler@12500000 { - memory-region = <&multimedia_reserved>; - /* ... */ - }; - - codec: codec@12600000 { - memory-region = <&multimedia_reserved>; - /* ... */ - }; - - pcie_device: pcie_device@0,0 { - reg = <0x83010000 0x0 0x00000000 0x0 0x00100000 - 0x83010000 0x0 0x00100000 0x0 0x00100000>; - memory-region = <&restricted_dma_reserved>; - /* ... */ - }; -}; +This file has been moved to reserved-memory.yaml. diff --git a/Documentation/devicetree/bindings/reserved-memory/reserved-memory.yaml b/Documentation/devicetree/bindings/reserved-memory/reserved-memory.yaml new file mode 100644 index 0000000..7a07440 --- /dev/null +++ b/Documentation/devicetree/bindings/reserved-memory/reserved-memory.yaml @@ -0,0 +1,100 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/reserved-memory/reserved-memory.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: /reserved-memory Child Node Common Device Tree Bindings + +maintainers: + - devicetree-spec@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. + + 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 (@
) should be appended to the name if the node + is a static allocation. + +properties: + reg: true + + size: + $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 1 + maxItems: 2 + description: > + Length based on parent's \#size-cells. Size in bytes of memory to + reserve. + + alignment: + $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 1 + maxItems: 2 + 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. + + no-map: + type: boolean + description: > + Indicates the operating system must not create a virtual mapping + of the region as part of its standard mapping of system memory, + nor permit speculative access to it under any circumstances other + than under the control of the device driver using the region. + + reusable: + type: boolean + description: > + The operating system can use the memory in this region with the + limitation that the device driver(s) owning the region need to be + able to reclaim it back. Typically that means that the operating + system can use that region to store volatile or cached data that + can be otherwise regenerated or migrated elsewhere. + +allOf: + - if: + required: + - no-map + + then: + not: + required: + - reusable + + - if: + required: + - reusable + + then: + not: + required: + - no-map + +oneOf: + - required: + - reg + + - required: + - size + +additionalProperties: true + +... diff --git a/Documentation/devicetree/bindings/reserved-memory/shared-dma-pool.yaml b/Documentation/devicetree/bindings/reserved-memory/shared-dma-pool.yaml new file mode 100644 index 0000000..a4bf757 --- /dev/null +++ b/Documentation/devicetree/bindings/reserved-memory/shared-dma-pool.yaml @@ -0,0 +1,87 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/reserved-memory/shared-dma-pool.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: /reserved-memory DMA pool node bindings + +maintainers: + - devicetree-spec@vger.kernel.org + +allOf: + - $ref: "reserved-memory.yaml" + +properties: + 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. + + - const: restricted-dma-pool + description: > + This indicates a region of memory meant to be used as a pool + of restricted DMA buffers for a set of devices. The memory + region would be the only region accessible to those devices. + When using this, the no-map and reusable properties must not + be set, so the operating system can create a virtual mapping + that will be used for synchronization. The main purpose for + restricted DMA is to mitigate the lack of DMA access control + on systems without an IOMMU, which could result in the DMA + accessing the system memory at unexpected times and/or + unexpected addresses, possibly leading to data leakage or + corruption. The feature on its own provides a basic level of + protection against the DMA overwriting buffer contents at + unexpected times. However, to protect against general data + leakage and system memory corruption, the system needs to + provide way to lock down the memory access, e.g., MPU. Note + that since coherent allocation needs remapping, one must set + up another device coherent pool by shared-dma-pool and use + dma_alloc_from_dev_coherent instead for atomic coherent + allocation. + + linux,cma-default: + type: boolean + description: > + If this property is present, then Linux will use the region for + the default pool of the contiguous memory allocator. + + linux,dma-default: + type: boolean + description: > + If this property is present, then Linux will use the region for + the default pool of the consistent DMA allocator. + +unevaluatedProperties: false + +examples: + - | + reserved-memory { + #address-cells = <1>; + #size-cells = <1>; + ranges; + + /* global autoconfigured region for contiguous allocations */ + linux,cma { + compatible = "shared-dma-pool"; + reusable; + size = <0x4000000>; + alignment = <0x2000>; + linux,cma-default; + }; + + display_reserved: framebuffer@78000000 { + reg = <0x78000000 0x800000>; + }; + + restricted_dma_reserved: restricted-dma-pool@50000000 { + compatible = "restricted-dma-pool"; + reg = <0x50000000 0x4000000>; + }; + }; + +... -- 2.7.4