Skip to contentSkip to conversation

Clarify language on /memreserve/

PATCH In review Grant Likely 5 participants 11 messages Sep 15, 2020 – Sep 17, 2020 7 messages not in the archive

lore
Share & tools
lore
#0 lore raw

PATCH 1/3 Clarify language on /memreserve/

The language was ambiguous. Rephrase and reformat to be more readable.

---
 source/chapter6-source-language.rst | 20 ++++++++++++++------
 1 file changed, 14 insertions(+), 6 deletions(-)
source/chapter6-source-language.rst +14 -6
index ed4e234..295fcd6 100755
@@ -233,15 +233,23 @@ File layout
             [child nodes]
         };
 
-The /dts-v1/; shall be present to identify the file as a version 1 DTS
+``/dts-v1/;`` shall be present to identify the file as a version 1 DTS
 (dts files without this tag will be treated by dtc as being in the
 obsolete version 0, which uses a different format for integers in
 addition to other small but incompatible changes).
 
-Memory reservations define an entry for the devicetree blob’s memory
-reservation table. They have the form: e.g., /memreserve/ <address>
-<length>; Where <address> and <length> are 64-bit C-style integers.
+Memory reservations (see section :ref:`sect-fdt-memory-reservation-block`)
+are represented by lines in the form::
 
-*  The / { }; section defines the root node of the devicetree.
+   /memreserve/ <address> <length>;
 
-*  C style (/* ... \*/) and C++ style (//) comments are supported.
+Where ``<address>`` and ``<length>`` are 64-bit C-style integers, e.g.,
+
+.. code-block:: dts
+
+   /memreserve/ 0x10000000 0x0004000;
+
+The ``/ { ... };`` section defines the root node of the devicetree, and
+all the device tree data is contained within it.
+
+C style (``/* ... \*/``) and C++ style (``//``) comments are supported.
Signature · 1 line
2.20.1

A message that is not in the archive (sent off-list or not yet received): [email protected]

#2 lore raw

PATCH 2/3 Import /reserved-memory specification text

Imported from linux kernel source:
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt

Very minor editorial changes made while importing, with one exception. Added clause that the 'no-map' and 'reusable' properties are mutually exclusive.

Cc Rob Herring <[email protected]>
Cc Heinrich Schuchardt <[email protected]>
Cc Ard Biesheuvel <[email protected]>
---
 source/chapter3-devicenodes.rst | 203 +++++++++++++++++++++++++++++++-
 1 file changed, 202 insertions(+), 1 deletion(-)
source/chapter3-devicenodes.rst +202 -1
index 3aa4650..3043b8a 100644
@@ -161,7 +161,8 @@ If the VLE storage attribute is supported, with VLE=0.
    :ref:`sect-standard-properties`) are allowed but are optional.
 
 
-**Examples**
+``/memory`` Examples
+~~~~~~~~~~~~~~~~~~~~
 
 Given a 64-bit Power system with the following physical memory layout:
 
@@ -200,6 +201,206 @@ memory ranges. The 2 GB I/O region is skipped. Note that the
 value of 2, which means that two 32-bit cells are required to define the
 address and length for the ``reg`` property of the memory node.
 
+``/reserved-memory`` Node
+-------------------------
+
+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 parent node
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. tabularcolumns:: | p{4cm} p{0.75cm} p{4cm} p{6.5cm} |
+.. table:: /reserved-memory Parent Node Properties
+
+   =================== ===== ================= ===============================================
+   Property Name       Usage Value Type        Definition
+   =================== ===== ================= ===============================================
+   ``#address-cells``  R     ``<u32>``         Specifies the number of ``<u32>`` cells to
+                                               represent the address in the ``reg`` property in
+                                               children of root.
+   ``#size-cells``     R     ``<u32>``         Specifies the number of ``<u32>`` cells to
+                                               represent the size in the ``reg`` property in
+                                               children of root.
+   ``ranges``          R     ``<prop encoded   This property represents the mapping between
+                             array>``          parent address to child address spaces (see
+                                               section :ref:`sect-standard-properties-ranges`,
+                                               ranges).
+   Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition
+   ===========================================================================================
+
+``#address-cells`` and ``#size-cells`` should use the same values as for the root node,
+and ``ranges`` should be empty so that address translation logic works correctly.
+
+/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.
+
+A reserved memory node requires either a ``reg`` property for static
+allocations, or a ``size`` property for dynamics allocations.
+Dynamic allocations may use ``alignment`` and ``alloc-ranges`` properties
+to constrain where the memory is allocated from.
+If both ``reg`` and ``size`` are present, then the region is treated as a
+static allocation with the ``reg`` property taking precedence and ``size``
+is ignored.
+
+.. tabularcolumns:: | p{4cm} p{0.75cm} p{4cm} p{6.5cm} |
+.. table:: ``/reserved-memory/`` Child Node Properties
+
+   ======================= ===== ========================= ===============================================
+   Property Name           Usage Value Type                Definition
+   ======================= ===== ========================= ===============================================
+   ``reg``                 O      ``<prop-encoded-array>`` Consists of an arbitrary number of address and
+                                                           size pairs that specify the physical address
+                                                           and size of the memory ranges.
+   ``size``                O      ``<prop-encoded-array>`` Size in bytes of memory to reserve for
+                                                           dynamically allocated regions.
+                                                           Size of this property is based on parent node's
+                                                           ``#size-cells`` property.
+   ``alignment``           O      ``<prop-encoded-array>`` Address boundary for alignment of allocation.
+                                                           Size of this property is based on parent node's
+                                                           ``#size-cells`` property.
+   ``alloc-ranges``        O      ``<prop-encoded-array>`` Specifies regions of memory that are acceptable
+                                                           to allocate from.
+                                                           Format is (address, length pairs) tuples in
+                                                           same format as for ``reg`` properties.
+   ``compatible``          O      ``<stringlist>``         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.
+
+                                                           - vendor specific string in the form
+                                                             ``<vendor>,[<device>-]<usage>``
+   ``no-map``              O      ``<empty>``              If present, 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``            O      ``<empty>``              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.
+   Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition
+   =======================================================================================================
+
+.. note:: All other standard properties (section
+   :ref:`sect-standard-properties`) are allowed but are optional.
+
+The ``no-map`` and ``reusable`` properties are mutually exclusive and both must
+not be used together in the same node.
+
+Linux implementation notes:
+
+- 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.
+
+.. tabularcolumns:: | p{4cm} p{0.75cm} p{4cm} p{6.5cm} |
+.. table:: Properties for referencing reserved-memory regions
+
+   ======================= ===== ========================= ===============================================
+   Property Name           Usage Value Type                Definition
+   ======================= ===== ========================= ===============================================
+   ``memory-region``       O     ``<prop-encoded-array>``  phandle, specifier pairs to children of
+                                                           ``/reserved-memory``
+   ``memory-region-names`` O     ``<stringlist>>``         A list of names, one for each corresponding
+                                                           entry in the ``memory-region`` property
+   Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition
+   =======================================================================================================
+
+``/reserved-memory`` Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This example defines 3 contiguous regions are defined 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), and
+one for multimedia processing (named ``multimedia-memory@77000000``, 64MiB).
+
+.. code-block:: dts
+
+   / {
+      #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>;
+         };
+      };
+
+      /* ... */
+
+      fb0: video@12300000 {
+         memory-region = <&display_reserved>;
+         /* ... */
+      };
+
+      scaler: scaler@12500000 {
+         memory-region = <&multimedia_reserved>;
+         /* ... */
+      };
+
+      codec: codec@12600000 {
+         memory-region = <&multimedia_reserved>;
+         /* ... */
+      };
+   };
+
 ``/chosen`` Node
 ----------------
 
