RPMsg-Lite update 06/2023

- QNX and ThreadX env. update
- RL_ENV_QUEUE_STATIC_STORAGE_SIZE macro correction
- Increase the rpmsg_lite queue size - could be 2U * (number of buffers allocated for one side/direction) for zero copy cases
- Code formatting using LLVM16
- Updated version to 5.1.0

README.md

@@ -93,6 +93,19 @@ mcuxsdk/examples/<board_name>/multicore_examples
 
 You can use the evkmimxrt1170 as the board_name for instance. Similar to MCUXpressoSDK packages the RPMsg_Lite examples use the 'rpmsg_lite_' name prefix.
 
+# Notes
+## Environment layers implementation
+Several environment layers are provided in lib/rpmsg_lite/porting/environment folder. Not all of them are fully tested however. Here is the list of environment layers that passed testing:
+- rpmsg_env_bm.c
+- rpmsg_env_freertos.c
+- rpmsg_env_xos.c
+- rpmsg_env_threadx.c
+
+The rest of environment layers has been created and used in some experimental projects, it has been running well at the time of creation but due to the lack of unit testing there is no guarantee it is still fully functional.
+
+## Shared memory configuration
+It is important to correctly initialize/configure the shared memory for data exchange in the application. The shared memory must be accessible from both the master and the remote core and it needs to be configured as Non-Cacheable memory. Dedicated shared memory section in liker file is also a good practise, it is recommended to use linker files from MCUXpressSDK packages for NXP devices based applications. It needs to be ensured no other application part/component is unintentionally accessing this part of memory. 
+
 # Configuration options
 
 The RPMsg-Lite can be configured at the compile time. The default configuration is defined in the rpmsg_default_config.h header file. This configuration can be customized by the user by including rpmsg_config.h file with custom settings. The following table summarizes all possible RPMsg-Lite configuration options.

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. 5.0.0"
+PROJECT_NUMBER         = "Rev. 5.1.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

doxygen/mainpage_rpmsg_lite.md

@@ -74,7 +74,20 @@ The user is responsible for destroying any RPMsg-Lite objects he has created in
 
 ![RPMsg Lite copy and no-copy interface, multiple scenarios](./images/rpmsg_lite_send_receive.png)
 
-# Configuration options {#configuration}
+# Notes {#notes}
+## Environment layers implementation {#Environment_layers_implementation}
+Several environment layers are provided in lib/rpmsg_lite/porting/environment folder. Not all of them are fully tested however. Here is the list of environment layers that passed testing:
+- rpmsg_env_bm.c
+- rpmsg_env_freertos.c
+- rpmsg_env_xos.c
+- rpmsg_env_threadx.c
+
+The rest of environment layers has been created and used in some experimental projects, it has been running well at the time of creation but due to the lack of unit testing there is no guarantee it is still fully functional.
+
+## Shared memory configuration {#Shared_memory_configuration}
+It is important to correctly initialize/configure the shared memory for data exchange in the application. The shared memory must be accessible from both the master and the remote core and it needs to be configured as Non-Cacheable memory. Dedicated shared memory section in liker file is also a good practise, it is recommended to use linker files from MCUXpressSDK packages for NXP devices based applications. It needs to be ensured no other application part/component is unintentionally accessing this part of memory. 
+
+# Configuration options {#configuration_options}
 
 The RPMsg-Lite can be configured at the compile time. The default configuration is defined in the rpmsg_default_config.h header file. This configuration can be customized by the user by including rpmsg_config.h file with custom settings. The following table summarizes all possible RPMsg-Lite configuration options.
 
@@ -117,4 +130,5 @@ This table summarizes revisions of this document.
 |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.  |
 |14.0           | 10/2022 | Timeout parameter added to rpmsg_lite_wait_for_link_up API function. <p> VRING_SIZE is set based on number of used buffers now (as calculated in vring_init) - updated for all platforms that are not communicating to Linux rpmsg counterpart. <p> Improveed debug check buffers implementation - instead of checking the pointer fits into shared memory check the presence in the VirtIO ring descriptors list.  |
