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