uart_async_adapter: Provide UART Async Adapter

rakons · nordicjm · commit 4e15d3b9898e · 2024-03-20T12:07:37.000Z
This commit moves UART Async Adapter as separate subsystem.

JIRA: NCSDK-26505

Signed-off-by: Radoslaw Koppel &lt;radoslaw.koppel@nordicsemi.no&gt;
Signed-off-by: Pekka Niskanen &lt;pekka.niskanen@nordicsemi.no&gt;
diff --git a/CODEOWNERS b/CODEOWNERS
@@ -268,6 +268,7 @@ Kconfig*                                  @tejlmand
 /subsys/shell/                            @nordic-krch
 /subsys/nrf_security/                     @frkv @Vge0rge @vili-nordic @SebastianBoe @mswarowsky
 /subsys/trusted_storage/                  @frkv @Vge0rge @vili-nordic @SebastianBoe @mswarowsky
+/subsys/uart_async_adapter/               @rakons
 /subsys/net_core_monitor/                 @maje-emb
 /subsys/zigbee/                           @milewr
 /tests/                                   @PerMac @katgiadla
diff --git a/doc/nrf/libraries/others/uart_async_adapter.rst b/doc/nrf/libraries/others/uart_async_adapter.rst
@@ -0,0 +1,102 @@
+.. _lib_uart_async_adapter:
+
+UART async adapter
+##################
+
+.. contents::
+   :local:
+   :depth: 2
+
+UART async adapter library works as an interface between interrupt-driven API of a UART device and software that is using the asynchronous API interface.
+
+.. note::
+   The current implementation is :ref:`experimental <software_maturity>`.
+
+Overview
+********
+
+Zephyr provides the following three different ways to access a UART peripheral:
+
+* Pooling API
+* Interrupt-driven API
+* Asynchronous API
+
+While most of the UART drivers provide all three APIs, some drivers still do not provide the asynchronous UART API.
+An example of such a driver is USB CDC ACM.
+The UART async adapter library is initialized with a UART device and communicates with it using the interrupt-driven API, providing an asynchronous API for the application.
+
+This removes the need to implement two ways of interfacing with UART devices in software.
+When using the UART async adapter library, the software only needs to implement interaction with a UART device using the asynchronous API and just initialize the adapter for the ones that do not support it.
+
+Requirements
+************
+
+To use the library, you need to enable the :kconfig:option:`CONFIG_UART_ASYNC_API` and :kconfig:option:`CONFIG_UART_INTERRUPT_DRIVEN` Kconfig options.
+
+Configuration
+*************
+
+Use the :kconfig:option:`CONFIG_UART_ASYNC_ADAPTER` Kconfig option to enable the library in the build system.
+
+Usage
+*****
+
+See the following code snippet to learn how to use this library:
+
+.. code-block:: c
+
+    #include <uart_async_adapter.h>
+
+    ...
+    /* Get the UART device we want to use */
+    static const struct device *uart = DEVICE_DT_GET([UART node identifier]);
+
+    /* Create UART async adapter instance */
+    UART_ASYNC_ADAPTER_INST_DEFINE(async_adapter);
+
+    /* UART initialization (called before any UART usage) */
+    static int uart_init(void)
+    {
+        if (!uart_test_async_api(uart)) {
+		/* Implement API adapter */
+		uart_async_adapter_init(async_adapter, uart);
+		uart = async_adapter;
+	}
+	/* Continue initialization using asynchronous API on uart device */
+	(...)
+    }
+
+.. note::
+   When using the library in the way shown in the code snippet, it is totally transparent to the application.
+
+If the selected UART device provides the asynchronous API, the adapter is not initialized.
+If the selected UART device does not provide the asynchronous API, the adapter is initialized to use such a device and a direct pointer to the device is replaced by the adapter.
+
+Samples using the library
+*************************
+
+The following |NCS| sample use this library:
+
+* :ref:`peripheral_uart`
+
+Limitations
+***********
+
+Using this library adds code and performance overhead over direct usage of UART asynchronous API provided by the driver.
+For UART drivers that only provide the interrupt-driven API, consider using it directly in the application.
+The library allows using UART devices with different APIs with only one API in the application, speeding up the development process.
+
+Dependencies
+************
+
+This module may use :ref:`zephyr:logging_api`.
+
+API documentation
+*****************
+
+| Header file: :file:`include/uart_async_adapter.h`
+| Source files: :file:`subsys/uart_async_adapter/`
+
+.. doxygengroup:: uart_async_adapter
+   :project: nrf
+   :members:
diff --git a/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst b/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst
@@ -362,7 +362,7 @@ Security libraries
 Other libraries
 ---------------
 
