Add documentation for the uma_carveout_options and uma_carveout
attributes in sysfs

Signed-off-by: Yo-Jung Leo Lin (AMD) <Leo.Lin@amd.com>
---
 Documentation/gpu/amdgpu/driver-misc.rst     | 26 ++++++++++++++++++++++++++
 drivers/gpu/drm/amd/amdgpu/amdgpu_atombios.c | 17 +++++++++++++++++
 2 files changed, 43 insertions(+)

diff --git a/Documentation/gpu/amdgpu/driver-misc.rst b/Documentation/gpu/amdgpu/driver-misc.rst
index 25b0c857816e..5a71fa9c6782 100644
--- a/Documentation/gpu/amdgpu/driver-misc.rst
+++ b/Documentation/gpu/amdgpu/driver-misc.rst
@@ -128,3 +128,29 @@ smartshift_bias
 
 .. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c
    :doc: smartshift_bias
+
+UMA Carveout
+============
+
+Some versions of Atom ROM expose available options for the VRAM carveout sizes,
+and allow changes to the carveout size via the ATCS function code 0xA on supported
+BIOS implementation.
+
+For those platforms, users can use the following file to set the carveout size,
+in a way similar to what Windows users can do in the "Tuning" tab in AMD
+Adrenalin.
+
+Note that for BIOS implementations that don't support this, these files will not
+get created at all.
+
+uma_carveout_options
+--------------------
+
+.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_atombios.c
+   :doc: uma_carveout_options
+
+uma_carveout
+--------------------
+
+.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_atombios.c
+   :doc: uma_carveout
diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_atombios.c b/drivers/gpu/drm/amd/amdgpu/amdgpu_atombios.c
index 1ebfd925b761..e9f71888ce57 100644
--- a/drivers/gpu/drm/amd/amdgpu/amdgpu_atombios.c
+++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_atombios.c
@@ -1855,6 +1855,17 @@ const struct attribute_group amdgpu_vbios_version_attr_group = {
 	.is_visible = amdgpu_vbios_version_attrs_is_visible,
 };
 
+/**
+ * DOC: uma_carveout
+ *
+ * This file is both readable and writable. When read, it shows the
+ * index of the current setting. Writing a valid index to this file
+ * allows users to change the UMA carveout size to the selected option
+ * on the next boot.
+ *
+ * The available options and their corresponding indices can be read
+ * from the uma_carveout_options file.
+ */
 static ssize_t uma_carveout_show(struct device *dev,
 				 struct device_attribute *attr,
 				 char *buf)
@@ -1904,6 +1915,12 @@ static ssize_t uma_carveout_store(struct device *dev,
 }
 static DEVICE_ATTR_RW(uma_carveout);
 
+/**
+ * DOC: uma_carveout_options
+ *
+ * This is a read-only file that lists all available UMA allocation
+ * options and their corresponding indices.
+ */
 static ssize_t uma_carveout_options_show(struct device *dev,
 					 struct device_attribute *attr,
 					 char *buf)

-- 
2.43.0

On 11/2/25 11:51 PM, Yo-Jung Leo Lin (AMD) wrote:
> Add documentation for the uma_carveout_options and uma_carveout
> attributes in sysfs
> 
> Signed-off-by: Yo-Jung Leo Lin (AMD) <Leo.Lin@amd.com>
> ---
>  Documentation/gpu/amdgpu/driver-misc.rst     | 26 ++++++++++++++++++++++++++
>  drivers/gpu/drm/amd/amdgpu/amdgpu_atombios.c | 17 +++++++++++++++++
>  2 files changed, 43 insertions(+)
> 
> diff --git a/Documentation/gpu/amdgpu/driver-misc.rst b/Documentation/gpu/amdgpu/driver-misc.rst
> index 25b0c857816e..5a71fa9c6782 100644
> --- a/Documentation/gpu/amdgpu/driver-misc.rst
> +++ b/Documentation/gpu/amdgpu/driver-misc.rst
> @@ -128,3 +128,29 @@ smartshift_bias
>  
>  .. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c
>     :doc: smartshift_bias
> +
> +UMA Carveout
> +============
> +
> +Some versions of Atom ROM expose available options for the VRAM carveout sizes,
> +and allow changes to the carveout size via the ATCS function code 0xA on supported
> +BIOS implementation.

        implementations.

> +
> +For those platforms, users can use the following file to set the carveout size,
> +in a way similar to what Windows users can do in the "Tuning" tab in AMD
> +Adrenalin.
> +
> +Note that for BIOS implementations that don't support this, these files will not
> +get created at all.

   be created at all.
or
   exist.
or
   be present.

