Add documentation for the Xen hypervisor sysctl controls in
/proc/sys/xen/balloon/.

Documents the hotplug_unpopulated tunable (available when
CONFIG_XEN_BALLOON_MEMORY_HOTPLUG is enabled) which controls
whether unpopulated memory regions are automatically hotplugged
when the Xen balloon driver needs to reclaim memory.

The documentation is based on source code analysis of
drivers/xen/balloon.c.

Signed-off-by: Shubham Chakraborty <chakrabortyshubham66@gmail.com>
---
 Documentation/admin-guide/sysctl/index.rst |  3 +-
 Documentation/admin-guide/sysctl/xen.rst   | 33 ++++++++++++++++++++++
 2 files changed, 35 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/admin-guide/sysctl/xen.rst

diff --git a/Documentation/admin-guide/sysctl/index.rst b/Documentation/admin-guide/sysctl/index.rst
index 4dd2c9b5d752..aae68373902f 100644
--- a/Documentation/admin-guide/sysctl/index.rst
+++ b/Documentation/admin-guide/sysctl/index.rst
@@ -84,7 +84,7 @@ sunrpc/		SUN Remote Procedure Call (NFS)
 user/		Per user namespace limits
 vm/		memory management tuning
 		buffer and cache management
-xen/		<undocumented>
+xen/		Xen hypervisor controls
 =============== ===============================================================
 
 These are the subdirs I have on my system or have been discovered by
@@ -102,3 +102,4 @@ it :-)
    sunrpc
    user
    vm
+   xen
diff --git a/Documentation/admin-guide/sysctl/xen.rst b/Documentation/admin-guide/sysctl/xen.rst
new file mode 100644
index 000000000000..957febd6bab9
--- /dev/null
+++ b/Documentation/admin-guide/sysctl/xen.rst
@@ -0,0 +1,33 @@
+===============
+/proc/sys/xen/
+===============
+
+These files show up in ``/proc/sys/xen/``, depending on the
+kernel configuration:
+
+.. contents:: :local:
+
+balloon/hotplug_unpopulated
+===========================
+
+This flag controls whether unpopulated memory ranges are automatically
+hotplugged as system RAM.
+
+- ``0``: Unpopulated ranges are not hotplugged (default).
+- ``1``: Unpopulated ranges are automatically hotplugged.
+
+When enabled, the Xen balloon driver will add memory regions that are
+marked as unpopulated in the Xen memory map to the system as usable RAM.
+This allows for dynamic memory expansion in Xen guest domains.
+
+This option is only available when the kernel is built with
+``CONFIG_XEN_BALLOON_MEMORY_HOTPLUG`` enabled.
+
+Copyright (c) 2026, Shubham Chakraborty <chakrabortyshubham66@gmail.com>
+
+For general info and legal blurb, please look in
+Documentation/admin-guide/sysctl/index.rst.
+
+.. See scripts/check-sysctl-docs to keep this up to date:
+.. scripts/check-sysctl-docs -vtable="xen" \
+..         $(git grep -l register_sysctl_)
-- 
2.39.5

On 04.03.26 15:16, Shubham Chakraborty wrote:
> Add documentation for the Xen hypervisor sysctl controls in
> /proc/sys/xen/balloon/.
> 
> Documents the hotplug_unpopulated tunable (available when
> CONFIG_XEN_BALLOON_MEMORY_HOTPLUG is enabled) which controls
> whether unpopulated memory regions are automatically hotplugged
> when the Xen balloon driver needs to reclaim memory.
> 
> The documentation is based on source code analysis of
> drivers/xen/balloon.c.
> 
> Signed-off-by: Shubham Chakraborty <chakrabortyshubham66@gmail.com>
> ---
>   Documentation/admin-guide/sysctl/index.rst |  3 +-
>   Documentation/admin-guide/sysctl/xen.rst   | 33 ++++++++++++++++++++++
>   2 files changed, 35 insertions(+), 1 deletion(-)
>   create mode 100644 Documentation/admin-guide/sysctl/xen.rst
> 
> diff --git a/Documentation/admin-guide/sysctl/index.rst b/Documentation/admin-guide/sysctl/index.rst
> index 4dd2c9b5d752..aae68373902f 100644
> --- a/Documentation/admin-guide/sysctl/index.rst
> +++ b/Documentation/admin-guide/sysctl/index.rst
> @@ -84,7 +84,7 @@ sunrpc/		SUN Remote Procedure Call (NFS)
>   user/		Per user namespace limits
>   vm/		memory management tuning
>   		buffer and cache management
> -xen/		<undocumented>
> +xen/		Xen hypervisor controls
>   =============== ===============================================================
>   
>   These are the subdirs I have on my system or have been discovered by
> @@ -102,3 +102,4 @@ it :-)

I think you edited the patch file, but this wasn't improving it. :-)

Please resend without additions making it malformed.

>      sunrpc
>      user
>      vm
> +   xen
> diff --git a/Documentation/admin-guide/sysctl/xen.rst b/Documentation/admin-guide/sysctl/xen.rst
> new file mode 100644
> index 000000000000..957febd6bab9
> --- /dev/null
> +++ b/Documentation/admin-guide/sysctl/xen.rst
> @@ -0,0 +1,33 @@
> +===============
> +/proc/sys/xen/
> +===============
> +
> +These files show up in ``/proc/sys/xen/``, depending on the
> +kernel configuration:
> +
> +.. contents:: :local:
> +
> +balloon/hotplug_unpopulated
> +===========================
> +
> +This flag controls whether unpopulated memory ranges are automatically
> +hotplugged as system RAM.
> +
> +- ``0``: Unpopulated ranges are not hotplugged (default).
> +- ``1``: Unpopulated ranges are automatically hotplugged.
> +
> +When enabled, the Xen balloon driver will add memory regions that are
> +marked as unpopulated in the Xen memory map to the system as usable RAM.
> +This allows for dynamic memory expansion in Xen guest domains.
> +
> +This option is only available when the kernel is built with
> +``CONFIG_XEN_BALLOON_MEMORY_HOTPLUG`` enabled.

The stuff below doesn't seem appropriate here, too. I think it can be
either dropped, or should move up in the file.

> +
> +Copyright (c) 2026, Shubham Chakraborty <chakrabortyshubham66@gmail.com>
> +
> +For general info and legal blurb, please look in
> +Documentation/admin-guide/sysctl/index.rst.
> +
> +.. See scripts/check-sysctl-docs to keep this up to date:
> +.. scripts/check-sysctl-docs -vtable="xen" \
> +..         $(git grep -l register_sysctl_)


Juergen