-|no_changes_yet_note|
+* Added the :ref:`lib_uart_async_adapter` library.
 
 Common Application Framework (CAF)
 ----------------------------------
diff --git a/include/uart_async_adapter.h b/include/uart_async_adapter.h
@@ -3,27 +3,31 @@
  *
  * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
  */
+#ifndef __UART_ASYNC_ADAPTER_H
+#define __UART_ASYNC_ADAPTER_H
 
 /** @file
  *  @brief UART asynchronous API adapter
  */
+#include <zephyr/device.h>
+#include <zephyr/drivers/uart.h>
+#include <zephyr/kernel.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
 
 /**
- * @brief UART asynchronous API universal adapter
- * @defgroup uart_async_adapter UART ASYNC adapter
+ * @defgroup uart_async_adapter UART async adapter
  * @{
+ * @brief UART asynchronous API universal adapter
  *
  * This module acts as an adapter between UART interrupt and async interface.
  *
- * @note The UART ASYNC API adapter implementation is experimental.
+ * @note The UART async API adapter implementation is experimental.
  *       It means it is not guaranteed to work in any corner situation.
  */
 
-#include <zephyr/device.h>
-#include <zephyr/drivers/uart.h>
-#include <zephyr/kernel.h>
-
-
 /**
  * @brief UART asynch adapter data structure
  *
@@ -42,7 +46,7 @@ struct uart_async_adapter_data {
 	struct k_spinlock lock;
 
 	/** Data used for output transmission */
