[PATCH 0/4] Alchemy fixes around timeouts

[PATCH 0/4] Alchemy fixes around timeouts

[Jan Kiszka]

See patches for details

Jan

Jan Kiszka (4):
  lib/alchemy: Fix rt_pipe_read* with timeouts
  lib/alchemy/testsuite: Fix pipe-1 test case
  lib/alchemy/testsuite: Extend pipe-1 test by timeout checks
  lib/alchemy: Fix/clarify documentation of *_timed functions regarding
    abs_timeout

 include/alchemy/pipe.h         |  8 +----
 lib/alchemy/buffer.c           | 28 ++++++----------
 lib/alchemy/cond.c             | 14 +++-----
 lib/alchemy/event.c            | 16 ++++-----
 lib/alchemy/heap.c             | 16 ++++-----
 lib/alchemy/mutex.c            | 12 +++----
 lib/alchemy/pipe.c             | 61 +++++++++++++++++++++++++++-------
 lib/alchemy/queue.c            | 32 +++++++-----------
 lib/alchemy/sem.c              | 16 ++++-----
 lib/alchemy/task.c             | 27 ++++++---------
 lib/alchemy/testsuite/pipe-1.c | 35 ++++++++++++++++++-
 11 files changed, 143 insertions(+), 122 deletions(-)

-- 
2.31.1

[PATCH 1/4] lib/alchemy: Fix rt_pipe_read* with timeouts

[Jan Kiszka]

From: Jan Kiszka <jan.kiszka@siemens.com>

The underlying IPC driver takes relative timeouts, but
rt_pipe_read_timed so far submitted absolute ones. This fixes this
function and also adds a non-inline rt_pipe_read to avoid pointless
conversions from relative to absolute and then to relative again.

Reported-by: Mauro S. <mau.salvi@tin.it>
Signed-off-by: Jan Kiszka <jan.kiszka@siemens.com>
---
 include/alchemy/pipe.h |  8 +-------
 lib/alchemy/pipe.c     | 45 ++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 44 insertions(+), 9 deletions(-)

diff --git a/include/alchemy/pipe.h b/include/alchemy/pipe.h
index a9eaf6c77c..4ae24f9817 100644
--- a/include/alchemy/pipe.h
+++ b/include/alchemy/pipe.h
@@ -64,14 +64,8 @@ ssize_t rt_pipe_read_until(RT_PIPE *pipe,
 				  alchemy_abs_timeout(timeout, &ts));
 }
 
-static inline
 ssize_t rt_pipe_read(RT_PIPE *pipe,
-		     void *buf, size_t size, RTIME timeout)
-{
-	struct timespec ts;
-	return rt_pipe_read_timed(pipe, buf, size,
-				  alchemy_rel_timeout(timeout, &ts));
-}
+		     void *buf, size_t size, RTIME timeout);
 
 ssize_t rt_pipe_write(RT_PIPE *pipe,
 		      const void *buf, size_t size, int mode);
diff --git a/lib/alchemy/pipe.c b/lib/alchemy/pipe.c
index 54d0164139..4b2c389806 100644
--- a/lib/alchemy/pipe.c
+++ b/lib/alchemy/pipe.c
@@ -310,6 +310,44 @@ out:
  *
  * @apitags{xthread-nowait, switch-primary}
  */
