Add Documentation for linux,usable-memory

Signed-off-by: Abhishek Tiwari <abhitiwari@linux.microsoft.com>
---
 .../bindings/linux,usable-memory.txt          | 32 +++++++++++++++++++
 1 file changed, 32 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/linux,usable-memory.txt

diff --git a/Documentation/devicetree/bindings/linux,usable-memory.txt b/Documentation/devicetree/bindings/linux,usable-memory.txt
new file mode 100644
index 000000000000..167054d2e9a2
--- /dev/null
+++ b/Documentation/devicetree/bindings/linux,usable-memory.txt
@@ -0,0 +1,32 @@
+linux,usable-memory
+===================
+
+Description
+-----------
+The ``linux,usable-memory`` property can be used to restrict usable memory
+region. This property holds a base address and size, Memory outside of this
+range is not accessible by the kernel. This property is particularly useful
+in specialized hardware platforms where certain memory regions must be
+reserved for specific use.
+
+Common use cases include:
+- Allocating ``ramoops`` region
+- Reserving memory for hardware-specific needs
+- Fake Protecting persistent memory (PMEM)
+
+Valid memory may be sparse within the specified range.
+An example device tree configuration is shown below:
+
+.. code-block:: dts
+/ {
+	&memory {
+		linux,usable-memory = <
+			0x00000000 0x80000000 0x00000000 0x1BA00000
+			0x00000000 0xA1000000 0x00000000 0x2AC00000
+		>;
+	};
+};
+
+While this property does not represent a real hardware, the address
+and the size are expressed in #address-cells and #size-cells,
+respectively, of the root node.
-- 
2.48.1

On Thu, Mar 13, 2025 at 9:03 AM Abhishek Tiwari
<abhitiwari@linux.microsoft.com> wrote:
>
> Add Documentation for linux,usable-memory
>
> Signed-off-by: Abhishek Tiwari <abhitiwari@linux.microsoft.com>
> ---
>  .../bindings/linux,usable-memory.txt          | 32 +++++++++++++++++++
>  1 file changed, 32 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/linux,usable-memory.txt
>
> diff --git a/Documentation/devicetree/bindings/linux,usable-memory.txt b/Documentation/devicetree/bindings/linux,usable-memory.txt
> new file mode 100644
> index 000000000000..167054d2e9a2
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/linux,usable-memory.txt
> @@ -0,0 +1,32 @@
> +linux,usable-memory
> +===================

This belongs here:
https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/memory.yaml

> +
> +Description
> +-----------
> +The ``linux,usable-memory`` property can be used to restrict usable memory
> +region. This property holds a base address and size, Memory outside of this
> +range is not accessible by the kernel. This property is particularly useful
> +in specialized hardware platforms where certain memory regions must be
> +reserved for specific use.
> +
> +Common use cases include:
> +- Allocating ``ramoops`` region
> +- Reserving memory for hardware-specific needs
> +- Fake Protecting persistent memory (PMEM)

All these examples belong in /reserved-memory nodes, not
linux,usable-memory. Go see the ramoops binding for example.

This was really for the case where you already have 'reg' (in the
memory node), but need to limit memory while at the same time not
overwriting 'reg'. Basically, for kexec where you can keep booting
another kernel forever. If that's not your usecase, you shouldn't be
using this.

Rob

On Thu, Mar 13, 2025 at 01:57:30PM -0500, Rob Herring wrote:
> On Thu, Mar 13, 2025 at 9:03 AM Abhishek Tiwari
> <abhitiwari@linux.microsoft.com> wrote:
> >
> > Add Documentation for linux,usable-memory
> >
> > Signed-off-by: Abhishek Tiwari <abhitiwari@linux.microsoft.com>
> > ---
> >  .../bindings/linux,usable-memory.txt          | 32 +++++++++++++++++++
> >  1 file changed, 32 insertions(+)
> >  create mode 100644 Documentation/devicetree/bindings/linux,usable-memory.txt
> >
> > diff --git a/Documentation/devicetree/bindings/linux,usable-memory.txt b/Documentation/devicetree/bindings/linux,usable-memory.txt
> > new file mode 100644
> > index 000000000000..167054d2e9a2
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/linux,usable-memory.txt
> > @@ -0,0 +1,32 @@
> > +linux,usable-memory
> > +===================
> 
> This belongs here:
> https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/memory.yaml
> 
> > +
> > +Description
> > +-----------
> > +The ``linux,usable-memory`` property can be used to restrict usable memory
> > +region. This property holds a base address and size, Memory outside of this
> > +range is not accessible by the kernel. This property is particularly useful
> > +in specialized hardware platforms where certain memory regions must be
> > +reserved for specific use.
> > +
> > +Common use cases include:
> > +- Allocating ``ramoops`` region
> > +- Reserving memory for hardware-specific needs
> > +- Fake Protecting persistent memory (PMEM)
> 
> All these examples belong in /reserved-memory nodes, not
> linux,usable-memory. Go see the ramoops binding for example.
> 
> This was really for the case where you already have 'reg' (in the
> memory node), but need to limit memory while at the same time not
> overwriting 'reg'. Basically, for kexec where you can keep booting
> another kernel forever. If that's not your usecase, you shouldn't be
> using this.
> 
> Rob

Thank you for your suggestions and explanations. I will update 
the definition and examples accordingly, and submit a PR with 
the documentation for this property in the specified repository.

On 13/03/2025 15:02, Abhishek Tiwari wrote:
> Add Documentation for linux,usable-memory
> 
> Signed-off-by: Abhishek Tiwari <abhitiwari@linux.microsoft.com>
> ---
>  .../bindings/linux,usable-memory.txt          | 32 +++++++++++++++++++

No TXT bindings anymore.

But anyway, please explain why reserved memory and the standard memory
node are not sufficient for you. For example:


> +
> +Common use cases include:
> +- Allocating ``ramoops`` region

this is reserved memory.

> +- Reserving memory for hardware-specific needs

Same.

> +- Fake Protecting persistent memory (PMEM)

Same.


What's more, explain why linux,usable-memory-range is not good... or you
just send some old patch from downstream forks?

Best regards,
Krzysztof