Signature · 1 line
2.20.1

A message that is not in the archive (sent off-list or not yet received): [email protected]

#4 lore raw

Re: [PATCH 2/3] Import /reserved-memory specification text

Quoted 3 lines · Grant Likely

Imported from linux kernel source:
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt

And what happens when this file is modified? Can you make it just contain "This has moved, see DT spec section x.y.z" or something like that?

Don't you want to convert it to schema for me first and then generate the spec content. ;)

Quoted 237 lines

Very minor editorial changes made while importing, with one exception. Added clause that the 'no-map' and 'reusable' properties are mutually exclusive.

Cc Rob Herring <[email protected]>
Cc Heinrich Schuchardt <[email protected]>
Cc Ard Biesheuvel <[email protected]>
---
 source/chapter3-devicenodes.rst | 203 +++++++++++++++++++++++++++++++-
 1 file changed, 202 insertions(+), 1 deletion(-)
source/chapter3-devicenodes.rst +202 -2
index 3aa4650..3043b8a 100644
@@ -161,7 +161,8 @@ If the VLE storage attribute is supported, with VLE=0.
    :ref:`sect-standard-properties`) are allowed but are optional.
 
 
-**Examples**
+``/memory`` Examples
+~~~~~~~~~~~~~~~~~~~~
 
 Given a 64-bit Power system with the following physical memory layout:
 
@@ -200,6 +201,206 @@ memory ranges. The 2 GB I/O region is skipped. Note that the
 value of 2, which means that two 32-bit cells are required to define the
 address and length for the ``reg`` property of the memory node.
 
+``/reserved-memory`` Node
+-------------------------
+
+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 parent node
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. tabularcolumns:: | p{4cm} p{0.75cm} p{4cm} p{6.5cm} |
+.. table:: /reserved-memory Parent Node Properties
+
+   =================== ===== ================= ===============================================
+   Property Name       Usage Value Type        Definition
+   =================== ===== ================= ===============================================
+   ``#address-cells``  R     ``<u32>``         Specifies the number of ``<u32>`` cells to
+                                               represent the address in the ``reg`` property in
+                                               children of root.
+   ``#size-cells``     R     ``<u32>``         Specifies the number of ``<u32>`` cells to
+                                               represent the size in the ``reg`` property in
+                                               children of root.
+   ``ranges``          R     ``<prop encoded   This property represents the mapping between
+                             array>``          parent address to child address spaces (see
+                                               section :ref:`sect-standard-properties-ranges`,
+                                               ranges).
+   Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition
+   ===========================================================================================
+
+``#address-cells`` and ``#size-cells`` should use the same values as for the root node,
+and ``ranges`` should be empty so that address translation logic works correctly.
+
+/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.
+
+A reserved memory node requires either a ``reg`` property for static
+allocations, or a ``size`` property for dynamics allocations.
+Dynamic allocations may use ``alignment`` and ``alloc-ranges`` properties
+to constrain where the memory is allocated from.
+If both ``reg`` and ``size`` are present, then the region is treated as a
+static allocation with the ``reg`` property taking precedence and ``size``
+is ignored.
+
+.. tabularcolumns:: | p{4cm} p{0.75cm} p{4cm} p{6.5cm} |
+.. table:: ``/reserved-memory/`` Child Node Properties
+
+   ======================= ===== ========================= ===============================================
+   Property Name           Usage Value Type                Definition
+   ======================= ===== ========================= ===============================================
+   ``reg``                 O      ``<prop-encoded-array>`` Consists of an arbitrary number of address and
+                                                           size pairs that specify the physical address
+                                                           and size of the memory ranges.
+   ``size``                O      ``<prop-encoded-array>`` Size in bytes of memory to reserve for
+                                                           dynamically allocated regions.
+                                                           Size of this property is based on parent node's
+                                                           ``#size-cells`` property.
+   ``alignment``           O      ``<prop-encoded-array>`` Address boundary for alignment of allocation.
+                                                           Size of this property is based on parent node's
+                                                           ``#size-cells`` property.
+   ``alloc-ranges``        O      ``<prop-encoded-array>`` Specifies regions of memory that are acceptable
+                                                           to allocate from.
+                                                           Format is (address, length pairs) tuples in
+                                                           same format as for ``reg`` properties.
+   ``compatible``          O      ``<stringlist>``         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.
+
+                                                           - vendor specific string in the form
+                                                             ``<vendor>,[<device>-]<usage>``
+   ``no-map``              O      ``<empty>``              If present, 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``            O      ``<empty>``              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.
+   Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition
+   =======================================================================================================
+
+.. note:: All other standard properties (section
+   :ref:`sect-standard-properties`) are allowed but are optional.
+
+The ``no-map`` and ``reusable`` properties are mutually exclusive and both must
+not be used together in the same node.
+
+Linux implementation notes:
+
+- 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.
+
+.. tabularcolumns:: | p{4cm} p{0.75cm} p{4cm} p{6.5cm} |
+.. table:: Properties for referencing reserved-memory regions
+
+   ======================= ===== ========================= ===============================================
+   Property Name           Usage Value Type                Definition
+   ======================= ===== ========================= ===============================================
+   ``memory-region``       O     ``<prop-encoded-array>``  phandle, specifier pairs to children of
+                                                           ``/reserved-memory``
+   ``memory-region-names`` O     ``<stringlist>>``         A list of names, one for each corresponding
+                                                           entry in the ``memory-region`` property
+   Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition
+   =======================================================================================================
+
+``/reserved-memory`` Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This example defines 3 contiguous regions are defined 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), and
+one for multimedia processing (named ``multimedia-memory@77000000``, 64MiB).
+
+.. code-block:: dts
+
+   / {
+      #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>;
+         };
+      };
+
+      /* ... */
+
+      fb0: video@12300000 {
+         memory-region = <&display_reserved>;
+         /* ... */
+      };
+
+      scaler: scaler@12500000 {
+         memory-region = <&multimedia_reserved>;
+         /* ... */
+      };
+
+      codec: codec@12600000 {
+         memory-region = <&multimedia_reserved>;
+         /* ... */
+      };
+   };
+
 ``/chosen`` Node
 ----------------
 
