From b05cecc7dac13fcbe5fd879c0c0dbd3cba57dff7 Mon Sep 17 00:00:00 2001
From: Christian Mauderer <christian.mauderer@embedded-brains.de>
Date: Wed, 26 May 2021 11:32:55 +0200
Subject: c-users: Add rtems_*mutex_try_lock

Closes #4440.
---
 c-user/self_contained_objects.rst | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/c-user/self_contained_objects.rst b/c-user/self_contained_objects.rst
index 0be1423..10d2b91 100644
--- a/c-user/self_contained_objects.rst
+++ b/c-user/self_contained_objects.rst
@@ -132,6 +132,10 @@ copies of the object in calls to
 
 * :c:func:`rtems_recursive_mutex_lock`,
 
+* :c:func:`rtems_mutex_try_lock`,
+
+* :c:func:`rtems_recursive_mutex_try_lock`,
+
 * :c:func:`rtems_mutex_unlock`,
 
 * :c:func:`rtems_recursive_mutex_unlock`,
@@ -262,6 +266,37 @@ NOTES:
 
     \clearpage
 
+Try to lock the mutex
+---------------------
+
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        int rtems_mutex_try_lock(
+          rtems_mutex *mutex
+        );
+
+        int rtems_recursive_mutex_try_lock(
+          rtems_recursive_mutex *mutex
+        );
+
+DESCRIPTION:
+    Tries to lock the ``mutex``. In case the mutex is not locked, it will be
+    locked and the function returns with a return value of ``0``. If the mutex
+    is already locked, the function will return with a value of ``EBUSY``.
+
+NOTES:
+    This function must be called from thread context with interrupts enabled.
+
+    For recursively locking a mutex, please also see the notes for
+    :c:func:`rtems_mutex_lock` and :c:func:`rtems_recursive_mutex_lock`.
+
+    Each mutex lock operation must have a corresponding unlock operation.
+
+.. raw:: latex
+
+    \clearpage
+
 Unlock the mutex
 ----------------
 
-- 
cgit v1.2.3