From d922fed7f721c5fa61bde5d2dc86b9f092e8a352 Mon Sep 17 00:00:00 2001
From: Lauren Murphy <lauren.murphy@intel.com>
Date: Mon, 1 Feb 2021 21:24:47 -0600
Subject: [PATCH] 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 #27829

Signed-off-by: Lauren Murphy <lauren.murphy@intel.com>
---
 .../kernel/synchronization/mutexes.rst        | 22 +++++++++++++++++++
 include/kernel.h                              |  4 ++--
 include/sys/mutex.h                           | 21 ++++++++++++++++++
 3 files changed, 45 insertions(+), 2 deletions(-)

diff --git a/doc/reference/kernel/synchronization/mutexes.rst b/doc/reference/kernel/synchronization/mutexes.rst
index 42010402557..ee833919ebb 100644
--- 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
index b576cd08226..b2afb24c9b4 100644
--- 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
index 964795cf44b..ab98a5490b3 100644
--- 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