+|15.0           | 06/2023 | Resolved issues in ThreadX env. layer implementation. <p> Added aarch64 support. <p> Increased the queue size to (2 * RL_BUFFER_COUNT) to cover zero copy cases.  |
 

lib/common/llist.c

@@ -58,7 +58,8 @@ void add_to_list(struct llist **head, struct llist *node)
 {
     if (node == LIST_NULL)
     {
-        return; /* coco validated: line never reached, add_to_list() is called from rpmsg_lite_create_ept() only and the node parameter not being null check is done before passing the parameter */
+        return; /* coco validated: line never reached, add_to_list() is called from rpmsg_lite_create_ept() only and the
+                   node parameter not being null check is done before passing the parameter */
     }
 
     if (*head != LIST_NULL)
@@ -91,7 +92,8 @@ void remove_from_list(struct llist **head, struct llist *node)
 {
     if ((*head == LIST_NULL) || (node == LIST_NULL))
     {
-        return; /* coco validated: line never reached, remove_from_list() is called from rpmsg_lite_destroy_ept() only, the head and node parameters not being null check is done before passing these parameters */
+        return; /* coco validated: line never reached, remove_from_list() is called from rpmsg_lite_destroy_ept() only,
+                   the head and node parameters not being null check is done before passing these parameters */
     }
 
     if (node == *head)

lib/include/environment/freertos/rpmsg_env_specific.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2021 NXP
+ * Copyright 2021-2023 NXP
  * All rights reserved.
  *
  *
@@ -38,10 +38,10 @@ 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 (2*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))
+#define RL_ENV_QUEUE_STATIC_STORAGE_SIZE (2 * RL_BUFFER_COUNT * sizeof(rpmsg_queue_rx_cb_data_t))
 #endif
 
 #endif /* RPMSG_ENV_SPECIFIC_H_ */

lib/include/environment/qnx/rpmsg_env_specific.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2021 NXP
+ * Copyright 2021,2023 NXP
  * All rights reserved.
  *
  *
@@ -22,6 +22,13 @@
 #include <stdint.h>
 #include "rpmsg_default_config.h"
 
+typedef struct rpmsg_env_init
+{
+    void *user_input; /* Pointer to user init cfg */
+    uint32_t pa;      /* Physical address of memory pool reserved for rpmsg */
+    void *va;         /* Virtual address of the memory pool */
+} rpmsg_env_init_t;
+
 typedef struct
 {
     uint32_t src;
@@ -30,15 +37,7 @@ typedef struct
 } rpmsg_queue_rx_cb_data_t;
 
 #if defined(RL_USE_STATIC_API) && (RL_USE_STATIC_API == 1)
-#include <pthread.h>
-#include <mqueue.h>
-
-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))
-   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))
+    #error "This RPMsg-Lite port requires RL_USE_STATIC_API set to 0"
 #endif
 
 #endif /* RPMSG_ENV_SPECIFIC_H_ */

lib/include/environment/threadx/rpmsg_env_specific.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2021 NXP
+ * Copyright 2021-2023 NXP
  * All rights reserved.
  *
  *
@@ -21,6 +21,7 @@
 
 #include <stdint.h>
 #include "rpmsg_default_config.h"
+#include "tx_api.h"
 
 typedef struct
 {
@@ -30,15 +31,14 @@ typedef struct
 } rpmsg_queue_rx_cb_data_t;
 
 #if defined(RL_USE_STATIC_API) && (RL_USE_STATIC_API == 1)
-#include "tx_api.h"
 #include "tx_event_flags.h"
 
 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 (2*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))
+#define RL_ENV_QUEUE_STATIC_STORAGE_SIZE (2 * RL_BUFFER_COUNT * sizeof(rpmsg_queue_rx_cb_data_t))
 #endif
 
 #endif /* RPMSG_ENV_SPECIFIC_H_ */

