RPMsg-Lite update 05/2022

- Adjust rpmsg_lite_is_link_up() to return RL_TRUE/RL_FALSE - Add support for custom shared memory arrangement per the RPMsg_Lite instance - Updated version to 4.0.0
nxp-mcuxpresso · May 27, 2022 · 9775c19 · 9775c19
1 parent 5ee99a9
commit 9775c19
Show file tree

Hide file tree

Showing 18 changed files with 355 additions and 89 deletions.
diff --git a/README.md b/README.md
@@ -97,6 +97,7 @@ The RPMsg-Lite can be configured at the compile time. The default configuration
 |RL_USE_ENVIRONMENT_CONTEXT    | (0)           | When enabled the environment layer uses its own context. Required for some environments (QNX). The default value is 0 (no context, saves some RAM).    |
 |RL_DEBUG_CHECK_BUFFERS        | (0)           | When enabled buffer debug checks in rpmsg_lite_send_nocopy() and rpmsg_lite_release_rx_buffer() functions are disabled. Do not use in RPMsg-Lite to Linux configuration.    |
 |RL_ALLOW_CONSUMED_BUFFERS_NOTIFICATION        | (0)           | When enabled the opposite side is notified each time received buffers are consumed and put into the queue of available buffers. Enable this option in RPMsg-Lite to Linux configuration to allow unblocking of the Linux blocking send. The default value is 0 (RPMsg-Lite to RPMsg-Lite communication).    |
+|RL_ALLOW_CUSTOM_SHMEM_CONFIG  | (0)           | It allows to define custom shared memory configuration and replacing the shared memory related global settings from rpmsg_config.h This is useful when multiple instances are running in parallel but different shared memory arrangement (vring size & alignment, buffers size & count) is required. The default value is 0 (all RPMsg_Lite instances use the same shared memory arrangement as defined by common config macros). |
 |RL_ASSERT                     | see rpmsg_default_config.h | Assert implementation.    |
 
 # Contributing to the rpmsg-lite project

diff --git a/doxygen/Doxyfile.rpmsglite b/doxygen/Doxyfile.rpmsglite
@@ -38,7 +38,7 @@ PROJECT_NAME           = "RPMsg-Lite User's Guide"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = "Rev. 3.2.0"
+PROJECT_NUMBER         = "Rev. 4.0.0"
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

diff --git a/doxygen/mainpage_rpmsg_lite.md b/doxygen/mainpage_rpmsg_lite.md
@@ -90,6 +90,7 @@ The RPMsg-Lite can be configured at the compile time. The default configuration
 |RL_USE_ENVIRONMENT_CONTEXT    | (0)           | When enabled the environment layer uses its own context. Required for some environments (QNX). The default value is 0 (no context, saves some RAM).    |
 |RL_DEBUG_CHECK_BUFFERS        | (0)           | When enabled buffer debug checks in rpmsg_lite_send_nocopy() and rpmsg_lite_release_rx_buffer() functions are disabled. Do not use in RPMsg-Lite to Linux configuration.    |
 |RL_ALLOW_CONSUMED_BUFFERS_NOTIFICATION        | (0)           | When enabled the opposite side is notified each time received buffers are consumed and put into the queue of available buffers. Enable this option in RPMsg-Lite to Linux configuration to allow unblocking of the Linux blocking send. The default value is 0 (RPMsg-Lite to RPMsg-Lite communication).    |
+|RL_ALLOW_CUSTOM_SHMEM_CONFIG  | (0)           | It allows to define custom shared memory configuration and replacing the shared memory related global settings from rpmsg_config.h This is useful when multiple instances are running in parallel but different shared memory arrangement (vring size & alignment, buffers size & count) is required. The default value is 0 (all RPMsg_Lite instances use the same shared memory arrangement as defined by common config macros). |
 |RL_ASSERT                     | see rpmsg_default_config.h | Assert implementation.    |
 
 
