From mboxrd@z Thu Jan 1 00:00:00 1970 From: Grant Likely Subject: Re: [PATCH 2/3] Import /reserved-memory specification text Date: Thu, 17 Sep 2020 10:00:35 +0100 Message-ID: <17b980e5-97e7-8afa-3d51-c462f2fe91ff@arm.com> References: <20200915170455.32520-1-grant.likely@arm.com> <20200915170455.32520-2-grant.likely@arm.com> Mime-Version: 1.0 Content-Transfer-Encoding: 7bit Return-path: DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=armh.onmicrosoft.com; s=selector2-armh-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=P28InEMaxfgRsoE1wYa7hSelPgYRX6wGTlNJnjagFVI=; b=ka8kwYq9oDLheSESJr8090Jz+6dW8ztfFBNyHLSEIJFgW7PG/uSs6P37XMYorVxGez0cAYjmrvkqsVz0+O9vYVNuEZ57WwXwubrUa9kqf4uF6jcIr9zm7TinPfGUpeEzqc9E/xy/jJ+sMUqMbq8ZD0rUVf2ltGw98NZXEPreRKY= DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=armh.onmicrosoft.com; s=selector2-armh-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=P28InEMaxfgRsoE1wYa7hSelPgYRX6wGTlNJnjagFVI=; b=ka8kwYq9oDLheSESJr8090Jz+6dW8ztfFBNyHLSEIJFgW7PG/uSs6P37XMYorVxGez0cAYjmrvkqsVz0+O9vYVNuEZ57WwXwubrUa9kqf4uF6jcIr9zm7TinPfGUpeEzqc9E/xy/jJ+sMUqMbq8ZD0rUVf2ltGw98NZXEPreRKY= In-Reply-To: <20200915170455.32520-2-grant.likely-5wv7dgnIgG8@public.gmane.org> Content-Language: en-US List-ID: Content-Type: text/plain; charset="us-ascii"; format="flowed" To: devicetree-spec-u79uwXL29TY76Z2rM5mHXA@public.gmane.org, Thierry Reding Cc: nd-5wv7dgnIgG8@public.gmane.org, Ard Biesheuvel , Leif Lindholm , Rob Herring , Heinrich Schuchardt [+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? Thanks, g. 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 > Cc: Rob Herring > Cc: Heinrich Schuchardt > Cc: Ard Biesheuvel > --- > 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 ```` Specifies the number of ```` cells to > + represent the address in the ``reg`` property in > + children of root. > + ``#size-cells`` R ```` Specifies the number of ```` cells to > + represent the size in the ``reg`` property in > + children of root. > + ``ranges`` R `` + 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 (``@
``) 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 ```` Consists of an arbitrary number of address and > + size pairs that specify the physical address > + and size of the memory ranges. > + ``size`` O ```` 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 ```` Address boundary for alignment of allocation. > + Size of this property is based on parent node's > + ``#size-cells`` property. > + ``alloc-ranges`` O ```` 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 ```` 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 > + ``,[-]`` > + ``no-map`` O ```` 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 ```` 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 ```` phandle, specifier pairs to children of > + ``/reserved-memory`` > + ``memory-region-names`` O ``>`` 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 > ---------------- > >