✨ (minor) Add console & steady clock (#12)

Author: kammce

CMakeLists.txt

@@ -21,6 +21,8 @@ libhal_test_and_make_library(
 
   SOURCES
   src/serial.cpp
+  src/console.cpp
+  src/steady_clock.cpp
 
   TEST_SOURCES
   tests/main.test.cpp

conanfile.py

@@ -35,7 +35,7 @@ class libhal_mac_conan(ConanFile):
     def requirements(self):
         # Replace with appropriate processor library
         self.requires("libhal/[^4.12.0]", transitive_headers=True)
-        self.requires("libhal-util/[^5.2.0]", transitive_headers=True)
+        self.requires("libhal-util/[^5.5.0]", transitive_headers=True)
 
     def package_info(self):
         self.cpp_info.set_property("cmake_target_name", "libhal::mac")

include/libhal-mac/console.hpp

@@ -0,0 +1,97 @@
+// Copyright 2024 - 2025 Khalil Estell and the libhal contributors
+//
+// 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
+//
+//      http://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.
+
+#pragma once
+
+#include <atomic>
+#include <memory_resource>
+#include <span>
+#include <thread>
+#include <vector>
+
+#include <libhal/pointers.hpp>
+#include <libhal/serial.hpp>
+#include <libhal/units.hpp>
+
+namespace hal::mac::inline v1 {
+/**
+ * @brief Serial communication interface using macOS console (stdin/stdout)
+ *
+ * Provides a way to simulate serial communication on macOS by redirecting
+ * serial I/O operations to the console. This is particularly useful for
+ * testing serial-based communication protocols and debugging embedded
+ * applications that rely on serial interfaces.
+ *
+ * The implementation uses a background thread to continuously read from stdin
+ * and store data in a circular buffer, while write operations are sent
+ * directly to stdout.
+ */
+class console_serial : public hal::v5::serial
+{
+public:
+  /**
+   * @brief Create a console serial instance
+   *
+   * @param p_allocator Memory allocator for internal buffer management
+   * @param p_buffer_size Size of the internal circular receive buffer (min: 32)
+   * @return A strong_ptr to the created console_serial instance
+   */
+  [[nodiscard]] static hal::v5::strong_ptr<console_serial> create(
+    std::pmr::polymorphic_allocator<> p_allocator,
+    hal::usize p_buffer_size);
+
+  /**
+   * @brief Public constructor - but use create() instead
+   */
+  console_serial(hal::v5::strong_ptr_only_token,
+                 std::pmr::polymorphic_allocator<> p_allocator,
+                 hal::usize p_buffer_size);
+
+  /**
+   * @brief Destroy the console serial object
+   *
+   * Stops the background receive thread and waits for it to complete before
+   * destruction.
+   */
+  ~console_serial() override;
+
+  // Non-copyable and non-movable
+  console_serial(console_serial const&) = delete;
+  console_serial& operator=(console_serial const&) = delete;
+  console_serial(console_serial&&) = delete;
+  console_serial& operator=(console_serial&&) = delete;
+
+private:
+  void driver_configure(hal::v5::serial::settings const& p_settings) override;
+  void driver_write(std::span<hal::byte const> p_data) override;
+  std::span<hal::byte const> driver_receive_buffer() override;
+  hal::usize driver_cursor() override;
+
+  /**
+   * @brief Background thread function for reading from stdin
+   */
+  void receive_thread_function();
+
+  /// Memory allocator for buffer management
+  std::pmr::polymorphic_allocator<> m_allocator;
+  /// Circular buffer for storing received data from stdin
+  std::pmr::vector<hal::byte> m_receive_buffer;
+  /// Atomic cursor position for thread-safe buffer access
+  std::atomic<hal::usize> m_receive_cursor{ 0 };
+  /// Atomic flag to signal thread termination
+  std::atomic<bool> m_stop_thread{ false };
+  /// Background thread for reading from stdin
+  std::thread m_receive_thread;
+};
+}  // namespace hal::mac::inline v1

include/libhal-mac/serial.hpp

@@ -111,25 +111,15 @@ class serial
   /**
    * @brief Set the DTR (Data Terminal Ready) signal state
    *
-<<<<<<< HEAD
-   * @param p_state true to assert DTR (set high), false to deassert (set low)
-=======
-   * @param p_state true to assert DTR (set high), false to de-assert (set
-low)
->>>>>>> 520fe79 (:tada: First commit w/ serial impl (#1))
+   * @param p_state true to assert DTR (set high), false to de-assert (set low)
    * @throws hal::operation_not_permitted if the operation fails
    */
   void set_dtr(bool p_state);
 
   /**
    * @brief Set the RTS (Request To Send) signal state
    *
-<<<<<<< HEAD
-   * @param p_state true to assert RTS (set high), false to deassert (set low)
-=======
-   * @param p_state true to assert RTS (set high), false to de-assert (set
-low)
->>>>>>> 520fe79 (:tada: First commit w/ serial impl (#1))
+   * @param p_state true to assert RTS (set high), false to de-assert (set low)
    * @throws hal::operation_not_permitted if the operation fails
    */
   void set_rts(bool p_state);

include/libhal-mac/steady_clock.hpp

@@ -0,0 +1,98 @@
+// Copyright 2024 - 2025 Khalil Estell and the libhal contributors
+//
+// 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
+//
+//      http://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.
+
+#pragma once
+
+#include <chrono>
+#include <memory_resource>
+
+#include <libhal/pointers.hpp>
+#include <libhal/steady_clock.hpp>
+#include <libhal/units.hpp>
+
+namespace hal::mac::inline v1 {
+/**
+ * @brief Steady clock implementation using std::chrono::steady_clock for v5
+ * interface
+ *
+ * Provides a high-resolution, monotonic time source for embedded applications
+ * running on macOS. The clock is guaranteed to never go backwards, making it
+ * suitable for measuring time intervals, implementing timeouts, and scheduling
+ * periodic tasks.
+ *
+ * The uptime is measured from the time of object construction, and the
+ * frequency is derived from std::chrono::steady_clock's period.
+ */
+class steady_clock
+  : public hal::v5::steady_clock
+  , public hal::v5::enable_strong_from_this<steady_clock>
+{
+public:
+  /**
+   * @brief Create a steady clock instance
+   *
+   * @param p_allocator Memory allocator (unused but follows libhal patterns)
+   * @return A strong_ptr to the created steady_clock instance
+   */
+  [[nodiscard]] static hal::v5::strong_ptr<steady_clock> create(
+    std::pmr::polymorphic_allocator<> p_allocator);
+
+  /**
+   * @brief Public constructor - but use create() instead
+   */
+  steady_clock(hal::v5::strong_ptr_only_token);
+
+private:
+  hal::v5::hertz driver_frequency() override;
+  hal::u64 driver_uptime() override;
+
+  /// Reference time point from construction for uptime calculations
+  std::chrono::steady_clock::time_point m_start_time;
+};
+
+/**
+ * @brief Steady clock implementation using std::chrono::steady_clock for legacy
+ * interface
+ *
+ * Provides the same functionality as steady_clock but implements the
+ * legacy hal::steady_clock interface for backward compatibility with older
+ * libhal code that hasn't been updated to the v5 API.
+ */
+class legacy_steady_clock
+  : public hal::steady_clock
+  , public hal::v5::enable_strong_from_this<legacy_steady_clock>
+{
+public:
+  /**
+   * @brief Create a legacy steady clock instance
+   *
+   * @param p_allocator Memory allocator (unused but follows libhal patterns)
+   * @return A strong_ptr to the created legacy_steady_clock instance
+   */
+  [[nodiscard]] static hal::v5::strong_ptr<legacy_steady_clock> create(
+    std::pmr::polymorphic_allocator<> p_allocator);
+
+  /**
+   * @brief Public constructor - but use create() instead
+   */
+  legacy_steady_clock(hal::v5::strong_ptr_only_token);
+
+private:
+  hal::hertz driver_frequency() override;
+  hal::u64 driver_uptime() override;
+
+  /// Reference time point from construction for uptime calculations
+  std::chrono::steady_clock::time_point m_start_time;
+};
+}  // namespace hal::mac::inline v1

src/console.cpp

@@ -0,0 +1,95 @@
+// Copyright 2024 - 2025 Khalil Estell and the libhal contributors
+//
+// 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
+//
+//      http://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.
+
+#include <libhal-mac/console.hpp>
+
+#include <chrono>
+#include <cstdio>
+
+#include <libhal/error.hpp>
+
+namespace hal::mac::inline v1 {
+
+hal::v5::strong_ptr<console_serial> console_serial::create(
+  std::pmr::polymorphic_allocator<> p_allocator,
+  hal::usize p_buffer_size)
+{
+  if (p_buffer_size < 32) {
+    p_buffer_size = 32;
+  }
+
+  return hal::v5::make_strong_ptr<console_serial>(
+    p_allocator, p_allocator, p_buffer_size);
+}
+
+console_serial::console_serial(hal::v5::strong_ptr_only_token,
+                               std::pmr::polymorphic_allocator<> p_allocator,
+                               hal::usize p_buffer_size)
+  : m_allocator(p_allocator)
+  , m_receive_buffer(p_buffer_size, hal::byte{ 0 }, p_allocator)
+  , m_receive_thread(&console_serial::receive_thread_function, this)
+{
+}
+
+console_serial::~console_serial()
+{
+  m_stop_thread.store(true, std::memory_order_release);
+  if (m_receive_thread.joinable()) {
+    m_receive_thread.join();
+  }
+}
+
+void console_serial::driver_configure(
+  hal::v5::serial::settings const& p_settings)
+{
+  // Console doesn't need configuration - settings are ignored
+  static_cast<void>(p_settings);
+}
+
+void console_serial::driver_write(std::span<hal::byte const> p_data)
+{
+  // Use fwrite to stdout for binary safety
+  std::fwrite(p_data.data(), 1, p_data.size(), stdout);
+  std::fflush(stdout);
+}
+
+std::span<hal::byte const> console_serial::driver_receive_buffer()
+{
+  return m_receive_buffer;
+}
+
+hal::usize console_serial::driver_cursor()
+{
+  return m_receive_cursor.load(std::memory_order_acquire);
+}
+
+void console_serial::receive_thread_function()
+{
+  while (!m_stop_thread.load(std::memory_order_acquire)) {
+    int ch = std::getchar();
+
+    if (ch != EOF) {
+      auto current_cursor = m_receive_cursor.load(std::memory_order_acquire);
+      m_receive_buffer[current_cursor] = static_cast<hal::byte>(ch);
+
+      auto new_cursor = (current_cursor + 1) % m_receive_buffer.size();
+      m_receive_cursor.store(new_cursor, std::memory_order_release);
+    } else {
+      // No data available, sleep briefly to avoid busy waiting
+      std::this_thread::sleep_for(std::chrono::milliseconds(10));
+    }
+  }
+}
+
+}  // namespace hal::mac::inline v1