> +
> +uma_carveout_options
> +--------------------
> +
> +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_atombios.c
> +   :doc: uma_carveout_options
> +
> +uma_carveout
> +--------------------
> +
> +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_atombios.c
> +   :doc: uma_carveout
> diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_atombios.c b/drivers/gpu/drm/amd/amdgpu/amdgpu_atombios.c
> index 1ebfd925b761..e9f71888ce57 100644
> --- a/drivers/gpu/drm/amd/amdgpu/amdgpu_atombios.c
> +++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_atombios.c
> @@ -1855,6 +1855,17 @@ const struct attribute_group amdgpu_vbios_version_attr_group = {
>  	.is_visible = amdgpu_vbios_version_attrs_is_visible,
>  };
>  
> +/**
> + * DOC: uma_carveout
> + *
> + * This file is both readable and writable. When read, it shows the
> + * index of the current setting. Writing a valid index to this file
> + * allows users to change the UMA carveout size to the selected option
> + * on the next boot.
> + *
> + * The available options and their corresponding indices can be read
> + * from the uma_carveout_options file.
> + */
>  static ssize_t uma_carveout_show(struct device *dev,
>  				 struct device_attribute *attr,
>  				 char *buf)
> @@ -1904,6 +1915,12 @@ static ssize_t uma_carveout_store(struct device *dev,
>  }
>  static DEVICE_ATTR_RW(uma_carveout);
>  
> +/**
> + * DOC: uma_carveout_options
> + *
> + * This is a read-only file that lists all available UMA allocation
> + * options and their corresponding indices.
> + */
>  static ssize_t uma_carveout_options_show(struct device *dev,
>  					 struct device_attribute *attr,
>  					 char *buf)
> 
Some examples like Mario mentioned would be nice.
-- 
~Randy

On 11/3/2025 1:51 AM, Yo-Jung Leo Lin (AMD) wrote:
> Add documentation for the uma_carveout_options and uma_carveout
> attributes in sysfs
> 
> Signed-off-by: Yo-Jung Leo Lin (AMD) <Leo.Lin@amd.com>
> ---
>   Documentation/gpu/amdgpu/driver-misc.rst     | 26 ++++++++++++++++++++++++++
>   drivers/gpu/drm/amd/amdgpu/amdgpu_atombios.c | 17 +++++++++++++++++
>   2 files changed, 43 insertions(+)
> 
> diff --git a/Documentation/gpu/amdgpu/driver-misc.rst b/Documentation/gpu/amdgpu/driver-misc.rst
> index 25b0c857816e..5a71fa9c6782 100644
> --- a/Documentation/gpu/amdgpu/driver-misc.rst
> +++ b/Documentation/gpu/amdgpu/driver-misc.rst
> @@ -128,3 +128,29 @@ smartshift_bias
>   
>   .. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c
>      :doc: smartshift_bias
> +
> +UMA Carveout
> +============
> +
> +Some versions of Atom ROM expose available options for the VRAM carveout sizes,
> +and allow changes to the carveout size via the ATCS function code 0xA on supported
> +BIOS implementation.
> +
> +For those platforms, users can use the following file to set the carveout size,
> +in a way similar to what Windows users can do in the "Tuning" tab in AMD
> +Adrenalin.
> +
> +Note that for BIOS implementations that don't support this, these files will not
> +get created at all.
> +
> +uma_carveout_options
> +--------------------
> +
> +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_atombios.c
> +   :doc: uma_carveout_options
> +
> +uma_carveout
> +--------------------
> +
> +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_atombios.c
> +   :doc: uma_carveout

How do you feel about adding some sample output from a test system for 
both files?  This might make it easier for userspace to implement 
parsing it.

> diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_atombios.c b/drivers/gpu/drm/amd/amdgpu/amdgpu_atombios.c
> index 1ebfd925b761..e9f71888ce57 100644
> --- a/drivers/gpu/drm/amd/amdgpu/amdgpu_atombios.c
> +++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_atombios.c
> @@ -1855,6 +1855,17 @@ const struct attribute_group amdgpu_vbios_version_attr_group = {
>   	.is_visible = amdgpu_vbios_version_attrs_is_visible,
>   };
>   
> +/**
> + * DOC: uma_carveout
> + *
> + * This file is both readable and writable. When read, it shows the
> + * index of the current setting. Writing a valid index to this file
> + * allows users to change the UMA carveout size to the selected option
> + * on the next boot.
> + *
> + * The available options and their corresponding indices can be read
> + * from the uma_carveout_options file.
> + */
>   static ssize_t uma_carveout_show(struct device *dev,
>   				 struct device_attribute *attr,
>   				 char *buf)
> @@ -1904,6 +1915,12 @@ static ssize_t uma_carveout_store(struct device *dev,
>   }
>   static DEVICE_ATTR_RW(uma_carveout);
>   
> +/**
> + * DOC: uma_carveout_options
> + *
> + * This is a read-only file that lists all available UMA allocation
> + * options and their corresponding indices.
> + */
>   static ssize_t uma_carveout_options_show(struct device *dev,
>   					 struct device_attribute *attr,
>   					 char *buf)
>