Bindings/reserved-memory/shared-dma-pool.yaml

   1 # SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
   2 %YAML 1.2
   3 ---
   4 $id: http://devicetree.org/schemas/reserved-memory/shared-dma-pool.yaml#
   5 $schema: http://devicetree.org/meta-schemas/core.yaml#
   6
   7 title: /reserved-memory DMA pool
   8
   9 maintainers:
  10   - devicetree-spec@vger.kernel.org
  11
  12 allOf:
  13   - $ref: reserved-memory.yaml
  14
  15 properties:
  16   compatible:
  17     oneOf:
  18       - const: shared-dma-pool
  19         description: >
  20           This indicates a region of memory meant to be used as a shared
  21           pool of DMA buffers for a set of devices. It can be used by an
  22           operating system to instantiate the necessary pool management
  23           subsystem if necessary.
  24
  25       - const: restricted-dma-pool
  26         description: >
  27           This indicates a region of memory meant to be used as a pool
  28           of restricted DMA buffers for a set of devices. The memory
  29           region would be the only region accessible to those devices.
  30           When using this, the no-map and reusable properties must not
  31           be set, so the operating system can create a virtual mapping
  32           that will be used for synchronization. The main purpose for
  33           restricted DMA is to mitigate the lack of DMA access control
  34           on systems without an IOMMU, which could result in the DMA
  35           accessing the system memory at unexpected times and/or
  36           unexpected addresses, possibly leading to data leakage or
  37           corruption. The feature on its own provides a basic level of
  38           protection against the DMA overwriting buffer contents at
  39           unexpected times. However, to protect against general data
  40           leakage and system memory corruption, the system needs to
  41           provide way to lock down the memory access, e.g., MPU. Note
  42           that since coherent allocation needs remapping, one must set
  43           up another device coherent pool by shared-dma-pool and use
  44           dma_alloc_from_dev_coherent instead for atomic coherent
  45           allocation.
  46
  47   linux,cma-default:
  48     type: boolean
  49     description: >
  50       If this property is present, then Linux will use the region for
  51       the default pool of the contiguous memory allocator.
  52
  53   linux,dma-default:
  54     type: boolean
  55     description: >
  56       If this property is present, then Linux will use the region for
  57       the default pool of the consistent DMA allocator.
  58
  59 if:
  60   properties:
  61     compatible:
  62       contains:
  63         const: restricted-dma-pool
  64 then:
  65   properties:
  66     no-map: false
  67     reusable: false
  68
  69 unevaluatedProperties: false
  70
  71 examples:
  72   - |
  73       reserved-memory {
  74           #address-cells = <1>;
  75           #size-cells = <1>;
  76           ranges;
  77
  78           /* global autoconfigured region for contiguous allocations */
  79           linux,cma {
  80               compatible = "shared-dma-pool";
  81               reusable;
  82               size = <0x4000000>;
  83               alignment = <0x2000>;
  84               linux,cma-default;
  85           };
  86
  87           display_reserved: framebuffer@78000000 {
  88               reg = <0x78000000 0x800000>;
  89           };
  90
  91           restricted_dma_reserved: restricted-dma-pool@50000000 {
  92               compatible = "restricted-dma-pool";
  93               reg = <0x50000000 0x4000000>;
  94           };
  95       };
  96
  97 ...