--

2.20.1

A message that is not in the archive (sent off-list or not yet received): CAL_JsqKLV+R2YAXOZuPYnMR8Wji4_PkiH+r+Fki59r436SqnEw-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org

#6 lore raw

Re: [PATCH 2/3] Import /reserved-memory specification text

Quoted 8 lines · Rob Herring
Quoted 3 lines · Grant Likely

Imported from linux kernel source:
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt

And what happens when this file is modified? Can you make it just contain "This has moved, see DT spec section x.y.z" or something like that?

I think so. My first thought was to remove the file entirely from Linux, but it might be better to leave the file in place and replace the contents with a hyperlink to the spec section.

Quoted 2 lines

Don't you want to convert it to schema for me first and then generate the spec content. ;)

:-p

Yeah I do, but I never got around to implementing that parser and instead that idea has just blocked all progress on the spec. So until that happens, if ever, I'd rather start bringing the content into dtspec that can be reformatted later.

g.

Quoted 237 lines
Quoted 237 lines

Very minor editorial changes made while importing, with one exception. Added clause that the 'no-map' and 'reusable' properties are mutually exclusive.

Cc Rob Herring <[email protected]>
Cc Heinrich Schuchardt <[email protected]>
Cc Ard Biesheuvel <[email protected]>
---
  source/chapter3-devicenodes.rst | 203 +++++++++++++++++++++++++++++++-
  1 file changed, 202 insertions(+), 1 deletion(-)
source/chapter3-devicenodes.rst +202 -2
index 3aa4650..3043b8a 100644
@@ -161,7 +161,8 @@ If the VLE storage attribute is supported, with VLE=0.
     :ref:`sect-standard-properties`) are allowed but are optional.
 
 
-**Examples**
+``/memory`` Examples
+~~~~~~~~~~~~~~~~~~~~
 
  Given a 64-bit Power system with the following physical memory layout:
 
@@ -200,6 +201,206 @@ memory ranges. The 2 GB I/O region is skipped. Note that the
  value of 2, which means that two 32-bit cells are required to define the
  address and length for the ``reg`` property of the memory node.
 
