pw_uart: Add uart_non_blocking.h API

This CL adds a callback UART API, uart_non_blocking.h, UartNonBlocking. Bug: 341356437 Bug: 331617095 Change-Id: Id670b07786a3437d101b9b1cbc94fb1570944a19 Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/210371 Commit-Queue: Alan Rosenthal <[email protected]> Reviewed-by: Jonathon Reinhart <[email protected]> Reviewed-by: Rishi Sikka <[email protected]> Presubmit-Verified: CQ Bot Account <[email protected]> Reviewed-by: Taylor Cramer <[email protected]> Lint: Lint 🤖 <[email protected]> Reviewed-by: Edward Shin <[email protected]>
google · Sep 26, 2024 · f946f6a · f946f6a
1 parent bbd82e3
commit f946f6a
Show file tree

Hide file tree

Showing 8 changed files with 474 additions and 3 deletions.
diff --git a/docs/BUILD.gn b/docs/BUILD.gn
@@ -334,6 +334,7 @@ _doxygen_input_files = [  # keep-sorted: start
   "$dir_pw_toolchain/public/pw_toolchain/no_destructor.h",
   "$dir_pw_transfer/public/pw_transfer/atomic_file_transfer_handler.h",
   "$dir_pw_uart/public/pw_uart/uart.h",
+  "$dir_pw_uart/public/pw_uart/uart_non_blocking.h",
   "$dir_pw_unit_test/light_public_overrides/pw_unit_test/framework_backend.h",
   "$dir_pw_unit_test/public/pw_unit_test/config.h",
   "$dir_pw_unit_test/public/pw_unit_test/event_handler.h",

diff --git a/pw_uart/BUILD.bazel b/pw_uart/BUILD.bazel
@@ -31,6 +31,20 @@ cc_library(
         "//pw_assert",
         "//pw_bytes",
         "//pw_chrono:system_clock",
+        "//pw_span",
+        "//pw_status",
+    ],
+)
+
+cc_library(
+    name = "uart_non_blocking",
+    hdrs = [
+        "public/pw_uart/uart_non_blocking.h",
+    ],
+    includes = ["public"],
+    deps = [
+        "//pw_assert",
+        "//pw_bytes",
         "//pw_function",
         "//pw_span",
         "//pw_status",
@@ -48,6 +62,17 @@ pw_cc_test(
     ],
 )
 
+pw_cc_test(
+    name = "uart_non_blocking_test",
+    srcs = [
+        "uart_non_blocking_test.cc",
+    ],
+    deps = [
+        ":uart_non_blocking",
+        "//pw_unit_test",
+    ],
+)
+
 # Bazel does not yet support building docs.
 filegroup(
     name = "docs",

diff --git a/pw_uart/BUILD.gn b/pw_uart/BUILD.gn
@@ -32,6 +32,17 @@ pw_source_set("uart") {
     "$dir_pw_assert",
     "$dir_pw_bytes",
     "$dir_pw_chrono:system_clock",
+    "$dir_pw_span",
+    "$dir_pw_status",
+  ]
+}
+
+pw_source_set("uart_non_blocking") {
+  public_configs = [ ":public_include_path" ]
+  public = [ "public/pw_uart/uart_non_blocking.h" ]
+  public_deps = [
+    "$dir_pw_assert",
+    "$dir_pw_bytes",
     "$dir_pw_function",
     "$dir_pw_span",
     "$dir_pw_status",
@@ -44,8 +55,17 @@ pw_test("uart_test") {
   deps = [ ":uart" ]
 }
 
+pw_test("uart_non_blocking_test") {
+  enable_if = pw_chrono_SYSTEM_CLOCK_BACKEND != ""
+  sources = [ "uart_non_blocking_test.cc" ]
+  deps = [ ":uart_non_blocking" ]
+}
+
 pw_doc_group("docs") {
-  inputs = [ "public/pw_uart/uart.h" ]
+  inputs = [
+    "public/pw_uart/uart.h",
+    "public/pw_uart/uart_non_blocking.h",
+  ]
   sources = [
     "backends.rst",
     "docs.rst",

diff --git a/pw_uart/CMakeLists.txt b/pw_uart/CMakeLists.txt
@@ -23,6 +23,18 @@ pw_add_library(pw_uart.uart INTERFACE
     pw_assert
     pw_bytes
     pw_chrono.system_clock
+    pw_status
+    pw_span
+)
+
+pw_add_library(pw_uart.uart_non_blocking INTERFACE
+  HEADERS
+    public/pw_uart/uart_non_blocking.h
+  PUBLIC_INCLUDES
+    public
+  PUBLIC_DEPS
+    pw_assert
+    pw_bytes
     pw_function
     pw_status
     pw_span

diff --git a/pw_uart/docs.rst b/pw_uart/docs.rst
@@ -11,6 +11,9 @@ as a blueprint for concrete UART implementations. You will need to write the
 backend code tailored to your specific hardware device to interact with the
 UART peripheral.
 
+Note: Drivers should not implement both Uart and UartNonBlocking. Drivers
+implement UartNonBlocking. A future adapter will allow a UartNonBlocking to be used as Uart.
+
 -----------
 Get started
 -----------
@@ -76,7 +79,8 @@ API reference
 .. doxygengroup:: pw_uart
    :content-only:
    :members:
-
+.. doxygenclass:: pw::uart::UartNonBlocking
+  :members:
 
 .. toctree::
    :hidden:

diff --git a/pw_uart/public/pw_uart/uart.h b/pw_uart/public/pw_uart/uart.h
@@ -21,7 +21,6 @@
 #include "pw_assert/assert.h"
 #include "pw_bytes/span.h"
 #include "pw_chrono/system_clock.h"
-#include "pw_function/function.h"
 #include "pw_status/status.h"
 #include "pw_status/status_with_size.h"