Clarify language on /memreserve/
PATCH 1/3 Clarify language on /memreserve/
The language was ambiguous. Rephrase and reformat to be more readable.
--- source/chapter6-source-language.rst | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-)
source/chapter6-source-language.rst +14 -6
@@ -233,15 +233,23 @@ File layout [child nodes] }; -The /dts-v1/; shall be present to identify the file as a version 1 DTS +``/dts-v1/;`` shall be present to identify the file as a version 1 DTS (dts files without this tag will be treated by dtc as being in the obsolete version 0, which uses a different format for integers in addition to other small but incompatible changes). -Memory reservations define an entry for the devicetree blob’s memory -reservation table. They have the form: e.g., /memreserve/ <address> -<length>; Where <address> and <length> are 64-bit C-style integers. +Memory reservations (see section :ref:`sect-fdt-memory-reservation-block`) +are represented by lines in the form:: -* The / { }; section defines the root node of the devicetree. + /memreserve/ <address> <length>; -* C style (/* ... \*/) and C++ style (//) comments are supported. +Where ``<address>`` and ``<length>`` are 64-bit C-style integers, e.g., + +.. code-block:: dts + + /memreserve/ 0x10000000 0x0004000; + +The ``/ { ... };`` section defines the root node of the devicetree, and +all the device tree data is contained within it. + +C style (``/* ... \*/``) and C++ style (``//``) comments are supported.
Signature · 1 line
2.20.1
A message that is not in the archive (sent off-list or not yet received): [email protected]
PATCH 2/3 Import /reserved-memory specification text
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.
--- source/chapter3-devicenodes.rst | 203 +++++++++++++++++++++++++++++++- 1 file changed, 202 insertions(+), 1 deletion(-)
source/chapter3-devicenodes.rst +202 -1
@@ -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 ----------------
Signature · 1 line
2.20.1
A message that is not in the archive (sent off-list or not yet received): [email protected]
Re: [PATCH 2/3] Import /reserved-memory specification text
Quoted 3 lines · Grant Likely
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
And what happens when this file is modified? Can you make it just contain "This has moved, see DT spec section x.y.z" or something like that?
Don't you want to convert it to schema for me first and then generate the spec content. ;)
Quoted 237 lines
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 | 203 +++++++++++++++++++++++++++++++- 1 file changed, 202 insertions(+), 1 deletion(-)source/chapter3-devicenodes.rst +202
-2@@ -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 ---------------- --2.20.1
A message that is not in the archive (sent off-list or not yet received): CAL_JsqKLV+R2YAXOZuPYnMR8Wji4_PkiH+r+Fki59r436SqnEw-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org
Re: [PATCH 2/3] Import /reserved-memory specification text
Quoted 8 lines · Rob Herring
Quoted 3 lines · Grant Likely
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.txtAnd what happens when this file is modified? Can you make it just contain "This has moved, see DT spec section x.y.z" or something like that?
I think so. My first thought was to remove the file entirely from Linux, but it might be better to leave the file in place and replace the contents with a hyperlink to the spec section.
Quoted 2 lines
Don't you want to convert it to schema for me first and then generate the spec content. ;)
:-p
Yeah I do, but I never got around to implementing that parser and instead that idea has just blocked all progress on the spec. So until that happens, if ever, I'd rather start bringing the content into dtspec that can be reformatted later.
g.
Quoted 237 lines
Quoted 237 lines
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 | 203 +++++++++++++++++++++++++++++++- 1 file changed, 202 insertions(+), 1 deletion(-)source/chapter3-devicenodes.rst +202
-2@@ -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 ---------------- --2.20.1
Re: [PATCH 2/3] Import /reserved-memory specification text
In reply to a message not in the archive[+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.
Quoted 237 lines · Grant Likely
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.txtVery 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 | 203 +++++++++++++++++++++++++++++++- 1 file changed, 202 insertions(+), 1 deletion(-)source/chapter3-devicenodes.rst +202
-1@@ -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 ----------------
A message that is not in the archive (sent off-list or not yet received): 17b980e5-97e7-8afa-3d51-c462f2fe91ff-5wv7dgnIgG8@public.gmane.org
Thierry Reding
Acked-byRe: [PATCH 2/3] Import /reserved-memory specification text
Quoted 7 lines · Grant Likely
[+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?
Quoted 232 lines · Grant Likely
Quoted 231 lines
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.txtVery 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 | 203 +++++++++++++++++++++++++++++++- 1 file changed, 202 insertions(+), 1 deletion(-)source/chapter3-devicenodes.rst +202
-1@@ -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 ----------------
PATCH 3/3 Add details of UEFI interaction with /memory and /reserved-memory
In reply to a message not in the archiveOutput from discussion on EBBR issue:
https://github.com/ARM-software/ebbr/issues/52
When using the UEFI ABI for booting, the DT memory map is ignored and instead UEFI GetMemoryMap() is used to find system memory. Also, regions described in /reserved-memory need to also be added to the UEFI memory map to protect against overlapping allocations. The patch adds language to cover both of those cases.
--- source/chapter3-devicenodes.rst | 26 +++++++++++++++++++++++--- source/chapter5-flattened-format.rst | 10 ++++++++++ source/references.rst | 4 ++++ 3 files changed, 37 insertions(+), 3 deletions(-)
source/chapter3-devicenodes.rst +23 -3
@@ -160,6 +160,12 @@ If the VLE storage attribute is supported, with VLE=0. .. note:: All other standard properties (section :ref:`sect-standard-properties`) are allowed but are optional. +``/memory`` node and UEFI +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When booting via [UEFI]_, the system memory map is obtained via the +GetMemoryMap() UEFI boot time service as defined in [UEFI]_ ยง 7.2, +and if present, the OS must ignore any ``/memory`` nodes. ``/memory`` Examples ~~~~~~~~~~~~~~~~~~~~
@@ -308,12 +314,12 @@ is ignored. 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. +Dynamic reserved memory regions must not be listed in the [UEFI]_ memory map +because they are allocated by the OS after exiting firmware boot services. + Linux implementation notes: - If a ``linux,cma-default`` property is present, then Linux will use the
@@ -341,6 +347,20 @@ nodes by adding a ``memory-region`` property to the device node. Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition ======================================================================================================= +.. _sect-reserved-memory-uefi: + +``/reserved-memory`` and UEFI +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +When booting via [UEFI]_, static ``/reserved-memory`` regions must +also be listed in the system memory map obtained via the GetMemoryMap() +UEFI boot time service as defined in [UEFI]_ ยง 7.2. +The reserved memory regions need to be included in the UEFI memory map to +protect against allocations by UEFI applications. + +Reserved regions with the ``no-map`` property must be listed in the memory +map with type ``EfiReservedMemoryType``. +All other reserved regions must be listed with type ``EfiBootServicesData``. + ``/reserved-memory`` Example ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
source/chapter5-flattened-format.rst +10 -0
@@ -234,6 +234,16 @@ reservation block as a whole, shall be located at an 8-byte aligned offset from the beginning of the devicetree blob (see section :ref:`sect-fdt-alignment`). +Memory Reservation Block and UEFI +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +As with the ``/reserved-memory`` node (section :ref:`sect-reserved-memory-uefi`), +when booting via [UEFI]_ entries in the Memory Reservation Block must also be +listed in the system memory map obtained via the GetMemoryMap() to protect against +allocations by UEFI applications. +The memory reservation block entries should be listed with type +``EfiBootServicesData``. + .. _sect-fdt-structure-block: Structure Block
source/references.rst +4 -0
@@ -23,3 +23,7 @@ .. [EPAPR] *Power.org Standard for Embedded Power Architecture Platform Requirements*, power.org, 2011, https://www.power.org/documentation/power-org-standard-for-embedded-power-architecture-platform-requirements-epapr-v1-1-2/ + +.. [UEFI] `Unified Extensable Firmware Interface Specification v2.8 Errata A + <https://uefi.org/sites/default/files/resources/UEFI_Spec_2_8_A_Feb14.pdf>`_, + February 2020, `UEFI Forum <http://www.uefi.org>`_
Signature · 1 line
2.20.1
A message that is not in the archive (sent off-list or not yet received): [email protected]
Re: [PATCH 3/3] Add details of UEFI interaction with /memory and /reserved-memory
Quoted 81 lines · Grant Likely
Output from discussion on EBBR issue:
https://github.com/ARM-software/ebbr/issues/52When using the UEFI ABI for booting, the DT memory map is ignored and instead UEFI
GetMemoryMap()is used to find system memory. Also, regions described in /reserved-memory need to also be added to the UEFI memory map to protect against overlapping allocations. The patch adds language to cover both of those cases.Signed-off-by Grant Likely <[email protected]>Cc Heinrich Schuchardt <[email protected]>Cc Ard Biesheuvel <[email protected]>--- source/chapter3-devicenodes.rst | 26 +++++++++++++++++++++++--- source/chapter5-flattened-format.rst | 10 ++++++++++ source/references.rst | 4 ++++ 3 files changed, 37 insertions(+), 3 deletions(-)source/chapter3-devicenodes.rst +23
-3@@ -160,6 +160,12 @@ If the VLE storage attribute is supported, with VLE=0. .. note:: All other standard properties (section :ref:`sect-standard-properties`) are allowed but are optional. +``/memory`` node and UEFI +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When booting via [UEFI]_, the system memory map is obtained via the +GetMemoryMap() UEFI boot time service as defined in [UEFI]_ ยง 7.2, +and if present, the OS must ignore any ``/memory`` nodes. ``/memory`` Examples ~~~~~~~~~~~~~~~~~~~~@@ -308,12 +314,12 @@ is ignored. 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. +Dynamic reserved memory regions must not be listed in the [UEFI]_ memory map +because they are allocated by the OS after exiting firmware boot services. + Linux implementation notes: - If a ``linux,cma-default`` property is present, then Linux will use the@@ -341,6 +347,20 @@ nodes by adding a ``memory-region`` property to the device node. Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition ======================================================================================================= +.. _sect-reserved-memory-uefi: + +``/reserved-memory`` and UEFI +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +When booting via [UEFI]_, static ``/reserved-memory`` regions must +also be listed in the system memory map obtained via the GetMemoryMap() +UEFI boot time service as defined in [UEFI]_ ยง 7.2. +The reserved memory regions need to be included in the UEFI memory map to +protect against allocations by UEFI applications. + +Reserved regions with the ``no-map`` property must be listed in the memory +map with type ``EfiReservedMemoryType``. +All other reserved regions must be listed with type ``EfiBootServicesData``. + ``/reserved-memory`` Example ~~~~~~~~~~~~~~~~~~~~~~~~~~~~source/chapter5-flattened-format.rst +0
-0@@ -234,6 +234,16 @@ reservation block as a whole, shall be located at an 8-byte aligned offset from the beginning of the devicetree blob (see section :ref:`sect-fdt-alignment`).
source/chapter5-flattened-format.rst reservation block as a whole, shall be located at an 8-byte aligned · line 246
Quoted 10 lines
source/chapter5-flattened-format.rst +10
-0+Memory Reservation Block and UEFI +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +As with the ``/reserved-memory`` node (section :ref:`sect-reserved-memory-uefi`), +when booting via [UEFI]_ entries in the Memory Reservation Block must also be +listed in the system memory map obtained via the GetMemoryMap() to protect against +allocations by UEFI applications. +The memory reservation block entries should be listed with type +``EfiBootServicesData``. +
Didn't we just agree this should be EfiReservedMemoryType ?
Quoted 18 lines
source/chapter5-flattened-format.rst +0
-0.. _sect-fdt-structure-block: Structure Blocksource/references.rst +4
-1@@ -23,3 +23,7 @@ .. [EPAPR] *Power.org Standard for Embedded Power Architecture Platform Requirements*, power.org, 2011, https://www.power.org/documentation/power-org-standard-for-embedded-power-architecture-platform-requirements-epapr-v1-1-2/ + +.. [UEFI] `Unified Extensable Firmware Interface Specification v2.8 Errata A + <https://uefi.org/sites/default/files/resources/UEFI_Spec_2_8_A_Feb14.pdf>`_, + February 2020, `UEFI Forum <http://www.uefi.org>`_ --2.20.1
A message that is not in the archive (sent off-list or not yet received): CAMj1kXGQTbU5uxPSsePxDTZrdeAvOf8Ev0iNmAHDcAoP_SYdHQ-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org
Re: [PATCH 3/3] Add details of UEFI interaction with /memory and /reserved-memory
Quoted 1 line · Ard Biesheuvel
On Tue, 15 Sep 2020 at 20:06, Grant Likely <[email protected]> wrote:
[...]
Quoted 4 lines
Quoted 4 lines
source/chapter5-flattened-format.rst +4
-0+Memory Reservation Block and UEFI +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +As with the ``/reserved-memory`` node (section :ref:`sect-reserved-memory-uefi`),
Quoted 8 lines
source/chapter5-flattened-format.rst reservation block as a whole, shall be located at an 8-byte aligned · line 246
Quoted 6 lines
source/chapter5-flattened-format.rst +6
-0+when booting via [UEFI]_ entries in the Memory Reservation Block must also be +listed in the system memory map obtained via the GetMemoryMap() to protect against +allocations by UEFI applications. +The memory reservation block entries should be listed with type +``EfiBootServicesData``. +Didn't we just agree this should be EfiReservedMemoryType ?
That would be I-made-the-change-but-neglected-to-git-commit--amend-the-patch kind of error. Oops!
g.
Quoted 28 lines · Grant Likely
The language was ambiguous. Rephrase and reformat to be more readable.
Co-authored-by Heinrich Schuchardt <[email protected]>Signed-off-by Grant Likely <[email protected]>Cc Heinrich Schuchardt <[email protected]>--- source/chapter6-source-language.rst | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-)source/chapter6-source-language.rst +3
-4@@ -233,15 +233,23 @@ File layout [child nodes] }; -The /dts-v1/; shall be present to identify the file as a version 1 DTS +``/dts-v1/;`` shall be present to identify the file as a version 1 DTS (dts files without this tag will be treated by dtc as being in the obsolete version 0, which uses a different format for integers in addition to other small but incompatible changes). -Memory reservations define an entry for the devicetree blob’s memory -reservation table. They have the form: e.g., /memreserve/ <address> -<length>; Where <address> and <length> are 64-bit C-style integers. +Memory reservations (see section :ref:`sect-fdt-memory-reservation-block`) +are represented by lines in the form::
source/chapter6-source-language.rst File layout · line 250
Quoted 10 lines
source/chapter6-source-language.rst +6
-2-* The / { }; section defines the root node of the devicetree. + /memreserve/ <address> <length>; -* C style (/* ... \*/) and C++ style (//) comments are supported. +Where ``<address>`` and ``<length>`` are 64-bit C-style integers, e.g., + +.. code-block:: dts + + /memreserve/ 0x10000000 0x0004000;
+ /memreserve/ 0x10000000 0x00004000;
The 28bit number looks strange here. Let's add another zero so that the number formats match (or remove the leading zeros).
Best regards
Heinrich
Quoted 6 lines
source/chapter6-source-language.rst +5
-0+ +The ``/ { ... };`` section defines the root node of the devicetree, and +all the device tree data is contained within it. + +C style (``/* ... \*/``) and C++ style (``//``) comments are supported.
A message that is not in the archive (sent off-list or not yet received): 389c3f6b-dc39-2b12-ebd4-034dc274e2f6-Mmb7MZpHnFY@public.gmane.org
Quoted 42 lines · Heinrich Schuchardt
Quoted 28 lines · Grant Likely
The language was ambiguous. Rephrase and reformat to be more readable.
Co-authored-by Heinrich Schuchardt <[email protected]>Signed-off-by Grant Likely <[email protected]>Cc Heinrich Schuchardt <[email protected]>--- source/chapter6-source-language.rst | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-)source/chapter6-source-language.rst +3
-4@@ -233,15 +233,23 @@ File layout [child nodes] }; -The /dts-v1/; shall be present to identify the file as a version 1 DTS +``/dts-v1/;`` shall be present to identify the file as a version 1 DTS (dts files without this tag will be treated by dtc as being in the obsolete version 0, which uses a different format for integers in addition to other small but incompatible changes). -Memory reservations define an entry for the devicetree blob’s memory -reservation table. They have the form: e.g., /memreserve/ <address> -<length>; Where <address> and <length> are 64-bit C-style integers. +Memory reservations (see section :ref:`sect-fdt-memory-reservation-block`) +are represented by lines in the form::source/chapter6-source-language.rst File layout · line 250
Quoted 10 lines
source/chapter6-source-language.rst +6
-2-* The / { }; section defines the root node of the devicetree. + /memreserve/ <address> <length>; -* C style (/* ... \*/) and C++ style (//) comments are supported. +Where ``<address>`` and ``<length>`` are 64-bit C-style integers, e.g., + +.. code-block:: dts + + /memreserve/ 0x10000000 0x0004000;+ /memreserve/
0x100000000x00004000;
Quoted 2 lines
The 28bit number looks strange here. Let's add another zero so that the number formats match (or remove the leading zeros).
Fixed, thanks.
g.
Quoted 12 lines
Best regards
Heinrich
Quoted 6 lines
source/chapter6-source-language.rst +5
-0+ +The ``/ { ... };`` section defines the root node of the devicetree, and +all the device tree data is contained within it. + +C style (``/* ... \*/``) and C++ style (``//``) comments are supported.