+``/reserved-memory`` Node
+-------------------------
+
+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 parent node
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. tabularcolumns:: | p{4cm} p{0.75cm} p{4cm} p{6.5cm} |
+.. table:: /reserved-memory Parent Node Properties
+
+   =================== ===== ================= ===============================================
+   Property Name       Usage Value Type        Definition
+   =================== ===== ================= ===============================================
+   ``#address-cells``  R     ``<u32>``         Specifies the number of ``<u32>`` cells to
+                                               represent the address in the ``reg`` property in
+                                               children of root.
+   ``#size-cells``     R     ``<u32>``         Specifies the number of ``<u32>`` cells to
+                                               represent the size in the ``reg`` property in
+                                               children of root.
+   ``ranges``          R     ``<prop encoded   This property represents the mapping between
+                             array>``          parent address to child address spaces (see
+                                               section :ref:`sect-standard-properties-ranges`,
+                                               ranges).
+   Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition
+   ===========================================================================================
+
+``#address-cells`` and ``#size-cells`` should use the same values as for the root node,
+and ``ranges`` should be empty so that address translation logic works correctly.
+
+/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.
+
+A reserved memory node requires either a ``reg`` property for static
+allocations, or a ``size`` property for dynamics allocations.
+Dynamic allocations may use ``alignment`` and ``alloc-ranges`` properties
+to constrain where the memory is allocated from.
+If both ``reg`` and ``size`` are present, then the region is treated as a
+static allocation with the ``reg`` property taking precedence and ``size``
+is ignored.
+
+.. tabularcolumns:: | p{4cm} p{0.75cm} p{4cm} p{6.5cm} |
+.. table:: ``/reserved-memory/`` Child Node Properties
+
+   ======================= ===== ========================= ===============================================
+   Property Name           Usage Value Type                Definition
+   ======================= ===== ========================= ===============================================
+   ``reg``                 O      ``<prop-encoded-array>`` Consists of an arbitrary number of address and
+                                                           size pairs that specify the physical address
+                                                           and size of the memory ranges.
+   ``size``                O      ``<prop-encoded-array>`` Size in bytes of memory to reserve for
+                                                           dynamically allocated regions.
+                                                           Size of this property is based on parent node's
+                                                           ``#size-cells`` property.
+   ``alignment``           O      ``<prop-encoded-array>`` Address boundary for alignment of allocation.
+                                                           Size of this property is based on parent node's
+                                                           ``#size-cells`` property.
+   ``alloc-ranges``        O      ``<prop-encoded-array>`` Specifies regions of memory that are acceptable
+                                                           to allocate from.
+                                                           Format is (address, length pairs) tuples in
+                                                           same format as for ``reg`` properties.
+   ``compatible``          O      ``<stringlist>``         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.
+
+                                                           - vendor specific string in the form
+                                                             ``<vendor>,[<device>-]<usage>``
+   ``no-map``              O      ``<empty>``              If present, 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``            O      ``<empty>``              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.
+   Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition
+   =======================================================================================================
+
+.. note:: All other standard properties (section
+   :ref:`sect-standard-properties`) are allowed but are optional.
+
+The ``no-map`` and ``reusable`` properties are mutually exclusive and both must
+not be used together in the same node.
+
+Linux implementation notes:
+
+- 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.
+
+.. tabularcolumns:: | p{4cm} p{0.75cm} p{4cm} p{6.5cm} |
+.. table:: Properties for referencing reserved-memory regions
+
+   ======================= ===== ========================= ===============================================
+   Property Name           Usage Value Type                Definition
+   ======================= ===== ========================= ===============================================
+   ``memory-region``       O     ``<prop-encoded-array>``  phandle, specifier pairs to children of
+                                                           ``/reserved-memory``
+   ``memory-region-names`` O     ``<stringlist>>``         A list of names, one for each corresponding
+                                                           entry in the ``memory-region`` property
+   Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition
+   =======================================================================================================
+
+``/reserved-memory`` Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This example defines 3 contiguous regions are defined 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), and
+one for multimedia processing (named ``multimedia-memory@77000000``, 64MiB).
+
+.. code-block:: dts
+
+   / {
+      #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>;
+         };
+      };
+
+      /* ... */
+
+      fb0: video@12300000 {
+         memory-region = <&display_reserved>;
+         /* ... */
+      };
+
+      scaler: scaler@12500000 {
+         memory-region = <&multimedia_reserved>;
+         /* ... */
+      };
+
+      codec: codec@12600000 {
+         memory-region = <&multimedia_reserved>;
+         /* ... */
+      };
+   };
+
  ``/chosen`` Node
  ----------------
 
--

2.20.1

#7 lore raw

Re: [PATCH 2/3] Import /reserved-memory specification text

In reply to a message not in the archive

[+Thierry]

Thierry, earlier this year you added the memory-region-names property to the reserved-memory binding. I'd like to move the whole binding into the devicetree specification (the patch below). Since you're one of the people who touched this document, can I get an 'Acked-by' from you to confirm I can copy your text over into a CC-BY-SA licensed document?

Thanks,
g.

Quoted 237 lines · Grant Likely

Imported from linux kernel source:
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt

Very minor editorial changes made while importing, with one exception. Added clause that the 'no-map' and 'reusable' properties are mutually exclusive.

Cc Rob Herring <[email protected]>
Cc Heinrich Schuchardt <[email protected]>
Cc Ard Biesheuvel <[email protected]>
---
  source/chapter3-devicenodes.rst | 203 +++++++++++++++++++++++++++++++-
  1 file changed, 202 insertions(+), 1 deletion(-)
source/chapter3-devicenodes.rst +202 -1
index 3aa4650..3043b8a 100644
@@ -161,7 +161,8 @@ If the VLE storage attribute is supported, with VLE=0.
     :ref:`sect-standard-properties`) are allowed but are optional.
 
 
-**Examples**
+``/memory`` Examples
+~~~~~~~~~~~~~~~~~~~~
 
  Given a 64-bit Power system with the following physical memory layout:
 
@@ -200,6 +201,206 @@ memory ranges. The 2 GB I/O region is skipped. Note that the
  value of 2, which means that two 32-bit cells are required to define the
  address and length for the ``reg`` property of the memory node.
 
