Re: [PATCH v3] dt-bindings: pmem: Convert binding to YAML

[Rob Herring <robh@kernel.org>]

On Fri, Jun 06, 2025 at 11:11:17AM -0700, Drew Fustini wrote:
> Convert the PMEM device tree binding from text to YAML. This will allow
> device trees with pmem-region nodes to pass dtbs_check.
> 
> Acked-by: Conor Dooley <conor.dooley@microchip.com>
> Acked-by: Oliver O'Halloran <oohall@gmail.com>
> Signed-off-by: Drew Fustini <drew@pdp7.com>
> ---
> Dan/Dave/Vishal: does it make sense for this pmem binding patch to go
> through the nvdimm tree?
> 
> Note: checkpatch complains about "DT binding docs and includes should
> be a separate patch". Rob told me that this a false positive. I'm hoping
> that I can fix the false positive at some point if I can remember enough
> perl :)
> 
> v3:
>  - no functional changes
>  - add Oliver's Acked-by
>  - bump version to avoid duplicate message-id mess in v2 and v2 resend:
>    https://lore.kernel.org/all/20250520021440.24324-1-drew@pdp7.com/
> 
> v2 resend:
>  - actually put v2 in the Subject
>  - add Conor's Acked-by
>    - https://lore.kernel.org/all/20250520-refract-fling-d064e11ddbdf@spud/
> 
> v2:
>  - remove the txt file to make the conversion complete
>  - https://lore.kernel.org/all/20250520021440.24324-1-drew@pdp7.com/
> 
> v1:
>  - https://lore.kernel.org/all/20250518035539.7961-1-drew@pdp7.com/
> 
>  .../devicetree/bindings/pmem/pmem-region.txt  | 65 -------------------
>  .../devicetree/bindings/pmem/pmem-region.yaml | 49 ++++++++++++++
>  MAINTAINERS                                   |  2 +-
>  3 files changed, 50 insertions(+), 66 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/pmem/pmem-region.txt
>  create mode 100644 Documentation/devicetree/bindings/pmem/pmem-region.yaml
> 
> diff --git a/Documentation/devicetree/bindings/pmem/pmem-region.txt b/Documentation/devicetree/bindings/pmem/pmem-region.txt
> deleted file mode 100644
> index cd79975e85ec..000000000000
> --- a/Documentation/devicetree/bindings/pmem/pmem-region.txt
> +++ /dev/null
> @@ -1,65 +0,0 @@
> -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 specify 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 associativity 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/Documentation/devicetree/bindings/pmem/pmem-region.yaml b/Documentation/devicetree/bindings/pmem/pmem-region.yaml
> new file mode 100644
> index 000000000000..a4aa4ce3318b
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/pmem/pmem-region.yaml
> @@ -0,0 +1,49 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/pmem-region.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +maintainers:
> +  - Bjorn Helgaas <bhelgaas@google.com>

Drop Bjorn. He only did typo fixes on this.

> +  - Oliver O'Halloran <oohall@gmail.com>
> +
> +title: Persistent Memory Regions
> +
> +description: |
> +  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.
> +
> +properties:
> +  compatible:
> +    const: pmem-region
> +
> +  reg:
> +    maxItems: 1
> +
> +  volatile:
> +    description: |

Don't need '|' here.

> +      Indicates the region is volatile (non-persistent) and the OS can skip
> +      cache flushes for writes
> +    type: boolean
> +
> +required:
> +  - compatible
> +  - reg
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    pmem@5000 {
> +        compatible = "pmem-region";
> +        reg = <0x00005000 0x00001000>;
> +    };
> diff --git a/MAINTAINERS b/MAINTAINERS
> index ee93363ec2cb..eba2b81ec568 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -13798,7 +13798,7 @@ M:	Oliver O'Halloran <oohall@gmail.com>
>  L:	nvdimm@lists.linux.dev
>  S:	Supported
>  Q:	https://patchwork.kernel.org/project/linux-nvdimm/list/
> -F:	Documentation/devicetree/bindings/pmem/pmem-region.txt
> +F:	Documentation/devicetree/bindings/pmem/pmem-region.yaml
>  F:	drivers/nvdimm/of_pmem.c
>  
>  LIBNVDIMM: NON-VOLATILE MEMORY DEVICE SUBSYSTEM
> -- 
> 2.43.0
>