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@xxxxxxxxxx> > 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 > > ---------------- > >
Attachment:
signature.asc
Description: PGP signature
