uart_requirements.hpp

Go to the documentation of this file.

/**
 * @file uart_requirements.hpp
 * @brief UART driver requirements validator
 * @ingroup validation
 *
 * Validates that UART drivers provide required functionality using the
 * method detection system. This is the core UART contract enforcement
 * for Sound Byte Libs drivers.
 *
 * ## UART Driver Contract
 *
 * Every Sound Byte Libs UART driver MUST implement these methods:
 * - `init(const UartHandle&)` - Initialize UART with manifest-resolved handle
 * - `init_rx(const UartHandle&)` - Initialize UART for RX-only (MIDI, sensors)
 * - `write_byte(uint8_t)` - Write single byte (blocking)
 * - `write(const uint8_t*, size_t)` - Write buffer (blocking)
 * - `write_string(const char*)` - Write null-terminated string (blocking)
 * - `available() -> bool` - Check if RX data is available
 * - `read_byte() -> uint8_t` - Read single byte from RX buffer
 *
 * Optional methods (validated if present):
 * - `try_write_byte(uint8_t) -> bool` - Non-spinning TX (STM32 only)
 * - `try_write_string(const char*) -> size_t` - Non-spinning TX (STM32 only)
 *
 * ## Validation Usage
 *
 * Add validation at the bottom of driver uart.hpp:
 * ```cpp
 * #include <sbl/validation/uart_requirements.hpp>
 * static_assert(sbl::validation::uart_driver_valid<sbl::driver::Uart<>>,
 *               "UART driver missing required methods");
 * ```
 *
 * @see method_detection.hpp
 */
 
#ifndef SBL_VALIDATION_UART_REQUIREMENTS_HPP_
#define SBL_VALIDATION_UART_REQUIREMENTS_HPP_
 
#include "method_detection.hpp"
 
namespace sbl {
namespace validation {
 
/**
 * @brief UART driver requirements validator
 *
 * Validates that UART drivers provide all required methods with correct
 * signatures and return types.
 */
template<typename UartDriver>
class UartDriverRequirements {
public:
    /**
     * @brief Validate all required UART methods
     */
    static constexpr bool validate() {
        // --- Required methods (all platforms) ---
 
        static_assert(has_uart_init<UartDriver>::value,
                      "SBL ERROR: UART driver missing init() method.\n"
                      "Required: static void/bool init(const sbl::UartHandle& handle)");
 
        static_assert(has_uart_init_rx<UartDriver>::value,
                      "SBL ERROR: UART driver missing init_rx() method.\n"
                      "Required: static void/bool init_rx(const sbl::UartHandle& handle)");
 
        static_assert(has_uart_write_byte<UartDriver>::value,
                      "SBL ERROR: UART driver missing write_byte() method.\n"
                      "Required: static void write_byte(uint8_t byte)");
 
        static_assert(has_uart_write<UartDriver>::value,
                      "SBL ERROR: UART driver missing write() method.\n"
                      "Required: static void write(const uint8_t* data, size_t len)");
 
        static_assert(has_uart_write_string<UartDriver>::value,
                      "SBL ERROR: UART driver missing write_string() method.\n"
                      "Required: static void write_string(const char* str)");
 
        static_assert(has_uart_available<UartDriver>::value,
                      "SBL ERROR: UART driver missing available() method.\n"
                      "Required: static bool available()");
 
        static_assert(has_uart_read_byte<UartDriver>::value,
                      "SBL ERROR: UART driver missing read_byte() method.\n"
                      "Required: static uint8_t read_byte()");
 
        // --- Return type validation ---
 
        static_assert(uart_available_returns_bool<UartDriver>::value,
                      "SBL ERROR: UART available() must return bool.");
 
        static_assert(uart_read_byte_returns_uint8<UartDriver>::value,
                      "SBL ERROR: UART read_byte() must return uint8_t.");
 
        // --- Optional methods (validated if present) ---
 
        static_assert(
            !has_uart_try_write_byte<UartDriver>::value ||
            uart_try_write_byte_returns_bool<UartDriver>::value,
            "SBL ERROR: If UART provides try_write_byte(), it must return bool.");
 
        return true;
    }
};
 
/**
 * @brief Helper to validate a UART driver implementation
 *
 * Usage:
 * ```cpp
 * static_assert(sbl::validation::uart_driver_valid<MyUartDriver>,
 *               "UART driver incomplete");
 * ```
 */
template<typename UartDriver>
constexpr bool uart_driver_valid = UartDriverRequirements<UartDriver>::validate();
 
} // namespace validation
} // namespace sbl
 
#endif // SBL_VALIDATION_UART_REQUIREMENTS_HPP_