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>

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

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;

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