Re: [PATCH v6 01/11] of: document bindings for reserved-memory nodes
On Fri, 28 Feb 2014 14:42:46 +0100, Marek Szyprowski wrote: > From: Grant Likely > > Reserved memory nodes allow for the reservation of static (fixed > address) regions, or dynamically allocated regions for a specific > purpose. > > Signed-off-by: Grant Likely > [joshc: Based on binding document proposed (in non-patch form) here: > http://lkml.kernel.org/g/20131030134702.19b57c40...@trevor.secretlab.ca > adapted to support #memory-region-cells] > Signed-off-by: Josh Cartwright > [mszyprow: removed #memory-region-cells property] > Signed-off-by: Marek Szyprowski Merged, thanks. g. > --- > .../bindings/reserved-memory/reserved-memory.txt | 136 > > 1 file changed, 136 insertions(+) > create mode 100644 > Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt > > diff --git > a/Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt > b/Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt > new file mode 100644 > index ..8b0d747a38e7 > --- /dev/null > +++ b/Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt > @@ -0,0 +1,136 @@ > +*** 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 instanciate the necessary pool > + management subsystem if necessary. > +- 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. > + > +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. > + > +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 > + > +Example > +--- > +This example defines 3 contiguous regions are defined for Linux kernel:
[PATCH v6 01/11] of: document bindings for reserved-memory nodes
From: Grant Likely
Reserved memory nodes allow for the reservation of static (fixed
address) regions, or dynamically allocated regions for a specific
purpose.
Signed-off-by: Grant Likely
[joshc: Based on binding document proposed (in non-patch form) here:
http://lkml.kernel.org/g/20131030134702.19b57c40...@trevor.secretlab.ca
adapted to support #memory-region-cells]
Signed-off-by: Josh Cartwright
[mszyprow: removed #memory-region-cells property]
Signed-off-by: Marek Szyprowski
---
.../bindings/reserved-memory/reserved-memory.txt | 136
1 file changed, 136 insertions(+)
create mode 100644
Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt
diff --git
a/Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt
b/Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt
new file mode 100644
index ..8b0d747a38e7
--- /dev/null
+++ b/Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt
@@ -0,0 +1,136 @@
+*** 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 instanciate the necessary pool
+ management subsystem if necessary.
+- 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.
+
+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.
+
+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
+
+Example
+---
+This example defines 3 contiguous regions are defined for Linux kernel:
+one default of all device drivers (named linux,cma@7200 and 64MiB in size),
+one dedicated to the framebuffer device (named framebuffer@7800, 8MiB), and
+one for multimedia processing (named multimedia-memory@7700, 64MiB).
+
+/ {
+ #address-cells = <1>;
+ #size-cells = <1>;
+
+
