[PATCH 1/3] docs(xeno3): Fix doxygen parsing of COBALT_IMPL_TIME64 wrappers

[PATCH 1/3] docs(xeno3): Fix doxygen parsing of COBALT_IMPL_TIME64 wrappers

[Clara Kowalsky]

The doxygen configuration lacks a definition for COBALT_IMPL_TIME64().
Therefore doxygen does not see the expanded wrapper prototype in
wrappers_time64.c and instead tries to match @param entries against the
macro call.

This raises warnings at doc build such as

lib/cobalt/wrappers_time64.c:42: warning: argument 'clock_id' of command @param is not found in the argument list of COBALT_IMPL_TIME64(int, clock_getres, __clock_getres64,(clockid_t clock_id, struct timespec *tp))

as doxygen is seeing the raw macro form

COBALT_IMPL_TIME64(int, clock_getres, __clock_getres64,
          (clockid_t clock_id, struct timespec *tp))

With the fix, doxygen rewrites the macro to

int clock_getres(clockid_t clock_id, struct timespec *tp)

It uses the first macro argument (return type), the second (function
name) and fourth (parameter list), but ignores the third (alternate
function name, unneeded).
By this, doxygen sees the actual public function prototype.
See #18.

Signed-off-by: Clara Kowalsky <clara.kowalsky@siemens.com>
---
 doc/doxygen/xeno3prm-common.conf.in | 1 +
 1 file changed, 1 insertion(+)

diff --git a/doc/doxygen/xeno3prm-common.conf.in b/doc/doxygen/xeno3prm-common.conf.in
index 71db05686..ee4ede10d 100644
--- a/doc/doxygen/xeno3prm-common.conf.in
+++ b/doc/doxygen/xeno3prm-common.conf.in
@@ -647,6 +647,7 @@ PREDEFINED = DOXYGEN_CPP			\
         "EXPORT_SYMBOL_GPL(symbol)=//"		\
         "DECLARE_BITMAP(symbol, nr)=unsigned long symbol[BITS_TO_LONGS(nr)]" \
 	"COBALT_IMPL(T,I,A)=T I A"		\
+	"COBALT_IMPL_TIME64(T,I,N,A)=T I A"	\
 	"COBALT_DECL(T,P)=T P"			\
 	"COBALT_SYSCALL(N,M,T,A)=T N A"		\
 	"COBALT_SYSCALL_DECL(N,T,A)=T N A"
-- 
2.55.0

[PATCH 2/3] docs: Fix a2x warning for PDF builds

[Clara Kowalsky]

The documentation PDF build passes "-D" to a2x, raising warnings such
as

a2x: WARNING: --destination-dir option is only applicable to HTML and manpage based outputs

Drop the unsupported option for PDF builds.
See #18.

Signed-off-by: Clara Kowalsky <clara.kowalsky@siemens.com>
---
 doc/asciidoc/Makefile.am | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/asciidoc/Makefile.am b/doc/asciidoc/Makefile.am
index 782c7a23f..669decaeb 100644
--- a/doc/asciidoc/Makefile.am
+++ b/doc/asciidoc/Makefile.am
@@ -91,7 +91,7 @@ html/%: %.adoc Makefile
 	$(A2X) -f manpage -D man1 $(ASCIIDOC_MAN_OPTS) $<
 
 %.pdf: %.adoc Makefile
-	$(A2X) -f pdf -D . $(ASCIIDOC_PDF_OPTS) $<
+	$(A2X) -f pdf $(ASCIIDOC_PDF_OPTS) $<
 
 $(tmpdir)/%.txt: %.adoc Makefile plaintext.conf plaintext.xsl
 	@$(mkdir_p) $(tmpdir)
-- 
2.55.0

Re: [PATCH 2/3] docs: Fix a2x warning for PDF builds

[Jan Kiszka]

On 03.09.26 10:34, Clara Kowalsky wrote:
> The documentation PDF build passes "-D" to a2x, raising warnings such
> as
> 
> a2x: WARNING: --destination-dir option is only applicable to HTML and manpage based outputs
> 
> Drop the unsupported option for PDF builds.
> See #18.
> 
> Signed-off-by: Clara Kowalsky <clara.kowalsky@siemens.com>
> ---
>  doc/asciidoc/Makefile.am | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/doc/asciidoc/Makefile.am b/doc/asciidoc/Makefile.am
> index 782c7a23f..669decaeb 100644
> --- a/doc/asciidoc/Makefile.am
> +++ b/doc/asciidoc/Makefile.am
> @@ -91,7 +91,7 @@ html/%: %.adoc Makefile
>  	$(A2X) -f manpage -D man1 $(ASCIIDOC_MAN_OPTS) $<
>  
>  %.pdf: %.adoc Makefile
> -	$(A2X) -f pdf -D . $(ASCIIDOC_PDF_OPTS) $<
> +	$(A2X) -f pdf $(ASCIIDOC_PDF_OPTS) $<
>  
>  $(tmpdir)/%.txt: %.adoc Makefile plaintext.conf plaintext.xsl
>  	@$(mkdir_p) $(tmpdir)

Could it be that this did have some side effects? My pipeline is red
because of missing .pdf files:

https://gitlab.com/Xenomai/xenomai3/xenomai-doc/-/jobs/16348492423

Jan

-- 
Siemens AG, Foundational Technologies
Linux Expert Center

Re: [PATCH 2/3] docs: Fix a2x warning for PDF builds

[Clara Kowalsky]

On 9/7/26 16:22, Jan Kiszka wrote:
> On 03.09.26 10:34, Clara Kowalsky wrote:
>> The documentation PDF build passes "-D" to a2x, raising warnings such
>> as
>>
>> a2x: WARNING: --destination-dir option is only applicable to HTML and manpage based outputs
>>
>> Drop the unsupported option for PDF builds.
>> See #18.
>>
>> Signed-off-by: Clara Kowalsky <clara.kowalsky@siemens.com>
>> ---
>>   doc/asciidoc/Makefile.am | 2 +-
>>   1 file changed, 1 insertion(+), 1 deletion(-)
>>
>> diff --git a/doc/asciidoc/Makefile.am b/doc/asciidoc/Makefile.am
>> index 782c7a23f..669decaeb 100644
>> --- a/doc/asciidoc/Makefile.am
>> +++ b/doc/asciidoc/Makefile.am
>> @@ -91,7 +91,7 @@ html/%: %.adoc Makefile
>>   	$(A2X) -f manpage -D man1 $(ASCIIDOC_MAN_OPTS) $<
>>   
>>   %.pdf: %.adoc Makefile
>> -	$(A2X) -f pdf -D . $(ASCIIDOC_PDF_OPTS) $<
>> +	$(A2X) -f pdf $(ASCIIDOC_PDF_OPTS) $<
>>   
>>   $(tmpdir)/%.txt: %.adoc Makefile plaintext.conf plaintext.xsl
>>   	@$(mkdir_p) $(tmpdir)
> 
> Could it be that this did have some side effects? My pipeline is red
> because of missing .pdf files:
> 
> https://gitlab.com/Xenomai/xenomai3/xenomai-doc/-/jobs/16348492423
> 
> Jan
> 
Yes. When omitting the -D destination dir, the pdf is placed in the 
source dir where the .adoc is located.
https://linux.die.net/man/1/a2x

build/doc/asciidoc$ a2x -f pdf -a icons -a toc -a toclevels=3 -a 
xenover=3.3 ../../../doc/asciidoc/MIGRATION.adoc