+``/reserved-memory`` Node
+-------------------------
+
+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 parent node
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. tabularcolumns:: | p{4cm} p{0.75cm} p{4cm} p{6.5cm} |
+.. table:: /reserved-memory Parent Node Properties
+
+   =================== ===== ================= ===============================================
+   Property Name       Usage Value Type        Definition
+   =================== ===== ================= ===============================================
+   ``#address-cells``  R     ``<u32>``         Specifies the number of ``<u32>`` cells to
+                                               represent the address in the ``reg`` property in
+                                               children of root.
+   ``#size-cells``     R     ``<u32>``         Specifies the number of ``<u32>`` cells to
+                                               represent the size in the ``reg`` property in
+                                               children of root.
+   ``ranges``          R     ``<prop encoded   This property represents the mapping between
+                             array>``          parent address to child address spaces (see
+                                               section :ref:`sect-standard-properties-ranges`,
+                                               ranges).
+   Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition
+   ===========================================================================================
+
+``#address-cells`` and ``#size-cells`` should use the same values as for the root node,
+and ``ranges`` should be empty so that address translation logic works correctly.
+
+/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.
+
+A reserved memory node requires either a ``reg`` property for static
+allocations, or a ``size`` property for dynamics allocations.
+Dynamic allocations may use ``alignment`` and ``alloc-ranges`` properties
+to constrain where the memory is allocated from.
+If both ``reg`` and ``size`` are present, then the region is treated as a
+static allocation with the ``reg`` property taking precedence and ``size``
+is ignored.
+
+.. tabularcolumns:: | p{4cm} p{0.75cm} p{4cm} p{6.5cm} |
+.. table:: ``/reserved-memory/`` Child Node Properties
+
+   ======================= ===== ========================= ===============================================
+   Property Name           Usage Value Type                Definition
+   ======================= ===== ========================= ===============================================
+   ``reg``                 O      ``<prop-encoded-array>`` Consists of an arbitrary number of address and
+                                                           size pairs that specify the physical address
+                                                           and size of the memory ranges.
+   ``size``                O      ``<prop-encoded-array>`` Size in bytes of memory to reserve for
+                                                           dynamically allocated regions.
+                                                           Size of this property is based on parent node's
+                                                           ``#size-cells`` property.
+   ``alignment``           O      ``<prop-encoded-array>`` Address boundary for alignment of allocation.
+                                                           Size of this property is based on parent node's
+                                                           ``#size-cells`` property.
+   ``alloc-ranges``        O      ``<prop-encoded-array>`` Specifies regions of memory that are acceptable
+                                                           to allocate from.
+                                                           Format is (address, length pairs) tuples in
+                                                           same format as for ``reg`` properties.
+   ``compatible``          O      ``<stringlist>``         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.
+
+                                                           - vendor specific string in the form
+                                                             ``<vendor>,[<device>-]<usage>``
+   ``no-map``              O      ``<empty>``              If present, 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``            O      ``<empty>``              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.
+   Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition
+   =======================================================================================================
+
+.. note:: All other standard properties (section
+   :ref:`sect-standard-properties`) are allowed but are optional.
+
+The ``no-map`` and ``reusable`` properties are mutually exclusive and both must
+not be used together in the same node.
+
+Linux implementation notes:
+
+- 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.
+
+.. tabularcolumns:: | p{4cm} p{0.75cm} p{4cm} p{6.5cm} |
+.. table:: Properties for referencing reserved-memory regions
+
+   ======================= ===== ========================= ===============================================
+   Property Name           Usage Value Type                Definition
+   ======================= ===== ========================= ===============================================
+   ``memory-region``       O     ``<prop-encoded-array>``  phandle, specifier pairs to children of
+                                                           ``/reserved-memory``
+   ``memory-region-names`` O     ``<stringlist>>``         A list of names, one for each corresponding
+                                                           entry in the ``memory-region`` property
+   Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition
+   =======================================================================================================
+
+``/reserved-memory`` Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This example defines 3 contiguous regions are defined 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), and
+one for multimedia processing (named ``multimedia-memory@77000000``, 64MiB).
+
+.. code-block:: dts
+
+   / {
+      #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>;
+         };
+      };
+
+      /* ... */
+
+      fb0: video@12300000 {
+         memory-region = <&display_reserved>;
+         /* ... */
+      };
+
+      scaler: scaler@12500000 {
+         memory-region = <&multimedia_reserved>;
+         /* ... */
+      };
+
+      codec: codec@12600000 {
+         memory-region = <&multimedia_reserved>;
+         /* ... */
+      };
+   };
+
  ``/chosen`` Node
  ----------------
 

A message that is not in the archive (sent off-list or not yet received): 17b980e5-97e7-8afa-3d51-c462f2fe91ff-5wv7dgnIgG8@public.gmane.org

#9 lore raw

Re: [PATCH 2/3] Import /reserved-memory specification text

Quoted 7 lines · Grant Likely

[+Thierry]

Thierry, earlier this year you added the memory-region-names property to the reserved-memory binding. I'd like to move the whole binding into the devicetree specification (the patch below). Since you're one of the people who touched this document, can I get an 'Acked-by' from you to confirm I can copy your text over into a CC-BY-SA licensed document?

Quoted 232 lines · Grant Likely
Quoted 231 lines

Imported from linux kernel source:
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt

Very minor editorial changes made while importing, with one exception. Added clause that the 'no-map' and 'reusable' properties are mutually exclusive.

Cc Rob Herring <[email protected]>
Cc Heinrich Schuchardt <[email protected]>
Cc Ard Biesheuvel <[email protected]>
---
  source/chapter3-devicenodes.rst | 203 +++++++++++++++++++++++++++++++-
  1 file changed, 202 insertions(+), 1 deletion(-)
source/chapter3-devicenodes.rst +202 -1
index 3aa4650..3043b8a 100644
@@ -161,7 +161,8 @@ If the VLE storage attribute is supported, with VLE=0.
     :ref:`sect-standard-properties`) are allowed but are optional.
-**Examples**
+``/memory`` Examples
+~~~~~~~~~~~~~~~~~~~~
  Given a 64-bit Power system with the following physical memory layout:
@@ -200,6 +201,206 @@ memory ranges. The 2 GB I/O region is skipped. Note that the
  value of 2, which means that two 32-bit cells are required to define the
  address and length for the ``reg`` property of the memory node.
