[PATCH] drm/amdgpu: update documentation for amdgpu_drv.c

[Michel Dänzer]

On 2018-06-28 08:31 PM, Alex Deucher wrote:
> On Thu, Jun 28, 2018 at 2:02 PM, Jiang, Sonny <Sonny.Jiang at amd.com> wrote:
>> Hi Alex,
>>
>>
>> What's your opinion about Michel's suggestion?
> 
> You should definitely update amdgpu.rst to include the new
> documentation section.  As for whether to have separate sections or
> one big section for the parameters, I could go either way.  If we have
> one big section, people will likely forget to update it when they add
> a new parameter.  On the other hand, if we have separate sections for
> each option, people will likely forget to update amdgpu.rst to add the
> new parameter.

I think it's easier to catch the latter in review, and while it is
slightly annoying needing an entry for each parameter in amdgpu.rst,
maybe it can serve as incentive against needlessly adding new module
parameters. :)

Right now there's a third possibility, see the diff below as an example. By
referencing amdgpu_drv.c without a :doc: or :internal: stanza, each DOC
comment is picked up automatically, with the text after DOC as the
heading. However, this will break down if we want to add general DOC
comments or function comments in amdgpu_drv.c.


P.S. I cherry-picked some upstream fixes from the Documentation tree to
amd-staging-drm-next, make htmldocs works again.


diff --git a/Documentation/gpu/amdgpu.rst b/Documentation/gpu/amdgpu.rst
index 765c2a32938f..a740e491dfcc 100644
--- a/Documentation/gpu/amdgpu.rst
+++ b/Documentation/gpu/amdgpu.rst
@@ -5,6 +5,13 @@
 The drm/amdgpu driver supports all AMD Radeon GPUs based on the Graphics Core
 Next (GCN) architecture.

+Module Parameters
+=================
+
+The amdgpu driver supports the following module parameters:
+
+.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_drv.c
+
 Core Driver Infrastructure
 ==========================

diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_drv.c b/drivers/gpu/drm/amd/amdgpu/amdgpu_drv.c
index dcdc97d6dc44..ff0299879601 100644
--- a/drivers/gpu/drm/amd/amdgpu/amdgpu_drv.c
+++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_drv.c
@@ -1,10 +1,3 @@
-/**
- * \file amdgpu_drv.c
- * AMD Amdgpu driver
- *
- * \author Gareth Hughes <gareth at valinux.com>
- */
-
 /*
  * Copyright 2000 VA Linux Systems, Inc., Sunnyvale, California.
  * All Rights Reserved.
@@ -136,6 +129,11 @@ int amdgpu_gpu_recovery = -1; /* auto */
 int amdgpu_emu_mode = 0;
 uint amdgpu_smu_memory_pool_size = 0;

+/**
+ * DOC: vramlimit
+ *
+ * Restrict VRAM for testing, in megabytes
+ */
 MODULE_PARM_DESC(vramlimit, "Restrict VRAM for testing, in megabytes");
 module_param_named(vramlimit, amdgpu_vram_limit, int, 0600);


-- 
Earthling Michel Dänzer               |               http://www.amd.com
Libre software enthusiast             |             Mesa and X developer