Commit af0d8135 authored by Thierry Reding's avatar Thierry Reding Committed by Joerg Roedel
Browse files

dt-bindings: reserved-memory: Document iommu-addresses 



This adds the "iommu-addresses" property to reserved-memory nodes, which
allow describing the interaction of memory regions with IOMMUs. Two use-
cases are supported:

  1. Static mappings can be described by pairing the "iommu-addresses"
     property with a "reg" property. This is mostly useful for adopting
     firmware-allocated buffers via identity mappings. One common use-
     case where this is required is if early firmware or bootloaders
     have set up a bootsplash framebuffer that a display controller is
     actively scanning out from during the operating system boot
     process.

  2. If an "iommu-addresses" property exists without a "reg" property,
     the reserved-memory node describes an IOVA reservation. Such memory
     regions are excluded from the IOVA space available to operating
     system drivers and can be used for regions that must not be used to
     map arbitrary buffers.

Each mapping or reservation is tied to a specific device via a phandle
to the device's device tree node. This allows a reserved-memory region
to be reused across multiple devices.

Reviewed-by: default avatarRob Herring <robh@kernel.org>
Reviewed-by: default avatarRobin Murphy <robin.murphy@arm.com>
Signed-off-by: default avatarThierry Reding <treding@nvidia.com>
Link: https://lore.kernel.org/r/20230120174251.4004100-3-thierry.reding@gmail.com


Signed-off-by: default avatarJoerg Roedel <jroedel@suse.de>
parent e251c213

Documentation/devicetree/bindings/reserved-memory/reserved-memory.yaml

+85 −4
Original line number Diff line number Diff line
@@ -52,6 +52,30 @@ properties: 
      Address and Length pairs. Specifies regions of memory that are

      acceptable to allocate from.



  iommu-addresses:

    $ref: /schemas/types.yaml#/definitions/phandle-array

    description: >

      A list of phandle and specifier pairs that describe static IO virtual

      address space mappings and carveouts associated with a given reserved

      memory region. The phandle in the first cell refers to the device for

      which the mapping or carveout is to be created.



      The specifier consists of an address/size pair and denotes the IO

      virtual address range of the region for the given device. The exact

      format depends on the values of the "#address-cells" and "#size-cells"

      properties of the device referenced via the phandle.



      When used in combination with a "reg" property, an IOVA mapping is to

      be established for this memory region. One example where this can be

      useful is to create an identity mapping for physical memory that the

      firmware has configured some hardware to access (such as a bootsplash

      framebuffer).



      If no "reg" property is specified, the "iommu-addresses" property

      defines carveout regions in the IOVA space for the given device. This

      can be useful if a certain memory region should not be mapped through

      the IOMMU.



  no-map:

    type: boolean

    description: >
@@ -89,12 +113,69 @@ allOf: 
          - no-map



oneOf:

  - oneOf:

      - required:

          - reg



      - required:

          - size



  - oneOf:

      # IOMMU reservations

      - required:

          - iommu-addresses



      # IOMMU mappings

      - required:

          - reg

          - iommu-addresses



additionalProperties: true



examples:

  - |

    / {

      compatible = "foo";

      model = "foo";



      #address-cells = <2>;

      #size-cells = <2>;



      reserved-memory {

        #address-cells = <2>;

        #size-cells = <2>;

        ranges;



        adsp_resv: reservation-adsp {

          /*

           * Restrict IOVA mappings for ADSP buffers to the 512 MiB region

           * from 0x40000000 - 0x5fffffff. Anything outside is reserved by

           * the ADSP for I/O memory and private memory allocations.

           */

          iommu-addresses = <&adsp 0x0 0x00000000 0x00 0x40000000>,

                            <&adsp 0x0 0x60000000 0xff 0xa0000000>;

        };



        fb: framebuffer@90000000 {

          reg = <0x0 0x90000000 0x0 0x00800000>;

          iommu-addresses = <&dc0 0x0 0x90000000 0x0 0x00800000>;

        };

      };



      bus@0 {

        #address-cells = <1>;

        #size-cells = <1>;

        ranges = <0x0 0x0 0x0 0x40000000>;



        adsp: adsp@2990000 {

          reg = <0x2990000 0x2000>;

          memory-region = <&adsp_resv>;

        };



        dc0: display@15200000 {

          reg = <0x15200000 0x10000>;

          memory-region = <&fb>;

        };

      };

    };

...