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