target/linux/ipq806x/patches/0053-of-document-bindings-for-reserved-memory-nodes.patch

   1 From 060a8e3db75ef98fb296b03b8fb0cdfcbcc76c6e Mon Sep 17 00:00:00 2001
   2 From: Grant Likely <grant.likely@linaro.org>
   3 Date: Fri, 28 Feb 2014 14:42:46 +0100
   4 Subject: [PATCH 053/182] of: document bindings for reserved-memory nodes
   5
   6 Reserved memory nodes allow for the reservation of static (fixed
   7 address) regions, or dynamically allocated regions for a specific
   8 purpose.
   9
  10 [joshc: Based on binding document proposed (in non-patch form) here:
  11  http://lkml.kernel.org/g/20131030134702.19B57C402A0@trevor.secretlab.ca
  12  adapted to support #memory-region-cells]
  13 Signed-off-by: Josh Cartwright <joshc@codeaurora.org>
  14 [mszyprow: removed #memory-region-cells property]
  15 Signed-off-by: Marek Szyprowski <m.szyprowski@samsung.com>
  16 [grant.likely: removed residual #memory-region-cells example]
  17 Signed-off-by: Grant Likely <grant.likely@linaro.org>
  18 ---
  19  .../bindings/reserved-memory/reserved-memory.txt   |  133 ++++++++++++++++++++
  20  1 file changed, 133 insertions(+)
  21  create mode 100644 Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt
  22
  23 diff --git a/Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt b/Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt
  24 new file mode 100644
  25 index 0000000..3da0ebd
  26 --- /dev/null
  27 +++ b/Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt
  28 @@ -0,0 +1,133 @@
  29 +*** Reserved memory regions ***
  30 +
  31 +Reserved memory is specified as a node under the /reserved-memory node.
  32 +The operating system shall exclude reserved memory from normal usage
  33 +one can create child nodes describing particular reserved (excluded from
  34 +normal use) memory regions. Such memory regions are usually designed for
  35 +the special usage by various device drivers.
  36 +
  37 +Parameters for each memory region can be encoded into the device tree
  38 +with the following nodes:
  39 +
  40 +/reserved-memory node
  41 +---------------------
  42 +#address-cells, #size-cells (required) - standard definition
  43 +    - Should use the same values as the root node
  44 +ranges (required) - standard definition
  45 +    - Should be empty
  46 +
  47 +/reserved-memory/ child nodes
  48 +-----------------------------
  49 +Each child of the reserved-memory node specifies one or more regions of
  50 +reserved memory. Each child node may either use a 'reg' property to
  51 +specify a specific range of reserved memory, or a 'size' property with
  52 +optional constraints to request a dynamically allocated block of memory.
  53 +
  54 +Following the generic-names recommended practice, node names should
  55 +reflect the purpose of the node (ie. "framebuffer" or "dma-pool"). Unit
  56 +address (@<address>) should be appended to the name if the node is a
  57 +static allocation.
  58 +
  59 +Properties:
  60 +Requires either a) or b) below.
  61 +a) static allocation
  62 +   reg (required) - standard definition
  63 +b) dynamic allocation
  64 +   size (required) - length based on parent's #size-cells
  65 +                   - Size in bytes of memory to reserve.
  66 +   alignment (optional) - length based on parent's #size-cells
  67 +                        - Address boundary for alignment of allocation.
  68 +   alloc-ranges (optional) - prop-encoded-array (address, length pairs).
  69 +                           - Specifies regions of memory that are
  70 +                             acceptable to allocate from.
  71 +
  72 +If both reg and size are present, then the reg property takes precedence
  73 +and size is ignored.
  74 +
  75 +Additional properties:
  76 +compatible (optional) - standard definition
  77 +    - may contain the following strings:
  78 +        - shared-dma-pool: This indicates a region of memory meant to be
  79 +          used as a shared pool of DMA buffers for a set of devices. It can
  80 +          be used by an operating system to instanciate the necessary pool
  81 +          management subsystem if necessary.
  82 +        - vendor specific string in the form <vendor>,[<device>-]<usage>
  83 +no-map (optional) - empty property
  84 +    - Indicates the operating system must not create a virtual mapping
  85 +      of the region as part of its standard mapping of system memory,
  86 +      nor permit speculative access to it under any circumstances other
  87 +      than under the control of the device driver using the region.
  88 +reusable (optional) - empty property
  89 +    - The operating system can use the memory in this region with the
  90 +      limitation that the device driver(s) owning the region need to be
  91 +      able to reclaim it back. Typically that means that the operating
  92 +      system can use that region to store volatile or cached data that
  93 +      can be otherwise regenerated or migrated elsewhere.
  94 +
  95 +Linux implementation note:
  96 +- If a "linux,cma-default" property is present, then Linux will use the
  97 +  region for the default pool of the contiguous memory allocator.
  98 +
  99 +Device node references to reserved memory
 100 +-----------------------------------------
 101 +Regions in the /reserved-memory node may be referenced by other device
 102 +nodes by adding a memory-region property to the device node.
 103 +
 104 +memory-region (optional) - phandle, specifier pairs to children of /reserved-memory
 105 +
 106 +Example
 107 +-------
 108 +This example defines 3 contiguous regions are defined for Linux kernel:
 109 +one default of all device drivers (named linux,cma@72000000 and 64MiB in size),
 110 +one dedicated to the framebuffer device (named framebuffer@78000000, 8MiB), and
 111 +one for multimedia processing (named multimedia-memory@77000000, 64MiB).
 112 +
 113 +/ {
 114 +       #address-cells = <1>;
 115 +       #size-cells = <1>;
 116 +
 117 +       memory {
 118 +               reg = <0x40000000 0x40000000>;
 119 +       };
 120 +
 121 +       reserved-memory {
 122 +               #address-cells = <1>;
 123 +               #size-cells = <1>;
 124 +               ranges;
 125 +
 126 +               /* global autoconfigured region for contiguous allocations */
 127 +               linux,cma {
 128 +                       compatible = "shared-dma-pool";
 129 +                       reusable;
 130 +                       size = <0x4000000>;
 131 +                       alignment = <0x2000>;
 132 +                       linux,cma-default;
 133 +               };
 134 +
 135 +               display_reserved: framebuffer@78000000 {
 136 +                       reg = <0x78000000 0x800000>;
 137 +               };
 138 +
 139 +               multimedia_reserved: multimedia@77000000 {
 140 +                       compatible = "acme,multimedia-memory";
 141 +                       reg = <0x77000000 0x4000000>;
 142 +               };
 143 +       };
 144 +
 145 +       /* ... */
 146 +
 147 +       fb0: video@12300000 {
 148 +               memory-region = <&display_reserved>;
 149 +               /* ... */
 150 +       };
 151 +
 152 +       scaler: scaler@12500000 {
 153 +               memory-region = <&multimedia_reserved>;
 154 +               /* ... */
 155 +       };
 156 +
 157 +       codec: codec@12600000 {
 158 +               memory-region = <&multimedia_reserved>;
 159 +               /* ... */
 160 +       };
 161 +};
 162 --
 163 1.7.10.4
 164