[PATCH] drm/gpusvm: use literal blocks for the indented code examples

[PATCH] drm/gpusvm: use literal blocks for the indented code examples

[Honglei Huang]

kernel-doc only recognises ".. code-block::" at column 0 of the comment.
The two examples under "- Pages:" are indented inside a list item, so
kernel-doc treated them as prose and rewrote "&drange->inline_pages",
"&range->notifier" and "&ctx" into :c:type: cross references. The
injected backticks then make Sphinx fail to lex the block as C.

Use a plain "::" literal block, which kernel-doc accepts at any
indentation. Syntax colouring is lost, but keeping ".. code-block:: c"
would mean lifting both examples out of the list item.

Fixes: cc2a6cbd6823 ("drm/gpusvm: let drm_gpusvm_get_pages() map an array of pages")
Reported-by: kernel test robot <lkp@intel.com>
Closes: https://lore.kernel.org/oe-kbuild-all/202610100125.d4Kk60aL-lkp@intel.com/
Signed-off-by: Honglei Huang <honghuan@amd.com>
---
 drivers/gpu/drm/drm_gpusvm.c | 8 ++------
 1 file changed, 2 insertions(+), 6 deletions(-)

diff --git a/drivers/gpu/drm/drm_gpusvm.c b/drivers/gpu/drm/drm_gpusvm.c
index b6c9d3a07dc..7b166bcb0d1 100644
--- a/drivers/gpu/drm/drm_gpusvm.c
+++ b/drivers/gpu/drm/drm_gpusvm.c
@@ -67,9 +67,7 @@
  *	sit in contiguous memory so a single drm_gpusvm_range_set_unmapped()
  *	can mark them all. A driver can keep one instance inline for the single
  *	device case and switch to a heap array only when more devices join,
- *	e.g.:
- *
- *	.. code-block:: c
+ *	e.g.::
  *
  *		struct driver_range {
  *			struct drm_gpusvm_range base;
@@ -99,9 +97,7 @@
  *	The 1:1 examples below pass @num_pages == 1 and &drange->pages. In the
  *	N:1 case the driver instead passes the whole array and its count, so a
  *	single call faults the CPU range once and DMA maps it for every owning
- *	drm_device, e.g.:
- *
- *	.. code-block:: c
+ *	drm_device, e.g.::
  *
  *		// GPU fault handler: one fault, one DMA mapping per device
  *		err = drm_gpusvm_get_pages(gpusvm, driver_pages(drange),

base-commit: 34081b8bbbbfb9adbe04f764f718de04df23a84a
-- 
2.34.1

Re: [PATCH] drm/gpusvm: use literal blocks for the indented code examples

[Matthew Brost]

On Wed, Oct 14, 2026 at 02:51:53PM +0800, Honglei Huang wrote:
> kernel-doc only recognises ".. code-block::" at column 0 of the comment.
> The two examples under "- Pages:" are indented inside a list item, so
> kernel-doc treated them as prose and rewrote "&drange->inline_pages",
> "&range->notifier" and "&ctx" into :c:type: cross references. The
> injected backticks then make Sphinx fail to lex the block as C.
> 
> Use a plain "::" literal block, which kernel-doc accepts at any
> indentation. Syntax colouring is lost, but keeping ".. code-block:: c"
> would mean lifting both examples out of the list item.
> 
> Fixes: cc2a6cbd6823 ("drm/gpusvm: let drm_gpusvm_get_pages() map an array of pages")

Hmm, I why Intel's CI didn't catch this - we typically build kernel doc
but perhaps we are building gpusvm. Let me check on this.

Anyways thanks for the fix:

Reviewed-by: Matthew Brost <matthew.brost@intel.com>

> Reported-by: kernel test robot <lkp@intel.com>
> Closes: https://lore.kernel.org/oe-kbuild-all/202610100125.d4Kk60aL-lkp@intel.com/
> Signed-off-by: Honglei Huang <honghuan@amd.com>
> ---
>  drivers/gpu/drm/drm_gpusvm.c | 8 ++------
>  1 file changed, 2 insertions(+), 6 deletions(-)
> 
> diff --git a/drivers/gpu/drm/drm_gpusvm.c b/drivers/gpu/drm/drm_gpusvm.c
> index b6c9d3a07dc..7b166bcb0d1 100644
> --- a/drivers/gpu/drm/drm_gpusvm.c
> +++ b/drivers/gpu/drm/drm_gpusvm.c
> @@ -67,9 +67,7 @@
>   *	sit in contiguous memory so a single drm_gpusvm_range_set_unmapped()
>   *	can mark them all. A driver can keep one instance inline for the single
>   *	device case and switch to a heap array only when more devices join,
> - *	e.g.:
> - *
> - *	.. code-block:: c
> + *	e.g.::
>   *
>   *		struct driver_range {
>   *			struct drm_gpusvm_range base;
> @@ -99,9 +97,7 @@
>   *	The 1:1 examples below pass @num_pages == 1 and &drange->pages. In the
>   *	N:1 case the driver instead passes the whole array and its count, so a
>   *	single call faults the CPU range once and DMA maps it for every owning
> - *	drm_device, e.g.:
> - *
> - *	.. code-block:: c
> + *	drm_device, e.g.::
>   *
>   *		// GPU fault handler: one fault, one DMA mapping per device
>   *		err = drm_gpusvm_get_pages(gpusvm, driver_pages(drange),
> 
> base-commit: 34081b8bbbbfb9adbe04f764f718de04df23a84a
> -- 
> 2.34.1
>