[PATCH v3] coresight: coresight.h: add '*' to kernel-doc lines

[PATCH v3] coresight: coresight.h: add '*' to kernel-doc lines

[Randy Dunlap]

kernel-doc reports 2 (kernel-doc) lines in coresight.h that don't have
a beginning '*' in them, so fix these lines.

Also convert struct coresight_trace_id_map to kernel-doc format to
remove another warning.

Warning: include/linux/coresight.h:173 bad line:
  connected to @src_port. NULL until the device is created
Warning: include/linux/coresight.h:177 bad line:
  needs to be filtered.
Warning: include/linux/coresight.h:236 This comment starts with '/**',
  but isn't a kernel-doc comment.

Fixes: ec9903d6cc34 ("coresight: Add support for trace filtering by source")
Fixes: d49c9cf15f89 ("coresight: Rename connection members to make the direction explicit")
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
---
v2: rebase & resend
v3: rebase & resend

Cc: James Clark <james.clark@arm.com>
Cc: Tao Zhang <quic_taozha@quicinc.com>
Cc: Suzuki K Poulose <suzuki.poulose@arm.com>
Cc: coresight@lists.linaro.org
Cc: Danilo Krummrich <dakr@kernel.org>
Cc: Mike Leach <mike.leach@arm.com>
Cc: Leo Yan <leo.yan@arm.com>
Cc: linux-arm-kernel@lists.infradead.org
---
 include/linux/coresight.h |    6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