@@ -113,4 +114,6 @@ This table summarizes revisions of this document.
 |9.0            | 12/2020 | Several MISRA C-2012 violations addressed <p> Introduced RL_ALLOW_CONSUMED_BUFFERS_NOTIFICATION config option to allow opposite side notification sending each time received buffers are consumed and put into the queue of available buffers <p> Added environment layers for Threadx <p> Added support for i.MX8QM multicore platform  |
 |10.0           | 06/2021 | Fixed incorrect description of the rpmsg_lite_get_endpoint_from_addr function <p> Updated RL_BUFFER_COUNT documentation <p> env_print macro adjusted to address MISRA 21.6 rule in MCUXpressoSDK projects  |
 |11.0           | 12/2021 | Improve static allocations - allow OS-specific objects being allocated statically, GitHub PR #14 <p> RPMsg-Lite: Minor Misra and typo corrections, GitHub PR #19, #20.  |
+|12.0           | 01/2022 | Introduce RL_ALLOW_CUSTOM_SHMEM_CONFIG configuration option to support custom shared memory arangement per the RPMsg_Lite instance.  |
+|13.0           | 04/2022 | Introduced new rpmsg_lite_wait_for_link_up() API function - this allows to avoid using busy loops in rtos environments, GitHub PR #21. <p> Adjust rpmsg_lite_is_link_up() to return RL_TRUE/RL_FALSE.  |
 
diff --git a/lib/include/environment/freertos/rpmsg_env_specific.h b/lib/include/environment/freertos/rpmsg_env_specific.h
@@ -38,7 +38,9 @@ typedef struct
 typedef StaticSemaphore_t LOCK_STATIC_CONTEXT;
 typedef StaticQueue_t rpmsg_static_queue_ctxt;
 
-/* Queue object static storage size in bytes, should be defined as (RL_BUFFER_COUNT*sizeof(rpmsg_queue_rx_cb_data_t)) */
+/* Queue object static storage size in bytes, should be defined as (RL_BUFFER_COUNT*sizeof(rpmsg_queue_rx_cb_data_t))
+   This macro helps the application to statically allocate the queue object static storage memory. Note, the
+   RL_BUFFER_COUNT is not applied for all instances when RL_ALLOW_CUSTOM_SHMEM_CONFIG is set to 1 ! */
 #define RL_ENV_QUEUE_STATIC_STORAGE_SIZE (RL_BUFFER_COUNT * sizeof(rpmsg_queue_rx_cb_data_t))
 #endif
 

diff --git a/lib/include/environment/qnx/rpmsg_env_specific.h b/lib/include/environment/qnx/rpmsg_env_specific.h
@@ -35,7 +35,9 @@ typedef struct
 
 typedef pthread_mutex_t LOCK_STATIC_CONTEXT;
 typedef env_queue_t rpmsg_static_queue_ctxt;
-/* Queue object static storage size in bytes, should be defined as (RL_BUFFER_COUNT*sizeof(rpmsg_queue_rx_cb_data_t)) */
+/* Queue object static storage size in bytes, should be defined as (RL_BUFFER_COUNT*sizeof(rpmsg_queue_rx_cb_data_t))
+   This macro helps the application to statically allocate the queue object static storage memory. Note, the
+   RL_BUFFER_COUNT is not applied for all instances when RL_ALLOW_CUSTOM_SHMEM_CONFIG is set to 1 ! */
 #define RL_ENV_QUEUE_STATIC_STORAGE_SIZE (RL_BUFFER_COUNT * sizeof(rpmsg_queue_rx_cb_data_t))
 #endif
 

diff --git a/lib/include/environment/threadx/rpmsg_env_specific.h b/lib/include/environment/threadx/rpmsg_env_specific.h
@@ -35,7 +35,9 @@ typedef struct
 
 typedef TX_SEMAPHORE LOCK_STATIC_CONTEXT;
 typedef TX_QUEUE rpmsg_static_queue_ctxt;
