IAR: Add OS Interface API header and documentation

ARM.CMSIS-Compiler.pdsc

@@ -224,6 +224,13 @@
         <file category="header" name="include/gcc/retarget_os.h"/>
       </files>
     </api>
+    <api Cclass="CMSIS-Compiler" Cgroup="OS Interface" Capiversion="1.0.0" exclusive="1" condition="IAR CortexDevice">
+      <description>Standard C Library OS Retarget Interface</description>
+      <files>
+        <file category="doc" name="documentation/html/group__retarget__os__iarclib.html"/>
+        <file category="header" name="include/iarcc/retarget_os.h"/>
+      </files>
+    </api>
   </apis>
 
   <components>

documentation/doxygen/compiler.dxy.in

@@ -1007,12 +1007,14 @@ INPUT                  = ./src/mainpage.md                 \
                          ./src/ref_retarget_fs.txt         \
                          ./src/ref_retarget_os.txt         \
                          ./src/ref_retarget_os_armclib.txt \
+                         ./src/ref_retarget_os_iarclib.txt \
                          ./src/ref_retarget_os_newlib.txt  \
                          ./src/ref_retarget_stderr.txt     \
                          ./src/ref_retarget_stdin.txt      \
                          ./src/ref_retarget_stdout.txt     \
                          ./src/ref_retarget_tty.txt        \
                          ../../include/armcc/retarget_os.h \
+                         ../../include/iarcc/retarget_os.h \
                          ../../include/gcc/retarget_os.h   \
                          ../../include/retarget_fs.h       \
                          ../../include/retarget_stderr.h   \

documentation/doxygen/src/ref_retarget_os_iarclib.txt

@@ -0,0 +1,27 @@
+
+/**
+\defgroup retarget_os_iarclib IAR C Library
+\ingroup os_interface_api
+\brief Declarations of types and functions for integrating an RTOS with the IAR Standard C Library
+@{
+*/
+
+void __iar_system_Mtxinit(__iar_Rmtx *lock);
+
+void __iar_system_Mtxdst(__iar_Rmtx *lock);
+
+void __iar_system_Mtxlock(__iar_Rmtx *lock);
+
+void __iar_system_Mtxunlock(__iar_Rmtx *lock);
+
+void __iar_file_Mtxinit(__iar_Rmtx *lock);
+
+void __iar_file_Mtxdst(__iar_Rmtx *lock);
+
+void __iar_file_Mtxlock(__iar_Rmtx *lock);
+
+void __iar_file_Mtxunlock(__iar_Rmtx *lock);
+
+/**
+@}
+*/

include/iarcc/retarget_os.h

@@ -0,0 +1,69 @@
+/*
+ * Copyright (C) 2026 ARM Limited or its affiliates. All rights reserved.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the License); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an AS IS BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef RETARGET_OS_H__
+#define RETARGET_OS_H__
+
+/*
+  The DLib_Threads.h header file defines the IAR multithreading support.
+
+  It provides interface for variables placed in thread-local storage (TLS) and
+  basic locks using mutex functions. Two kinds of locks are used - system locks
+  and file stream locks. The file stream locks are used when the state of a
+  file stream is updated (only in the Full library configuration). The system
+  locks are used to guard heap and the C library internal states.
+
+  Note: To enable multithread support, use the linker option ‑‑threaded_lib.
+*/
+#include <DLib_Threads.h>
+
+// ==== LOCKS ====
+
+/// \fn void __iar_system_Mtxinit(__iar_Rmtx *lock)
+/// \brief Initialize a system lock
+/// \param[in]  lock  pointer to user defined lock object
+
+/// \fn void __iar_system_Mtxdst(__iar_Rmtx *lock)
+/// \brief Destroy a system lock
+/// \param[in]  lock  pointer to user defined lock object
+
+/// \fn void __iar_system_Mtxlock(__iar_Rmtx *lock)
+/// \brief Lock a system lock
+/// \param[in]  lock  pointer to user defined lock object
+
+/// \fn void __iar_system_Mtxunlock(__iar_Rmtx *lock)
+/// \brief Unlock a system lock
+/// \param[in]  lock  pointer to user defined lock object
+
+/// \fn void __iar_file_Mtxinit(__iar_Rmtx *lock)
+/// \brief Initialize a file lock
+/// \param[in]  lock  pointer to user defined lock object
+
+/// \fn void __iar_file_Mtxdst(__iar_Rmtx *lock)
+/// \brief Destroy a file lock
+/// \param[in]  lock  pointer to user defined lock object
+
+/// \fn void __iar_file_Mtxlock(__iar_Rmtx *lock)
+/// \brief Lock a file lock
+/// \param[in]  lock  pointer to user defined lock object
+
+/// \fn void __iar_file_Mtxunlock(__iar_Rmtx *lock)
+/// \brief Unlock a file lock
+/// \param[in]  lock  pointer to user defined lock object
+
+#endif /* RETARGET_OS_H__ */

