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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]



[+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@xxxxxxx>
Cc: Rob Herring <robh@xxxxxxxxxx>
Cc: Heinrich Schuchardt <xypron.glpk@xxxxxx>
Cc: Ard Biesheuvel <ardb@xxxxxxxxxx>
---
  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
  ----------------



[Index of Archives]     [Device Tree]     [Linux Driver Backports]     [Video for Linux]     [Linux USB Devel]     [Linux Audio Users]     [Photos]     [Yosemite Photos]     [Linux Kernel]     [Linux SCSI]     [XFree86]     [Yosemite Backpacking]

  Powered by Linux