-/* Queue object static storage size in bytes, should be defined as (RL_BUFFER_COUNT*sizeof(rpmsg_queue_rx_cb_data_t)) */
+/* Queue object static storage size in bytes, should be defined as (RL_BUFFER_COUNT*sizeof(rpmsg_queue_rx_cb_data_t))
+   This macro helps the application to statically allocate the queue object static storage memory. Note, the
+   RL_BUFFER_COUNT is not applied for all instances when RL_ALLOW_CUSTOM_SHMEM_CONFIG is set to 1 ! */
 #define RL_ENV_QUEUE_STATIC_STORAGE_SIZE (RL_BUFFER_COUNT * sizeof(rpmsg_queue_rx_cb_data_t))
 #endif
 

diff --git a/lib/include/environment/xos/rpmsg_env_specific.h b/lib/include/environment/xos/rpmsg_env_specific.h
@@ -34,7 +34,9 @@ typedef struct
 
 typedef XosSem LOCK_STATIC_CONTEXT;
 typedef void rpmsg_static_queue_ctxt;
-/* Queue object static storage size in bytes, should be defined as (RL_BUFFER_COUNT*sizeof(rpmsg_queue_rx_cb_data_t)) */
+/* Queue object static storage size in bytes, should be defined as (RL_BUFFER_COUNT*sizeof(rpmsg_queue_rx_cb_data_t))
+   This macro helps the application to statically allocate the queue object static storage memory. Note, the
+   RL_BUFFER_COUNT is not applied for all instances when RL_ALLOW_CUSTOM_SHMEM_CONFIG is set to 1 ! */
 #define RL_ENV_QUEUE_STATIC_STORAGE_SIZE (XOS_MSGQ_SIZE(RL_BUFFER_COUNT, sizeof(rpmsg_queue_rx_cb_data_t)))
 #endif
 

diff --git a/lib/include/environment/zephyr/rpmsg_env_specific.h b/lib/include/environment/zephyr/rpmsg_env_specific.h
@@ -26,7 +26,9 @@
 
 typedef k_sem LOCK_STATIC_CONTEXT;
 typedef k_msgq rpmsg_static_queue_ctxt;
-/* Queue object static storage size in bytes, should be defined as (RL_BUFFER_COUNT*sizeof(rpmsg_queue_rx_cb_data_t)) */
+/* Queue object static storage size in bytes, should be defined as (RL_BUFFER_COUNT*sizeof(rpmsg_queue_rx_cb_data_t))
+   This macro helps the application to statically allocate the queue object static storage memory. Note, the
+   RL_BUFFER_COUNT is not applied for all instances when RL_ALLOW_CUSTOM_SHMEM_CONFIG is set to 1 ! */
 #define RL_ENV_QUEUE_STATIC_STORAGE_SIZE (RL_BUFFER_COUNT * sizeof(rpmsg_queue_rx_cb_data_t))
 #endif
 

diff --git a/lib/include/rpmsg_default_config.h b/lib/include/rpmsg_default_config.h
@@ -56,6 +56,20 @@
 #define RL_MS_PER_INTERVAL (1)
 #endif
 
+//! @def RL_ALLOW_CUSTOM_SHMEM_CONFIG
+//!
+//! This option allows to define custom shared memory configuration and replacing
+//! the shared memory related global settings from rpmsg_config.h This is useful
+//! when multiple instances are running in parallel but different shared memory
+//! arrangement (vring size & alignment, buffers size & count) is required. Note,
+//! that once enabled the platform_get_custom_shmem_config() function needs
+//! to be implemented in platform layer. The default value is 0 (all RPMsg_Lite
+//! instances use the same shared memory arrangement as defined by common config macros).
+#ifndef RL_ALLOW_CUSTOM_SHMEM_CONFIG
+#define RL_ALLOW_CUSTOM_SHMEM_CONFIG (0)
+#endif
+
+#if !(defined(RL_ALLOW_CUSTOM_SHMEM_CONFIG) && (RL_ALLOW_CUSTOM_SHMEM_CONFIG == 1))
 //! @def RL_BUFFER_PAYLOAD_SIZE
 //!
 //! Size of the buffer payload, it must be equal to (240, 496, 1008, ...)
