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 <maxime@cerno.tech> Signed-off-by: Rob Herring <robh@kernel.org> Link: https://lore.kernel.org/r/20210901091852.479202-6-maxime@cerno.tech
This commit is contained in:
Maxime Ripard
Rob Herring
parent
0e3e0fa766
commit
bf99826f23
@ -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>;
|
||||
};
|
||||
|
||||
...
|
||||
@ -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 (@<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 <vendor>,[<device>-]<usage>
|
||||
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.
|
||||
|
||||
@ -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 (@<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
|
||||
|
||||
...
|
||||
@ -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>;
|
||||
};
|
||||
};
|
||||
|
||||
...
|
||||
Loading…
Reference in New Issue
Block a user