From mboxrd@z Thu Jan 1 00:00:00 1970 From: Grant Likely Subject: [PATCH 2/3] Import /reserved-memory specification text Date: Tue, 15 Sep 2020 18:04:55 +0100 Message-ID: <20200915170455.32520-2-grant.likely@arm.com> References: <20200915170455.32520-1-grant.likely@arm.com> Mime-Version: 1.0 Content-Transfer-Encoding: 8bit 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=XvoxDDq5lKZM89kRZo/PYofr3eNklg+eo6GN72Vrjcg=; b=rgiZzrtYODmVtNqZ9XFU+7WFs61sdchL2yHfXpDYc7OLm0PfTHBpCDKV5lJhaNQacCXfb8I7v7L0+6Cld5rHN+MeOhmg87wkhHVMk2NGhm2hW+Xx2465eLAn5ojW38hUK0MUInohAHjjBcwx+697VHU/NwprZrxKJzW6+hpIPhs= 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=XvoxDDq5lKZM89kRZo/PYofr3eNklg+eo6GN72Vrjcg=; b=rgiZzrtYODmVtNqZ9XFU+7WFs61sdchL2yHfXpDYc7OLm0PfTHBpCDKV5lJhaNQacCXfb8I7v7L0+6Cld5rHN+MeOhmg87wkhHVMk2NGhm2hW+Xx2465eLAn5ojW38hUK0MUInohAHjjBcwx+697VHU/NwprZrxKJzW6+hpIPhs= In-Reply-To: <20200915170455.32520-1-grant.likely-5wv7dgnIgG8@public.gmane.org> Sender: devicetree-spec-owner-u79uwXL29TY76Z2rM5mHXA@public.gmane.org List-ID: Content-Type: text/plain; charset="us-ascii" To: devicetree-spec-u79uwXL29TY76Z2rM5mHXA@public.gmane.org Cc: nd-5wv7dgnIgG8@public.gmane.org, Ard Biesheuvel , Leif Lindholm , Grant Likely , Rob Herring , Heinrich Schuchardt 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 ```` 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 ---------------- -- 2.20.1