@@ -77,6 +91,19 @@
 #define RL_BUFFER_COUNT (2U)
 #endif
 
+#else
+//! Define the buffer payload and count per different link IDs (rpmsg_lite instance) when RL_ALLOW_CUSTOM_SHMEM_CONFIG
+//! is set.
+//! Refer to the rpmsg_plaform.h for the used link IDs.
+#ifndef RL_BUFFER_PAYLOAD_SIZE
+#define RL_BUFFER_PAYLOAD_SIZE(link_id) (496U)
+#endif
+
+#ifndef RL_BUFFER_COUNT
+#define RL_BUFFER_COUNT(link_id) (((link_id) == 0U) ? 256U : 2U)
+#endif
+#endif /* !(defined(RL_ALLOW_CUSTOM_SHMEM_CONFIG) && (RL_ALLOW_CUSTOM_SHMEM_CONFIG == 1))*/
+
 //! @def RL_API_HAS_ZEROCOPY
 //!
 //! Zero-copy API functions enabled/disabled.

diff --git a/lib/include/rpmsg_env.h b/lib/include/rpmsg_env.h
@@ -2,7 +2,7 @@
  * Copyright (c) 2014, Mentor Graphics Corporation
  * Copyright (c) 2015 Xilinx, Inc.
  * Copyright (c) 2016 Freescale Semiconductor, Inc.
- * Copyright 2016-2021 NXP
+ * Copyright 2016-2022 NXP
  * Copyright 2021 ACRIOS Systems s.r.o.
  * All rights reserved.
  *

diff --git a/lib/include/rpmsg_lite.h b/lib/include/rpmsg_lite.h
@@ -2,7 +2,7 @@
  * Copyright (c) 2014, Mentor Graphics Corporation
  * Copyright (c) 2015 Xilinx, Inc.
  * Copyright (c) 2016 Freescale Semiconductor, Inc.
- * Copyright 2016-2021 NXP
+ * Copyright 2016-2022 NXP
  * Copyright 2021 ACRIOS Systems s.r.o.
  * All rights reserved.
  *
