Hello Grant, Some minor typos. Looks all good to me for the rest, by the way.
On Mon, 14 Sep 2020 at 21:59, Grant Likely <[email protected]> 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 <[email protected]> > Cc: Rob Herring <[email protected]> > Cc: Heinrich Schuchardt <[email protected]> > Cc: Ard Biesheuvel <[email protected]> > --- > 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 Minor: looks like above and below lines are separated sentences. "... normal usage. One can ...". > +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), ``linux,cma`` base address is dynamically assigned: remove @72000000 from above line. > +one dedicated to the framebuffer device (named ``framebuffer@78000000``, > 8MiB), and > +one for multimedia processing (named ``multimedia-memory@77000000``, 64MiB). Fix name that is ``multimedia@77000000`` in the example. Regards, Etienne > + > +.. 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. > _______________________________________________ > boot-architecture mailing list > [email protected] > https://lists.linaro.org/mailman/listinfo/boot-architecture _______________________________________________ boot-architecture mailing list [email protected] https://lists.linaro.org/mailman/listinfo/boot-architecture