+``/reserved-memory`` Node
+-------------------------
+
+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 parent node
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. tabularcolumns:: | p{4cm} p{0.75cm} p{4cm} p{6.5cm} |
+.. table:: /reserved-memory Parent Node Properties
+
+   =================== ===== ================= ===============================================
+   Property Name       Usage Value Type        Definition
+   =================== ===== ================= ===============================================
+   ``#address-cells``  R     ``<u32>``         Specifies the number of ``<u32>`` cells to
+                                               represent the address in the ``reg`` property in
+                                               children of root.
+   ``#size-cells``     R     ``<u32>``         Specifies the number of ``<u32>`` cells to
+                                               represent the size in the ``reg`` property in
+                                               children of root.
+   ``ranges``          R     ``<prop encoded   This property represents the mapping between
+                             array>``          parent address to child address spaces (see
+                                               section :ref:`sect-standard-properties-ranges`,
+                                               ranges).
+   Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition
+   ===========================================================================================
+
+``#address-cells`` and ``#size-cells`` should use the same values as for the root node,
+and ``ranges`` should be empty so that address translation logic works correctly.
+
+/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.
+
+A reserved memory node requires either a ``reg`` property for static
+allocations, or a ``size`` property for dynamics allocations.
+Dynamic allocations may use ``alignment`` and ``alloc-ranges`` properties
+to constrain where the memory is allocated from.
+If both ``reg`` and ``size`` are present, then the region is treated as a
+static allocation with the ``reg`` property taking precedence and ``size``
+is ignored.
+
+.. tabularcolumns:: | p{4cm} p{0.75cm} p{4cm} p{6.5cm} |
+.. table:: ``/reserved-memory/`` Child Node Properties
+
+   ======================= ===== ========================= ===============================================
+   Property Name           Usage Value Type                Definition
+   ======================= ===== ========================= ===============================================
+   ``reg``                 O      ``<prop-encoded-array>`` Consists of an arbitrary number of address and
+                                                           size pairs that specify the physical address
+                                                           and size of the memory ranges.
+   ``size``                O      ``<prop-encoded-array>`` Size in bytes of memory to reserve for
+                                                           dynamically allocated regions.
+                                                           Size of this property is based on parent node's
+                                                           ``#size-cells`` property.
+   ``alignment``           O      ``<prop-encoded-array>`` Address boundary for alignment of allocation.
+                                                           Size of this property is based on parent node's
+                                                           ``#size-cells`` property.
+   ``alloc-ranges``        O      ``<prop-encoded-array>`` Specifies regions of memory that are acceptable
+                                                           to allocate from.
+                                                           Format is (address, length pairs) tuples in
+                                                           same format as for ``reg`` properties.
+   ``compatible``          O      ``<stringlist>``         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.
+
+                                                           - vendor specific string in the form
+                                                             ``<vendor>,[<device>-]<usage>``
+   ``no-map``              O      ``<empty>``              If present, 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``            O      ``<empty>``              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.
+   Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition
+   =======================================================================================================
+
+.. note:: All other standard properties (section
+   :ref:`sect-standard-properties`) are allowed but are optional.
+
+The ``no-map`` and ``reusable`` properties are mutually exclusive and both must
+not be used together in the same node.
+
+Linux implementation notes:
+
+- 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.
+
+.. tabularcolumns:: | p{4cm} p{0.75cm} p{4cm} p{6.5cm} |
+.. table:: Properties for referencing reserved-memory regions
+
+   ======================= ===== ========================= ===============================================
+   Property Name           Usage Value Type                Definition
+   ======================= ===== ========================= ===============================================
+   ``memory-region``       O     ``<prop-encoded-array>``  phandle, specifier pairs to children of
+                                                           ``/reserved-memory``
+   ``memory-region-names`` O     ``<stringlist>>``         A list of names, one for each corresponding
+                                                           entry in the ``memory-region`` property
+   Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition
+   =======================================================================================================
+
+``/reserved-memory`` Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This example defines 3 contiguous regions are defined 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), and
+one for multimedia processing (named ``multimedia-memory@77000000``, 64MiB).
+
+.. code-block:: dts
+
+   / {
+      #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>;
+         };
+      };
+
+      /* ... */
+
+      fb0: video@12300000 {
+         memory-region = <&display_reserved>;
+         /* ... */
+      };
+
+      scaler: scaler@12500000 {
+         memory-region = <&multimedia_reserved>;
+         /* ... */
+      };
+
+      codec: codec@12600000 {
+         memory-region = <&multimedia_reserved>;
+         /* ... */
+      };
+   };
+
  ``/chosen`` Node
  ----------------
 
#10 lore raw

PATCH 3/3 Add details of UEFI interaction with /memory and /reserved-memory

In reply to a message not in the archive

Output from discussion on EBBR issue:
https://github.com/ARM-software/ebbr/issues/52

When using the UEFI ABI for booting, the DT memory map is ignored and instead UEFI GetMemoryMap() is used to find system memory. Also, regions described in /reserved-memory need to also be added to the UEFI memory map to protect against overlapping allocations. The patch adds language to cover both of those cases.

Cc Heinrich Schuchardt <[email protected]>
Cc Ard Biesheuvel <[email protected]>
---
 source/chapter3-devicenodes.rst      | 26 +++++++++++++++++++++++---
 source/chapter5-flattened-format.rst | 10 ++++++++++
 source/references.rst                |  4 ++++
 3 files changed, 37 insertions(+), 3 deletions(-)
source/chapter3-devicenodes.rst +23 -3
index 3043b8a..a78a742 100644
@@ -160,6 +160,12 @@ If the VLE storage attribute is supported, with VLE=0.
 .. note:: All other standard properties (section
    :ref:`sect-standard-properties`) are allowed but are optional.
 
+``/memory`` node and UEFI
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When booting via [UEFI]_, the system memory map is obtained via the
+GetMemoryMap() UEFI boot time service as defined in [UEFI]_ ยง 7.2,
+and if present, the OS must ignore any ``/memory`` nodes.
 
 ``/memory`` Examples
 ~~~~~~~~~~~~~~~~~~~~
@@ -308,12 +314,12 @@ is ignored.
    Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition
    =======================================================================================================
 
-.. note:: All other standard properties (section
-   :ref:`sect-standard-properties`) are allowed but are optional.
-
 The ``no-map`` and ``reusable`` properties are mutually exclusive and both must
 not be used together in the same node.
 
+Dynamic reserved memory regions must not be listed in the [UEFI]_ memory map
+because they are allocated by the OS after exiting firmware boot services.
+
 Linux implementation notes:
 
 - If a ``linux,cma-default`` property is present, then Linux will use the
@@ -341,6 +347,20 @@ nodes by adding a ``memory-region`` property to the device node.
    Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition
    =======================================================================================================
 
+.. _sect-reserved-memory-uefi:
+
+``/reserved-memory`` and UEFI
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+When booting via [UEFI]_, static ``/reserved-memory`` regions must
+also be listed in the system memory map obtained via the GetMemoryMap()
+UEFI boot time service as defined in [UEFI]_ ยง 7.2.
+The reserved memory regions need to be included in the UEFI memory map to
+protect against allocations by UEFI applications.
+
+Reserved regions with the ``no-map`` property must be listed in the memory
+map with type ``EfiReservedMemoryType``.
+All other reserved regions must be listed with type ``EfiBootServicesData``.
+
 ``/reserved-memory`` Example
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
source/chapter5-flattened-format.rst +10 -0
index 28e5bd4..b1e2b8b 100644
@@ -234,6 +234,16 @@ reservation block as a whole, shall be located at an 8-byte aligned
 offset from the beginning of the devicetree blob (see section
 :ref:`sect-fdt-alignment`).
 
