doc/devicetree: Persistent memory region bindings

Add device-tree binding documentation for the nvdimm region driver.

Cc: devicetree@vger.kernel.org
Signed-off-by: Oliver O'Halloran <oohall@gmail.com>
Acked-by: Michael Ellerman <mpe@ellerman.id.au>
Signed-off-by: Dan Williams <dan.j.williams@intel.com>

diff --git a/Documentation/devicetree/bindings/pmem/pmem-region.txt b/Documentation/devicetree/bindings/pmem/pmem-region.txt
new file mode 100644 (file)
index 0000000..5cfa4f0
--- /dev/null
+++ b/Documentation/devicetree/bindings/pmem/pmem-region.txt
@@ -0,0 +1,65 @@
+Device-tree bindings for persistent memory regions
+-----------------------------------------------------
+
+Persistent memory refers to a class of memory devices that are:
+
+       a) Usable as main system memory (i.e. cacheable), and
+       b) Retain their contents across power failure.
+
+Given b) it is best to think of persistent memory as a kind of memory mapped
+storage device. To ensure data integrity the operating system needs to manage
+persistent regions separately to the normal memory pool. To aid with that this
+binding provides a standardised interface for discovering where persistent
+memory regions exist inside the physical address space.
+
+Bindings for the region nodes:
+-----------------------------
+
+Required properties:
+       - compatible = "pmem-region"
+
+       - reg = <base, size>;
+               The reg property should specificy an address range that is
+               translatable to a system physical address range. This address
+               range should be mappable as normal system memory would be
+               (i.e cacheable).
+
+               If the reg property contains multiple address ranges
+               each address range will be treated as though it was specified
+               in a separate device node. Having multiple address ranges in a
+               node implies no special relationship between the two ranges.
+
+Optional properties:
+       - Any relevant NUMA assocativity properties for the target platform.
+
+       - volatile; This property indicates that this region is actually
+         backed by non-persistent memory. This lets the OS know that it
+         may skip the cache flushes required to ensure data is made
+         persistent after a write.
+
+         If this property is absent then the OS must assume that the region
+         is backed by non-volatile memory.
+
+Examples:
+--------------------
+
+       /*
+        * This node specifies one 4KB region spanning from
+        * 0x5000 to 0x5fff that is backed by non-volatile memory.
+        */
+       pmem@5000 {
+               compatible = "pmem-region";
+               reg = <0x00005000 0x00001000>;
+       };
+
+       /*
+        * This node specifies two 4KB regions that are backed by
+        * volatile (normal) memory.
+        */
+       pmem@6000 {
+               compatible = "pmem-region";
+               reg = < 0x00006000 0x00001000
+                       0x00008000 0x00001000 >;
+               volatile;
+       };
+

diff --git a/MAINTAINERS b/MAINTAINERS
index 06230c06a071303f212f9f9ae81a248d358b6b19..662a71da42c784d8e59de52253d84354bfd0629e 100644 (file)
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -8041,6 +8041,7 @@ L:        linux-nvdimm@lists.01.org
 Q:     https://patchwork.kernel.org/project/linux-nvdimm/list/
 S:     Supported
 F:     drivers/nvdimm/of_pmem.c
+F:     Documentation/devicetree/bindings/pmem/pmem-region.txt
 
 LIBNVDIMM: NON-VOLATILE MEMORY DEVICE SUBSYSTEM
 M:     Dan Williams <dan.j.williams@intel.com>