Address review comments.

Perform the following changes:
- change definition of `void Mutex::lock(void)` to `osStatus Mutex::lock(void)`.
- change definition of `void Mutex::unlock()` to `osStatus Mutex::unlock()`.
- use MBED_ERROR1 macro to check the lock/unlock operation status.
- add notes in the description of lock/unlock functions: "This function asserts status of the lock/unlock operation (will not return in case of failure). Use of the return value is deprecated, as the return is expected to become void in the future.".
- modify/add description of the return value.
- remove reference to Mbed 6.
- make `lock(millisec)` deprecated in favour of lock(), trylock() and trylock_for() functions.

rtos/Mutex.cpp

@@ -51,14 +51,18 @@ void Mutex::constructor(const char *name)
     MBED_ASSERT(_id);
 }
 
-void Mutex::lock(void)
+osStatus Mutex::lock(void)
 {
     osStatus status = osMutexAcquire(_id, osWaitForever);
     if (osOK == status) {
         _count++;
     }
 
-    MBED_ASSERT(status == osOK);
+    if (status != osOK) {
+        MBED_ERROR1(MBED_MAKE_ERROR(MBED_MODULE_KERNEL, MBED_ERROR_CODE_MUTEX_LOCK_FAILED), "Mutex lock failed", status);
+    }
+
+    return osOK;
 }
 
 osStatus Mutex::lock(uint32_t millisec)
@@ -68,9 +72,13 @@ osStatus Mutex::lock(uint32_t millisec)
         _count++;
     }
 
-    MBED_ASSERT(status == osOK ||
-                (status == osErrorResource && millisec == 0) ||
-                (status == osErrorTimeout && millisec != osWaitForever));
+    bool success = (status == osOK ||
+                    (status == osErrorResource && millisec == 0) ||
+                    (status == osErrorTimeout && millisec != osWaitForever));
+
+    if (!success) {
+        MBED_ERROR1(MBED_MAKE_ERROR(MBED_MODULE_KERNEL, MBED_ERROR_CODE_MUTEX_LOCK_FAILED), "Mutex lock failed", status);
+    }
 
     return status;
 }
@@ -87,9 +95,13 @@ bool Mutex::trylock_for(uint32_t millisec)
         return true;
     }
 
-    MBED_ASSERT(status == osOK ||
-                (status == osErrorResource && millisec == 0) ||
-                (status == osErrorTimeout && millisec != osWaitForever));
+    bool success = (status == osOK ||
+                    (status == osErrorResource && millisec == 0) ||
+                    (status == osErrorTimeout && millisec != osWaitForever));
+
+    if (!success) {
+        MBED_ERROR1(MBED_MAKE_ERROR(MBED_MODULE_KERNEL, MBED_ERROR_CODE_MUTEX_LOCK_FAILED), "Mutex lock failed", status);
+    }
 
     return false;
 }
@@ -108,13 +120,17 @@ bool Mutex::trylock_until(uint64_t millisec)
     }
 }
 
-void Mutex::unlock()
+osStatus Mutex::unlock()
 {
     _count--;
 
     osStatus status = osMutexRelease(_id);
 
-    MBED_ASSERT(status == osOK);
+    if (status != osOK) {
+        MBED_ERROR1(MBED_MAKE_ERROR(MBED_MODULE_KERNEL, MBED_ERROR_CODE_MUTEX_UNLOCK_FAILED), "Mutex unlock failed", status);
+    }
+
+    return osOK;
 }
 
 osThreadId Mutex::get_owner()

rtos/Mutex.h

@@ -74,7 +74,6 @@ public:
     /** Create and Initialize a Mutex object
 
      @param name name to be used for this mutex. It has to stay allocated for the lifetime of the thread.
-
      @note You cannot call this function from ISR context.
     */
     Mutex(const char *name);
@@ -82,26 +81,31 @@ public:
     /**
       Wait until a Mutex becomes available.
 
+      @return  status code that indicates the execution status of the function:
+               @a osOK the mutex has been obtained.
+
       @note You cannot call this function from ISR context.
+      @note This function treats RTOS errors as fatal system errors, so can only return osOK.
+            Use of the return value is deprecated, as the return is expected to become void in the future.
      */
-    void lock(void);
+    osStatus lock(void);
 
     /**
       For backwards compatibility.
-      @deprecated Do not use this function. This function has been replaced with trylock_for and lock(void) functions.
+      @deprecated Do not use this function. This function has been replaced with lock(), trylock() and trylock_for() functions.
 
       Wait until a Mutex becomes available.
       @param   millisec  timeout value or 0 in case of no time-out.
       @return  status code that indicates the execution status of the function:
                @a osOK the mutex has been obtained.
                @a osErrorTimeout the mutex could not be obtained in the given time.
-               @a osErrorParameter internal error.
                @a osErrorResource the mutex could not be obtained when no timeout was specified.
-               @a osErrorISR this function cannot be called from the interrupt service routine.
 
       @note You cannot call this function from ISR context.
+      @note This function treats RTOS errors as fatal system errors, so can only return osOK or
+            osErrorResource in case when millisec is 0 or osErrorTimeout if millisec is not osWaitForever.
      */
-    MBED_DEPRECATED_SINCE("mbed-os-5.10.0", "Replaced with trylock_for and lock(void) functions")
+    MBED_DEPRECATED_SINCE("mbed-os-5.10.0", "Replaced with lock(), trylock() and trylock_for() functions")
     osStatus lock(uint32_t millisec);
 
     /** Try to lock the mutex, and return immediately
@@ -139,9 +143,14 @@ public:
     /**
       Unlock the mutex that has previously been locked by the same thread
 
+      @return status code that indicates the execution status of the function:
+              @a osOK the mutex has been released.
+
       @note You cannot call this function from ISR context.
+      @note This function treats RTOS errors as fatal system errors, so can only return osOK.
+            Use of the return value is deprecated, as the return is expected to become void in the future.
      */
-    void unlock();
+    osStatus unlock();
 
     /** Get the owner the this mutex
       @return  the current owner of this mutex.