+Memory Reservation Block and UEFI
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As with the ``/reserved-memory`` node (section :ref:`sect-reserved-memory-uefi`),
+when booting via [UEFI]_ entries in the Memory Reservation Block must also be
+listed in the system memory map obtained via the GetMemoryMap() to protect against
+allocations by UEFI applications.
+The memory reservation block entries should be listed with type
+``EfiBootServicesData``.
+
 .. _sect-fdt-structure-block:
 
 Structure Block
source/references.rst +4 -0
index 961fa20..8400e96 100644
@@ -23,3 +23,7 @@
 .. [EPAPR] *Power.org Standard for Embedded Power Architecture
    Platform Requirements*, power.org, 2011,
    https://www.power.org/documentation/power-org-standard-for-embedded-power-architecture-platform-requirements-epapr-v1-1-2/
+
+.. [UEFI] `Unified Extensable Firmware Interface Specification v2.8 Errata A
+   <https://uefi.org/sites/default/files/resources/UEFI_Spec_2_8_A_Feb14.pdf>`_,
+   February 2020, `UEFI Forum <http://www.uefi.org>`_
Signature · 1 line
2.20.1

A message that is not in the archive (sent off-list or not yet received): [email protected]

#12 lore raw

Re: [PATCH 3/3] Add details of UEFI interaction with /memory and /reserved-memory

Quoted 81 lines · Grant Likely

Output from discussion on EBBR issue:
https://github.com/ARM-software/ebbr/issues/52

When using the UEFI ABI for booting, the DT memory map is ignored and instead UEFI GetMemoryMap() is used to find system memory. Also, regions described in /reserved-memory need to also be added to the UEFI memory map to protect against overlapping allocations. The patch adds language to cover both of those cases.

Cc Heinrich Schuchardt <[email protected]>
Cc Ard Biesheuvel <[email protected]>
---
 source/chapter3-devicenodes.rst      | 26 +++++++++++++++++++++++---
 source/chapter5-flattened-format.rst | 10 ++++++++++
 source/references.rst                |  4 ++++
 3 files changed, 37 insertions(+), 3 deletions(-)
source/chapter3-devicenodes.rst +23 -3
index 3043b8a..a78a742 100644
@@ -160,6 +160,12 @@ If the VLE storage attribute is supported, with VLE=0.
 .. note:: All other standard properties (section
    :ref:`sect-standard-properties`) are allowed but are optional.
 
+``/memory`` node and UEFI
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When booting via [UEFI]_, the system memory map is obtained via the
+GetMemoryMap() UEFI boot time service as defined in [UEFI]_ ยง 7.2,
+and if present, the OS must ignore any ``/memory`` nodes.
 
 ``/memory`` Examples
 ~~~~~~~~~~~~~~~~~~~~
@@ -308,12 +314,12 @@ is ignored.
    Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition
    =======================================================================================================
 
-.. note:: All other standard properties (section
-   :ref:`sect-standard-properties`) are allowed but are optional.
-
 The ``no-map`` and ``reusable`` properties are mutually exclusive and both must
 not be used together in the same node.
 
+Dynamic reserved memory regions must not be listed in the [UEFI]_ memory map
+because they are allocated by the OS after exiting firmware boot services.
+
 Linux implementation notes:
 
 - If a ``linux,cma-default`` property is present, then Linux will use the
@@ -341,6 +347,20 @@ nodes by adding a ``memory-region`` property to the device node.
    Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition
    =======================================================================================================
 
+.. _sect-reserved-memory-uefi:
+
+``/reserved-memory`` and UEFI
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+When booting via [UEFI]_, static ``/reserved-memory`` regions must
+also be listed in the system memory map obtained via the GetMemoryMap()
+UEFI boot time service as defined in [UEFI]_ ยง 7.2.
+The reserved memory regions need to be included in the UEFI memory map to
+protect against allocations by UEFI applications.
+
+Reserved regions with the ``no-map`` property must be listed in the memory
+map with type ``EfiReservedMemoryType``.
+All other reserved regions must be listed with type ``EfiBootServicesData``.
+
 ``/reserved-memory`` Example
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
source/chapter5-flattened-format.rst +0 -0
index 28e5bd4..b1e2b8b 100644
@@ -234,6 +234,16 @@ reservation block as a whole, shall be located at an 8-byte aligned
 offset from the beginning of the devicetree blob (see section
 :ref:`sect-fdt-alignment`).
 

source/chapter5-flattened-format.rst reservation block as a whole, shall be located at an 8-byte aligned · line 246

Quoted 10 lines
source/chapter5-flattened-format.rst +10 -0
+Memory Reservation Block and UEFI
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As with the ``/reserved-memory`` node (section :ref:`sect-reserved-memory-uefi`),
+when booting via [UEFI]_ entries in the Memory Reservation Block must also be
+listed in the system memory map obtained via the GetMemoryMap() to protect against
+allocations by UEFI applications.
+The memory reservation block entries should be listed with type
+``EfiBootServicesData``.
+

Didn't we just agree this should be EfiReservedMemoryType ?

Quoted 18 lines
source/chapter5-flattened-format.rst +0 -0
 .. _sect-fdt-structure-block:
 
 Structure Block
source/references.rst +4 -1
index 961fa20..8400e96 100644
@@ -23,3 +23,7 @@
 .. [EPAPR] *Power.org Standard for Embedded Power Architecture
    Platform Requirements*, power.org, 2011,
    https://www.power.org/documentation/power-org-standard-for-embedded-power-architecture-platform-requirements-epapr-v1-1-2/
