doc: Fix sys_mutex and futex missing documentation

Adds API reference for sys_mutex and futex to mutex documentation, adds Doxygen documentation for SYS_MUTEX_DEFINE and fixes typo in futex documentation. Fixes zephyrproject-rtos#27829 Signed-off-by: Lauren Murphy <[email protected]>
laurenmurphyx64 · Feb 2, 2021 · fb3719e · fb3719e
1 parent 4c8760b
commit fb3719e
Show file tree

Hide file tree

Showing 3 changed files with 45 additions and 2 deletions.
diff --git a/doc/reference/kernel/synchronization/mutexes.rst b/doc/reference/kernel/synchronization/mutexes.rst
@@ -166,3 +166,25 @@ API Reference
 
 .. doxygengroup:: mutex_apis
    :project: Zephyr
+
+Futex API Reference
+*********************************
+
+k_futex is a lightweight mutual exclusion primitive designed to minimize
+kernel involvement. Uncontended operation relies only on atomic access
+to shared memory. k_futex are tracked as kernel objects and can live in
+user memory so that any access bypasses the kernel object permission
+management mechanism.
+
+.. doxygengroup:: futex_apis
+   :project: Zephyr
+
+User Mode Mutex API Reference
+*********************************
+
+sys_mutex behaves almost exactly like k_mutex, with the added advantage
+that a sys_mutex instance can reside in user memory. When user mode isn't
+enabled, sys_mutex behaves like k_mutex.
+
+.. doxygengroup:: user_mutex_apis
+   :project: Zephyr
diff --git a/include/kernel.h b/include/kernel.h
@@ -1945,8 +1945,8 @@ static inline void *z_impl_k_queue_peek_tail(struct k_queue *queue)
  * A k_futex is a lightweight mutual exclusion primitive designed
  * to minimize kernel involvement. Uncontended operation relies
  * only on atomic access to shared memory. k_futex are tracked as
- * kernel objects and can live in user memory so any access bypass
- * the kernel object permission management mechanism.
+ * kernel objects and can live in user memory so that any access
+ * bypasses the kernel object permission management mechanism.
  */
 struct k_futex {
 	atomic_t val;

diff --git a/include/sys/mutex.h b/include/sys/mutex.h
@@ -33,6 +33,23 @@ struct sys_mutex {
 	atomic_t val;
 };
 
+/**
+ * @defgroup user_mutex_apis User mode mutex APIs
+ * @ingroup kernel_apis
+ * @{
+ */
+
+/**
+ * @brief Statically define and initialize a sys_mutex
+ *
+ * The mutex can be accessed outside the module where it is defined using:
+ *
+ * @code extern struct sys_mutex <name>; @endcode
+ *
+ * Route this to memory domains using K_APP_DMEM().
+ *
+ * @param name Name of the mutex.
+ */
 #define SYS_MUTEX_DEFINE(name) \
 	struct sys_mutex name
 
@@ -153,6 +170,10 @@ static inline int sys_mutex_unlock(struct sys_mutex *mutex)
 
 #endif /* CONFIG_USERSPACE */
 
+/**
+ * @}
+ */
+
 #ifdef __cplusplus
 }
 #endif