source/os_interface/iar/retarget_os_rtos2.c

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2023 ARM Limited or its affiliates. All rights reserved.
+ * Copyright (C) 2023-2026 ARM Limited or its affiliates. All rights reserved.
  *
  * SPDX-License-Identifier: Apache-2.0
  *
@@ -15,6 +15,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+#include "retarget_os.h"
 
 #include "cmsis_os2.h"
 #include "cmsis_compiler.h"
@@ -47,71 +48,84 @@ static uint32_t is_thread_mode (void) {
 }
 
 /* Define retarget mutex structure to hold mutex identifier */
-struct rt_mutex_s {
+typedef struct {
   osMutexId_t id;
-};
+} rt_mutex_t;
 
 #pragma language=save
 #pragma language=extended
-/* Initialize mutex */
-__USED void __iar_system_Mtxinit(struct rt_mutex_s *mutex)
-{
+
+/* Initialize a system lock (create new mutex) */
+__USED void __iar_system_Mtxinit(__iar_Rmtx *lock) {
+  rt_mutex_t *mutex = (rt_mutex_t *)lock;
+  osMutexAttr_t attr = {
+    .attr_bits = osMutexRecursive
+  };
+
   if (os_kernel_is_initialized()) {
-    mutex->id = osMutexNew(NULL);
+    mutex->id = osMutexNew(&attr);
   }
 }
 
-/* Acquire mutex */
-__USED void __iar_system_Mtxlock(struct rt_mutex_s *mutex)
-{
+/* Lock a system lock (acquire mutex) */
+__USED void __iar_system_Mtxlock(__iar_Rmtx *lock) {
+  rt_mutex_t *mutex = (rt_mutex_t *)lock;
+
   if (os_kernel_is_running() && is_thread_mode()) {
     (void)osMutexAcquire(mutex->id, osWaitForever);
   }
 }
 
-/* Release mutex */
-__USED void __iar_system_Mtxunlock(struct rt_mutex_s *mutex) // Unlock a system lock
-{
+/*  Unlock a system lock (release mutex) */
+__USED void __iar_system_Mtxunlock(__iar_Rmtx *lock) {
+  rt_mutex_t *mutex = (rt_mutex_t *)lock;
+
   if (os_kernel_is_running() && is_thread_mode()) {
     (void)osMutexRelease(mutex->id);
   }
 }
 
-/* Free mutex */
-__USED void __iar_system_Mtxdst(struct rt_mutex_s *mutex)    // Destroy a system lock
-{
+/* Destroy a system lock (delete mutex) */
+__USED void __iar_system_Mtxdst(__iar_Rmtx *lock) {
+  rt_mutex_t *mutex = (rt_mutex_t *)lock;
+
   (void)osMutexDelete(mutex->id);
 }
 
-//#endif //defined(_DLIB_THREAD_SUPPORT) && _DLIB_THREAD_SUPPORT > 0
+/* Initialize a file lock (create new mutex) */
+__USED void __iar_file_Mtxinit(__iar_Rmtx *lock) {
+  rt_mutex_t *mutex = (rt_mutex_t *)lock;
+  osMutexAttr_t attr = {
+    .attr_bits = osMutexRecursive
+  };
 
-/* Initialize mutex */
-__USED void __iar_file_Mtxinit(struct rt_mutex_s *mutex)
-{
   if (os_kernel_is_initialized()) {
-    mutex->id = osMutexNew(NULL);
+    mutex->id = osMutexNew(&attr);
   }
 }
 
-/* Acquire mutex */
-__USED void __iar_file_Mtxlock(struct rt_mutex_s *mutex)
-{
+/* Lock a file lock (acquire mutex) */
+__USED void __iar_file_Mtxlock(__iar_Rmtx *lock) {
+  rt_mutex_t *mutex = (rt_mutex_t *)lock;
+
   if (os_kernel_is_running() && is_thread_mode()) {
     (void)osMutexAcquire(mutex->id, osWaitForever);
   }
 }
 
-/* Release mutex */
-__USED void __iar_file_Mtxunlock(struct rt_mutex_s *mutex) // Unlock a system lock
-{
+/* Unlock a file lock (release mutex) */
+__USED void __iar_file_Mtxunlock(__iar_Rmtx *lock) {
+  rt_mutex_t *mutex = (rt_mutex_t *)lock;
+
   if (os_kernel_is_running() && is_thread_mode()) {
     (void)osMutexRelease(mutex->id);
   }
 }
 
-/* Free mutex */
-__USED void __iar_file_Mtxdst(struct rt_mutex_s *mutex)    // Destroy a system lock
-{
+/* Destroy a file lock (delete mutex) */
+__USED void __iar_file_Mtxdst(__iar_Rmtx *lock) {
+  rt_mutex_t *mutex = (rt_mutex_t *)lock;
+
   (void)osMutexDelete(mutex->id);
 }