+
+.. [UEFI] `Unified Extensable Firmware Interface Specification v2.8 Errata A
+   <https://uefi.org/sites/default/files/resources/UEFI_Spec_2_8_A_Feb14.pdf>`_,
+   February 2020, `UEFI Forum <http://www.uefi.org>`_
--

2.20.1

A message that is not in the archive (sent off-list or not yet received): CAMj1kXGQTbU5uxPSsePxDTZrdeAvOf8Ev0iNmAHDcAoP_SYdHQ-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org

#14 lore raw

Re: [PATCH 3/3] Add details of UEFI interaction with /memory and /reserved-memory

Quoted 1 line · Ard Biesheuvel

On Tue, 15 Sep 2020 at 20:06, Grant Likely <[email protected]> wrote:

[...]

Quoted 4 lines
Quoted 4 lines
source/chapter5-flattened-format.rst +4 -0
+Memory Reservation Block and UEFI
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As with the ``/reserved-memory`` node (section :ref:`sect-reserved-memory-uefi`),
Quoted 8 lines

source/chapter5-flattened-format.rst reservation block as a whole, shall be located at an 8-byte aligned · line 246

Quoted 6 lines
source/chapter5-flattened-format.rst +6 -0
+when booting via [UEFI]_ entries in the Memory Reservation Block must also be
+listed in the system memory map obtained via the GetMemoryMap() to protect against
+allocations by UEFI applications.
+The memory reservation block entries should be listed with type
+``EfiBootServicesData``.
+

Didn't we just agree this should be EfiReservedMemoryType ?

That would be I-made-the-change-but-neglected-to-git-commit--amend-the-patch kind of error. Oops!

g.

#15 lore raw
In reply to a message not in the archive
Quoted 28 lines · Grant Likely

The language was ambiguous. Rephrase and reformat to be more readable.

---
 source/chapter6-source-language.rst | 20 ++++++++++++++------
 1 file changed, 14 insertions(+), 6 deletions(-)
source/chapter6-source-language.rst +3 -4
index ed4e234..295fcd6 100755
@@ -233,15 +233,23 @@ File layout
             [child nodes]
         };
 
-The /dts-v1/; shall be present to identify the file as a version 1 DTS
+``/dts-v1/;`` shall be present to identify the file as a version 1 DTS
 (dts files without this tag will be treated by dtc as being in the
 obsolete version 0, which uses a different format for integers in
 addition to other small but incompatible changes).
 
-Memory reservations define an entry for the devicetree blob’s memory
-reservation table. They have the form: e.g., /memreserve/ <address>
-<length>; Where <address> and <length> are 64-bit C-style integers.
+Memory reservations (see section :ref:`sect-fdt-memory-reservation-block`)
+are represented by lines in the form::

source/chapter6-source-language.rst File layout · line 250

Quoted 10 lines
source/chapter6-source-language.rst +6 -2
 
-*  The / { }; section defines the root node of the devicetree.
+   /memreserve/ <address> <length>;
 
-*  C style (/* ... \*/) and C++ style (//) comments are supported.
+Where ``<address>`` and ``<length>`` are 64-bit C-style integers, e.g.,
+
+.. code-block:: dts
+
+   /memreserve/ 0x10000000 0x0004000;

+ /memreserve/ 0x10000000 0x00004000;

The 28bit number looks strange here. Let's add another zero so that the number formats match (or remove the leading zeros).

Best regards

Heinrich

Quoted 6 lines
source/chapter6-source-language.rst +5 -0
+
+The ``/ { ... };`` section defines the root node of the devicetree, and
+all the device tree data is contained within it.
+
+C style (``/* ... \*/``) and C++ style (``//``) comments are supported.

A message that is not in the archive (sent off-list or not yet received): 389c3f6b-dc39-2b12-ebd4-034dc274e2f6-Mmb7MZpHnFY@public.gmane.org

#17 lore raw
Quoted 42 lines · Heinrich Schuchardt
Quoted 28 lines · Grant Likely

The language was ambiguous. Rephrase and reformat to be more readable.

---
  source/chapter6-source-language.rst | 20 ++++++++++++++------
  1 file changed, 14 insertions(+), 6 deletions(-)
source/chapter6-source-language.rst +3 -4
index ed4e234..295fcd6 100755
@@ -233,15 +233,23 @@ File layout
              [child nodes]
          };
 
-The /dts-v1/; shall be present to identify the file as a version 1 DTS
+``/dts-v1/;`` shall be present to identify the file as a version 1 DTS
  (dts files without this tag will be treated by dtc as being in the
  obsolete version 0, which uses a different format for integers in
  addition to other small but incompatible changes).
 
-Memory reservations define an entry for the devicetree blob’s memory
-reservation table. They have the form: e.g., /memreserve/ <address>
-<length>; Where <address> and <length> are 64-bit C-style integers.
+Memory reservations (see section :ref:`sect-fdt-memory-reservation-block`)
+are represented by lines in the form::

source/chapter6-source-language.rst File layout · line 250

Quoted 10 lines
source/chapter6-source-language.rst +6 -2
 
-*  The / { }; section defines the root node of the devicetree.
+   /memreserve/ <address> <length>;
 
-*  C style (/* ... \*/) and C++ style (//) comments are supported.
+Where ``<address>`` and ``<length>`` are 64-bit C-style integers, e.g.,
+
+.. code-block:: dts
+
+   /memreserve/ 0x10000000 0x0004000;

+ /memreserve/ 0x10000000 0x00004000;

Quoted 2 lines

The 28bit number looks strange here. Let's add another zero so that the number formats match (or remove the leading zeros).

Fixed, thanks.

g.

Quoted 12 lines

Best regards

Heinrich

Quoted 6 lines
source/chapter6-source-language.rst +5 -0
+
+The ``/ { ... };`` section defines the root node of the devicetree, and
+all the device tree data is contained within it.
+
+C style (``/* ... \*/``) and C++ style (``//``) comments are supported.