[PATCH 1/3] Clarify language on /memreserve/

[PATCH 1/3] Clarify language on /memreserve/

[Grant Likely]

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

Co-authored-by: Heinrich Schuchardt <xypron.glpk-Mmb7MZpHnFY@public.gmane.org>
Signed-off-by: Grant Likely <grant.likely-5wv7dgnIgG8@public.gmane.org>
Cc: Heinrich Schuchardt <xypron.glpk-Mmb7MZpHnFY@public.gmane.org>
---
 source/chapter6-source-language.rst | 20 ++++++++++++++------
 1 file changed, 14 insertions(+), 6 deletions(-)

diff --git a/source/chapter6-source-language.rst b/source/chapter6-source-language.rst
index ed4e234..295fcd6 100755
--- a/source/chapter6-source-language.rst
+++ b/source/chapter6-source-language.rst
@@ -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.
-- 
2.20.1

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

[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.

Signed-off-by: Grant Likely <grant.likely-5wv7dgnIgG8@public.gmane.org>
Cc: Rob Herring <robh-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
Cc: Heinrich Schuchardt <xypron.glpk-Mmb7MZpHnFY@public.gmane.org>
Cc: Ard Biesheuvel <ardb-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
---
 source/chapter3-devicenodes.rst | 203 +++++++++++++++++++++++++++++++-
 1 file changed, 202 insertions(+), 1 deletion(-)

diff --git a/source/chapter3-devicenodes.rst b/source/chapter3-devicenodes.rst
index 3aa4650..3043b8a 100644
--- a/source/chapter3-devicenodes.rst
+++ b/source/chapter3-devicenodes.rst
@@ -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

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

[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.

Signed-off-by: Grant Likely <grant.likely-5wv7dgnIgG8@public.gmane.org>
Cc: Heinrich Schuchardt <xypron.glpk-Mmb7MZpHnFY@public.gmane.org>
Cc: Ard Biesheuvel <ardb-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
---
 source/chapter3-devicenodes.rst      | 26 +++++++++++++++++++++++---
 source/chapter5-flattened-format.rst | 10 ++++++++++
 source/references.rst                |  4 ++++
 3 files changed, 37 insertions(+), 3 deletions(-)

diff --git a/source/chapter3-devicenodes.rst b/source/chapter3-devicenodes.rst
index 3043b8a..a78a742 100644
--- a/source/chapter3-devicenodes.rst
+++ b/source/chapter3-devicenodes.rst
@@ -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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/source/chapter5-flattened-format.rst b/source/chapter5-flattened-format.rst
index 28e5bd4..b1e2b8b 100644
--- a/source/chapter5-flattened-format.rst
+++ b/source/chapter5-flattened-format.rst
@@ -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
diff --git a/source/references.rst b/source/references.rst
index 961fa20..8400e96 100644
--- a/source/references.rst
+++ b/source/references.rst
@@ -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

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

[Ard Biesheuvel]

On Tue, 15 Sep 2020 at 20:06, Grant Likely <grant.likely-5wv7dgnIgG8@public.gmane.org> wrote:
>
> 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.
>
> Signed-off-by: Grant Likely <grant.likely-5wv7dgnIgG8@public.gmane.org>
> Cc: Heinrich Schuchardt <xypron.glpk-Mmb7MZpHnFY@public.gmane.org>
> Cc: Ard Biesheuvel <ardb-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
> ---
>  source/chapter3-devicenodes.rst      | 26 +++++++++++++++++++++++---
>  source/chapter5-flattened-format.rst | 10 ++++++++++
>  source/references.rst                |  4 ++++
>  3 files changed, 37 insertions(+), 3 deletions(-)
>
> diff --git a/source/chapter3-devicenodes.rst b/source/chapter3-devicenodes.rst
> index 3043b8a..a78a742 100644
> --- a/source/chapter3-devicenodes.rst
> +++ b/source/chapter3-devicenodes.rst
> @@ -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
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> diff --git a/source/chapter5-flattened-format.rst b/source/chapter5-flattened-format.rst
> index 28e5bd4..b1e2b8b 100644
> --- a/source/chapter5-flattened-format.rst
> +++ b/source/chapter5-flattened-format.rst
> @@ -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``.
> +

Didn't we just agree this should be EfiReservedMemoryType ?

>  .. _sect-fdt-structure-block:
>
>  Structure Block
> diff --git a/source/references.rst b/source/references.rst
> index 961fa20..8400e96 100644
> --- a/source/references.rst
> +++ b/source/references.rst
> @@ -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
>

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

[Grant Likely]

On 15/09/2020 18:09, Ard Biesheuvel wrote:
> On Tue, 15 Sep 2020 at 20:06, Grant Likely <grant.likely-5wv7dgnIgG8@public.gmane.org> wrote:
[...]
>> +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 ?

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

g.

Re: [PATCH 1/3] Clarify language on /memreserve/

[Heinrich Schuchardt]

On 9/15/20 7:04 PM, Grant Likely wrote:
> The language was ambiguous. Rephrase and reformat to be more readable.
>
> Co-authored-by: Heinrich Schuchardt <xypron.glpk-Mmb7MZpHnFY@public.gmane.org>
> Signed-off-by: Grant Likely <grant.likely-5wv7dgnIgG8@public.gmane.org>
> Cc: Heinrich Schuchardt <xypron.glpk-Mmb7MZpHnFY@public.gmane.org>
> ---
>  source/chapter6-source-language.rst | 20 ++++++++++++++------
>  1 file changed, 14 insertions(+), 6 deletions(-)
>
> diff --git a/source/chapter6-source-language.rst b/source/chapter6-source-language.rst
> index ed4e234..295fcd6 100755
> --- a/source/chapter6-source-language.rst
> +++ b/source/chapter6-source-language.rst
> @@ -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;

+   /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

> +
> +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.
>

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

[Rob Herring]

On Tue, Sep 15, 2020 at 11:06 AM Grant Likely <grant.likely-5wv7dgnIgG8@public.gmane.org> wrote:
>
> 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. ;)

>
> Very minor editorial changes made while importing, with one exception.
> Added clause that the 'no-map' and 'reusable' properties are mutually
> exclusive.
>
> Signed-off-by: Grant Likely <grant.likely-5wv7dgnIgG8@public.gmane.org>
> Cc: Rob Herring <robh-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
> Cc: Heinrich Schuchardt <xypron.glpk-Mmb7MZpHnFY@public.gmane.org>
> Cc: Ard Biesheuvel <ardb-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
> ---
>  source/chapter3-devicenodes.rst | 203 +++++++++++++++++++++++++++++++-
>  1 file changed, 202 insertions(+), 1 deletion(-)
>
> diff --git a/source/chapter3-devicenodes.rst b/source/chapter3-devicenodes.rst
> index 3aa4650..3043b8a 100644
> --- a/source/chapter3-devicenodes.rst
> +++ b/source/chapter3-devicenodes.rst
> @@ -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
>

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

[Grant Likely]

On 16/09/2020 17:11, Rob Herring wrote:
> On Tue, Sep 15, 2020 at 11:06 AM Grant Likely <grant.likely-5wv7dgnIgG8@public.gmane.org> wrote:
>>
>> 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.

> 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.

>>
>> Very minor editorial changes made while importing, with one exception.
>> Added clause that the 'no-map' and 'reusable' properties are mutually
>> exclusive.
>>
>> Signed-off-by: Grant Likely <grant.likely-5wv7dgnIgG8@public.gmane.org>
>> Cc: Rob Herring <robh-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
>> Cc: Heinrich Schuchardt <xypron.glpk-Mmb7MZpHnFY@public.gmane.org>
>> Cc: Ard Biesheuvel <ardb-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
>> ---
>>   source/chapter3-devicenodes.rst | 203 +++++++++++++++++++++++++++++++-
>>   1 file changed, 202 insertions(+), 1 deletion(-)
>>
>> diff --git a/source/chapter3-devicenodes.rst b/source/chapter3-devicenodes.rst
>> index 3aa4650..3043b8a 100644
>> --- a/source/chapter3-devicenodes.rst
>> +++ b/source/chapter3-devicenodes.rst
>> @@ -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
>>

Re: [PATCH 1/3] Clarify language on /memreserve/

[Grant Likely]

On 15/09/2020 21:45, Heinrich Schuchardt wrote:
> On 9/15/20 7:04 PM, Grant Likely wrote:
>> The language was ambiguous. Rephrase and reformat to be more readable.
>>
>> Co-authored-by: Heinrich Schuchardt <xypron.glpk-Mmb7MZpHnFY@public.gmane.org>
>> Signed-off-by: Grant Likely <grant.likely-5wv7dgnIgG8@public.gmane.org>
>> Cc: Heinrich Schuchardt <xypron.glpk-Mmb7MZpHnFY@public.gmane.org>
>> ---
>>   source/chapter6-source-language.rst | 20 ++++++++++++++------
>>   1 file changed, 14 insertions(+), 6 deletions(-)
>>
>> diff --git a/source/chapter6-source-language.rst b/source/chapter6-source-language.rst
>> index ed4e234..295fcd6 100755
>> --- a/source/chapter6-source-language.rst
>> +++ b/source/chapter6-source-language.rst
>> @@ -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;
> 
> +   /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).

