Fixed. Thanks Etienne
g.
On 16/09/2020 11:45, Etienne Carriere wrote:
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 grant.likely@arm.com wrote:
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
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 inchildren of root.- ``#size-cells`` R ``<u32>`` Specifies the number of ``<u32>`` cells to
represent the size in the ``reg`` property inchildren of root.- ``ranges`` R ``<prop encoded This property represents the mapping between
array>`` parent address to child address spaces (seesection :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 addressand 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 insame format as for ``reg`` properties.- ``compatible`` O ``<stringlist>`` May contain the following strings:
- ``shared-dma-pool``: This indicates a region ofmemory meant to be used as a shared pool of DMAbuffers for a set of devices.It can be used by an operating system toinstantiate the necessary pool managementsubsystem 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 aspart of its standard mapping of system memory,nor permit speculative access to it under anycircumstances other than under the control ofthe device driver using the region.- ``reusable`` O ``<empty>`` The operating system can use the memory in this
region with the limitation that the devicedriver(s) owning the region need to be able toreclaim it back.Typically that means that the operating systemcan use that region to store volatile or cacheddata that can be otherwise regenerated ormigrated 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 boot-architecture@lists.linaro.org https://lists.linaro.org/mailman/listinfo/boot-architecture
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.