[rtems commit] score: Document Futex Handler

[Sebastian Huber]

Module:    rtems
Branch:    master
Commit:    ce8f31ced53a11ec27633239f871657fb2a2680b
Changeset: http://git.rtems.org/rtems/commit/?id=ce8f31ced53a11ec27633239f871657fb2a2680b

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Tue Aug 31 14:26:47 2021 +0200

score: Document Futex Handler

The behaviour of the futex operations is defined by Linux:

https://man7.org/linux/man-pages/man2/futex.2.html

Use EAGIN instead of EWOULDBLOCK to be in line with the Linux man page.
These error numbers have the same value in Newlib.  Using the same error
numbers helps to avoid confusion.

When you look at the history of the Linux man page you see that they
replaced EWOULDBLOCK with EAGAIN over time.  At the time of the RTEMS
futex implementation they used EWOULDBLOCK.

---

 cpukit/score/src/futex.c | 42 ++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 40 insertions(+), 2 deletions(-)

diff --git a/cpukit/score/src/futex.c b/cpukit/score/src/futex.c
index b65a843..9bf4d8b 100644
--- a/cpukit/score/src/futex.c
+++ b/cpukit/score/src/futex.c
@@ -1,11 +1,12 @@
 /**
  * @file
  *
- * @ingroup RTEMSScore
+ * @ingroup RTEMSScoreFutex
  *
  * @brief This source file contains the implementation of
  *   _Futex_Wait() and _Futex_Wake().
  */
+
 /*
  * Copyright (c) 2015, 2016 embedded brains GmbH.  All rights reserved.
  *
@@ -20,6 +21,18 @@
  * http://www.rtems.org/license/LICENSE.
  */
 
+/**
+ * @defgroup RTEMSScoreFutex Futex Handler
+ *
+ * @ingroup RTEMSScore
+ *
+ * @brief This group contains the Futex Handler implementation.
+ *
+ * The behaviour of the futex operations is defined by Linux, see also:
+ *
+ * https://man7.org/linux/man-pages/man2/futex.2.html
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -84,6 +97,22 @@ static void _Futex_Queue_release(
   _ISR_Local_enable( level );
 }
 
+/**
+ * @brief Performs the ``FUTEX_WAIT`` operation.
+ *
+ * @param[in, out] _futex is the futex object.
+ *
+ * @param[in] uaddr is the address to the futex state.
+ *
+ * @param val is the expected futex state value.
+ *
+ * @retval 0 Returns zero if the futex state is equal to the expected value.
+ *   In this case the calling thread is enqueued on the thread queue of the
+ *   futex object.
+ *
+ * @retval EAGAIN Returns EAGAIN if the futex state is not equal to the
+ *   expected value.
+ */
 int _Futex_Wait( struct _Futex_Control *_futex, int *uaddr, int val )
 {
   Futex_Control        *futex;
@@ -113,7 +142,7 @@ int _Futex_Wait( struct _Futex_Control *_futex, int *uaddr, int val )
     eno = 0;
   } else {
     _Futex_Queue_release( futex, level, &queue_context );
-    eno = EWOULDBLOCK;
+    eno = EAGAIN;
   }
 
   return eno;
@@ -143,6 +172,15 @@ static Thread_Control *_Futex_Flush_filter(
   return the_thread;
 }
 
+/**
+ * @brief Performs the ``FUTEX_WAKE`` operation.
+ *
+ * @param[in, out] _futex is the futex object.
+ *
+ * @param count is the maximum count of threads to wake up.
+ *
+ * @return Returns the count of woken up threads.
+ */
 int _Futex_Wake( struct _Futex_Control *_futex, int count )
 {
   Futex_Control *futex;