Imported from linux kernel source: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Docu...
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@arm.com Cc: Rob Herring robh@kernel.org Cc: Heinrich Schuchardt xypron.glpk@gmx.de Cc: Ard Biesheuvel ardb@kernel.org --- source/chapter3-devicenodes.rst | 199 ++++++++++++++++++++++++++++++++ 1 file changed, 199 insertions(+)
diff --git a/source/chapter3-devicenodes.rst b/source/chapter3-devicenodes.rst index 3aa4650..1c1149a 100644 --- a/source/chapter3-devicenodes.rst +++ b/source/chapter3-devicenodes.rst @@ -200,6 +200,205 @@ 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 + ======================================================================================================= + +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
IMPORTANT NOTICE: The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you.