dt-bindings: Add documentation for the mem-offline driver

%YAML 1.2

---

$id: http://devicetree.org/schemas/bindings/arm/msm/memory-offline.yaml#

$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Memory Offline Driver binding

maintainers:

  - Isaac J. Manjarres <isaacm@quicinc.com>

description: |+

  The memory offline driver supports the onlining and offlining of DDR memory.

  Through the mem-offline node you can configure how much of the DDR will

  support being offlined/onlined.

  By default all memory is onlined when the device has booted up.

  Note that offlinable memory can only support movable memory allocations so

  designating too much memory as offlinable can result in system performance and

  stability issues.

  For more information on how to request the onlining and offlining of memory

  see the memory hotplug documentation (Documentation/memory-hotplug.txt).

properties:

  compatible:

    items:

      - const: qcom,mem-offline

  granule:

    $ref: '/schemas/types.yaml#/definitions/uint32'

    maxItems: 1

    description:

      The minimum granule size in mega-bytes for memory onlining/offlining.

  offline-sizes:

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

    minItems: 1

    description:

      Array of offlinable memory region sizes to apply to targets based on

      their DDR size.

      Each entry in the array is a pair of sizes, where the first size in the

      pair is the minimum amount of DDR required in the system in bytes, and

      the second item in the pair is the size of the offlinable region in

      bytes which will be applied to the system.

      The offlinable memory region size from the entry where the minimum amount

      of DDR required in the system is closest, but not greater, than the

      amount of DDR in the system will be applied.

      If there are no entries with a minimum amount of DDR required that is less

      than the amount of DDR in the system then no offlinable region will be

      created.

      For example, in the following configuration:

              offline-sizes = <0x1 0x40000000 0x0 0x40000000>,

                              <0x1 0xc0000000 0x0 0x80000000>;

      On a 4GB target no offlinable region will be created.

      On a 6GB target a 1GB offlinable region will be created.

      On an 8GB target a 2GB offlinable region will be created.

      On a 12GB target a 2GB offlinable region will be created.

  mboxes:

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

    maxItems: 1

    description:

      Reference to the mailbox used by the driver to make requests to

      online/offline memory.

required:

  - compatible

  - offline-sizes

  - mboxes

examples:

  - |

    mem-offline {

        compatible = "qcom,mem-offline";

        granule = <512>;

        offline-sizes = <0x1 0x40000000 0x0 0x40000000>,

                        <0x1 0xc0000000 0x0 0x80000000>;

        mboxes = <&qmp_aop 0>;

    };