When using "-D .", the warning is printed that the option is not 
supported for pdf outputs, but it actually places the .pdf into the 
wanted directory.

As we want the pdfs generated in the build dir, let's omit the commit 
and live with the warning.

Clara

Re: [PATCH 2/3] docs: Fix a2x warning for PDF builds

[Jan Kiszka]

On 08.09.26 09:27, Clara Kowalsky wrote:
> 
> 
> On 9/7/26 16:22, Jan Kiszka wrote:
>> On 03.09.26 10:34, Clara Kowalsky wrote:
>>> The documentation PDF build passes "-D" to a2x, raising warnings such
>>> as
>>>
>>> a2x: WARNING: --destination-dir option is only applicable to HTML and
>>> manpage based outputs
>>>
>>> Drop the unsupported option for PDF builds.
>>> See #18.
>>>
>>> Signed-off-by: Clara Kowalsky <clara.kowalsky@siemens.com>
>>> ---
>>>   doc/asciidoc/Makefile.am | 2 +-
>>>   1 file changed, 1 insertion(+), 1 deletion(-)
>>>
>>> diff --git a/doc/asciidoc/Makefile.am b/doc/asciidoc/Makefile.am
>>> index 782c7a23f..669decaeb 100644
>>> --- a/doc/asciidoc/Makefile.am
>>> +++ b/doc/asciidoc/Makefile.am
>>> @@ -91,7 +91,7 @@ html/%: %.adoc Makefile
>>>       $(A2X) -f manpage -D man1 $(ASCIIDOC_MAN_OPTS) $<
>>>     %.pdf: %.adoc Makefile
>>> -    $(A2X) -f pdf -D . $(ASCIIDOC_PDF_OPTS) $<
>>> +    $(A2X) -f pdf $(ASCIIDOC_PDF_OPTS) $<
>>>     $(tmpdir)/%.txt: %.adoc Makefile plaintext.conf plaintext.xsl
>>>       @$(mkdir_p) $(tmpdir)
>>
>> Could it be that this did have some side effects? My pipeline is red
>> because of missing .pdf files:
>>
>> https://gitlab.com/Xenomai/xenomai3/xenomai-doc/-/jobs/16348492423
>>
>> Jan
>>
> Yes. When omitting the -D destination dir, the pdf is placed in the
> source dir where the .adoc is located.
> https://linux.die.net/man/1/a2x
> 
> build/doc/asciidoc$ a2x -f pdf -a icons -a toc -a toclevels=3 -a
> xenover=3.3 ../../../doc/asciidoc/MIGRATION.adoc
> 
> When using "-D .", the warning is printed that the option is not
> supported for pdf outputs, but it actually places the .pdf into the
> wanted directory.
> 
> As we want the pdfs generated in the build dir, let's omit the commit
> and live with the warning.
> 

Weird tool: complains that the option is not applicable, provides not
alternative to it, and also does what it is told.

Agreed, let's drop this change.

Jan

-- 
Siemens AG, Foundational Technologies
Linux Expert Center

[PATCH 3/3] docs: Match actual return type for RTDM doxygen declarations

[Clara Kowalsky]

The RTDM doxygen-only declarations were corrected to match the actual
return semantics (int instead void).

This fixes warnings such as

kernel/cobalt/rtdm/core.c:420: warning: found documented return type for rtdm_timedwait that does not return anything

See #18.

Signed-off-by: Clara Kowalsky <clara.kowalsky@siemens.com>
---
 kernel/cobalt/rtdm/core.c   | 28 ++++++++++++++--------------
 kernel/cobalt/rtdm/drvlib.c |  2 +-
 2 files changed, 15 insertions(+), 15 deletions(-)

diff --git a/kernel/cobalt/rtdm/core.c b/kernel/cobalt/rtdm/core.c
index f30055a79..002fb51cf 100644
--- a/kernel/cobalt/rtdm/core.c
+++ b/kernel/cobalt/rtdm/core.c
@@ -414,7 +414,7 @@ rtdm_timedwait_condition(struct rtdm_wait_queue *wq, C_expr condition,
 			 nanosecs_rel_t timeout, rtdm_toseq_t *toseq);
 
 /**
- * @fn void rtdm_timedwait(struct rtdm_wait_queue *wq, nanosecs_rel_t timeout, rtdm_toseq_t *toseq)
+ * @fn int rtdm_timedwait(struct rtdm_wait_queue *wq, nanosecs_rel_t timeout, rtdm_toseq_t *toseq)
  * @brief Timed sleep on a waitqueue unconditionally
  *
  * The calling task is put to sleep until the waitqueue is signaled by
@@ -443,11 +443,11 @@ rtdm_timedwait_condition(struct rtdm_wait_queue *wq, C_expr condition,
  *
  * @coretags{primary-only, might-switch}
  */