lib/include/environment/xos/rpmsg_env_specific.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2021 NXP
+ * Copyright 2021-2023 NXP
  * All rights reserved.
  *
  *
@@ -34,10 +34,10 @@ 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 (2*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)))
+#define RL_ENV_QUEUE_STATIC_STORAGE_SIZE (XOS_MSGQ_SIZE(2 * RL_BUFFER_COUNT, sizeof(rpmsg_queue_rx_cb_data_t)))
 #endif
 
 #endif /* RPMSG_ENV_SPECIFIC_H_ */

lib/include/environment/zephyr/rpmsg_env_specific.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2021 NXP
+ * Copyright 2021-2023 NXP
  * All rights reserved.
  *
  *
@@ -26,10 +26,10 @@
 
 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 (2*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))
+#define RL_ENV_QUEUE_STATIC_STORAGE_SIZE (2 * RL_BUFFER_COUNT * sizeof(rpmsg_queue_rx_cb_data_t))
 #endif
 
 #endif /* RPMSG_ENV_SPECIFIC_H_ */

lib/include/platform/aarch64/rpmsg_platform.h

@@ -24,15 +24,15 @@
 #define VRING_SIZE (0x8000UL)
 #endif
 
-/* size of shared memory + 2*VRING size */
+/* define shared memory space for VRINGS per one channel */
 #define RL_VRING_OVERHEAD (2UL * VRING_SIZE)
 
 #define RL_GET_VQ_ID(link_id, queue_id) (((queue_id)&0x1U) | (((link_id) << 1U) & 0xFFFFFFFEU))
 #define RL_GET_LINK_ID(id)              (((id)&0xFFFFFFFEU) >> 1U)
 #define RL_GET_Q_ID(id)                 ((id)&0x1U)
 
-#define RL_PLATFORM_USER_LINK_ID           (0U)
-#define RL_PLATFORM_HIGHEST_LINK_ID        (15U)
+#define RL_PLATFORM_USER_LINK_ID    (0U)
+#define RL_PLATFORM_HIGHEST_LINK_ID (15U)
 
 /* platform interrupt related functions */
 int32_t platform_init_interrupt(uint32_t vector_id, void *isr_data);

lib/include/platform/imx6sx_m4/rpmsg_platform.h

@@ -51,8 +51,8 @@ void platform_time_delay(uint32_t num_msec);
 void platform_map_mem_region(uint32_t vrt_addr, uint32_t phy_addr, uint32_t size, uint32_t flags);
 void platform_cache_all_flush_invalidate(void);
 void platform_cache_disable(void);
-uint32_t platform_vatopa(void *addr);
-void *platform_patova(uint32_t addr);
+uintptr_t platform_vatopa(void *addr);
+void *platform_patova(uintptr_t addr);
 
 /* platform init/deinit */
 int32_t platform_init(void);

lib/include/platform/imx7d_m4/rpmsg_platform.h

@@ -51,8 +51,8 @@ void platform_time_delay(uint32_t num_msec);
 void platform_map_mem_region(uint32_t vrt_addr, uint32_t phy_addr, uint32_t size, uint32_t flags);
 void platform_cache_all_flush_invalidate(void);
 void platform_cache_disable(void);
-uint32_t platform_vatopa(void *addr);
-void *platform_patova(uint32_t addr);
+uintptr_t platform_vatopa(void *addr);
+void *platform_patova(uintptr_t addr);
 
 /* platform init/deinit */
 int32_t platform_init(void);

lib/include/platform/imx7ulp_m4/rpmsg_platform.h

@@ -52,8 +52,8 @@ void platform_time_delay(uint32_t num_msec);
 void platform_map_mem_region(uint32_t vrt_addr, uint32_t phy_addr, uint32_t size, uint32_t flags);
 void platform_cache_all_flush_invalidate(void);
 void platform_cache_disable(void);