+ssize_t rt_pipe_read(RT_PIPE *pipe,
+		     void *buf, size_t size, RTIME timeout)
+{
+	struct alchemy_pipe *pcb;
+	int err = 0, flags;
+	struct timespec ts;
+	struct timeval tv;
+	ssize_t ret;
+
+	pcb = find_alchemy_pipe(pipe, &err);
+	if (pcb == NULL)
+		return err;
+
+	if (timeout == TM_NONBLOCK)
+		flags = MSG_DONTWAIT;
+	else {
+		if (!threadobj_current_p())
+			return -EPERM;
+		if (timeout != TM_INFINITE) {
+			clockobj_ticks_to_timespec(&alchemy_clock, timeout,
+						   &ts);
+			tv.tv_sec = ts.tv_sec;
+			tv.tv_usec = ts.tv_nsec / 1000;
+		} else {
+			tv.tv_sec = 0;
+			tv.tv_usec = 0;
+		}
+		__RT(setsockopt(pcb->sock, SOL_SOCKET,
+				SO_RCVTIMEO, &tv, sizeof(tv)));
+		flags = 0;
+	}
+
+	ret = __RT(recvfrom(pcb->sock, buf, size, flags, NULL, 0));
+	if (ret < 0)
+		ret = -errno;
+
+	return ret;
+}
 
 /**
  * @fn ssize_t rt_pipe_read_until(RT_PIPE *pipe, void *buf, size_t size, RTIME abs_timeout)
@@ -394,6 +432,7 @@ ssize_t rt_pipe_read_timed(RT_PIPE *pipe,
 			   void *buf, size_t size,
 			   const struct timespec *abs_timeout)
 {
+	struct timespec now, timeout;
 	struct alchemy_pipe *pcb;
 	int err = 0, flags;
 	struct timeval tv;
@@ -409,8 +448,10 @@ ssize_t rt_pipe_read_timed(RT_PIPE *pipe,
 		if (!threadobj_current_p())
 			return -EPERM;
 		if (abs_timeout) {
-			tv.tv_sec = abs_timeout->tv_sec;
-			tv.tv_usec = abs_timeout->tv_nsec / 1000;
+			__RT(clock_gettime(CLOCK_COPPERPLATE, &now));
+			timespec_sub(&timeout, abs_timeout, &now);
+			tv.tv_sec = timeout.tv_sec;
+			tv.tv_usec = timeout.tv_nsec / 1000;
 		} else {
 			tv.tv_sec = 0;
 			tv.tv_usec = 0;
-- 
2.31.1

[PATCH 2/4] lib/alchemy/testsuite: Fix pipe-1 test case

[Jan Kiszka]

From: Jan Kiszka <jan.kiszka@siemens.com>

A missing initialization led to early termination and crashes.

Signed-off-by: Jan Kiszka <jan.kiszka@siemens.com>
---
 lib/alchemy/testsuite/pipe-1.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/alchemy/testsuite/pipe-1.c b/lib/alchemy/testsuite/pipe-1.c
index 7272079eec..3f821efe41 100644
--- a/lib/alchemy/testsuite/pipe-1.c
+++ b/lib/alchemy/testsuite/pipe-1.c
@@ -23,7 +23,7 @@ struct pipe_message {
 static void realtime_task(void *arg)
 {
 	struct pipe_message m;
-	int ret, seq;
+	int ret, seq = 0;
 
 	traceobj_enter(&trobj);
 
-- 
2.31.1

[PATCH 3/4] lib/alchemy/testsuite: Extend pipe-1 test by timeout checks

[Jan Kiszka]

From: Jan Kiszka <jan.kiszka@siemens.com>

Validates all three rt_pipe_read functions /wrt non-blocking read as
well as timeouts.

Signed-off-by: Jan Kiszka <jan.kiszka@siemens.com>
---
 lib/alchemy/testsuite/pipe-1.c | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/lib/alchemy/testsuite/pipe-1.c b/lib/alchemy/testsuite/pipe-1.c
index 3f821efe41..4202be2bac 100644
--- a/lib/alchemy/testsuite/pipe-1.c
+++ b/lib/alchemy/testsuite/pipe-1.c
@@ -73,7 +73,10 @@ static void *regular_thread(void *arg)
 
 int main(int argc, char *const argv[])
 {
+	struct timespec ts_start, ts_end, ts_timeout, ts_delta;
 	struct pipe_message m;
+	RTIME start, end;
+	SRTIME timeout;
 	int ret;
 
 	traceobj_init(&trobj, argv[0], 0);
@@ -97,6 +100,36 @@ int main(int argc, char *const argv[])
 	ret = rt_pipe_read(&mpipe, &m, sizeof(m), TM_NONBLOCK);
 	traceobj_check(&trobj, ret, -EWOULDBLOCK);
 
+	ret = rt_pipe_read_until(&mpipe, &m, sizeof(m), TM_NONBLOCK);
+	traceobj_check(&trobj, ret, -EWOULDBLOCK);
+
+	ts_timeout.tv_sec = 0;
+	ts_timeout.tv_nsec = 0;
+	ret = rt_pipe_read_timed(&mpipe, &m, sizeof(m), &ts_timeout);
+	traceobj_check(&trobj, ret, -EWOULDBLOCK);
+
+	start = rt_timer_read();
+	timeout = rt_timer_ns2ticks(100000000);
+	ret = rt_pipe_read(&mpipe, &m, sizeof(m), timeout);
+	end = rt_timer_read();
+	traceobj_assert(&trobj, end - start >= timeout);
+	traceobj_assert(&trobj, end - start < timeout + rt_timer_ns2ticks(5000000));
+
+	start = rt_timer_read();
+	timeout = start + rt_timer_ns2ticks(100000000);
+	ret = rt_pipe_read_until(&mpipe, &m, sizeof(m), timeout);
+	end = rt_timer_read();
+	traceobj_assert(&trobj, end >= timeout);
+	traceobj_assert(&trobj, end < timeout + rt_timer_ns2ticks(5000000));
+
+	clock_gettime(CLOCK_COPPERPLATE, &ts_start);
+	timespec_adds(&ts_timeout, &ts_start, 100000000);
+	ret = rt_pipe_read_timed(&mpipe, &m, sizeof(m), &ts_timeout);
+	clock_gettime(CLOCK_COPPERPLATE, &ts_end);
+	timespec_sub(&ts_delta, &ts_end, &ts_timeout);
+	traceobj_assert(&trobj, ts_delta.tv_sec >= 0);
+	traceobj_assert(&trobj, ts_delta.tv_nsec < 5000000);
+
 	ret = pthread_create(&t_reg, NULL, regular_thread, NULL);
 	traceobj_check(&trobj, ret, 0);
 
-- 
2.31.1

[PATCH 4/4] lib/alchemy: Fix/clarify documentation of *_timed functions regarding abs_timeout

[Jan Kiszka]

From: Jan Kiszka <jan.kiszka@siemens.com>

abs_timeout is not provided in ticks but actually seconds/nanoseconds.
Clarify this and remove the related wrong note from those functions
headers.

Signed-off-by: Jan Kiszka <jan.kiszka@siemens.com>
---
 lib/alchemy/buffer.c | 28 ++++++++++------------------
 lib/alchemy/cond.c   | 14 +++++---------
 lib/alchemy/event.c  | 16 ++++++----------
 lib/alchemy/heap.c   | 16 ++++++----------
 lib/alchemy/mutex.c  | 12 ++++--------
 lib/alchemy/pipe.c   | 16 ++++++----------
 lib/alchemy/queue.c  | 32 ++++++++++++--------------------
 lib/alchemy/sem.c    | 16 ++++++----------
 lib/alchemy/task.c   | 27 ++++++++++-----------------
 9 files changed, 65 insertions(+), 112 deletions(-)

diff --git a/lib/alchemy/buffer.c b/lib/alchemy/buffer.c
index 4e814459e5..1fa281f3a2 100644
--- a/lib/alchemy/buffer.c
+++ b/lib/alchemy/buffer.c
@@ -396,12 +396,12 @@ out:
  * error value. However, short reads are allowed when a potential
  * deadlock situation is detected (see note below).
  *
- * @param abs_timeout An absolute date expressed in clock ticks,
- * specifying a time limit to wait for a message to be available from
- * the buffer (see note). Passing NULL causes the caller to block
- * indefinitely until enough data is available. Passing { .tv_sec = 0,
- * .tv_nsec = 0 } causes the service to return immediately without
- * blocking in case not enough data is available.
+ * @param abs_timeout An absolute date expressed in seconds / nanoseconds,
+ * based on the Alchemy clock, specifying a time limit to wait for a
+ * message to be available from the buffer. Passing NULL causes the caller
+ * to block indefinitely until enough data is available. Passing
+ * { .tv_sec = 0, .tv_nsec = 0 } causes the service to return immediately
+ * without blocking in case not enough data is available.
  *
  * @return The number of bytes read from the buffer is returned upon
  * success. Otherwise:
@@ -449,10 +449,6 @@ out:
  * should likely be fixed, in order to eliminate such condition.
  *
  * @apitags{xthread-nowait, switch-primary}
- *
- * @note @a abs_timeout is interpreted as a multiple of the Alchemy
- * clock resolution (see --alchemy-clock-resolution option, defaults
- * to 1 nanosecond).
  */
 ssize_t rt_buffer_read_timed(RT_BUFFER *bf,
 			     void *ptr, size_t size,
@@ -638,10 +634,10 @@ out:
  * value, in which case the buffer is left untouched, and zero is
  * returned to the caller.
  *
- * @param abs_timeout An absolute date expressed in clock ticks,
- * specifying a time limit to wait for enough buffer space to be
- * available to hold the message (see note). Passing NULL causes the
- * caller to block indefinitely until enough buffer space is
+ * @param abs_timeout An absolute date expressed in seconds / nanoseconds,
+ * based on the Alchemy clock, specifying a time limit to wait for enough
+ * buffer space to be available to hold the message. Passing NULL causes
+ * the caller to block indefinitely until enough buffer space is
  * available. Passing { .tv_sec = 0, .tv_nsec = 0 } causes the service
  * to return immediately without blocking in case of buffer space
  * shortage.
@@ -672,10 +668,6 @@ out:
  * called from a Xenomai thread.
  *
  * @apitags{xthread-nowait, switch-primary}
- *
- * @note @a abs_timeout is interpreted as a multiple of the Alchemy
- * clock resolution (see --alchemy-clock-resolution option, defaults
- * to 1 nanosecond).
  */
 ssize_t rt_buffer_write_timed(RT_BUFFER *bf,
 			      const void *ptr, size_t size,
diff --git a/lib/alchemy/cond.c b/lib/alchemy/cond.c
index 8c9adbb83e..e4ad71454f 100644
--- a/lib/alchemy/cond.c
+++ b/lib/alchemy/cond.c
@@ -332,11 +332,11 @@ int rt_cond_broadcast(RT_COND *cond)
  * @param mutex The address of the mutex serializing the access to the
  * shared data.
  *
- * @param abs_timeout An absolute date expressed in clock ticks,
- * specifying a time limit to wait for the condition variable to be
- * signaled  (see note). Passing NULL causes the caller to
- * block indefinitely. Passing { .tv_sec = 0, .tv_nsec = 0 } causes
- * the caller to return immediately without block.
+ * @param abs_timeout An absolute date expressed in seconds / nanoseconds,
+ * based on the Alchemy clock, specifying a time limit to wait for the
+ * condition variable to be signaled. Passing NULL causes the caller to
+ * block indefinitely. Passing { .tv_sec = 0, .tv_nsec = 0 } causes the
+ * caller to return immediately without block.
  *
  * @return Zero is returned upon success. Otherwise:
  *
@@ -360,10 +360,6 @@ int rt_cond_broadcast(RT_COND *cond)
  * called from a Xenomai thread.
  *
  * @apitags{xthread-only, switch-primary}
- *
- * @note @a abs_timeout is interpreted as a multiple of the Alchemy
- * clock resolution (see --alchemy-clock-resolution option, defaults
- * to 1 nanosecond).
  */
 int rt_cond_wait_timed(RT_COND *cond, RT_MUTEX *mutex,
 		       const struct timespec *abs_timeout)
diff --git a/lib/alchemy/event.c b/lib/alchemy/event.c
index 40bd15e9f1..8ccd99b860 100644
--- a/lib/alchemy/event.c
+++ b/lib/alchemy/event.c
@@ -352,12 +352,12 @@ out:
  * means that the request is fulfilled when at all bits set into @a
  * mask are set in the current event mask.
  *
- * @param abs_timeout An absolute date expressed in clock ticks,
- * specifying a time limit to wait for the request to be satisfied
- * (see note). Passing NULL causes the caller to block indefinitely
- * until the request is satisfied. Passing { .tv_sec = 0, .tv_nsec = 0
- * } causes the service to return without blocking in case the request
- * cannot be satisfied immediately.
+ * @param abs_timeout An absolute date expressed in seconds / nanoseconds,
+ * based on the Alchemy clock, specifying a time limit to wait for the
+ * request to be satisfied. Passing NULL causes the caller to block
+ * indefinitely until the request is satisfied. Passing
+ * { .tv_sec = 0, .tv_nsec = 0 } causes the service to return without
+ * blocking in case the request cannot be satisfied immediately.
  *
  * @return Zero is returned upon success. Otherwise:
  *
@@ -382,10 +382,6 @@ out:
  * called from a Xenomai thread.
  *
  * @apitags{xthread-nowait, switch-primary}
- *
- * @note @a abs_timeout value is interpreted as a multiple of the
- * Alchemy clock resolution (see --alchemy-clock-resolution option,
- * defaults to 1 nanosecond).
  */
 int rt_event_wait_timed(RT_EVENT *event,
 			unsigned int mask, unsigned int *mask_r,
diff --git a/lib/alchemy/heap.c b/lib/alchemy/heap.c
index 4715375c3f..c658c46b2e 100644
--- a/lib/alchemy/heap.c
+++ b/lib/alchemy/heap.c
@@ -376,12 +376,12 @@ out:
  * case, the same block covering the entire heap space is returned to
  * all callers of this service.
  *
- * @param abs_timeout An absolute date expressed in clock ticks,
- * specifying a time limit to wait for a block of the requested size
- * to be available from the heap (see note). Passing NULL causes the
- * caller to block indefinitely until a block is available. Passing {
- * .tv_sec = 0, .tv_nsec = 0 } causes the service to return
- * immediately without blocking in case a block is not available.
+ * @param abs_timeout An absolute date expressed in seconds / nanoseconds,
+ * based on the Alchemy clock, specifying a time limit to wait for a block
+ * of the requested size to be available from the heap. Passing NULL causes
+ * the caller to block indefinitely until a block is available. Passing
+ * { .tv_sec = 0, .tv_nsec = 0 } causes the service to return immediately
+ * without blocking in case a block is not available.
  *
  * @param blockp A pointer to a memory location which will be written
  * upon success with the address of the allocated block, or the start
@@ -420,10 +420,6 @@ out:
  * next page size. The allocation page size is currently 512 bytes
  * long (HOBJ_PAGE_SIZE), which means that any request larger than 1k
  * will be rounded up to the next 512 byte boundary.
- *
- * @note @a abs_timeout is interpreted as a multiple of the Alchemy
- * clock resolution (see --alchemy-clock-resolution option, defaults
- * to 1 nanosecond).
  */
 int rt_heap_alloc_timed(RT_HEAP *heap,
 			size_t size, const struct timespec *abs_timeout,
diff --git a/lib/alchemy/mutex.c b/lib/alchemy/mutex.c
index 42cd1375b3..09eb1364ef 100644
--- a/lib/alchemy/mutex.c
+++ b/lib/alchemy/mutex.c
@@ -261,10 +261,10 @@ out:
  *
  * @param mutex The mutex descriptor.
  *
- * @param abs_timeout An absolute date expressed in clock ticks,
- * specifying a time limit to wait for the mutex to be available (see
- * note). Passing NULL the caller to block indefinitely. Passing {
- * .tv_sec = 0, .tv_nsec = 0 } causes the service to return
+ * @param abs_timeout An absolute date expressed in seconds / nanoseconds,
+ * based on the Alchemy clock, specifying a time limit to wait for the
+ * mutex to be available. Passing NULL the caller to block indefinitely.
+ * Passing { .tv_sec = 0, .tv_nsec = 0 } causes the service to return
  * immediately without blocking in case @a mutex is already locked by
  * another task.
  *
@@ -294,10 +294,6 @@ out:
  * Over the Cobalt core, an Alchemy task with priority zero keeps
  * running in primary mode until it releases the mutex, at which point
  * it is switched back to secondary mode automatically.
- *
- * @note @a abs_timeout is interpreted as a multiple of the Alchemy
- * clock resolution (see --alchemy-clock-resolution option, defaults
- * to 1 nanosecond).
  */
 int rt_mutex_acquire_timed(RT_MUTEX *mutex,
 			   const struct timespec *abs_timeout)
diff --git a/lib/alchemy/pipe.c b/lib/alchemy/pipe.c
index 4b2c389806..c334349aa0 100644
--- a/lib/alchemy/pipe.c
+++ b/lib/alchemy/pipe.c
@@ -393,12 +393,12 @@ ssize_t rt_pipe_read(RT_PIPE *pipe,
  * be lost. If @a size is zero, this call returns immediately with no
  * other action.
  *
- * @param abs_timeout An absolute date expressed in clock ticks,
- * specifying a time limit to wait for a message to be available from
- * the pipe (see note). Passing NULL causes the caller to block
- * indefinitely until a message is available. Passing { .tv_sec = 0,
- * .tv_nsec = 0 } causes the service to return immediately without
- * blocking in case no message is available.
+ * @param abs_timeout An absolute date expressed in seconds / nanoseconds,
+ * based on the Alchemy clock, specifying a time limit to wait for a
+ * message to be available from the pipe. Passing NULL causes the caller
+ * to block indefinitely until a message is available. Passing
+ * { .tv_sec = 0, .tv_nsec = 0 } causes the service to return immediately
+ * without blocking in case no message is available.
  *
  * @return The number of bytes available from the received message is
  * returned upon success. Otherwise:
@@ -423,10 +423,6 @@ ssize_t rt_pipe_read(RT_PIPE *pipe,
  * called from a Xenomai thread.
  *
  * @apitags{xthread-nowait, switch-primary}
- *
- * @note @a abs_timeout is interpreted as a multiple of the Alchemy
- * clock resolution (see --alchemy-clock-resolution option, defaults
- * to 1 nanosecond).
  */
 ssize_t rt_pipe_read_timed(RT_PIPE *pipe,
 			   void *buf, size_t size,
diff --git a/lib/alchemy/queue.c b/lib/alchemy/queue.c
index b720059214..c45e424547 100644
--- a/lib/alchemy/queue.c
+++ b/lib/alchemy/queue.c
@@ -764,12 +764,12 @@ out:
  * with the address of the received message, upon success. Once
  * consumed, the message space should be freed using rt_queue_free().
  *
- * @param abs_timeout An absolute date expressed in clock ticks,
- * specifying a time limit to wait for a message to be available from
- * the queue (see note). Passing NULL causes the caller to block
- * indefinitely until a message is available. Passing { .tv_sec = 0,
- * .tv_nsec = 0 } causes the service to return immediately without
- * blocking in case no message is available.
+ * @param abs_timeout An absolute date expressed in seconds / nanoseconds,
+ * based on the Alchemy clock, specifying a time limit to wait for a
+ * message to be available from the queue. Passing NULL causes the caller
+ * to block indefinitely until a message is available. Passing
+ * { .tv_sec = 0, .tv_nsec = 0 } causes the service to return immediately
+ * without blocking in case no message is available.
  *
  * @return The number of bytes available from the received message is
  * returned upon success. Zero is a possible value corresponding to a
@@ -796,10 +796,6 @@ out:
  * called from a Xenomai thread.
  *
  * @apitags{xthread-nowait, switch-primary}
- *
- * @note @a abs_timeout is interpreted as a multiple of the Alchemy
- * clock resolution (see --alchemy-clock-resolution option, defaults
- * to 1 nanosecond).
  */
 ssize_t rt_queue_receive_timed(RT_QUEUE *queue, void **bufp,
 			       const struct timespec *abs_timeout)
@@ -929,12 +925,12 @@ out:
  * @param size The length in bytes of the memory area pointed to by @a
  * buf. Messages larger than @a size are truncated appropriately.
  *
- * @param abs_timeout An absolute date expressed in clock ticks,
- * specifying a time limit to wait for a message to be available from
- * the queue (see note). Passing NULL causes the caller to block
- * indefinitely until a message is available. Passing { .tv_sec = 0,
- * .tv_nsec = 0 } causes the service to return immediately without
- * blocking in case no message is available.
+ * @param abs_timeout An absolute date expressed in seconds / nanoseconds,
+ * based on the Alchemy clock, specifying a time limit to wait for a
+ * message to be available from the queue. Passing NULL causes the
+ * caller to block indefinitely until a message is available. Passing
+ * { .tv_sec = 0, .tv_nsec = 0 } causes the service to return immediately
+ * without blocking in case no message is available.
  *
  * @return The number of bytes copied to @a buf is returned upon
  * success. Zero is a possible value corresponding to a zero-sized
@@ -960,10 +956,6 @@ out:
  * called from a Xenomai thread.
  *
  * @apitags{xthread-nowait, switch-primary}
- *
- * @note @a abs_timeout is interpreted as a multiple of the Alchemy
- * clock resolution (see --alchemy-clock-resolution option, defaults
- * to 1 nanosecond).
  */
 ssize_t rt_queue_read_timed(RT_QUEUE *queue,
 			    void *buf, size_t size,
diff --git a/lib/alchemy/sem.c b/lib/alchemy/sem.c
index 9e43c6b318..497756ebd2 100644
--- a/lib/alchemy/sem.c
+++ b/lib/alchemy/sem.c
@@ -336,12 +336,12 @@ out:
  *
  * @param sem The semaphore descriptor.
  *
- * @param abs_timeout An absolute date expressed in clock ticks,
- * specifying a time limit to wait for the request to be satisfied
- * (see note). Passing NULL causes the caller to block indefinitely
- * until the request is satisfied. Passing { .tv_sec = 0, .tv_nsec = 0
- * } causes the service to return without blocking in case the request
- * cannot be satisfied immediately.
+ * @param abs_timeout An absolute date expressed in seconds / nanoseconds,
+ * based on the Alchemy clock, specifying a time limit to wait for the
+ * request to be satisfied. Passing NULL causes the caller to block
+ * indefinitely until the request is satisfied. Passing { .tv_sec = 0,
+ * .tv_nsec = 0 } causes the service to return without blocking in case
+ * the request cannot be satisfied immediately.
  *
  * @return Zero is returned upon success. Otherwise:
  *
@@ -365,10 +365,6 @@ out:
  * called from a Xenomai thread.
  *
  * @apitags{xthread-nowait, switch-primary}
- *
- * @note @a abs_timeout is interpreted as a multiple of the Alchemy
- * clock resolution (see --alchemy-clock-resolution option, defaults
- * to 1 nanosecond).
  */
 int rt_sem_p_timed(RT_SEM *sem, const struct timespec *abs_timeout)
 {
diff --git a/lib/alchemy/task.c b/lib/alchemy/task.c
index 9afa2af579..9e6101df59 100644
--- a/lib/alchemy/task.c
+++ b/lib/alchemy/task.c
@@ -1678,13 +1678,13 @@ out:
  * Upon return, mcb_r->opcode will contain the status code sent back
  * from the remote task using rt_task_reply(), or zero if unspecified.
  *
- * @param abs_timeout An absolute date expressed in clock ticks,
- * specifying a time limit to wait for the recipient task to reply to
- * the initial message (see note). Passing NULL causes the caller to
- * block indefinitely until a reply is received.  Passing { .tv_sec =
- * 0, .tv_nsec = 0 } causes the service to return without blocking in
- * case the recipient task is not waiting for messages at the time of
- * the call.
+ * @param abs_timeout An absolute date expressed in seconds / nanoseconds,
+ * based on the Alchemy clock, specifying a time limit to wait for the
+ * recipient task to reply to the initial message. Passing NULL causes
+ * the caller to block indefinitely until a reply is received. Passing
+ * { .tv_sec = 0, .tv_nsec = 0 } causes the service to return without
+ * blocking in case the recipient task is not waiting for messages at
+ * the time of the call.
  *
  * @return A positive value is returned upon success, representing the
  * length (in bytes) of the reply message returned by the remote
@@ -1714,10 +1714,6 @@ out:
  * task.
  *
  * @apitags{xthread-only, switch-primary}
- *
- * @note @a abs_timeout is interpreted as a multiple of the Alchemy
- * clock resolution (see --alchemy-clock-resolution option, defaults
- * to 1 nanosecond).
  */
 ssize_t rt_task_send_timed(RT_TASK *task,
 			   RT_TASK_MCB *mcb_s, RT_TASK_MCB *mcb_r,
@@ -1892,8 +1888,9 @@ out:
  * Upon return, mcb_r->opcode will contain the operation code sent
  * from the remote task using rt_task_send().
  *
- * @param abs_timeout The number of clock ticks to wait for receiving
- * a message (see note). Passing NULL causes the caller to block
+ * @param abs_timeout An absolute date expressed in seconds / nanoseconds,
+ * based on the Alchemy clock, specifying the time limit to wait for
+ * receiving a message. Passing NULL causes the caller to block
  * indefinitely until a remote task eventually sends a message.
  * Passing { .tv_sec = 0, .tv_nsec = 0 } causes the service to return
  * immediately without waiting if no remote task is currently waiting
@@ -1921,10 +1918,6 @@ out:
  * timeout.
  *
  * @apitags{xthread-only, switch-primary}
- *
- * @note @a abs_timeout is interpreted as a multiple of the Alchemy
- * clock resolution (see --alchemy-clock-resolution option, defaults
- * to 1 nanosecond).
  */
 int rt_task_receive_timed(RT_TASK_MCB *mcb_r,
 			  const struct timespec *abs_timeout)
-- 
2.31.1