--- linux-next-20260717.orig/include/linux/coresight.h
+++ linux-next-20260717/include/linux/coresight.h
@@ -177,11 +177,11 @@ struct coresight_desc {
  * @dest_port:	destination's input port number @src_port is connected to.
  * @dest_fwnode: destination component's fwnode handle.
  * @dest_dev:	a @coresight_device representation of the component
-		connected to @src_port. NULL until the device is created
+ *		connected to @src_port. NULL until the device is created
  * @link: Representation of the connection as a sysfs link.
  * @filter_src_fwnode: filter source component's fwnode handle.
  * @filter_src_dev: a @coresight_device representation of the component that
-		needs to be filtered.
+ *		needs to be filtered.
  *
  * The full connection structure looks like this, where in_conns store
  * references to same connection as the source device's out_conns.
@@ -234,7 +234,7 @@ struct coresight_sysfs_link {
 #define CORESIGHT_TRACE_IDS_MAX 128
 
 /**
- * Trace ID map.
+ * struct coresight_trace_id_map - Trace ID map.
  *
  * @used_ids:	Bitmap to register available (bit = 0) and in use (bit = 1) IDs.
  *		Initialised so that the reserved IDs are permanently marked as

Re: [PATCH v3] coresight: coresight.h: add '*' to kernel-doc lines

[Randy Dunlap]

ping?

On 7/19/26 3:24 PM, Randy Dunlap wrote:
> kernel-doc reports 2 (kernel-doc) lines in coresight.h that don't have
> a beginning '*' in them, so fix these lines.
> 
> Also convert struct coresight_trace_id_map to kernel-doc format to
> remove another warning.
> 
> Warning: include/linux/coresight.h:173 bad line:
>   connected to @src_port. NULL until the device is created
> Warning: include/linux/coresight.h:177 bad line:
>   needs to be filtered.
> Warning: include/linux/coresight.h:236 This comment starts with '/**',
>   but isn't a kernel-doc comment.
> 
> Fixes: ec9903d6cc34 ("coresight: Add support for trace filtering by source")
> Fixes: d49c9cf15f89 ("coresight: Rename connection members to make the direction explicit")
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> ---
> v2: rebase & resend
> v3: rebase & resend
> 
> Cc: James Clark <james.clark@arm.com>
> Cc: Tao Zhang <quic_taozha@quicinc.com>
> Cc: Suzuki K Poulose <suzuki.poulose@arm.com>
> Cc: coresight@lists.linaro.org
> Cc: Danilo Krummrich <dakr@kernel.org>
> Cc: Mike Leach <mike.leach@arm.com>
> Cc: Leo Yan <leo.yan@arm.com>
> Cc: linux-arm-kernel@lists.infradead.org
> ---
>  include/linux/coresight.h |    6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
> 
> --- linux-next-20260717.orig/include/linux/coresight.h
> +++ linux-next-20260717/include/linux/coresight.h
> @@ -177,11 +177,11 @@ struct coresight_desc {
>   * @dest_port:	destination's input port number @src_port is connected to.
>   * @dest_fwnode: destination component's fwnode handle.
>   * @dest_dev:	a @coresight_device representation of the component
> -		connected to @src_port. NULL until the device is created
> + *		connected to @src_port. NULL until the device is created
>   * @link: Representation of the connection as a sysfs link.
>   * @filter_src_fwnode: filter source component's fwnode handle.
>   * @filter_src_dev: a @coresight_device representation of the component that
> -		needs to be filtered.
> + *		needs to be filtered.
>   *
>   * The full connection structure looks like this, where in_conns store
>   * references to same connection as the source device's out_conns.
> @@ -234,7 +234,7 @@ struct coresight_sysfs_link {
>  #define CORESIGHT_TRACE_IDS_MAX 128
>  
>  /**
> - * Trace ID map.
> + * struct coresight_trace_id_map - Trace ID map.
>   *
>   * @used_ids:	Bitmap to register available (bit = 0) and in use (bit = 1) IDs.
>   *		Initialised so that the reserved IDs are permanently marked as

-- 
~Randy

Re: [PATCH v3] coresight: coresight.h: add '*' to kernel-doc lines

[Anshuman Khandual]

On 20/07/26 3:54 AM, Randy Dunlap wrote:
> kernel-doc reports 2 (kernel-doc) lines in coresight.h that don't have
> a beginning '*' in them, so fix these lines.
> 
> Also convert struct coresight_trace_id_map to kernel-doc format to
> remove another warning.
> 
> Warning: include/linux/coresight.h:173 bad line:
>   connected to @src_port. NULL until the device is created
> Warning: include/linux/coresight.h:177 bad line:
>   needs to be filtered.
> Warning: include/linux/coresight.h:236 This comment starts with '/**',
>   but isn't a kernel-doc comment.
> 
> Fixes: ec9903d6cc34 ("coresight: Add support for trace filtering by source")
> Fixes: d49c9cf15f89 ("coresight: Rename connection members to make the direction explicit")
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> ---
> v2: rebase & resend
> v3: rebase & resend
> 
> Cc: James Clark <james.clark@arm.com>
> Cc: Tao Zhang <quic_taozha@quicinc.com>
> Cc: Suzuki K Poulose <suzuki.poulose@arm.com>
> Cc: coresight@lists.linaro.org
> Cc: Danilo Krummrich <dakr@kernel.org>
> Cc: Mike Leach <mike.leach@arm.com>
> Cc: Leo Yan <leo.yan@arm.com>
> Cc: linux-arm-kernel@lists.infradead.org
> ---
>  include/linux/coresight.h |    6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
> 
> --- linux-next-20260717.orig/include/linux/coresight.h
> +++ linux-next-20260717/include/linux/coresight.h
> @@ -177,11 +177,11 @@ struct coresight_desc {
>   * @dest_port:	destination's input port number @src_port is connected to.
>   * @dest_fwnode: destination component's fwnode handle.
>   * @dest_dev:	a @coresight_device representation of the component
> -		connected to @src_port. NULL until the device is created
> + *		connected to @src_port. NULL until the device is created
>   * @link: Representation of the connection as a sysfs link.
>   * @filter_src_fwnode: filter source component's fwnode handle.
>   * @filter_src_dev: a @coresight_device representation of the component that
> -		needs to be filtered.
> + *		needs to be filtered.
>   *
>   * The full connection structure looks like this, where in_conns store
>   * references to same connection as the source device's out_conns.
> @@ -234,7 +234,7 @@ struct coresight_sysfs_link {
>  #define CORESIGHT_TRACE_IDS_MAX 128
>  
>  /**
> - * Trace ID map.
> + * struct coresight_trace_id_map - Trace ID map.
>   *
>   * @used_ids:	Bitmap to register available (bit = 0) and in use (bit = 1) IDs.
>   *		Initialised so that the reserved IDs are permanently marked as
> 

But still there are more warnings left in the documentation file
even after the patch applied. Should they be fixed as well ?

./scripts/kernel-doc -none include/linux/coresight.h
Warning: include/linux/coresight.h:216 struct member 'src_dev' not described in 'coresight_connection'
Warning: include/linux/coresight.h:216 struct member 'src_refcnt' not described in 'coresight_connection'
Warning: include/linux/coresight.h:216 struct member 'dest_refcnt' not described in 'coresight_connection'
Warning: include/linux/coresight.h:248 struct member 'cpu_map' not described in 'coresight_trace_id_map'
Warning: include/linux/coresight.h:248 struct member 'lock' not described in 'coresight_trace_id_map'
Warning: include/linux/coresight.h:312 struct member 'perf_sink_id_map' not described in 'coresight_device'
Warning: include/linux/coresight.h:216 struct member 'src_dev' not described in 'coresight_connection'
Warning: include/linux/coresight.h:216 struct member 'src_refcnt' not described in 'coresight_connection'
Warning: include/linux/coresight.h:216 struct member 'dest_refcnt' not described in 'coresight_connection'
Warning: include/linux/coresight.h:248 struct member 'cpu_map' not described in 'coresight_trace_id_map'
Warning: include/linux/coresight.h:248 struct member 'lock' not described in 'coresight_trace_id_map'
Warning: include/linux/coresight.h:312 struct member 'perf_sink_id_map' not described in 'coresight_device'

Re: [PATCH v3] coresight: coresight.h: add '*' to kernel-doc lines

[Randy Dunlap]

On 7/27/26 10:31 PM, Anshuman Khandual wrote:
> 
> 
> On 20/07/26 3:54 AM, Randy Dunlap wrote:
>> kernel-doc reports 2 (kernel-doc) lines in coresight.h that don't have
>> a beginning '*' in them, so fix these lines.
>>
>> Also convert struct coresight_trace_id_map to kernel-doc format to
>> remove another warning.
>>
>> Warning: include/linux/coresight.h:173 bad line:
>>   connected to @src_port. NULL until the device is created
>> Warning: include/linux/coresight.h:177 bad line:
>>   needs to be filtered.
>> Warning: include/linux/coresight.h:236 This comment starts with '/**',
>>   but isn't a kernel-doc comment.
>>
>> Fixes: ec9903d6cc34 ("coresight: Add support for trace filtering by source")
>> Fixes: d49c9cf15f89 ("coresight: Rename connection members to make the direction explicit")
>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
>> ---
>> v2: rebase & resend
>> v3: rebase & resend
>>
>> Cc: James Clark <james.clark@arm.com>
>> Cc: Tao Zhang <quic_taozha@quicinc.com>
>> Cc: Suzuki K Poulose <suzuki.poulose@arm.com>
>> Cc: coresight@lists.linaro.org
>> Cc: Danilo Krummrich <dakr@kernel.org>
>> Cc: Mike Leach <mike.leach@arm.com>
>> Cc: Leo Yan <leo.yan@arm.com>
>> Cc: linux-arm-kernel@lists.infradead.org
>> ---
>>  include/linux/coresight.h |    6 +++---
>>  1 file changed, 3 insertions(+), 3 deletions(-)
>>
>> --- linux-next-20260717.orig/include/linux/coresight.h
>> +++ linux-next-20260717/include/linux/coresight.h
>> @@ -177,11 +177,11 @@ struct coresight_desc {
>>   * @dest_port:	destination's input port number @src_port is connected to.
>>   * @dest_fwnode: destination component's fwnode handle.
>>   * @dest_dev:	a @coresight_device representation of the component
>> -		connected to @src_port. NULL until the device is created
>> + *		connected to @src_port. NULL until the device is created
>>   * @link: Representation of the connection as a sysfs link.
>>   * @filter_src_fwnode: filter source component's fwnode handle.
>>   * @filter_src_dev: a @coresight_device representation of the component that
>> -		needs to be filtered.
>> + *		needs to be filtered.
>>   *
>>   * The full connection structure looks like this, where in_conns store
>>   * references to same connection as the source device's out_conns.
>> @@ -234,7 +234,7 @@ struct coresight_sysfs_link {
>>  #define CORESIGHT_TRACE_IDS_MAX 128
>>  
>>  /**
>> - * Trace ID map.
>> + * struct coresight_trace_id_map - Trace ID map.
>>   *
>>   * @used_ids:	Bitmap to register available (bit = 0) and in use (bit = 1) IDs.
>>   *		Initialised so that the reserved IDs are permanently marked as
>>
> 
> But still there are more warnings left in the documentation file
> even after the patch applied. Should they be fixed as well ?

Yes, I know that. Hopefully someone with expertise in this area can add a few
comments there.

> ./scripts/kernel-doc -none include/linux/coresight.h
> Warning: include/linux/coresight.h:216 struct member 'src_dev' not described in 'coresight_connection'
> Warning: include/linux/coresight.h:216 struct member 'src_refcnt' not described in 'coresight_connection'
> Warning: include/linux/coresight.h:216 struct member 'dest_refcnt' not described in 'coresight_connection'
> Warning: include/linux/coresight.h:248 struct member 'cpu_map' not described in 'coresight_trace_id_map'
> Warning: include/linux/coresight.h:248 struct member 'lock' not described in 'coresight_trace_id_map'
> Warning: include/linux/coresight.h:312 struct member 'perf_sink_id_map' not described in 'coresight_device'

Note that half of these are just duplicates of the lines above.

> Warning: include/linux/coresight.h:216 struct member 'src_dev' not described in 'coresight_connection'
> Warning: include/linux/coresight.h:216 struct member 'src_refcnt' not described in 'coresight_connection'
> Warning: include/linux/coresight.h:216 struct member 'dest_refcnt' not described in 'coresight_connection'
> Warning: include/linux/coresight.h:248 struct member 'cpu_map' not described in 'coresight_trace_id_map'
> Warning: include/linux/coresight.h:248 struct member 'lock' not described in 'coresight_trace_id_map'
> Warning: include/linux/coresight.h:312 struct member 'perf_sink_id_map' not described in 'coresight_device'

thanks.
-- 
~Randy