-uint32_t platform_vatopa(void *addr);
-void *platform_patova(uint32_t addr);
+uintptr_t platform_vatopa(void *addr);
+void *platform_patova(uintptr_t addr);
 
 /* platform init/deinit */
 int32_t platform_init(void);

lib/include/platform/imx8mm_m4/rpmsg_platform.h

@@ -55,8 +55,8 @@ void platform_time_delay(uint32_t num_msec);
 void platform_map_mem_region(uint32_t vrt_addr, uint32_t phy_addr, uint32_t size, uint32_t flags);
 void platform_cache_all_flush_invalidate(void);
 void platform_cache_disable(void);
-uint32_t platform_vatopa(void *addr);
-void *platform_patova(uint32_t addr);
+uintptr_t platform_vatopa(void *addr);
+void *platform_patova(uintptr_t addr);
 
 /* platform init/deinit */
 int32_t platform_init(void);

lib/include/platform/imx8mn_m7/rpmsg_platform.h

@@ -51,8 +51,8 @@ void platform_time_delay(uint32_t num_msec);
 void platform_map_mem_region(uint32_t vrt_addr, uint32_t phy_addr, uint32_t size, uint32_t flags);
 void platform_cache_all_flush_invalidate(void);
 void platform_cache_disable(void);
-uint32_t platform_vatopa(void *addr);
-void *platform_patova(uint32_t addr);
+uintptr_t platform_vatopa(void *addr);
+void *platform_patova(uintptr_t addr);
 
 /* platform init/deinit */
 int32_t platform_init(void);

lib/include/platform/imx8mp_m7/rpmsg_platform.h

@@ -50,8 +50,8 @@ void platform_time_delay(uint32_t num_msec);
 void platform_map_mem_region(uint32_t vrt_addr, uint32_t phy_addr, uint32_t size, uint32_t flags);
 void platform_cache_all_flush_invalidate(void);
 void platform_cache_disable(void);
-uint32_t platform_vatopa(void *addr);
-void *platform_patova(uint32_t addr);
+uintptr_t platform_vatopa(void *addr);
+void *platform_patova(uintptr_t addr);
 
 /* platform init/deinit */
 int32_t platform_init(void);

lib/include/platform/imx8mq_m4/rpmsg_platform.h

@@ -51,8 +51,8 @@ void platform_time_delay(uint32_t num_msec);
 void platform_map_mem_region(uint32_t vrt_addr, uint32_t phy_addr, uint32_t size, uint32_t flags);
 void platform_cache_all_flush_invalidate(void);
 void platform_cache_disable(void);
-uint32_t platform_vatopa(void *addr);
-void *platform_patova(uint32_t addr);
+uintptr_t platform_vatopa(void *addr);
+void *platform_patova(uintptr_t addr);
 
 /* platform init/deinit */
 int32_t platform_init(void);

lib/include/platform/imx8qm_m4/rpmsg_platform.h

@@ -76,8 +76,8 @@ void platform_time_delay(uint32_t num_msec);
 void platform_map_mem_region(uint32_t vrt_addr, uint32_t phy_addr, uint32_t size, uint32_t flags);
 void platform_cache_all_flush_invalidate(void);
 void platform_cache_disable(void);
-uint32_t platform_vatopa(void *addr);
-void *platform_patova(uint32_t addr);
+uintptr_t platform_vatopa(void *addr);
+void *platform_patova(uintptr_t addr);
 
 /* platform init/deinit */
 int32_t platform_init(void);

lib/include/platform/imx8qx_cm4/rpmsg_platform.h

@@ -52,8 +52,8 @@ void platform_time_delay(uint32_t num_msec);
 void platform_map_mem_region(uint32_t vrt_addr, uint32_t phy_addr, uint32_t size, uint32_t flags);
 void platform_cache_all_flush_invalidate(void);
 void platform_cache_disable(void);
-uint32_t platform_vatopa(void *addr);
-void *platform_patova(uint32_t addr);
+uintptr_t platform_vatopa(void *addr);
+void *platform_patova(uintptr_t addr);
 
 /* platform init/deinit */
 int32_t platform_init(void);

