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