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 ; @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