lib/include/platform/imxrt1160/rpmsg_platform.h

@@ -58,8 +58,8 @@ void platform_time_delay(uint32_t num_msec);
 void platform_map_mem_region(uint32_t vrt_addr, uint32_t phy_addr, uint32_t size, uint32_t flags);
 void platform_cache_all_flush_invalidate(void);
 void platform_cache_disable(void);
-uint32_t platform_vatopa(void *addr);
-void *platform_patova(uint32_t addr);
+uintptr_t platform_vatopa(void *addr);
+void *platform_patova(uintptr_t addr);
 
 /* platform init/deinit */
 int32_t platform_init(void);

lib/include/platform/imxrt1170/rpmsg_platform.h

@@ -58,8 +58,8 @@ void platform_time_delay(uint32_t num_msec);
 void platform_map_mem_region(uint32_t vrt_addr, uint32_t phy_addr, uint32_t size, uint32_t flags);
 void platform_cache_all_flush_invalidate(void);
 void platform_cache_disable(void);
-uint32_t platform_vatopa(void *addr);
-void *platform_patova(uint32_t addr);
+uintptr_t platform_vatopa(void *addr);
+void *platform_patova(uintptr_t addr);
 
 /* platform init/deinit */
 int32_t platform_init(void);

lib/include/platform/imxrt500_fusionf1/rpmsg_platform.h

@@ -57,8 +57,8 @@ void platform_time_delay(uint32_t num_msec);
 void platform_map_mem_region(uint32_t vrt_addr, uint32_t phy_addr, uint32_t size, uint32_t flags);
 void platform_cache_all_flush_invalidate(void);
 void platform_cache_disable(void);
-uint32_t platform_vatopa(void *addr);
-void *platform_patova(uint32_t addr);
+uintptr_t platform_vatopa(void *addr);
+void *platform_patova(uintptr_t addr);
 
 /* platform init/deinit */
 int32_t platform_init(void);

lib/include/platform/imxrt500_m33/rpmsg_platform.h

@@ -57,8 +57,8 @@ void platform_time_delay(uint32_t num_msec);
 void platform_map_mem_region(uint32_t vrt_addr, uint32_t phy_addr, uint32_t size, uint32_t flags);
 void platform_cache_all_flush_invalidate(void);
 void platform_cache_disable(void);
-uint32_t platform_vatopa(void *addr);
-void *platform_patova(uint32_t addr);
+uintptr_t platform_vatopa(void *addr);
+void *platform_patova(uintptr_t addr);
 
 /* platform init/deinit */
 int32_t platform_init(void);

lib/include/platform/imxrt600_hifi4/rpmsg_platform.h

@@ -57,8 +57,8 @@ void platform_time_delay(uint32_t num_msec);
 void platform_map_mem_region(uint32_t vrt_addr, uint32_t phy_addr, uint32_t size, uint32_t flags);
 void platform_cache_all_flush_invalidate(void);
 void platform_cache_disable(void);
-uint32_t platform_vatopa(void *addr);
-void *platform_patova(uint32_t addr);
+uintptr_t platform_vatopa(void *addr);
+void *platform_patova(uintptr_t addr);
 
 /* platform init/deinit */
 int32_t platform_init(void);

lib/include/platform/imxrt600_m33/rpmsg_platform.h

@@ -57,8 +57,8 @@ void platform_time_delay(uint32_t num_msec);
 void platform_map_mem_region(uint32_t vrt_addr, uint32_t phy_addr, uint32_t size, uint32_t flags);
 void platform_cache_all_flush_invalidate(void);
 void platform_cache_disable(void);
-uint32_t platform_vatopa(void *addr);
-void *platform_patova(uint32_t addr);
+uintptr_t platform_vatopa(void *addr);
+void *platform_patova(uintptr_t addr);
 
 /* platform init/deinit */
 int32_t platform_init(void);