Fixed, thanks.

g.

> 
> Best regards
> 
> Heinrich
> 
>> +
>> +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.
>>
> 

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

[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?

Thanks,
g.

On 15/09/2020 18:04, Grant Likely wrote:
> 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.
> 
> Signed-off-by: Grant Likely <grant.likely-5wv7dgnIgG8@public.gmane.org>
> Cc: Rob Herring <robh-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
> Cc: Heinrich Schuchardt <xypron.glpk-Mmb7MZpHnFY@public.gmane.org>
> Cc: Ard Biesheuvel <ardb-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
> ---
>   source/chapter3-devicenodes.rst | 203 +++++++++++++++++++++++++++++++-
>   1 file changed, 202 insertions(+), 1 deletion(-)
> 
> diff --git a/source/chapter3-devicenodes.rst b/source/chapter3-devicenodes.rst
> index 3aa4650..3043b8a 100644
> --- a/source/chapter3-devicenodes.rst
> +++ b/source/chapter3-devicenodes.rst
> @@ -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
>   ----------------
>   
> 

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

[Thierry Reding]

[-- Attachment #1: Type: text/plain, Size: 13977 bytes --]

On Thu, Sep 17, 2020 at 10:00:35AM +0100, Grant Likely wrote:
> [+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?

Acked-by: Thierry Reding <treding-DDmLM1+adcrQT0dZR+AlfA@public.gmane.org>

> On 15/09/2020 18:04, Grant Likely wrote:
> > 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.
> > 
> > Signed-off-by: Grant Likely <grant.likely-5wv7dgnIgG8@public.gmane.org>
> > Cc: Rob Herring <robh-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
> > Cc: Heinrich Schuchardt <xypron.glpk-Mmb7MZpHnFY@public.gmane.org>
> > Cc: Ard Biesheuvel <ardb-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
> > ---
> >   source/chapter3-devicenodes.rst | 203 +++++++++++++++++++++++++++++++-
> >   1 file changed, 202 insertions(+), 1 deletion(-)
> > 
> > diff --git a/source/chapter3-devicenodes.rst b/source/chapter3-devicenodes.rst
> > index 3aa4650..3043b8a 100644
> > --- a/source/chapter3-devicenodes.rst
> > +++ b/source/chapter3-devicenodes.rst
> > @@ -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
> >   ----------------
> > 

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]