-void rtdm_timedwait(struct rtdm_wait_queue *wq,
+int rtdm_timedwait(struct rtdm_wait_queue *wq,
 		    nanosecs_rel_t timeout, rtdm_toseq_t *toseq);
 
 /**
- * @fn void rtdm_timedwait_locked(struct rtdm_wait_queue *wq, nanosecs_rel_t timeout, rtdm_toseq_t *toseq)
+ * @fn int rtdm_timedwait_locked(struct rtdm_wait_queue *wq, nanosecs_rel_t timeout, rtdm_toseq_t *toseq)
  * @brief Timed sleep on a locked waitqueue unconditionally
  *
  * The calling task is put to sleep until the waitqueue is signaled by
@@ -481,7 +481,7 @@ void rtdm_timedwait(struct rtdm_wait_queue *wq,
  *
  * @coretags{primary-only, might-switch}
  */
-void rtdm_timedwait_locked(struct rtdm_wait_queue *wq,
+int rtdm_timedwait_locked(struct rtdm_wait_queue *wq,
 			   nanosecs_rel_t timeout, rtdm_toseq_t *toseq);
 
 /**
@@ -509,7 +509,7 @@ void rtdm_timedwait_locked(struct rtdm_wait_queue *wq,
 rtdm_wait_condition(struct rtdm_wait_queue *wq, C_expr condition);
 
 /**
- * @fn void rtdm_wait(struct rtdm_wait_queue *wq)
+ * @fn int rtdm_wait(struct rtdm_wait_queue *wq)
  * @brief Sleep on a waitqueue unconditionally
  *
  * The calling task is put to sleep until the waitqueue is signaled by
@@ -526,10 +526,10 @@ rtdm_wait_condition(struct rtdm_wait_queue *wq, C_expr condition);
  *
  * @coretags{primary-only, might-switch}
  */
-void rtdm_wait(struct rtdm_wait_queue *wq);
+int rtdm_wait(struct rtdm_wait_queue *wq);
 
 /**
- * @fn void rtdm_wait_locked(struct rtdm_wait_queue *wq)
+ * @fn int rtdm_wait_locked(struct rtdm_wait_queue *wq)
  * @brief Sleep on a locked waitqueue unconditionally
  *
  * The calling task is put to sleep until the waitqueue is signaled by
@@ -551,7 +551,7 @@ void rtdm_wait(struct rtdm_wait_queue *wq);
  *
  * @coretags{primary-only, might-switch}
  */
-void rtdm_wait_locked(struct rtdm_wait_queue *wq);
+int rtdm_wait_locked(struct rtdm_wait_queue *wq);
 
 /**
  * @fn void rtdm_waitqueue_lock(struct rtdm_wait_queue *wq, rtdm_lockctx_t context)
@@ -585,7 +585,7 @@ void rtdm_waitqueue_lock(struct rtdm_wait_queue *wq, rtdm_lockctx_t context);
 void rtdm_waitqueue_unlock(struct rtdm_wait_queue *wq, rtdm_lockctx_t context);
 
 /**
- * @fn void rtdm_waitqueue_signal(struct rtdm_wait_queue *wq)
+ * @fn int rtdm_waitqueue_signal(struct rtdm_wait_queue *wq)
  * @brief Signal a waitqueue
  *
  * Signals the waitqueue @a wq, waking up a single waiter (if
@@ -598,10 +598,10 @@ void rtdm_waitqueue_unlock(struct rtdm_wait_queue *wq, rtdm_lockctx_t context);
  *
  * @coretags{unrestricted, might-switch}
  */
-void rtdm_waitqueue_signal(struct rtdm_wait_queue *wq);
+int rtdm_waitqueue_signal(struct rtdm_wait_queue *wq);
 
 /**
- * @fn void rtdm_waitqueue_broadcast(struct rtdm_wait_queue *wq)
+ * @fn int rtdm_waitqueue_broadcast(struct rtdm_wait_queue *wq)
  * @brief Broadcast a waitqueue
  *
  * Broadcast the waitqueue @a wq, waking up all waiters. Each
@@ -614,10 +614,10 @@ void rtdm_waitqueue_signal(struct rtdm_wait_queue *wq);
  *
  * @coretags{unrestricted, might-switch}
  */
-void rtdm_waitqueue_broadcast(struct rtdm_wait_queue *wq);
+int rtdm_waitqueue_broadcast(struct rtdm_wait_queue *wq);
 
 /**
- * @fn void rtdm_waitqueue_flush(struct rtdm_wait_queue *wq)
+ * @fn int rtdm_waitqueue_flush(struct rtdm_wait_queue *wq)
  * @brief Flush a waitqueue
  *
  * Flushes the waitqueue @a wq, unblocking all waiters with an error
@@ -630,7 +630,7 @@ void rtdm_waitqueue_broadcast(struct rtdm_wait_queue *wq);
  *
  * @coretags{unrestricted, might-switch}
  */
-void rtdm_waitqueue_flush(struct rtdm_wait_queue *wq);
+int rtdm_waitqueue_flush(struct rtdm_wait_queue *wq);
 
 /**
  * @fn void rtdm_waitqueue_wakeup(struct rtdm_wait_queue *wq, rtdm_task_t waiter)
diff --git a/kernel/cobalt/rtdm/drvlib.c b/kernel/cobalt/rtdm/drvlib.c
index d9de62946..c2e7e1195 100644
--- a/kernel/cobalt/rtdm/drvlib.c
+++ b/kernel/cobalt/rtdm/drvlib.c
@@ -2270,7 +2270,7 @@ EXPORT_SYMBOL_GPL(rtdm_get_iov_flatlen);
  *
  * @coretags{unrestricted}
  */
-void rtdm_printk_ratelimited(const char *format, ...);
+int rtdm_printk_ratelimited(const char *format, ...);
 
 /**
  * Allocate memory block
-- 
2.55.0

Re: [PATCH 3/3] docs: Match actual return type for RTDM doxygen declarations

[Jan Kiszka]

On 03.09.26 10:34, Clara Kowalsky wrote:
> The RTDM doxygen-only declarations were corrected to match the actual
> return semantics (int instead void).
> 
> This fixes warnings such as
> 
> kernel/cobalt/rtdm/core.c:420: warning: found documented return type for rtdm_timedwait that does not return anything
> 
> See #18.
> 
> Signed-off-by: Clara Kowalsky <clara.kowalsky@siemens.com>
> ---
>  kernel/cobalt/rtdm/core.c   | 28 ++++++++++++++--------------
>  kernel/cobalt/rtdm/drvlib.c |  2 +-
>  2 files changed, 15 insertions(+), 15 deletions(-)
> 
> diff --git a/kernel/cobalt/rtdm/core.c b/kernel/cobalt/rtdm/core.c
> index f30055a79..002fb51cf 100644
> --- a/kernel/cobalt/rtdm/core.c
> +++ b/kernel/cobalt/rtdm/core.c
> @@ -414,7 +414,7 @@ rtdm_timedwait_condition(struct rtdm_wait_queue *wq, C_expr condition,
>  			 nanosecs_rel_t timeout, rtdm_toseq_t *toseq);
>  
>  /**
> - * @fn void rtdm_timedwait(struct rtdm_wait_queue *wq, nanosecs_rel_t timeout, rtdm_toseq_t *toseq)
> + * @fn int rtdm_timedwait(struct rtdm_wait_queue *wq, nanosecs_rel_t timeout, rtdm_toseq_t *toseq)
>   * @brief Timed sleep on a waitqueue unconditionally
>   *
>   * The calling task is put to sleep until the waitqueue is signaled by
> @@ -443,11 +443,11 @@ rtdm_timedwait_condition(struct rtdm_wait_queue *wq, C_expr condition,
>   *
>   * @coretags{primary-only, might-switch}
>   */
> -void rtdm_timedwait(struct rtdm_wait_queue *wq,
> +int rtdm_timedwait(struct rtdm_wait_queue *wq,
>  		    nanosecs_rel_t timeout, rtdm_toseq_t *toseq);
>  
>  /**
> - * @fn void rtdm_timedwait_locked(struct rtdm_wait_queue *wq, nanosecs_rel_t timeout, rtdm_toseq_t *toseq)
> + * @fn int rtdm_timedwait_locked(struct rtdm_wait_queue *wq, nanosecs_rel_t timeout, rtdm_toseq_t *toseq)
>   * @brief Timed sleep on a locked waitqueue unconditionally
>   *
>   * The calling task is put to sleep until the waitqueue is signaled by
> @@ -481,7 +481,7 @@ void rtdm_timedwait(struct rtdm_wait_queue *wq,
>   *
>   * @coretags{primary-only, might-switch}
>   */
> -void rtdm_timedwait_locked(struct rtdm_wait_queue *wq,
> +int rtdm_timedwait_locked(struct rtdm_wait_queue *wq,
>  			   nanosecs_rel_t timeout, rtdm_toseq_t *toseq);
>  
>  /**
> @@ -509,7 +509,7 @@ void rtdm_timedwait_locked(struct rtdm_wait_queue *wq,
>  rtdm_wait_condition(struct rtdm_wait_queue *wq, C_expr condition);
>  
>  /**
> - * @fn void rtdm_wait(struct rtdm_wait_queue *wq)
> + * @fn int rtdm_wait(struct rtdm_wait_queue *wq)
>   * @brief Sleep on a waitqueue unconditionally
>   *
>   * The calling task is put to sleep until the waitqueue is signaled by
> @@ -526,10 +526,10 @@ rtdm_wait_condition(struct rtdm_wait_queue *wq, C_expr condition);
>   *
>   * @coretags{primary-only, might-switch}
>   */
> -void rtdm_wait(struct rtdm_wait_queue *wq);
> +int rtdm_wait(struct rtdm_wait_queue *wq);
>  
>  /**
> - * @fn void rtdm_wait_locked(struct rtdm_wait_queue *wq)
> + * @fn int rtdm_wait_locked(struct rtdm_wait_queue *wq)
>   * @brief Sleep on a locked waitqueue unconditionally
>   *
>   * The calling task is put to sleep until the waitqueue is signaled by
> @@ -551,7 +551,7 @@ void rtdm_wait(struct rtdm_wait_queue *wq);
>   *
>   * @coretags{primary-only, might-switch}
>   */
> -void rtdm_wait_locked(struct rtdm_wait_queue *wq);
> +int rtdm_wait_locked(struct rtdm_wait_queue *wq);
>  
>  /**
>   * @fn void rtdm_waitqueue_lock(struct rtdm_wait_queue *wq, rtdm_lockctx_t context)
> @@ -585,7 +585,7 @@ void rtdm_waitqueue_lock(struct rtdm_wait_queue *wq, rtdm_lockctx_t context);
>  void rtdm_waitqueue_unlock(struct rtdm_wait_queue *wq, rtdm_lockctx_t context);
>  
>  /**
> - * @fn void rtdm_waitqueue_signal(struct rtdm_wait_queue *wq)
> + * @fn int rtdm_waitqueue_signal(struct rtdm_wait_queue *wq)
>   * @brief Signal a waitqueue
>   *
>   * Signals the waitqueue @a wq, waking up a single waiter (if
> @@ -598,10 +598,10 @@ void rtdm_waitqueue_unlock(struct rtdm_wait_queue *wq, rtdm_lockctx_t context);
>   *
>   * @coretags{unrestricted, might-switch}
>   */
> -void rtdm_waitqueue_signal(struct rtdm_wait_queue *wq);
> +int rtdm_waitqueue_signal(struct rtdm_wait_queue *wq);
>  
>  /**
> - * @fn void rtdm_waitqueue_broadcast(struct rtdm_wait_queue *wq)
> + * @fn int rtdm_waitqueue_broadcast(struct rtdm_wait_queue *wq)
>   * @brief Broadcast a waitqueue
>   *
>   * Broadcast the waitqueue @a wq, waking up all waiters. Each
> @@ -614,10 +614,10 @@ void rtdm_waitqueue_signal(struct rtdm_wait_queue *wq);
>   *
>   * @coretags{unrestricted, might-switch}
>   */
> -void rtdm_waitqueue_broadcast(struct rtdm_wait_queue *wq);
> +int rtdm_waitqueue_broadcast(struct rtdm_wait_queue *wq);
>  
>  /**
> - * @fn void rtdm_waitqueue_flush(struct rtdm_wait_queue *wq)
> + * @fn int rtdm_waitqueue_flush(struct rtdm_wait_queue *wq)
>   * @brief Flush a waitqueue
>   *
>   * Flushes the waitqueue @a wq, unblocking all waiters with an error
> @@ -630,7 +630,7 @@ void rtdm_waitqueue_broadcast(struct rtdm_wait_queue *wq);
>   *
>   * @coretags{unrestricted, might-switch}
>   */
> -void rtdm_waitqueue_flush(struct rtdm_wait_queue *wq);
> +int rtdm_waitqueue_flush(struct rtdm_wait_queue *wq);
>  
>  /**
>   * @fn void rtdm_waitqueue_wakeup(struct rtdm_wait_queue *wq, rtdm_task_t waiter)
> diff --git a/kernel/cobalt/rtdm/drvlib.c b/kernel/cobalt/rtdm/drvlib.c
> index d9de62946..c2e7e1195 100644
> --- a/kernel/cobalt/rtdm/drvlib.c
> +++ b/kernel/cobalt/rtdm/drvlib.c
> @@ -2270,7 +2270,7 @@ EXPORT_SYMBOL_GPL(rtdm_get_iov_flatlen);
>   *
>   * @coretags{unrestricted}
>   */
> -void rtdm_printk_ratelimited(const char *format, ...);
> +int rtdm_printk_ratelimited(const char *format, ...);
>  

This is not correct. Please fix the documentation.

Please check once more that all the other functions are actually
returning something. Most should, but maybe there is one more off.

Thanks,
Jan

-- 
Siemens AG, Foundational Technologies
Linux Expert Center

Re: [PATCH 3/3] docs: Match actual return type for RTDM doxygen declarations

[Clara Kowalsky]

On 9/3/26 12:53, Jan Kiszka wrote:
> On 03.09.26 10:34, Clara Kowalsky wrote:
>> The RTDM doxygen-only declarations were corrected to match the actual
>> return semantics (int instead void).
>>
>> This fixes warnings such as
>>
>> kernel/cobalt/rtdm/core.c:420: warning: found documented return type for rtdm_timedwait that does not return anything
>>
>> See #18.
>>
>> Signed-off-by: Clara Kowalsky <clara.kowalsky@siemens.com>
>> ---
>>   kernel/cobalt/rtdm/core.c   | 28 ++++++++++++++--------------
>>   kernel/cobalt/rtdm/drvlib.c |  2 +-
>>   2 files changed, 15 insertions(+), 15 deletions(-)
>>
>> diff --git a/kernel/cobalt/rtdm/core.c b/kernel/cobalt/rtdm/core.c
>> index f30055a79..002fb51cf 100644
>> --- a/kernel/cobalt/rtdm/core.c
>> +++ b/kernel/cobalt/rtdm/core.c
>> @@ -414,7 +414,7 @@ rtdm_timedwait_condition(struct rtdm_wait_queue *wq, C_expr condition,
>>   			 nanosecs_rel_t timeout, rtdm_toseq_t *toseq);
>>   
>>   /**
>> - * @fn void rtdm_timedwait(struct rtdm_wait_queue *wq, nanosecs_rel_t timeout, rtdm_toseq_t *toseq)
>> + * @fn int rtdm_timedwait(struct rtdm_wait_queue *wq, nanosecs_rel_t timeout, rtdm_toseq_t *toseq)
>>    * @brief Timed sleep on a waitqueue unconditionally
>>    *
>>    * The calling task is put to sleep until the waitqueue is signaled by
>> @@ -443,11 +443,11 @@ rtdm_timedwait_condition(struct rtdm_wait_queue *wq, C_expr condition,
>>    *
>>    * @coretags{primary-only, might-switch}
>>    */
>> -void rtdm_timedwait(struct rtdm_wait_queue *wq,
>> +int rtdm_timedwait(struct rtdm_wait_queue *wq,
>>   		    nanosecs_rel_t timeout, rtdm_toseq_t *toseq);
>>   
>>   /**
>> - * @fn void rtdm_timedwait_locked(struct rtdm_wait_queue *wq, nanosecs_rel_t timeout, rtdm_toseq_t *toseq)
>> + * @fn int rtdm_timedwait_locked(struct rtdm_wait_queue *wq, nanosecs_rel_t timeout, rtdm_toseq_t *toseq)
>>    * @brief Timed sleep on a locked waitqueue unconditionally
>>    *
>>    * The calling task is put to sleep until the waitqueue is signaled by
>> @@ -481,7 +481,7 @@ void rtdm_timedwait(struct rtdm_wait_queue *wq,
>>    *
>>    * @coretags{primary-only, might-switch}
>>    */
>> -void rtdm_timedwait_locked(struct rtdm_wait_queue *wq,
>> +int rtdm_timedwait_locked(struct rtdm_wait_queue *wq,
>>   			   nanosecs_rel_t timeout, rtdm_toseq_t *toseq);
>>   
>>   /**
>> @@ -509,7 +509,7 @@ void rtdm_timedwait_locked(struct rtdm_wait_queue *wq,
>>   rtdm_wait_condition(struct rtdm_wait_queue *wq, C_expr condition);
>>   
>>   /**
>> - * @fn void rtdm_wait(struct rtdm_wait_queue *wq)
>> + * @fn int rtdm_wait(struct rtdm_wait_queue *wq)
>>    * @brief Sleep on a waitqueue unconditionally
>>    *
>>    * The calling task is put to sleep until the waitqueue is signaled by
>> @@ -526,10 +526,10 @@ rtdm_wait_condition(struct rtdm_wait_queue *wq, C_expr condition);
>>    *
>>    * @coretags{primary-only, might-switch}
>>    */
>> -void rtdm_wait(struct rtdm_wait_queue *wq);
>> +int rtdm_wait(struct rtdm_wait_queue *wq);
>>   
>>   /**
>> - * @fn void rtdm_wait_locked(struct rtdm_wait_queue *wq)
>> + * @fn int rtdm_wait_locked(struct rtdm_wait_queue *wq)
>>    * @brief Sleep on a locked waitqueue unconditionally
>>    *
>>    * The calling task is put to sleep until the waitqueue is signaled by
>> @@ -551,7 +551,7 @@ void rtdm_wait(struct rtdm_wait_queue *wq);
>>    *
>>    * @coretags{primary-only, might-switch}
>>    */
>> -void rtdm_wait_locked(struct rtdm_wait_queue *wq);
>> +int rtdm_wait_locked(struct rtdm_wait_queue *wq);
>>   
>>   /**
>>    * @fn void rtdm_waitqueue_lock(struct rtdm_wait_queue *wq, rtdm_lockctx_t context)
>> @@ -585,7 +585,7 @@ void rtdm_waitqueue_lock(struct rtdm_wait_queue *wq, rtdm_lockctx_t context);
>>   void rtdm_waitqueue_unlock(struct rtdm_wait_queue *wq, rtdm_lockctx_t context);
>>   
>>   /**
>> - * @fn void rtdm_waitqueue_signal(struct rtdm_wait_queue *wq)
>> + * @fn int rtdm_waitqueue_signal(struct rtdm_wait_queue *wq)
>>    * @brief Signal a waitqueue
>>    *
>>    * Signals the waitqueue @a wq, waking up a single waiter (if
>> @@ -598,10 +598,10 @@ void rtdm_waitqueue_unlock(struct rtdm_wait_queue *wq, rtdm_lockctx_t context);
>>    *
>>    * @coretags{unrestricted, might-switch}
>>    */
>> -void rtdm_waitqueue_signal(struct rtdm_wait_queue *wq);
>> +int rtdm_waitqueue_signal(struct rtdm_wait_queue *wq);
>>   
>>   /**
>> - * @fn void rtdm_waitqueue_broadcast(struct rtdm_wait_queue *wq)
>> + * @fn int rtdm_waitqueue_broadcast(struct rtdm_wait_queue *wq)
>>    * @brief Broadcast a waitqueue
>>    *
>>    * Broadcast the waitqueue @a wq, waking up all waiters. Each
>> @@ -614,10 +614,10 @@ void rtdm_waitqueue_signal(struct rtdm_wait_queue *wq);
>>    *
>>    * @coretags{unrestricted, might-switch}
>>    */
>> -void rtdm_waitqueue_broadcast(struct rtdm_wait_queue *wq);
>> +int rtdm_waitqueue_broadcast(struct rtdm_wait_queue *wq);
>>   
>>   /**
>> - * @fn void rtdm_waitqueue_flush(struct rtdm_wait_queue *wq)
>> + * @fn int rtdm_waitqueue_flush(struct rtdm_wait_queue *wq)
>>    * @brief Flush a waitqueue
>>    *
>>    * Flushes the waitqueue @a wq, unblocking all waiters with an error
>> @@ -630,7 +630,7 @@ void rtdm_waitqueue_broadcast(struct rtdm_wait_queue *wq);
>>    *
>>    * @coretags{unrestricted, might-switch}
>>    */
>> -void rtdm_waitqueue_flush(struct rtdm_wait_queue *wq);
>> +int rtdm_waitqueue_flush(struct rtdm_wait_queue *wq);
>>   
>>   /**
>>    * @fn void rtdm_waitqueue_wakeup(struct rtdm_wait_queue *wq, rtdm_task_t waiter)
>> diff --git a/kernel/cobalt/rtdm/drvlib.c b/kernel/cobalt/rtdm/drvlib.c
>> index d9de62946..c2e7e1195 100644
>> --- a/kernel/cobalt/rtdm/drvlib.c
>> +++ b/kernel/cobalt/rtdm/drvlib.c
>> @@ -2270,7 +2270,7 @@ EXPORT_SYMBOL_GPL(rtdm_get_iov_flatlen);
>>    *
>>    * @coretags{unrestricted}
>>    */
>> -void rtdm_printk_ratelimited(const char *format, ...);
>> +int rtdm_printk_ratelimited(const char *format, ...);
>>   
> 
> This is not correct. Please fix the documentation.
> 
> Please check once more that all the other functions are actually
> returning something. Most should, but maybe there is one more off.
> 
> Thanks,
> Jan
> 
I checked for all other functions and they all return something. This 
one is only one off. I'll send a v2.

Clara

Re: [PATCH 1/3] docs(xeno3): Fix doxygen parsing of COBALT_IMPL_TIME64 wrappers

[Florian Bezdeka]

On Thu, 2026-09-03 at 10:34 +0200, Clara Kowalsky wrote:
> The doxygen configuration lacks a definition for COBALT_IMPL_TIME64().
> Therefore doxygen does not see the expanded wrapper prototype in
> wrappers_time64.c and instead tries to match @param entries against the
> macro call.
> 
> This raises warnings at doc build such as
> 
> lib/cobalt/wrappers_time64.c:42: warning: argument 'clock_id' of command @param is not found in the argument list of COBALT_IMPL_TIME64(int, clock_getres, __clock_getres64,(clockid_t clock_id, struct timespec *tp))
> 
> as doxygen is seeing the raw macro form
> 
> COBALT_IMPL_TIME64(int, clock_getres, __clock_getres64,
>           (clockid_t clock_id, struct timespec *tp))
> 
> With the fix, doxygen rewrites the macro to
> 
> int clock_getres(clockid_t clock_id, struct timespec *tp)

Hm. The generated documentation should be "generic", right? 

Depending on the chosen build configuration clock_getres OR
__clock_getres64 would be correct, but that is also hidden from the user
in glibc land, so we should probably do the same "hiding" here. 

That said: LGTM.

> 
> It uses the first macro argument (return type), the second (function
> name) and fourth (parameter list), but ignores the third (alternate
> function name, unneeded).
> By this, doxygen sees the actual public function prototype.
> See #18.
> 
> Signed-off-by: Clara Kowalsky <clara.kowalsky@siemens.com>
> ---
>  doc/doxygen/xeno3prm-common.conf.in | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/doc/doxygen/xeno3prm-common.conf.in b/doc/doxygen/xeno3prm-common.conf.in
> index 71db05686..ee4ede10d 100644
> --- a/doc/doxygen/xeno3prm-common.conf.in
> +++ b/doc/doxygen/xeno3prm-common.conf.in
> @@ -647,6 +647,7 @@ PREDEFINED = DOXYGEN_CPP			\
>          "EXPORT_SYMBOL_GPL(symbol)=//"		\
>          "DECLARE_BITMAP(symbol, nr)=unsigned long symbol[BITS_TO_LONGS(nr)]" \
>  	"COBALT_IMPL(T,I,A)=T I A"		\
> +	"COBALT_IMPL_TIME64(T,I,N,A)=T I A"	\
>  	"COBALT_DECL(T,P)=T P"			\

No complains about COBALT_DECL_TIME64? Would have expected something
similar...

>  	"COBALT_SYSCALL(N,M,T,A)=T N A"		\
>  	"COBALT_SYSCALL_DECL(N,T,A)=T N A"
> -- 
> 2.55.0

Question to the complete series: Is
https://gitlab.com/Xenomai/xenomai3/xenomai/-/work_items/18 completely
closed with this series applied?

Re: [PATCH 1/3] docs(xeno3): Fix doxygen parsing of COBALT_IMPL_TIME64 wrappers

[Clara Kowalsky]

On 9/3/26 11:48, Florian Bezdeka wrote:
> On Thu, 2026-09-03 at 10:34 +0200, Clara Kowalsky wrote:
>> The doxygen configuration lacks a definition for COBALT_IMPL_TIME64().
>> Therefore doxygen does not see the expanded wrapper prototype in
>> wrappers_time64.c and instead tries to match @param entries against the
>> macro call.
>>
>> This raises warnings at doc build such as
>>
>> lib/cobalt/wrappers_time64.c:42: warning: argument 'clock_id' of command @param is not found in the argument list of COBALT_IMPL_TIME64(int, clock_getres, __clock_getres64,(clockid_t clock_id, struct timespec *tp))
>>
>> as doxygen is seeing the raw macro form
>>
>> COBALT_IMPL_TIME64(int, clock_getres, __clock_getres64,
>>            (clockid_t clock_id, struct timespec *tp))
>>
>> With the fix, doxygen rewrites the macro to
>>
>> int clock_getres(clockid_t clock_id, struct timespec *tp)
> 
> Hm. The generated documentation should be "generic", right?
> 
> Depending on the chosen build configuration clock_getres OR
> __clock_getres64 would be correct, but that is also hidden from the user
> in glibc land, so we should probably do the same "hiding" here.
> 
> That said: LGTM.

The doxygen mapping should describe the stable public API, not whichever 
internal symbol is emitted for a particular time ABI. So the generated 
docs should expose only the generic API name clock_getres, regardless 
which build variant is selected.
> 
>>
>> It uses the first macro argument (return type), the second (function
>> name) and fourth (parameter list), but ignores the third (alternate
>> function name, unneeded).
>> By this, doxygen sees the actual public function prototype.
>> See #18.
>>
>> Signed-off-by: Clara Kowalsky <clara.kowalsky@siemens.com>
>> ---
>>   doc/doxygen/xeno3prm-common.conf.in | 1 +
>>   1 file changed, 1 insertion(+)
>>
>> diff --git a/doc/doxygen/xeno3prm-common.conf.in b/doc/doxygen/xeno3prm-common.conf.in
>> index 71db05686..ee4ede10d 100644
>> --- a/doc/doxygen/xeno3prm-common.conf.in
>> +++ b/doc/doxygen/xeno3prm-common.conf.in
>> @@ -647,6 +647,7 @@ PREDEFINED = DOXYGEN_CPP			\
>>           "EXPORT_SYMBOL_GPL(symbol)=//"		\
>>           "DECLARE_BITMAP(symbol, nr)=unsigned long symbol[BITS_TO_LONGS(nr)]" \
>>   	"COBALT_IMPL(T,I,A)=T I A"		\
>> +	"COBALT_IMPL_TIME64(T,I,N,A)=T I A"	\
>>   	"COBALT_DECL(T,P)=T P"			\
> 
> No complains about COBALT_DECL_TIME64? Would have expected something
> similar...

I built the documentation with:
./scripts/bootstrap
./configure --enable-doc-build
make -C doc -B V=1 2>&1 | tee /tmp/xeno-doc-build.log

And checked for warnings:
rg -i warn /tmp/xeno-doc-build.log

I didn't get any warnings for COBALT_DECL_TIME64.

> 
>>   	"COBALT_SYSCALL(N,M,T,A)=T N A"		\
>>   	"COBALT_SYSCALL_DECL(N,T,A)=T N A"
>> -- 
>> 2.55.0
> 
> Question to the complete series: Is
> https://gitlab.com/Xenomai/xenomai3/xenomai/-/work_items/18 completely
> closed with this series applied?

Yes, those 3 commits fix all doxygen warnings.

BR,
Clara

Re: [PATCH 1/3] docs(xeno3): Fix doxygen parsing of COBALT_IMPL_TIME64 wrappers

[Jan Kiszka]

On 03.09.26 12:34, Clara Kowalsky wrote:
> 
> 
> On 9/3/26 11:48, Florian Bezdeka wrote:
>> On Thu, 2026-09-03 at 10:34 +0200, Clara Kowalsky wrote:
>>> The doxygen configuration lacks a definition for COBALT_IMPL_TIME64().
>>> Therefore doxygen does not see the expanded wrapper prototype in
>>> wrappers_time64.c and instead tries to match @param entries against the
>>> macro call.
>>>
>>> This raises warnings at doc build such as
>>>
>>> lib/cobalt/wrappers_time64.c:42: warning: argument 'clock_id' of
>>> command @param is not found in the argument list of
>>> COBALT_IMPL_TIME64(int, clock_getres, __clock_getres64,(clockid_t
>>> clock_id, struct timespec *tp))
>>>
>>> as doxygen is seeing the raw macro form
>>>
>>> COBALT_IMPL_TIME64(int, clock_getres, __clock_getres64,
>>>            (clockid_t clock_id, struct timespec *tp))
>>>
>>> With the fix, doxygen rewrites the macro to
>>>
>>> int clock_getres(clockid_t clock_id, struct timespec *tp)
>>
>> Hm. The generated documentation should be "generic", right?
>>
>> Depending on the chosen build configuration clock_getres OR
>> __clock_getres64 would be correct, but that is also hidden from the user
>> in glibc land, so we should probably do the same "hiding" here.
>>
>> That said: LGTM.
> 
> The doxygen mapping should describe the stable public API, not whichever
> internal symbol is emitted for a particular time ABI. So the generated
> docs should expose only the generic API name clock_getres, regardless
> which build variant is selected.
>>
>>>
>>> It uses the first macro argument (return type), the second (function
>>> name) and fourth (parameter list), but ignores the third (alternate
>>> function name, unneeded).
>>> By this, doxygen sees the actual public function prototype.
>>> See #18.
>>>
>>> Signed-off-by: Clara Kowalsky <clara.kowalsky@siemens.com>
>>> ---
>>>   doc/doxygen/xeno3prm-common.conf.in | 1 +
>>>   1 file changed, 1 insertion(+)
>>>
>>> diff --git a/doc/doxygen/xeno3prm-common.conf.in b/doc/doxygen/
>>> xeno3prm-common.conf.in
>>> index 71db05686..ee4ede10d 100644
>>> --- a/doc/doxygen/xeno3prm-common.conf.in
>>> +++ b/doc/doxygen/xeno3prm-common.conf.in
>>> @@ -647,6 +647,7 @@ PREDEFINED = DOXYGEN_CPP            \
>>>           "EXPORT_SYMBOL_GPL(symbol)=//"        \
>>>           "DECLARE_BITMAP(symbol, nr)=unsigned long
>>> symbol[BITS_TO_LONGS(nr)]" \
>>>       "COBALT_IMPL(T,I,A)=T I A"        \
>>> +    "COBALT_IMPL_TIME64(T,I,N,A)=T I A"    \
>>>       "COBALT_DECL(T,P)=T P"            \
>>
>> No complains about COBALT_DECL_TIME64? Would have expected something
>> similar...
> 
> I built the documentation with:
> ./scripts/bootstrap
> ./configure --enable-doc-build
> make -C doc -B V=1 2>&1 | tee /tmp/xeno-doc-build.log
> 
> And checked for warnings:
> rg -i warn /tmp/xeno-doc-build.log
> 
> I didn't get any warnings for COBALT_DECL_TIME64.
> 

I guess that's because function docs are normally attached to the
implementation, not the declaration.

>>
>>>       "COBALT_SYSCALL(N,M,T,A)=T N A"        \
>>>       "COBALT_SYSCALL_DECL(N,T,A)=T N A"
>>> -- 
>>> 2.55.0
>>
>> Question to the complete series: Is
>> https://gitlab.com/Xenomai/xenomai3/xenomai/-/work_items/18 completely
>> closed with this series applied?
> 
> Yes, those 3 commits fix all doxygen warnings.
> 

Thanks! Patches 1 and 2 applied now. 3 is waiting for an update (but I
pushed it too quickly already - will be replaced).

Jan

-- 
Siemens AG, Foundational Technologies
Linux Expert Center

Re: [PATCH 1/3] docs(xeno3): Fix doxygen parsing of COBALT_IMPL_TIME64 wrappers

[Florian Bezdeka]

On Thu, 2026-09-03 at 12:58 +0200, Jan Kiszka wrote:
> On 03.09.26 12:34, Clara Kowalsky wrote:
> > 
> > 
> > On 9/3/26 11:48, Florian Bezdeka wrote:
> > > On Thu, 2026-09-03 at 10:34 +0200, Clara Kowalsky wrote:
> > > > The doxygen configuration lacks a definition for COBALT_IMPL_TIME64().
> > > > Therefore doxygen does not see the expanded wrapper prototype in
> > > > wrappers_time64.c and instead tries to match @param entries against the
> > > > macro call.
> > > > 
> > > > This raises warnings at doc build such as
> > > > 
> > > > lib/cobalt/wrappers_time64.c:42: warning: argument 'clock_id' of
> > > > command @param is not found in the argument list of
> > > > COBALT_IMPL_TIME64(int, clock_getres, __clock_getres64,(clockid_t
> > > > clock_id, struct timespec *tp))
> > > > 
> > > > as doxygen is seeing the raw macro form
> > > > 
> > > > COBALT_IMPL_TIME64(int, clock_getres, __clock_getres64,
> > > >            (clockid_t clock_id, struct timespec *tp))
> > > > 
> > > > With the fix, doxygen rewrites the macro to
> > > > 
> > > > int clock_getres(clockid_t clock_id, struct timespec *tp)
> > > 
> > > Hm. The generated documentation should be "generic", right?
> > > 
> > > Depending on the chosen build configuration clock_getres OR
> > > __clock_getres64 would be correct, but that is also hidden from the user
> > > in glibc land, so we should probably do the same "hiding" here.
> > > 
> > > That said: LGTM.
> > 
> > The doxygen mapping should describe the stable public API, not whichever
> > internal symbol is emitted for a particular time ABI. So the generated
> > docs should expose only the generic API name clock_getres, regardless
> > which build variant is selected.
> > > 
> > > > 
> > > > It uses the first macro argument (return type), the second (function
> > > > name) and fourth (parameter list), but ignores the third (alternate
> > > > function name, unneeded).
> > > > By this, doxygen sees the actual public function prototype.
> > > > See #18.
> > > > 
> > > > Signed-off-by: Clara Kowalsky <clara.kowalsky@siemens.com>
> > > > ---
> > > >   doc/doxygen/xeno3prm-common.conf.in | 1 +
> > > >   1 file changed, 1 insertion(+)
> > > > 
> > > > diff --git a/doc/doxygen/xeno3prm-common.conf.in b/doc/doxygen/
> > > > xeno3prm-common.conf.in
> > > > index 71db05686..ee4ede10d 100644
> > > > --- a/doc/doxygen/xeno3prm-common.conf.in
> > > > +++ b/doc/doxygen/xeno3prm-common.conf.in
> > > > @@ -647,6 +647,7 @@ PREDEFINED = DOXYGEN_CPP            \
> > > >           "EXPORT_SYMBOL_GPL(symbol)=//"        \
> > > >           "DECLARE_BITMAP(symbol, nr)=unsigned long
> > > > symbol[BITS_TO_LONGS(nr)]" \
> > > >       "COBALT_IMPL(T,I,A)=T I A"        \
> > > > +    "COBALT_IMPL_TIME64(T,I,N,A)=T I A"    \
> > > >       "COBALT_DECL(T,P)=T P"            \
> > > 
> > > No complains about COBALT_DECL_TIME64? Would have expected something
> > > similar...
> > 
> > I built the documentation with:
> > ./scripts/bootstrap
> > ./configure --enable-doc-build
> > make -C doc -B V=1 2>&1 | tee /tmp/xeno-doc-build.log
> > 
> > And checked for warnings:
> > rg -i warn /tmp/xeno-doc-build.log
> > 
> > I didn't get any warnings for COBALT_DECL_TIME64.
> > 
> 
> I guess that's because function docs are normally attached to the
> implementation, not the declaration.

Normally COBALT_IMPL and COBALT_IMPL_TIME64 as well as COBALT_DECL and
COBALT_DECL_TIME64 should be treated synchronously / in lock step.

COBALT_DECL_TIME64 is missing here, but maybe COBALT_DECL is not needed
as well?

Florian
> > 

Re: [PATCH 1/3] docs(xeno3): Fix doxygen parsing of COBALT_IMPL_TIME64 wrappers

[Clara Kowalsky]

[-- Attachment #1: Type: text/plain, Size: 4040 bytes --]



On 9/4/26 08:27, Florian Bezdeka wrote:
> On Thu, 2026-09-03 at 12:58 +0200, Jan Kiszka wrote:
>> On 03.09.26 12:34, Clara Kowalsky wrote:
>>>
>>>
>>> On 9/3/26 11:48, Florian Bezdeka wrote:
>>>> On Thu, 2026-09-03 at 10:34 +0200, Clara Kowalsky wrote:
>>>>> The doxygen configuration lacks a definition for COBALT_IMPL_TIME64().
>>>>> Therefore doxygen does not see the expanded wrapper prototype in
>>>>> wrappers_time64.c and instead tries to match @param entries against the
>>>>> macro call.
>>>>>
>>>>> This raises warnings at doc build such as
>>>>>
>>>>> lib/cobalt/wrappers_time64.c:42: warning: argument 'clock_id' of
>>>>> command @param is not found in the argument list of
>>>>> COBALT_IMPL_TIME64(int, clock_getres, __clock_getres64,(clockid_t
>>>>> clock_id, struct timespec *tp))
>>>>>
>>>>> as doxygen is seeing the raw macro form
>>>>>
>>>>> COBALT_IMPL_TIME64(int, clock_getres, __clock_getres64,
>>>>>             (clockid_t clock_id, struct timespec *tp))
>>>>>
>>>>> With the fix, doxygen rewrites the macro to
>>>>>
>>>>> int clock_getres(clockid_t clock_id, struct timespec *tp)
>>>>
>>>> Hm. The generated documentation should be "generic", right?
>>>>
>>>> Depending on the chosen build configuration clock_getres OR
>>>> __clock_getres64 would be correct, but that is also hidden from the user
>>>> in glibc land, so we should probably do the same "hiding" here.
>>>>
>>>> That said: LGTM.
>>>
>>> The doxygen mapping should describe the stable public API, not whichever
>>> internal symbol is emitted for a particular time ABI. So the generated
>>> docs should expose only the generic API name clock_getres, regardless
>>> which build variant is selected.
>>>>
>>>>>
>>>>> It uses the first macro argument (return type), the second (function
>>>>> name) and fourth (parameter list), but ignores the third (alternate
>>>>> function name, unneeded).
>>>>> By this, doxygen sees the actual public function prototype.
>>>>> See #18.
>>>>>
>>>>> Signed-off-by: Clara Kowalsky <clara.kowalsky@siemens.com>
>>>>> ---
>>>>>    doc/doxygen/xeno3prm-common.conf.in | 1 +
>>>>>    1 file changed, 1 insertion(+)
>>>>>
>>>>> diff --git a/doc/doxygen/xeno3prm-common.conf.in b/doc/doxygen/
>>>>> xeno3prm-common.conf.in
>>>>> index 71db05686..ee4ede10d 100644
>>>>> --- a/doc/doxygen/xeno3prm-common.conf.in
>>>>> +++ b/doc/doxygen/xeno3prm-common.conf.in
>>>>> @@ -647,6 +647,7 @@ PREDEFINED = DOXYGEN_CPP            \
>>>>>            "EXPORT_SYMBOL_GPL(symbol)=//"        \
>>>>>            "DECLARE_BITMAP(symbol, nr)=unsigned long
>>>>> symbol[BITS_TO_LONGS(nr)]" \
>>>>>        "COBALT_IMPL(T,I,A)=T I A"        \
>>>>> +    "COBALT_IMPL_TIME64(T,I,N,A)=T I A"    \
>>>>>        "COBALT_DECL(T,P)=T P"            \
>>>>
>>>> No complains about COBALT_DECL_TIME64? Would have expected something
>>>> similar...
>>>
>>> I built the documentation with:
>>> ./scripts/bootstrap
>>> ./configure --enable-doc-build
>>> make -C doc -B V=1 2>&1 | tee /tmp/xeno-doc-build.log
>>>
>>> And checked for warnings:
>>> rg -i warn /tmp/xeno-doc-build.log
>>>
>>> I didn't get any warnings for COBALT_DECL_TIME64.
>>>
>>
>> I guess that's because function docs are normally attached to the
>> implementation, not the declaration.
> 
> Normally COBALT_IMPL and COBALT_IMPL_TIME64 as well as COBALT_DECL and
> COBALT_DECL_TIME64 should be treated synchronously / in lock step.
> 
> COBALT_DECL_TIME64 is missing here, but maybe COBALT_DECL is not needed
> as well?
> 
> Florian

I had a look at the generated doc/doxygen/html/xeno3prm/index.html. When 
both COBALT_IMPL* and COBALT_DECL* are listed in 
xeno3prm-common.conf.in, searching for e.g., timer_create lists 2 
results, but they point to the same doc entry. Doxygen is indexing in 
this case the declarations from the headers and the implementations with 
documentation attached. See attachments.
I would suggest to drop COBALT_DECL to avoid those duplicates in the 
search results.

Clara
>>>

[-- Attachment #2: duplicate-result.png --]
[-- Type: image/png, Size: 31377 bytes --]

[-- Attachment #3: one-result.png --]
[-- Type: image/png, Size: 8727 bytes --]

Re: [PATCH 1/3] docs(xeno3): Fix doxygen parsing of COBALT_IMPL_TIME64 wrappers

[Florian Bezdeka]

On Thu, 2026-09-03 at 12:34 +0200, Clara Kowalsky wrote:
> On 9/3/26 11:48, Florian Bezdeka wrote:
> > On Thu, 2026-09-03 at 10:34 +0200, Clara Kowalsky wrote:
> > > The doxygen configuration lacks a definition for COBALT_IMPL_TIME64().
> > > Therefore doxygen does not see the expanded wrapper prototype in
> > > wrappers_time64.c and instead tries to match @param entries against the
> > > macro call.
> > > 
> > > This raises warnings at doc build such as
> > > 
> > > lib/cobalt/wrappers_time64.c:42: warning: argument 'clock_id' of command @param is not found in the argument list of COBALT_IMPL_TIME64(int, clock_getres, __clock_getres64,(clockid_t clock_id, struct timespec *tp))
> > > 
> > > as doxygen is seeing the raw macro form
> > > 
> > > COBALT_IMPL_TIME64(int, clock_getres, __clock_getres64,
> > >            (clockid_t clock_id, struct timespec *tp))
> > > 
> > > With the fix, doxygen rewrites the macro to
> > > 
> > > int clock_getres(clockid_t clock_id, struct timespec *tp)
> > 
> > Hm. The generated documentation should be "generic", right?
> > 
> > Depending on the chosen build configuration clock_getres OR
> > __clock_getres64 would be correct, but that is also hidden from the user
> > in glibc land, so we should probably do the same "hiding" here.
> > 
> > That said: LGTM.
> 
> The doxygen mapping should describe the stable public API, not whichever 
> internal symbol is emitted for a particular time ABI. So the generated 
> docs should expose only the generic API name clock_getres, regardless 
> which build variant is selected.
> > 
> > > 
> > > It uses the first macro argument (return type), the second (function
> > > name) and fourth (parameter list), but ignores the third (alternate
> > > function name, unneeded).
> > > By this, doxygen sees the actual public function prototype.
> > > See #18.
> > > 
> > > Signed-off-by: Clara Kowalsky <clara.kowalsky@siemens.com>
> > > ---
> > >   doc/doxygen/xeno3prm-common.conf.in | 1 +
> > >   1 file changed, 1 insertion(+)
> > > 
> > > diff --git a/doc/doxygen/xeno3prm-common.conf.in b/doc/doxygen/xeno3prm-common.conf.in
> > > index 71db05686..ee4ede10d 100644
> > > --- a/doc/doxygen/xeno3prm-common.conf.in
> > > +++ b/doc/doxygen/xeno3prm-common.conf.in
> > > @@ -647,6 +647,7 @@ PREDEFINED = DOXYGEN_CPP			\
> > >           "EXPORT_SYMBOL_GPL(symbol)=//"		\
> > >           "DECLARE_BITMAP(symbol, nr)=unsigned long symbol[BITS_TO_LONGS(nr)]" \
> > >   	"COBALT_IMPL(T,I,A)=T I A"		\
> > > +	"COBALT_IMPL_TIME64(T,I,N,A)=T I A"	\
> > >   	"COBALT_DECL(T,P)=T P"			\
> > 
> > No complains about COBALT_DECL_TIME64? Would have expected something
> > similar...
> 
> I built the documentation with:
> ./scripts/bootstrap
> ./configure --enable-doc-build
> make -C doc -B V=1 2>&1 | tee /tmp/xeno-doc-build.log
> 
> And checked for warnings:
> rg -i warn /tmp/xeno-doc-build.log
> 
> I didn't get any warnings for COBALT_DECL_TIME64.
> 
> > 
> > >   	"COBALT_SYSCALL(N,M,T,A)=T N A"		\
> > >   	"COBALT_SYSCALL_DECL(N,T,A)=T N A"
> > > -- 
> > > 2.55.0
> > 
> > Question to the complete series: Is
> > https://gitlab.com/Xenomai/xenomai3/xenomai/-/work_items/18 completely
> > closed with this series applied?
> 
> Yes, those 3 commits fix all doxygen warnings.
> 
Nice. Adding a

Closes: #18

tag to the commit description would auto-close the issue once the commit
reaches main/master.