@@ -39,10 +39,10 @@ extern "C" {
 #endif
 
 #include <stddef.h>
+#include "rpmsg_compiler.h"
 #include "virtqueue.h"
 #include "rpmsg_env.h"
 #include "llist.h"
-#include "rpmsg_compiler.h"
 #include "rpmsg_default_config.h"
 
 //! @addtogroup rpmsg_lite
@@ -52,7 +52,7 @@ extern "C" {
  * Definitions
  ******************************************************************************/
 
-#define RL_VERSION "3.2.0" /*!< Current RPMsg Lite version */
+#define RL_VERSION "4.0.0" /*!< Current RPMsg Lite version */
 
 /* Shared memory "allocator" parameters */
 #define RL_WORD_SIZE (sizeof(uint32_t))
@@ -67,8 +67,8 @@ extern "C" {
 #define RL_NULL       ((void *)0)
 #define RL_REMOTE     (0)
 #define RL_MASTER     (1)
-#define RL_TRUE       (1U)
-#define RL_FALSE      (0U)
+#define RL_TRUE       (1UL)
+#define RL_FALSE      (0UL)
 #define RL_ADDR_ANY   (0xFFFFFFFFU)
 #define RL_RELEASE    (0)
 #define RL_HOLD       (1)
@@ -287,12 +287,12 @@ int32_t rpmsg_lite_send(struct rpmsg_lite_instance *rpmsg_lite_dev,
 /*!
  * @brief Function to get the link state
  *
- * @param rpmsg_lite_dev    RPMsg-Lite instance
+ * @param rpmsg_lite_dev    RPMsg-Lite instance pointer
  *
- * @return True when link up, false when down.
+ * @return RL_TRUE when link up, RL_FALSE when down.
  *
  */
-int32_t rpmsg_lite_is_link_up(struct rpmsg_lite_instance *rpmsg_lite_dev);
+uint32_t rpmsg_lite_is_link_up(struct rpmsg_lite_instance *rpmsg_lite_dev);
 
 /*!
  * @brief Function to wait until the link is up. Returns

diff --git a/lib/rpmsg_lite/porting/environment/rpmsg_env_bm.c b/lib/rpmsg_lite/porting/environment/rpmsg_env_bm.c
@@ -2,7 +2,7 @@
  * Copyright (c) 2014, Mentor Graphics Corporation
  * Copyright (c) 2015 Xilinx, Inc.
  * Copyright (c) 2016 Freescale Semiconductor, Inc.
- * Copyright 2016-2021 NXP
+ * Copyright 2016-2022 NXP
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -43,21 +43,21 @@
  *
  **************************************************************************/
 
+#include "rpmsg_compiler.h"
 #include "rpmsg_env.h"
 #include "rpmsg_platform.h"
 #include "virtqueue.h"
-#include "rpmsg_compiler.h"
 
 #include <stdlib.h>
 #include <string.h>
 
 static int32_t env_init_counter = 0;
 
 /* Max supported ISR counts */
-#define ISR_COUNT (12U) /* Change for multiple remote cores */
-                        /*!
-                         * Structure to keep track of registered ISR's.
-                         */
+#define ISR_COUNT (12U)
+/*!
+ * Structure to keep track of registered ISR's.
+ */
 struct isr_info
 {
     void *data;

diff --git a/lib/rpmsg_lite/porting/environment/rpmsg_env_freertos.c b/lib/rpmsg_lite/porting/environment/rpmsg_env_freertos.c
@@ -2,7 +2,7 @@
  * Copyright (c) 2014, Mentor Graphics Corporation
  * Copyright (c) 2015 Xilinx, Inc.
  * Copyright (c) 2016 Freescale Semiconductor, Inc.
- * Copyright 2016-2021 NXP
+ * Copyright 2016-2022 NXP
  * Copyright 2021 ACRIOS Systems s.r.o.
  * All rights reserved.
  *
@@ -44,20 +44,21 @@
  *
  **************************************************************************/
 
+#include "rpmsg_compiler.h"
 #include "rpmsg_env.h"
 #include "FreeRTOS.h"
 #include "task.h"
 #include "semphr.h"
 #include "rpmsg_platform.h"
 #include "virtqueue.h"
-#include "rpmsg_compiler.h"
 #include "event_groups.h"
+#include "rpmsg_lite.h"
 
 #include <stdlib.h>
 #include <string.h>
 
-static int32_t env_init_counter   = 0;
-static SemaphoreHandle_t env_sema = ((void *)0);
+static int32_t env_init_counter       = 0;
+static SemaphoreHandle_t env_sema     = ((void *)0);
 static EventGroupHandle_t event_group = ((void *)0);
 #if defined(RL_USE_STATIC_API) && (RL_USE_STATIC_API == 1)
 LOCK_STATIC_CONTEXT env_sem_static_context;
@@ -107,10 +108,10 @@ static int32_t env_in_isr(void)
  */
 void env_wait_for_link_up(volatile uint32_t *link_state, uint32_t link_id)
 {
-    (void)xEventGroupClearBits(event_group, (1 << link_id));
+    (void)xEventGroupClearBits(event_group, (EventBits_t)(1UL << link_id));
     if (*link_state != 1U)
     {
-        xEventGroupWaitBits(event_group, (1 << link_id), pdFALSE, pdTRUE, portMAX_DELAY);
+        (void)xEventGroupWaitBits(event_group, (EventBits_t)(1UL << link_id), pdFALSE, pdTRUE, portMAX_DELAY);
     }
 }
 
@@ -125,12 +126,12 @@ void env_tx_callback(uint32_t link_id)
     BaseType_t xHigherPriorityTaskWoken = pdFALSE;
     if (env_in_isr() != 0)
     {
-        (void)xEventGroupSetBitsFromISR(event_group, (1 << link_id), &xHigherPriorityTaskWoken);
-        portYIELD_FROM_ISR(xHigherPriorityTaskWoken);
+        (void)xEventGroupSetBitsFromISR(event_group, (EventBits_t)(1UL << link_id), &xHigherPriorityTaskWoken);
+        portEND_SWITCHING_ISR(xHigherPriorityTaskWoken);
     }
     else
     {
-        (void)xEventGroupSetBits(event_group, (1 << link_id));
+        (void)xEventGroupSetBits(event_group, (EventBits_t)(1UL << link_id));
     }
 }
 
@@ -144,23 +145,23 @@ int32_t env_init(void)
 {
     int32_t retval;
     vTaskSuspendAll(); /* stop scheduler */
-    // verify 'env_init_counter'
+    /* verify 'env_init_counter' */
     RL_ASSERT(env_init_counter >= 0);
     if (env_init_counter < 0)
     {
         (void)xTaskResumeAll(); /* re-enable scheduler */
         return -1;
     }
     env_init_counter++;
-    // multiple call of 'env_init' - return ok
+    /* multiple call of 'env_init' - return ok */
     if (env_init_counter == 1)
     {
-        // first call
+        /* first call */
 #if defined(RL_USE_STATIC_API) && (RL_USE_STATIC_API == 1)
-        env_sema = xSemaphoreCreateBinaryStatic(&env_sem_static_context);
+        env_sema    = xSemaphoreCreateBinaryStatic(&env_sem_static_context);
         event_group = xEventGroupCreateStatic(&event_group_static_context);
 #else
-        env_sema = xSemaphoreCreateBinary();
+        env_sema    = xSemaphoreCreateBinary();
         event_group = xEventGroupCreate();
 #endif
 #if (configUSE_16_BIT_TICKS == 1)
@@ -203,20 +204,20 @@ int32_t env_deinit(void)
     int32_t retval;
 
     vTaskSuspendAll(); /* stop scheduler */
-    // verify 'env_init_counter'
+    /* verify 'env_init_counter' */
     RL_ASSERT(env_init_counter > 0);
     if (env_init_counter <= 0)
     {
         (void)xTaskResumeAll(); /* re-enable scheduler */
         return -1;
     }
 
-    // counter on zero - call platform deinit
+    /* counter on zero - call platform deinit */
     env_init_counter--;
-    // multiple call of 'env_deinit' - return ok
+    /* multiple call of 'env_deinit' - return ok */
     if (env_init_counter <= 0)
     {
-        // last call
+        /* last call */
         (void)memset(isr_table, 0, sizeof(isr_table));
         retval = platform_deinit();
         vEventGroupDelete(event_group);

diff --git a/lib/rpmsg_lite/porting/environment/rpmsg_env_qnx.c b/lib/rpmsg_lite/porting/environment/rpmsg_env_qnx.c
@@ -2,7 +2,7 @@
  * Copyright (c) 2014, Mentor Graphics Corporation
  * Copyright (c) 2015 Xilinx, Inc.
  * Copyright (c) 2016 Freescale Semiconductor, Inc.
- * Copyright 2016-2021 NXP
+ * Copyright 2016-2022 NXP
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -109,6 +109,30 @@ void *env_get_platform_context(void *env_context)
     return env->platform_context;
 }
 
+/*!
+ * env_wait_for_link_up
+ *
+ * Wait until the link_state parameter of the rpmsg_lite_instance is set.
+ * Busy loop implementation for now, to be replaced by events.
+ *
+ */
+void env_wait_for_link_up(volatile uint32_t *link_state, uint32_t link_id)
+{
+    while (*link_state != 1U)
+    {
+    }
+}
+
+/*!
+ * env_tx_callback
+ *
+ * Set event to notify task waiting in env_wait_for_link_up().
+ *
+ */
+void env_tx_callback(uint32_t link_id)
+{
+}
+
 /*!
  * env_init
  *