| Thierry Reding | e8dfad4 | 2019-03-21 19:10:02 +0100 | [diff] [blame] | 1 | *** Reserved memory regions *** |
| 2 | |
| 3 | Reserved memory is specified as a node under the /reserved-memory node. |
| 4 | The operating system shall exclude reserved memory from normal usage |
| 5 | one can create child nodes describing particular reserved (excluded from |
| 6 | normal use) memory regions. Such memory regions are usually designed for |
| 7 | the special usage by various device drivers. |
| 8 | |
| 9 | Parameters for each memory region can be encoded into the device tree |
| 10 | with the following nodes: |
| 11 | |
| 12 | /reserved-memory node |
| 13 | --------------------- |
| 14 | #address-cells, #size-cells (required) - standard definition |
| 15 | - Should use the same values as the root node |
| 16 | ranges (required) - standard definition |
| 17 | - Should be empty |
| 18 | |
| 19 | /reserved-memory/ child nodes |
| 20 | ----------------------------- |
| 21 | Each child of the reserved-memory node specifies one or more regions of |
| 22 | reserved memory. Each child node may either use a 'reg' property to |
| 23 | specify a specific range of reserved memory, or a 'size' property with |
| 24 | optional constraints to request a dynamically allocated block of memory. |
| 25 | |
| 26 | Following the generic-names recommended practice, node names should |
| 27 | reflect the purpose of the node (ie. "framebuffer" or "dma-pool"). Unit |
| 28 | address (@<address>) should be appended to the name if the node is a |
| 29 | static allocation. |
| 30 | |
| 31 | Properties: |
| 32 | Requires either a) or b) below. |
| 33 | a) static allocation |
| 34 | reg (required) - standard definition |
| 35 | b) dynamic allocation |
| 36 | size (required) - length based on parent's #size-cells |
| 37 | - Size in bytes of memory to reserve. |
| 38 | alignment (optional) - length based on parent's #size-cells |
| 39 | - Address boundary for alignment of allocation. |
| 40 | alloc-ranges (optional) - prop-encoded-array (address, length pairs). |
| 41 | - Specifies regions of memory that are |
| 42 | acceptable to allocate from. |
| 43 | |
| 44 | If both reg and size are present, then the reg property takes precedence |
| 45 | and size is ignored. |
| 46 | |
| 47 | Additional properties: |
| 48 | compatible (optional) - standard definition |
| 49 | - may contain the following strings: |
| 50 | - shared-dma-pool: This indicates a region of memory meant to be |
| 51 | used as a shared pool of DMA buffers for a set of devices. It can |
| 52 | be used by an operating system to instantiate the necessary pool |
| 53 | management subsystem if necessary. |
| 54 | - vendor specific string in the form <vendor>,[<device>-]<usage> |
| 55 | no-map (optional) - empty property |
| 56 | - Indicates the operating system must not create a virtual mapping |
| 57 | of the region as part of its standard mapping of system memory, |
| 58 | nor permit speculative access to it under any circumstances other |
| 59 | than under the control of the device driver using the region. |
| 60 | reusable (optional) - empty property |
| 61 | - The operating system can use the memory in this region with the |
| 62 | limitation that the device driver(s) owning the region need to be |
| 63 | able to reclaim it back. Typically that means that the operating |
| 64 | system can use that region to store volatile or cached data that |
| 65 | can be otherwise regenerated or migrated elsewhere. |
| 66 | |
| 67 | Linux implementation note: |
| 68 | - If a "linux,cma-default" property is present, then Linux will use the |
| 69 | region for the default pool of the contiguous memory allocator. |
| 70 | |
| 71 | - If a "linux,dma-default" property is present, then Linux will use the |
| 72 | region for the default pool of the consistent DMA allocator. |
| 73 | |
| 74 | Device node references to reserved memory |
| 75 | ----------------------------------------- |
| 76 | Regions in the /reserved-memory node may be referenced by other device |
| 77 | nodes by adding a memory-region property to the device node. |
| 78 | |
| 79 | memory-region (optional) - phandle, specifier pairs to children of /reserved-memory |
| 80 | |
| 81 | Example |
| 82 | ------- |
| 83 | This example defines 3 contiguous regions are defined for Linux kernel: |
| 84 | one default of all device drivers (named linux,cma@72000000 and 64MiB in size), |
| 85 | one dedicated to the framebuffer device (named framebuffer@78000000, 8MiB), and |
| 86 | one for multimedia processing (named multimedia-memory@77000000, 64MiB). |
| 87 | |
| 88 | / { |
| 89 | #address-cells = <1>; |
| 90 | #size-cells = <1>; |
| 91 | |
| 92 | memory { |
| 93 | reg = <0x40000000 0x40000000>; |
| 94 | }; |
| 95 | |
| 96 | reserved-memory { |
| 97 | #address-cells = <1>; |
| 98 | #size-cells = <1>; |
| 99 | ranges; |
| 100 | |
| 101 | /* global autoconfigured region for contiguous allocations */ |
| 102 | linux,cma { |
| 103 | compatible = "shared-dma-pool"; |
| 104 | reusable; |
| 105 | size = <0x4000000>; |
| 106 | alignment = <0x2000>; |
| 107 | linux,cma-default; |
| 108 | }; |
| 109 | |
| 110 | display_reserved: framebuffer@78000000 { |
| 111 | reg = <0x78000000 0x800000>; |
| 112 | }; |
| 113 | |
| 114 | multimedia_reserved: multimedia@77000000 { |
| 115 | compatible = "acme,multimedia-memory"; |
| 116 | reg = <0x77000000 0x4000000>; |
| 117 | }; |
| 118 | }; |
| 119 | |
| 120 | /* ... */ |
| 121 | |
| 122 | fb0: video@12300000 { |
| 123 | memory-region = <&display_reserved>; |
| 124 | /* ... */ |
| 125 | }; |
| 126 | |
| 127 | scaler: scaler@12500000 { |
| 128 | memory-region = <&multimedia_reserved>; |
| 129 | /* ... */ |
| 130 | }; |
| 131 | |
| 132 | codec: codec@12600000 { |
| 133 | memory-region = <&multimedia_reserved>; |
| 134 | /* ... */ |
| 135 | }; |
| 136 | }; |