-	struct {
+	struct uart_async_adapter_data_rx {
 		/** The original buffer pointer set when data transfer was requested */
 		const uint8_t *buf;
 		/** Current buffer position */
@@ -56,7 +60,7 @@ struct uart_async_adapter_data {
 	} tx;
 
 	/** Data used for input transmission */
-	struct {
+	struct uart_async_adapter_data_tx {
 		/** Base buffer pointer used now for data reception */
 		uint8_t *buf;
 		/** Current position to write data into */
@@ -79,7 +83,7 @@ struct uart_async_adapter_data {
 };
 
 /**
- * @brief Driver API for ASYNC adapter
+ * @brief Driver API for async adapter
  *
  * The API of the UART async adapter uses standard UART API structure.
  */
@@ -88,7 +92,7 @@ extern const struct uart_driver_api uart_async_adapter_driver_api;
 /**
  * @brief The name of the data instance connected with created device instance
  *
- * @name _dev_name The name of the created device instance
+ * @param _dev_name The name of the created device instance
  */
 #define UART_ASYNC_ADAPTER_INST_DATA_NAME(_dev_name) _CONCAT(uart_async_adapter_data_, _dev_name)
 
@@ -99,7 +103,7 @@ extern const struct uart_driver_api uart_async_adapter_driver_api;
 /**
  * @brief The macro that creates and instance of the UART async adapter
  *
- * @name _dev The name of the created device instance
+ * @param _dev The name of the created device instance
  */
 #define UART_ASYNC_ADAPTER_INST_DEFINE(_dev) \
 	static struct uart_async_adapter_data UART_ASYNC_ADAPTER_INST_DATA_NAME(_dev); \
@@ -124,3 +128,9 @@ extern const struct uart_driver_api uart_async_adapter_driver_api;
 void uart_async_adapter_init(const struct device *dev, const struct device *target);
 
 /** @} */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* __UART_ASYNC_ADAPTER_H */
diff --git a/samples/bluetooth/peripheral_uart/CMakeLists.txt b/samples/bluetooth/peripheral_uart/CMakeLists.txt
@@ -13,11 +13,6 @@ target_sources(app PRIVATE
   src/main.c
 )
 
-# Include UART ASYNC API adapter
-target_sources_ifdef(CONFIG_BT_NUS_UART_ASYNC_ADAPTER app PRIVATE
-  src/uart_async_adapter.c
-)
-
 # NORDIC SDK APP END
 
 zephyr_library_include_directories(.)
diff --git a/samples/bluetooth/peripheral_uart/Kconfig b/samples/bluetooth/peripheral_uart/Kconfig
@@ -33,11 +33,4 @@ config BT_NUS_UART_RX_WAIT_TIME
 	help
 	  Wait for RX complete event time in microseconds
 
-config BT_NUS_UART_ASYNC_ADAPTER
-	bool "Enable UART async adapter"
-	select SERIAL_SUPPORT_ASYNC
-	help
-	  Enables asynchronous adapter for UART drives that supports only
-	  IRQ interface.
-
 endmenu
diff --git a/samples/bluetooth/peripheral_uart/README.rst b/samples/bluetooth/peripheral_uart/README.rst
@@ -91,13 +91,11 @@ See :ref:`peripheral_uart_sample_activating_variants` for details about how to b
 Async adapter experimental module
 ---------------------------------
 
-The default sample configuration uses the UART async API, which is an :ref:`experimental <software_maturity>` module.
-The UART async adapter creates and initializes an instance of the async module.
+The default sample configuration uses the UART async API.
+The sample uses the :ref:`lib_uart_async_adapter` library to communicate with the USB CDC ACM driver.
 This is needed because the USB CDC ACM implementation provides only the interrupt interface.
-The adapter uses data provided in the :c:struct:`uart_async_adapter_data` to connect to the UART device that does not use the asynchronous interface.
 
-The module requires the :ref:`CONFIG_BT_NUS_UART_ASYNC_ADAPTER <CONFIG_BT_NUS_UART_ASYNC_ADAPTER>` to be set to ``y``.
-For more information about the adapter, see the :file:`uart_async_adapter` source files available in the :file:`peripheral_uart/src` directory.
+To use the library, set the :kconfig:option:`CONFIG_UART_ASYNC_ADAPTER` Kconfig option to ``y``.
 
 MCUboot with serial recovery of the networking core image
 =========================================================
@@ -148,9 +146,9 @@ Configuration options
 
 Check and configure the following configuration options for the sample:
 
-.. _CONFIG_BT_NUS_UART_ASYNC_ADAPTER:
+.. _CONFIG_UART_ASYNC_ADAPTER:
 
-CONFIG_BT_NUS_UART_ASYNC_ADAPTER - Enable UART async adapter
+CONFIG_UART_ASYNC_ADAPTER - Enable UART async adapter
    Enables asynchronous adapter for UART drives that supports only IRQ interface.
 
 Building and running
@@ -210,12 +208,9 @@ After programming the sample to your development kit, complete the following ste
 Dependencies
 ************
 
-This sample uses the following sample-specific library:
-
-* :file:`uart_async_adapter` at :file:`peripheral_uart/src`
-
 This sample uses the following |NCS| libraries:
 
+* :ref:`lib_uart_async_adapter`
 * :ref:`nus_service_readme`
 * :ref:`dk_buttons_and_leds_readme`
 
diff --git a/samples/bluetooth/peripheral_uart/boards/thingy53_nrf5340_cpuapp.conf b/samples/bluetooth/peripheral_uart/boards/thingy53_nrf5340_cpuapp.conf
@@ -20,7 +20,7 @@ CONFIG_USB_COMPOSITE_DEVICE=y
 # Enable back logging over UART as this sample config uses only RTT by default
 CONFIG_LOG_BACKEND_UART=y
 
-CONFIG_BT_NUS_UART_ASYNC_ADAPTER=y
+CONFIG_UART_ASYNC_ADAPTER=y
 CONFIG_UART_INTERRUPT_DRIVEN=y
 
 # Disable the UARTE0 enabled in default project configuration
diff --git a/samples/bluetooth/peripheral_uart/boards/thingy53_nrf5340_cpuapp_ns.conf b/samples/bluetooth/peripheral_uart/boards/thingy53_nrf5340_cpuapp_ns.conf
@@ -20,7 +20,7 @@ CONFIG_USB_COMPOSITE_DEVICE=y
 # Enable back logging over UART as this sample config uses only RTT by default
 CONFIG_LOG_BACKEND_UART=y
 
-CONFIG_BT_NUS_UART_ASYNC_ADAPTER=y
+CONFIG_UART_ASYNC_ADAPTER=y
 CONFIG_UART_INTERRUPT_DRIVEN=y
 
 # Disable the UARTE0 enabled in default project configuration
diff --git a/samples/bluetooth/peripheral_uart/prj_cdc.conf b/samples/bluetooth/peripheral_uart/prj_cdc.conf
@@ -7,7 +7,7 @@
 # Enable the UART driver
 CONFIG_UART_LINE_CTRL=y
 CONFIG_UART_INTERRUPT_DRIVEN=y
-CONFIG_BT_NUS_UART_ASYNC_ADAPTER=y
+CONFIG_UART_ASYNC_ADAPTER=y
 CONFIG_USB_DEVICE_STACK=y
 CONFIG_USB_DEVICE_REMOTE_WAKEUP=n
 CONFIG_USB_CDC_ACM=y
diff --git a/samples/bluetooth/peripheral_uart/src/main.c b/samples/bluetooth/peripheral_uart/src/main.c
@@ -7,7 +7,7 @@
 /** @file
  *  @brief Nordic UART Bridge Service (NUS) sample
  */
-#include "uart_async_adapter.h"
+#include <uart_async_adapter.h>
 
 #include <zephyr/types.h>
 #include <zephyr/kernel.h>
@@ -81,10 +81,10 @@ static const struct bt_data sd[] = {
 	BT_DATA_BYTES(BT_DATA_UUID128_ALL, BT_UUID_NUS_VAL),
 };
 
-#if CONFIG_BT_NUS_UART_ASYNC_ADAPTER
+#ifdef CONFIG_UART_ASYNC_ADAPTER
 UART_ASYNC_ADAPTER_INST_DEFINE(async_adapter);
 #else
-static const struct device *const async_adapter;
+#define async_adapter NULL
 #endif
 
 static void uart_cb(const struct device *dev, struct uart_event *evt, void *user_data)
@@ -260,7 +260,7 @@ static int uart_init(void)
 	k_work_init_delayable(&uart_work, uart_work_handler);
 
 
-	if (IS_ENABLED(CONFIG_BT_NUS_UART_ASYNC_ADAPTER) && !uart_test_async_api(uart)) {
+	if (IS_ENABLED(CONFIG_UART_ASYNC_ADAPTER) && !uart_test_async_api(uart)) {
 		/* Implement API adapter */
 		uart_async_adapter_init(async_adapter, uart);
 		uart = async_adapter;
diff --git a/subsys/CMakeLists.txt b/subsys/CMakeLists.txt
@@ -68,3 +68,4 @@ add_subdirectory_ifdef(CONFIG_NRF_DM dm)
 add_subdirectory_ifdef(CONFIG_EMDS emds)
 add_subdirectory_ifdef(CONFIG_NET_CORE_MONITOR net_core_monitor)
 add_subdirectory_ifdef(CONFIG_AUDIO_MODULE audio_module)
+add_subdirectory_ifdef(CONFIG_UART_ASYNC_ADAPTER uart_async_adapter)
diff --git a/subsys/Kconfig b/subsys/Kconfig
@@ -33,5 +33,6 @@ rsource "dm/Kconfig"
 rsource "nrf_security/Kconfig"
 rsource "net_core_monitor/Kconfig"
 rsource "audio_module/Kconfig"
+rsource "uart_async_adapter/Kconfig"
 rsource "trusted_storage/Kconfig"
 endmenu
diff --git a/subsys/uart_async_adapter/CMakeLists.txt b/subsys/uart_async_adapter/CMakeLists.txt
@@ -0,0 +1,7 @@
+#
+# Copyright (c) 2024 Nordic Semiconductor
+#
+# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+#
+
+zephyr_sources(uart_async_adapter.c)
diff --git a/subsys/uart_async_adapter/Kconfig b/subsys/uart_async_adapter/Kconfig
@@ -0,0 +1,22 @@
+#
+# Copyright (c) 2024 Nordic Semiconductor
+#
+# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+#
+
+menuconfig UART_ASYNC_ADAPTER
+	bool "Enable UART async adapter [EXPERIMENTAL]"
+	select EXPERIMENTAL
+	select SERIAL_SUPPORT_ASYNC
+	depends on SERIAL_SUPPORT_INTERRUPT
+	help
+	  Enables asynchronous adapter for UART drives that supports only
+	  IRQ interface.
+
+if UART_ASYNC_ADAPTER
+
+module = UART_ASYNC_ADAPTER
+module-str = UART Async Adapter
+source "${ZEPHYR_BASE}/subsys/logging/Kconfig.template.log_config"
+
+endif
diff --git a/subsys/uart_async_adapter/uart_async_adapter.c b/subsys/uart_async_adapter/uart_async_adapter.c
@@ -7,12 +7,12 @@
 /** @file
  *  @brief UART asynchronous API adapter implementation
  */
-#include "uart_async_adapter.h"
+#include <uart_async_adapter.h>
 #include <zephyr/drivers/uart.h>
 #include <zephyr/sys/__assert.h>
 
 #include <zephyr/logging/log.h>
-LOG_MODULE_REGISTER(uart_async_adapter);
+LOG_MODULE_REGISTER(uart_async_adapter, CONFIG_UART_ASYNC_ADAPTER_LOG_LEVEL);
 
 
 #if !IS_ENABLED(CONFIG_UART_ASYNC_API)
