* [Intel-gfx] [PATCH v6 44/80] docs: gpu: i915.rst: Fix several C duplication warnings
[not found] <cover.1602589096.git.mchehab+huawei@kernel.org>
@ 2020-10-13 11:53 ` Mauro Carvalho Chehab
2020-10-16 11:01 ` Joonas Lahtinen
2020-10-16 12:03 ` Lionel Landwerlin
0 siblings, 2 replies; 7+ messages in thread
From: Mauro Carvalho Chehab @ 2020-10-13 11:53 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Thomas Zimmermann, Jonathan Corbet, Mauro Carvalho Chehab,
dri-devel, linux-kernel, David Airlie, Maxime Ripard, intel-gfx
As reported by Sphinx:
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1147: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_oa_wait_unlocked'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1169: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_oa_poll_wait'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1189: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_oa_read'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2669: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_oa_stream_enable'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2734: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_oa_stream_disable'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2820: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_oa_stream_init'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3010: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_read'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3098: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_poll_locked'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3129: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_poll'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3152: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_enable_locked'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3181: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_disable_locked'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3273: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_ioctl'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3296: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_destroy_locked'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3321: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_release'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3379: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_open_ioctl_locked'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3534: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'read_properties_unlocked'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3717: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_open_ioctl'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3760: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_register'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3789: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_unregister'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4009: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_add_config_ioctl'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4162: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_remove_config_ioctl'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4260: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_init'.
./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4423: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
Declaration is 'i915_perf_fini'.
With Sphinx 3, C declarations can't be duplicated anymore,
so let's exclude those from the other internals found on
i915_perf.c file.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/gpu/i915.rst | 29 +++++++++++++++++++++++++----
1 file changed, 25 insertions(+), 4 deletions(-)
diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index 33cc6ddf8f64..cff1f154b473 100644
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -636,15 +636,36 @@ i915 Perf Observation Architecture Stream
.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
:functions: i915_oa_poll_wait
-All i915 Perf Internals
------------------------
+Other i915 Perf Internals
+-------------------------
-This section simply includes all currently documented i915 perf internals, in
-no particular order, but may include some more minor utilities or platform
+This section simply includes all other currently documented i915 perf internals,
+in no particular order, but may include some more minor utilities or platform
specific details than found in the more high-level sections.
.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
:internal:
+ :no-identifiers:
+ i915_perf_init
+ i915_perf_fini
+ i915_perf_register
+ i915_perf_unregister
+ i915_perf_open_ioctl
+ i915_perf_release
+ i915_perf_add_config_ioctl
+ i915_perf_remove_config_ioctl
+ read_properties_unlocked
+ i915_perf_open_ioctl_locked
+ i915_perf_destroy_locked
+ i915_perf_read i915_perf_ioctl
+ i915_perf_enable_locked
+ i915_perf_disable_locked
+ i915_perf_poll i915_perf_poll_locked
+ i915_oa_stream_init i915_oa_read
+ i915_oa_stream_enable
+ i915_oa_stream_disable
+ i915_oa_wait_unlocked
+ i915_oa_poll_wait
Style
=====
--
2.26.2
_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx
^ permalink raw reply related [flat|nested] 7+ messages in thread
* Re: [Intel-gfx] [PATCH v6 44/80] docs: gpu: i915.rst: Fix several C duplication warnings
2020-10-13 11:53 ` [Intel-gfx] [PATCH v6 44/80] docs: gpu: i915.rst: Fix several C duplication warnings Mauro Carvalho Chehab
@ 2020-10-16 11:01 ` Joonas Lahtinen
2020-10-16 11:37 ` Mauro Carvalho Chehab
2020-10-16 12:03 ` Lionel Landwerlin
1 sibling, 1 reply; 7+ messages in thread
From: Joonas Lahtinen @ 2020-10-16 11:01 UTC (permalink / raw)
To: Linux Doc Mailing List, Mauro Carvalho Chehab, Lionel Landwerlin
Cc: Thomas Zimmermann, Jonathan Corbet, Mauro Carvalho Chehab,
dri-devel, linux-kernel, David Airlie, Maxime Ripard, intel-gfx
+ Lionel
Can you please take a look at best resolving the below problem.
Maybe we should eliminate the duplicate declarations? Updating such
a list manually seems error prone to me.
Regards, Joonas
Quoting Mauro Carvalho Chehab (2020-10-13 14:53:59)
> As reported by Sphinx:
>
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1147: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_oa_wait_unlocked'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1169: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_oa_poll_wait'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1189: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_oa_read'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2669: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_oa_stream_enable'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2734: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_oa_stream_disable'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2820: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_oa_stream_init'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3010: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_perf_read'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3098: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_perf_poll_locked'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3129: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_perf_poll'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3152: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_perf_enable_locked'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3181: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_perf_disable_locked'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3273: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_perf_ioctl'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3296: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_perf_destroy_locked'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3321: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_perf_release'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3379: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_perf_open_ioctl_locked'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3534: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'read_properties_unlocked'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3717: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_perf_open_ioctl'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3760: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_perf_register'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3789: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_perf_unregister'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4009: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_perf_add_config_ioctl'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4162: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_perf_remove_config_ioctl'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4260: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_perf_init'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4423: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_perf_fini'.
>
> With Sphinx 3, C declarations can't be duplicated anymore,
> so let's exclude those from the other internals found on
> i915_perf.c file.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
> Documentation/gpu/i915.rst | 29 +++++++++++++++++++++++++----
> 1 file changed, 25 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> index 33cc6ddf8f64..cff1f154b473 100644
> --- a/Documentation/gpu/i915.rst
> +++ b/Documentation/gpu/i915.rst
> @@ -636,15 +636,36 @@ i915 Perf Observation Architecture Stream
> .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
> :functions: i915_oa_poll_wait
>
> -All i915 Perf Internals
> ------------------------
> +Other i915 Perf Internals
> +-------------------------
>
> -This section simply includes all currently documented i915 perf internals, in
> -no particular order, but may include some more minor utilities or platform
> +This section simply includes all other currently documented i915 perf internals,
> +in no particular order, but may include some more minor utilities or platform
> specific details than found in the more high-level sections.
>
> .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
> :internal:
> + :no-identifiers:
> + i915_perf_init
> + i915_perf_fini
> + i915_perf_register
> + i915_perf_unregister
> + i915_perf_open_ioctl
> + i915_perf_release
> + i915_perf_add_config_ioctl
> + i915_perf_remove_config_ioctl
> + read_properties_unlocked
> + i915_perf_open_ioctl_locked
> + i915_perf_destroy_locked
> + i915_perf_read i915_perf_ioctl
> + i915_perf_enable_locked
> + i915_perf_disable_locked
> + i915_perf_poll i915_perf_poll_locked
> + i915_oa_stream_init i915_oa_read
> + i915_oa_stream_enable
> + i915_oa_stream_disable
> + i915_oa_wait_unlocked
> + i915_oa_poll_wait
>
> Style
> =====
> --
> 2.26.2
>
_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [Intel-gfx] [PATCH v6 44/80] docs: gpu: i915.rst: Fix several C duplication warnings
2020-10-16 11:01 ` Joonas Lahtinen
@ 2020-10-16 11:37 ` Mauro Carvalho Chehab
2020-10-16 11:39 ` Lionel Landwerlin
0 siblings, 1 reply; 7+ messages in thread
From: Mauro Carvalho Chehab @ 2020-10-16 11:37 UTC (permalink / raw)
To: Joonas Lahtinen
Cc: Maxime Ripard, Thomas Zimmermann, Jonathan Corbet, David Airlie,
dri-devel, Linux Doc Mailing List, linux-kernel, intel-gfx
Em Fri, 16 Oct 2020 14:01:07 +0300
Joonas Lahtinen <joonas.lahtinen@linux.intel.com> escreveu:
> + Lionel
>
> Can you please take a look at best resolving the below problem.
>
> Maybe we should eliminate the duplicate declarations? Updating such
> a list manually seems error prone to me.
For Kernel 5.10, IMO the best is to apply this patch as-is, as any
other thing would need to be postponed, and we want 5.10 free of
doc warnings.
Yet, when I wrote this one, I almost took a different approach:
to implement something like @*group (or \*group) directives that
exists on doxygen:
https://www.doxygen.nl/manual/grouping.html
If something like that gets added to kernel-doc syntax, then
one could do something like:
/**
* DOC: some foo description
* @group foo
*/
/**
* foo1 - do some foo things
* @group foo
...
*/
/**
* foo2 - do some other foo things
* @group foo
...
*/
/**
* bar - do bar things
* @group bar
...
*/
And then, at kernel-doc markup:
FOO
===
.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
:group: foo
BAR
===
.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
:group: bar
I suspect that something like that would be a lot easier to maintain.
Once having someone like that implemented, it should be easy to also
have something like this:
OTHERS
======
.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
:export:
:not-grouped:
in order to pick other functions that aren't grouped.
I suspect that implementing something like that at kernel-doc.pl
won't be hard.
Regards,
Mauro
>
> Regards, Joonas
>
> Quoting Mauro Carvalho Chehab (2020-10-13 14:53:59)
> > As reported by Sphinx:
> >
> > ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1147: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> > Declaration is 'i915_oa_wait_unlocked'.
> > ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1169: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> > Declaration is 'i915_oa_poll_wait'.
> > ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1189: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> > Declaration is 'i915_oa_read'.
> > ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2669: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> > Declaration is 'i915_oa_stream_enable'.
> > ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2734: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> > Declaration is 'i915_oa_stream_disable'.
> > ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2820: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> > Declaration is 'i915_oa_stream_init'.
> > ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3010: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> > Declaration is 'i915_perf_read'.
> > ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3098: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> > Declaration is 'i915_perf_poll_locked'.
> > ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3129: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> > Declaration is 'i915_perf_poll'.
> > ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3152: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> > Declaration is 'i915_perf_enable_locked'.
> > ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3181: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> > Declaration is 'i915_perf_disable_locked'.
> > ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3273: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> > Declaration is 'i915_perf_ioctl'.
> > ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3296: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> > Declaration is 'i915_perf_destroy_locked'.
> > ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3321: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> > Declaration is 'i915_perf_release'.
> > ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3379: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> > Declaration is 'i915_perf_open_ioctl_locked'.
> > ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3534: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> > Declaration is 'read_properties_unlocked'.
> > ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3717: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> > Declaration is 'i915_perf_open_ioctl'.
> > ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3760: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> > Declaration is 'i915_perf_register'.
> > ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3789: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> > Declaration is 'i915_perf_unregister'.
> > ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4009: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> > Declaration is 'i915_perf_add_config_ioctl'.
> > ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4162: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> > Declaration is 'i915_perf_remove_config_ioctl'.
> > ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4260: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> > Declaration is 'i915_perf_init'.
> > ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4423: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> > Declaration is 'i915_perf_fini'.
> >
> > With Sphinx 3, C declarations can't be duplicated anymore,
> > so let's exclude those from the other internals found on
> > i915_perf.c file.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > ---
> > Documentation/gpu/i915.rst | 29 +++++++++++++++++++++++++----
> > 1 file changed, 25 insertions(+), 4 deletions(-)
> >
> > diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> > index 33cc6ddf8f64..cff1f154b473 100644
> > --- a/Documentation/gpu/i915.rst
> > +++ b/Documentation/gpu/i915.rst
> > @@ -636,15 +636,36 @@ i915 Perf Observation Architecture Stream
> > .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
> > :functions: i915_oa_poll_wait
> >
> > -All i915 Perf Internals
> > ------------------------
> > +Other i915 Perf Internals
> > +-------------------------
> >
> > -This section simply includes all currently documented i915 perf internals, in
> > -no particular order, but may include some more minor utilities or platform
> > +This section simply includes all other currently documented i915 perf internals,
> > +in no particular order, but may include some more minor utilities or platform
> > specific details than found in the more high-level sections.
> >
> > .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
> > :internal:
> > + :no-identifiers:
> > + i915_perf_init
> > + i915_perf_fini
> > + i915_perf_register
> > + i915_perf_unregister
> > + i915_perf_open_ioctl
> > + i915_perf_release
> > + i915_perf_add_config_ioctl
> > + i915_perf_remove_config_ioctl
> > + read_properties_unlocked
> > + i915_perf_open_ioctl_locked
> > + i915_perf_destroy_locked
> > + i915_perf_read i915_perf_ioctl
> > + i915_perf_enable_locked
> > + i915_perf_disable_locked
> > + i915_perf_poll i915_perf_poll_locked
> > + i915_oa_stream_init i915_oa_read
> > + i915_oa_stream_enable
> > + i915_oa_stream_disable
> > + i915_oa_wait_unlocked
> > + i915_oa_poll_wait
> >
> > Style
> > =====
> > --
> > 2.26.2
> >
Thanks,
Mauro
_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [Intel-gfx] [PATCH v6 44/80] docs: gpu: i915.rst: Fix several C duplication warnings
2020-10-16 11:37 ` Mauro Carvalho Chehab
@ 2020-10-16 11:39 ` Lionel Landwerlin
2020-10-16 11:50 ` Jani Nikula
0 siblings, 1 reply; 7+ messages in thread
From: Lionel Landwerlin @ 2020-10-16 11:39 UTC (permalink / raw)
To: Mauro Carvalho Chehab, Joonas Lahtinen
Cc: Thomas Zimmermann, Jonathan Corbet, David Airlie, dri-devel,
Linux Doc Mailing List, linux-kernel, Maxime Ripard, intel-gfx
On 16/10/2020 14:37, Mauro Carvalho Chehab wrote:
> Em Fri, 16 Oct 2020 14:01:07 +0300
> Joonas Lahtinen <joonas.lahtinen@linux.intel.com> escreveu:
>
>> + Lionel
>>
>> Can you please take a look at best resolving the below problem.
>>
>> Maybe we should eliminate the duplicate declarations? Updating such
>> a list manually seems error prone to me.
> For Kernel 5.10, IMO the best is to apply this patch as-is, as any
> other thing would need to be postponed, and we want 5.10 free of
> doc warnings.
That's odd... Most of the functions are documented. Is it that we're
missing the "()" after the function name maybe?
-Lionel
>
> Yet, when I wrote this one, I almost took a different approach:
> to implement something like @*group (or \*group) directives that
> exists on doxygen:
>
> https://www.doxygen.nl/manual/grouping.html
>
> If something like that gets added to kernel-doc syntax, then
> one could do something like:
>
> /**
> * DOC: some foo description
> * @group foo
> */
>
> /**
> * foo1 - do some foo things
> * @group foo
> ...
> */
>
> /**
> * foo2 - do some other foo things
> * @group foo
> ...
> */
>
> /**
> * bar - do bar things
> * @group bar
> ...
> */
>
>
> And then, at kernel-doc markup:
>
> FOO
> ===
>
> .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
> :group: foo
>
>
> BAR
> ===
> .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
> :group: bar
>
>
> I suspect that something like that would be a lot easier to maintain.
>
> Once having someone like that implemented, it should be easy to also
> have something like this:
>
> OTHERS
> ======
> .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
> :export:
> :not-grouped:
>
> in order to pick other functions that aren't grouped.
>
> I suspect that implementing something like that at kernel-doc.pl
> won't be hard.
>
> Regards,
> Mauro
>
>> Regards, Joonas
>>
>> Quoting Mauro Carvalho Chehab (2020-10-13 14:53:59)
>>> As reported by Sphinx:
>>>
>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1147: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>> Declaration is 'i915_oa_wait_unlocked'.
>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1169: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>> Declaration is 'i915_oa_poll_wait'.
>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1189: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>> Declaration is 'i915_oa_read'.
>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2669: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>> Declaration is 'i915_oa_stream_enable'.
>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2734: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>> Declaration is 'i915_oa_stream_disable'.
>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2820: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>> Declaration is 'i915_oa_stream_init'.
>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3010: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>> Declaration is 'i915_perf_read'.
>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3098: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>> Declaration is 'i915_perf_poll_locked'.
>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3129: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>> Declaration is 'i915_perf_poll'.
>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3152: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>> Declaration is 'i915_perf_enable_locked'.
>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3181: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>> Declaration is 'i915_perf_disable_locked'.
>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3273: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>> Declaration is 'i915_perf_ioctl'.
>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3296: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>> Declaration is 'i915_perf_destroy_locked'.
>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3321: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>> Declaration is 'i915_perf_release'.
>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3379: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>> Declaration is 'i915_perf_open_ioctl_locked'.
>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3534: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>> Declaration is 'read_properties_unlocked'.
>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3717: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>> Declaration is 'i915_perf_open_ioctl'.
>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3760: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>> Declaration is 'i915_perf_register'.
>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3789: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>> Declaration is 'i915_perf_unregister'.
>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4009: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>> Declaration is 'i915_perf_add_config_ioctl'.
>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4162: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>> Declaration is 'i915_perf_remove_config_ioctl'.
>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4260: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>> Declaration is 'i915_perf_init'.
>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4423: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>> Declaration is 'i915_perf_fini'.
>>>
>>> With Sphinx 3, C declarations can't be duplicated anymore,
>>> so let's exclude those from the other internals found on
>>> i915_perf.c file.
>>>
>>> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>>> ---
>>> Documentation/gpu/i915.rst | 29 +++++++++++++++++++++++++----
>>> 1 file changed, 25 insertions(+), 4 deletions(-)
>>>
>>> diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
>>> index 33cc6ddf8f64..cff1f154b473 100644
>>> --- a/Documentation/gpu/i915.rst
>>> +++ b/Documentation/gpu/i915.rst
>>> @@ -636,15 +636,36 @@ i915 Perf Observation Architecture Stream
>>> .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
>>> :functions: i915_oa_poll_wait
>>>
>>> -All i915 Perf Internals
>>> ------------------------
>>> +Other i915 Perf Internals
>>> +-------------------------
>>>
>>> -This section simply includes all currently documented i915 perf internals, in
>>> -no particular order, but may include some more minor utilities or platform
>>> +This section simply includes all other currently documented i915 perf internals,
>>> +in no particular order, but may include some more minor utilities or platform
>>> specific details than found in the more high-level sections.
>>>
>>> .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
>>> :internal:
>>> + :no-identifiers:
>>> + i915_perf_init
>>> + i915_perf_fini
>>> + i915_perf_register
>>> + i915_perf_unregister
>>> + i915_perf_open_ioctl
>>> + i915_perf_release
>>> + i915_perf_add_config_ioctl
>>> + i915_perf_remove_config_ioctl
>>> + read_properties_unlocked
>>> + i915_perf_open_ioctl_locked
>>> + i915_perf_destroy_locked
>>> + i915_perf_read i915_perf_ioctl
>>> + i915_perf_enable_locked
>>> + i915_perf_disable_locked
>>> + i915_perf_poll i915_perf_poll_locked
>>> + i915_oa_stream_init i915_oa_read
>>> + i915_oa_stream_enable
>>> + i915_oa_stream_disable
>>> + i915_oa_wait_unlocked
>>> + i915_oa_poll_wait
>>>
>>> Style
>>> =====
>>> --
>>> 2.26.2
>>>
>
>
> Thanks,
> Mauro
_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [Intel-gfx] [PATCH v6 44/80] docs: gpu: i915.rst: Fix several C duplication warnings
2020-10-16 11:39 ` Lionel Landwerlin
@ 2020-10-16 11:50 ` Jani Nikula
2020-10-16 12:02 ` Lionel Landwerlin
0 siblings, 1 reply; 7+ messages in thread
From: Jani Nikula @ 2020-10-16 11:50 UTC (permalink / raw)
To: Lionel Landwerlin, Mauro Carvalho Chehab, Joonas Lahtinen
Cc: Thomas Zimmermann, Jonathan Corbet, David Airlie, intel-gfx,
Linux Doc Mailing List, linux-kernel, Maxime Ripard, dri-devel
On Fri, 16 Oct 2020, Lionel Landwerlin <lionel.g.landwerlin@intel.com> wrote:
> On 16/10/2020 14:37, Mauro Carvalho Chehab wrote:
>> Em Fri, 16 Oct 2020 14:01:07 +0300
>> Joonas Lahtinen <joonas.lahtinen@linux.intel.com> escreveu:
>>
>>> + Lionel
>>>
>>> Can you please take a look at best resolving the below problem.
>>>
>>> Maybe we should eliminate the duplicate declarations? Updating such
>>> a list manually seems error prone to me.
>> For Kernel 5.10, IMO the best is to apply this patch as-is, as any
>> other thing would need to be postponed, and we want 5.10 free of
>> doc warnings.
>
>
> That's odd... Most of the functions are documented. Is it that we're
> missing the "()" after the function name maybe?
The problem is we first include named functions, and then go on to
include everything again, duplicating the documentation for the named
functions.
BR,
Jani.
>
>
> -Lionel
>
>
>>
>> Yet, when I wrote this one, I almost took a different approach:
>> to implement something like @*group (or \*group) directives that
>> exists on doxygen:
>>
>> https://www.doxygen.nl/manual/grouping.html
>>
>> If something like that gets added to kernel-doc syntax, then
>> one could do something like:
>>
>> /**
>> * DOC: some foo description
>> * @group foo
>> */
>>
>> /**
>> * foo1 - do some foo things
>> * @group foo
>> ...
>> */
>>
>> /**
>> * foo2 - do some other foo things
>> * @group foo
>> ...
>> */
>>
>> /**
>> * bar - do bar things
>> * @group bar
>> ...
>> */
>>
>>
>> And then, at kernel-doc markup:
>>
>> FOO
>> ===
>>
>> .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
>> :group: foo
>>
>>
>> BAR
>> ===
>> .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
>> :group: bar
>>
>>
>> I suspect that something like that would be a lot easier to maintain.
>>
>> Once having someone like that implemented, it should be easy to also
>> have something like this:
>>
>> OTHERS
>> ======
>> .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
>> :export:
>> :not-grouped:
>>
>> in order to pick other functions that aren't grouped.
>>
>> I suspect that implementing something like that at kernel-doc.pl
>> won't be hard.
>>
>> Regards,
>> Mauro
>>
>>> Regards, Joonas
>>>
>>> Quoting Mauro Carvalho Chehab (2020-10-13 14:53:59)
>>>> As reported by Sphinx:
>>>>
>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1147: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>> Declaration is 'i915_oa_wait_unlocked'.
>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1169: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>> Declaration is 'i915_oa_poll_wait'.
>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1189: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>> Declaration is 'i915_oa_read'.
>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2669: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>> Declaration is 'i915_oa_stream_enable'.
>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2734: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>> Declaration is 'i915_oa_stream_disable'.
>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2820: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>> Declaration is 'i915_oa_stream_init'.
>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3010: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>> Declaration is 'i915_perf_read'.
>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3098: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>> Declaration is 'i915_perf_poll_locked'.
>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3129: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>> Declaration is 'i915_perf_poll'.
>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3152: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>> Declaration is 'i915_perf_enable_locked'.
>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3181: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>> Declaration is 'i915_perf_disable_locked'.
>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3273: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>> Declaration is 'i915_perf_ioctl'.
>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3296: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>> Declaration is 'i915_perf_destroy_locked'.
>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3321: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>> Declaration is 'i915_perf_release'.
>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3379: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>> Declaration is 'i915_perf_open_ioctl_locked'.
>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3534: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>> Declaration is 'read_properties_unlocked'.
>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3717: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>> Declaration is 'i915_perf_open_ioctl'.
>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3760: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>> Declaration is 'i915_perf_register'.
>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3789: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>> Declaration is 'i915_perf_unregister'.
>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4009: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>> Declaration is 'i915_perf_add_config_ioctl'.
>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4162: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>> Declaration is 'i915_perf_remove_config_ioctl'.
>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4260: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>> Declaration is 'i915_perf_init'.
>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4423: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>> Declaration is 'i915_perf_fini'.
>>>>
>>>> With Sphinx 3, C declarations can't be duplicated anymore,
>>>> so let's exclude those from the other internals found on
>>>> i915_perf.c file.
>>>>
>>>> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>>>> ---
>>>> Documentation/gpu/i915.rst | 29 +++++++++++++++++++++++++----
>>>> 1 file changed, 25 insertions(+), 4 deletions(-)
>>>>
>>>> diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
>>>> index 33cc6ddf8f64..cff1f154b473 100644
>>>> --- a/Documentation/gpu/i915.rst
>>>> +++ b/Documentation/gpu/i915.rst
>>>> @@ -636,15 +636,36 @@ i915 Perf Observation Architecture Stream
>>>> .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
>>>> :functions: i915_oa_poll_wait
>>>>
>>>> -All i915 Perf Internals
>>>> ------------------------
>>>> +Other i915 Perf Internals
>>>> +-------------------------
>>>>
>>>> -This section simply includes all currently documented i915 perf internals, in
>>>> -no particular order, but may include some more minor utilities or platform
>>>> +This section simply includes all other currently documented i915 perf internals,
>>>> +in no particular order, but may include some more minor utilities or platform
>>>> specific details than found in the more high-level sections.
>>>>
>>>> .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
>>>> :internal:
>>>> + :no-identifiers:
>>>> + i915_perf_init
>>>> + i915_perf_fini
>>>> + i915_perf_register
>>>> + i915_perf_unregister
>>>> + i915_perf_open_ioctl
>>>> + i915_perf_release
>>>> + i915_perf_add_config_ioctl
>>>> + i915_perf_remove_config_ioctl
>>>> + read_properties_unlocked
>>>> + i915_perf_open_ioctl_locked
>>>> + i915_perf_destroy_locked
>>>> + i915_perf_read i915_perf_ioctl
>>>> + i915_perf_enable_locked
>>>> + i915_perf_disable_locked
>>>> + i915_perf_poll i915_perf_poll_locked
>>>> + i915_oa_stream_init i915_oa_read
>>>> + i915_oa_stream_enable
>>>> + i915_oa_stream_disable
>>>> + i915_oa_wait_unlocked
>>>> + i915_oa_poll_wait
>>>>
>>>> Style
>>>> =====
>>>> --
>>>> 2.26.2
>>>>
>>
>>
>> Thanks,
>> Mauro
>
>
--
Jani Nikula, Intel Open Source Graphics Center
_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [Intel-gfx] [PATCH v6 44/80] docs: gpu: i915.rst: Fix several C duplication warnings
2020-10-16 11:50 ` Jani Nikula
@ 2020-10-16 12:02 ` Lionel Landwerlin
0 siblings, 0 replies; 7+ messages in thread
From: Lionel Landwerlin @ 2020-10-16 12:02 UTC (permalink / raw)
To: Jani Nikula, Mauro Carvalho Chehab, Joonas Lahtinen
Cc: Thomas Zimmermann, Jonathan Corbet, David Airlie, intel-gfx,
Linux Doc Mailing List, linux-kernel, Maxime Ripard, dri-devel
On 16/10/2020 14:50, Jani Nikula wrote:
> On Fri, 16 Oct 2020, Lionel Landwerlin <lionel.g.landwerlin@intel.com> wrote:
>> On 16/10/2020 14:37, Mauro Carvalho Chehab wrote:
>>> Em Fri, 16 Oct 2020 14:01:07 +0300
>>> Joonas Lahtinen <joonas.lahtinen@linux.intel.com> escreveu:
>>>
>>>> + Lionel
>>>>
>>>> Can you please take a look at best resolving the below problem.
>>>>
>>>> Maybe we should eliminate the duplicate declarations? Updating such
>>>> a list manually seems error prone to me.
>>> For Kernel 5.10, IMO the best is to apply this patch as-is, as any
>>> other thing would need to be postponed, and we want 5.10 free of
>>> doc warnings.
>>
>> That's odd... Most of the functions are documented. Is it that we're
>> missing the "()" after the function name maybe?
> The problem is we first include named functions, and then go on to
> include everything again, duplicating the documentation for the named
> functions.
>
> BR,
> Jani.
Thanks, now the patch makes sense.
-Lionel
>
>
>>
>> -Lionel
>>
>>
>>> Yet, when I wrote this one, I almost took a different approach:
>>> to implement something like @*group (or \*group) directives that
>>> exists on doxygen:
>>>
>>> https://www.doxygen.nl/manual/grouping.html
>>>
>>> If something like that gets added to kernel-doc syntax, then
>>> one could do something like:
>>>
>>> /**
>>> * DOC: some foo description
>>> * @group foo
>>> */
>>>
>>> /**
>>> * foo1 - do some foo things
>>> * @group foo
>>> ...
>>> */
>>>
>>> /**
>>> * foo2 - do some other foo things
>>> * @group foo
>>> ...
>>> */
>>>
>>> /**
>>> * bar - do bar things
>>> * @group bar
>>> ...
>>> */
>>>
>>>
>>> And then, at kernel-doc markup:
>>>
>>> FOO
>>> ===
>>>
>>> .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
>>> :group: foo
>>>
>>>
>>> BAR
>>> ===
>>> .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
>>> :group: bar
>>>
>>>
>>> I suspect that something like that would be a lot easier to maintain.
>>>
>>> Once having someone like that implemented, it should be easy to also
>>> have something like this:
>>>
>>> OTHERS
>>> ======
>>> .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
>>> :export:
>>> :not-grouped:
>>>
>>> in order to pick other functions that aren't grouped.
>>>
>>> I suspect that implementing something like that at kernel-doc.pl
>>> won't be hard.
>>>
>>> Regards,
>>> Mauro
>>>
>>>> Regards, Joonas
>>>>
>>>> Quoting Mauro Carvalho Chehab (2020-10-13 14:53:59)
>>>>> As reported by Sphinx:
>>>>>
>>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1147: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>> Declaration is 'i915_oa_wait_unlocked'.
>>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1169: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>> Declaration is 'i915_oa_poll_wait'.
>>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1189: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>> Declaration is 'i915_oa_read'.
>>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2669: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>> Declaration is 'i915_oa_stream_enable'.
>>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2734: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>> Declaration is 'i915_oa_stream_disable'.
>>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2820: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>> Declaration is 'i915_oa_stream_init'.
>>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3010: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>> Declaration is 'i915_perf_read'.
>>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3098: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>> Declaration is 'i915_perf_poll_locked'.
>>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3129: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>> Declaration is 'i915_perf_poll'.
>>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3152: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>> Declaration is 'i915_perf_enable_locked'.
>>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3181: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>> Declaration is 'i915_perf_disable_locked'.
>>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3273: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>> Declaration is 'i915_perf_ioctl'.
>>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3296: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>> Declaration is 'i915_perf_destroy_locked'.
>>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3321: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>> Declaration is 'i915_perf_release'.
>>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3379: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>> Declaration is 'i915_perf_open_ioctl_locked'.
>>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3534: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>> Declaration is 'read_properties_unlocked'.
>>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3717: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>> Declaration is 'i915_perf_open_ioctl'.
>>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3760: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>> Declaration is 'i915_perf_register'.
>>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3789: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>> Declaration is 'i915_perf_unregister'.
>>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4009: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>> Declaration is 'i915_perf_add_config_ioctl'.
>>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4162: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>> Declaration is 'i915_perf_remove_config_ioctl'.
>>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4260: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>> Declaration is 'i915_perf_init'.
>>>>> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4423: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
>>>>> Declaration is 'i915_perf_fini'.
>>>>>
>>>>> With Sphinx 3, C declarations can't be duplicated anymore,
>>>>> so let's exclude those from the other internals found on
>>>>> i915_perf.c file.
>>>>>
>>>>> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>>>>> ---
>>>>> Documentation/gpu/i915.rst | 29 +++++++++++++++++++++++++----
>>>>> 1 file changed, 25 insertions(+), 4 deletions(-)
>>>>>
>>>>> diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
>>>>> index 33cc6ddf8f64..cff1f154b473 100644
>>>>> --- a/Documentation/gpu/i915.rst
>>>>> +++ b/Documentation/gpu/i915.rst
>>>>> @@ -636,15 +636,36 @@ i915 Perf Observation Architecture Stream
>>>>> .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
>>>>> :functions: i915_oa_poll_wait
>>>>>
>>>>> -All i915 Perf Internals
>>>>> ------------------------
>>>>> +Other i915 Perf Internals
>>>>> +-------------------------
>>>>>
>>>>> -This section simply includes all currently documented i915 perf internals, in
>>>>> -no particular order, but may include some more minor utilities or platform
>>>>> +This section simply includes all other currently documented i915 perf internals,
>>>>> +in no particular order, but may include some more minor utilities or platform
>>>>> specific details than found in the more high-level sections.
>>>>>
>>>>> .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
>>>>> :internal:
>>>>> + :no-identifiers:
>>>>> + i915_perf_init
>>>>> + i915_perf_fini
>>>>> + i915_perf_register
>>>>> + i915_perf_unregister
>>>>> + i915_perf_open_ioctl
>>>>> + i915_perf_release
>>>>> + i915_perf_add_config_ioctl
>>>>> + i915_perf_remove_config_ioctl
>>>>> + read_properties_unlocked
>>>>> + i915_perf_open_ioctl_locked
>>>>> + i915_perf_destroy_locked
>>>>> + i915_perf_read i915_perf_ioctl
>>>>> + i915_perf_enable_locked
>>>>> + i915_perf_disable_locked
>>>>> + i915_perf_poll i915_perf_poll_locked
>>>>> + i915_oa_stream_init i915_oa_read
>>>>> + i915_oa_stream_enable
>>>>> + i915_oa_stream_disable
>>>>> + i915_oa_wait_unlocked
>>>>> + i915_oa_poll_wait
>>>>>
>>>>> Style
>>>>> =====
>>>>> --
>>>>> 2.26.2
>>>>>
>>>
>>> Thanks,
>>> Mauro
>>
_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [Intel-gfx] [PATCH v6 44/80] docs: gpu: i915.rst: Fix several C duplication warnings
2020-10-13 11:53 ` [Intel-gfx] [PATCH v6 44/80] docs: gpu: i915.rst: Fix several C duplication warnings Mauro Carvalho Chehab
2020-10-16 11:01 ` Joonas Lahtinen
@ 2020-10-16 12:03 ` Lionel Landwerlin
1 sibling, 0 replies; 7+ messages in thread
From: Lionel Landwerlin @ 2020-10-16 12:03 UTC (permalink / raw)
To: Mauro Carvalho Chehab, Linux Doc Mailing List
Cc: Jonathan Corbet, David Airlie, intel-gfx, linux-kernel, dri-devel,
Thomas Zimmermann
On 13/10/2020 14:53, Mauro Carvalho Chehab wrote:
> As reported by Sphinx:
>
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1147: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_oa_wait_unlocked'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1169: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_oa_poll_wait'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:1189: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_oa_read'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2669: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_oa_stream_enable'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2734: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_oa_stream_disable'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:2820: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_oa_stream_init'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3010: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_perf_read'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3098: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_perf_poll_locked'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3129: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_perf_poll'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3152: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_perf_enable_locked'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3181: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_perf_disable_locked'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3273: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_perf_ioctl'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3296: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_perf_destroy_locked'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3321: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_perf_release'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3379: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_perf_open_ioctl_locked'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3534: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'read_properties_unlocked'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3717: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_perf_open_ioctl'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3760: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_perf_register'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:3789: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_perf_unregister'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4009: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_perf_add_config_ioctl'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4162: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_perf_remove_config_ioctl'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4260: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_perf_init'.
> ./Documentation/gpu/i915:646: ./drivers/gpu/drm/i915/i915_perf.c:4423: WARNING: Duplicate C declaration, also defined in 'gpu/i915'.
> Declaration is 'i915_perf_fini'.
>
> With Sphinx 3, C declarations can't be duplicated anymore,
> so let's exclude those from the other internals found on
> i915_perf.c file.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Lionel Landwerlin <lionel.g.landwerlin@intel.com>
> ---
> Documentation/gpu/i915.rst | 29 +++++++++++++++++++++++++----
> 1 file changed, 25 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> index 33cc6ddf8f64..cff1f154b473 100644
> --- a/Documentation/gpu/i915.rst
> +++ b/Documentation/gpu/i915.rst
> @@ -636,15 +636,36 @@ i915 Perf Observation Architecture Stream
> .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
> :functions: i915_oa_poll_wait
>
> -All i915 Perf Internals
> ------------------------
> +Other i915 Perf Internals
> +-------------------------
>
> -This section simply includes all currently documented i915 perf internals, in
> -no particular order, but may include some more minor utilities or platform
> +This section simply includes all other currently documented i915 perf internals,
> +in no particular order, but may include some more minor utilities or platform
> specific details than found in the more high-level sections.
>
> .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
> :internal:
> + :no-identifiers:
> + i915_perf_init
> + i915_perf_fini
> + i915_perf_register
> + i915_perf_unregister
> + i915_perf_open_ioctl
> + i915_perf_release
> + i915_perf_add_config_ioctl
> + i915_perf_remove_config_ioctl
> + read_properties_unlocked
> + i915_perf_open_ioctl_locked
> + i915_perf_destroy_locked
> + i915_perf_read i915_perf_ioctl
> + i915_perf_enable_locked
> + i915_perf_disable_locked
> + i915_perf_poll i915_perf_poll_locked
> + i915_oa_stream_init i915_oa_read
> + i915_oa_stream_enable
> + i915_oa_stream_disable
> + i915_oa_wait_unlocked
> + i915_oa_poll_wait
>
> Style
> =====
_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx
^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2020-10-16 15:44 UTC | newest]
Thread overview: 7+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
[not found] <cover.1602589096.git.mchehab+huawei@kernel.org>
2020-10-13 11:53 ` [Intel-gfx] [PATCH v6 44/80] docs: gpu: i915.rst: Fix several C duplication warnings Mauro Carvalho Chehab
2020-10-16 11:01 ` Joonas Lahtinen
2020-10-16 11:37 ` Mauro Carvalho Chehab
2020-10-16 11:39 ` Lionel Landwerlin
2020-10-16 11:50 ` Jani Nikula
2020-10-16 12:02 ` Lionel Landwerlin
2020-10-16 12:03 ` Lionel Landwerlin
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox