feat: add lab-rv32i-freertos-integration card

include/FreeRTOSConfig.h

@@ -0,0 +1,70 @@
+#ifndef FREERTOS_CONFIG_H
+#define FREERTOS_CONFIG_H
+
+#define configCPU_CLOCK_HZ                       ( 10000000UL )
+#define configTICK_RATE_HZ                       ( 1000U )
+#define configMTIME_BASE_ADDRESS                 ( 0xC0000100UL )
+#define configMTIMECMP_BASE_ADDRESS              ( 0xC0000108UL )
+#define configUSE_PREEMPTION                     1
+#define configUSE_TIME_SLICING                   1
+#define configNUMBER_OF_CORES                    1
+#define configUSE_PORT_OPTIMISED_TASK_SELECTION  0
+#define configUSE_IDLE_HOOK                      0
+#define configUSE_TICK_HOOK                      0
+#define configMAX_PRIORITIES                     5
+#define configMINIMAL_STACK_SIZE                 128
+#define configMAX_TASK_NAME_LEN                  16
+#define configTICK_TYPE_WIDTH_IN_BITS            TICK_TYPE_WIDTH_32_BITS
+#define configIDLE_SHOULD_YIELD                  1
+
+#define configSUPPORT_DYNAMIC_ALLOCATION         1
+#define configSUPPORT_STATIC_ALLOCATION          1
+#define configKERNEL_PROVIDED_STATIC_MEMORY      1
+#define configTOTAL_HEAP_SIZE                    ( 16U * 1024U )
+#define configAPPLICATION_ALLOCATED_HEAP         1
+#define configUSE_MALLOC_FAILED_HOOK             0
+#define configHEAP_CLEAR_MEMORY_ON_FREE          0
+
+#define configUSE_TIMERS                         1
+#define configTIMER_TASK_PRIORITY                4
+#define configTIMER_QUEUE_LENGTH                 8
+#define configTIMER_TASK_STACK_DEPTH             256
+#define configUSE_MUTEXES                        0
+#define configUSE_RECURSIVE_MUTEXES              0
+#define configUSE_COUNTING_SEMAPHORES            0
+#define configUSE_TASK_NOTIFICATIONS             1
+#define configUSE_TRACE_FACILITY                 1
+#define configUSE_STATS_FORMATTING_FUNCTIONS     0
+#define configGENERATE_RUN_TIME_STATS            0
+#define configUSE_CO_ROUTINES                    0
+#define configUSE_NEWLIB_REENTRANT               0
+#define configUSE_POSIX_ERRNO                    0
+#define configCHECK_FOR_STACK_OVERFLOW           0
+#define configRECORD_STACK_HIGH_ADDRESS          1
+
+#define INCLUDE_vTaskDelay                       1
+#define INCLUDE_vTaskDelayUntil                  0
+#define INCLUDE_vTaskDelete                      1
+#define INCLUDE_vTaskSuspend                     1
+#define INCLUDE_eTaskGetState                    1
+#define INCLUDE_uxTaskPriorityGet                1
+#define INCLUDE_vTaskPrioritySet                 0
+#define INCLUDE_xTaskGetSchedulerState           1
+#define INCLUDE_uxTaskGetStackHighWaterMark      1
+#define INCLUDE_xTimerPendFunctionCall           0
+
+#define configENABLE_FPU                         0
+#define configENABLE_VPU                         0
+#define configISR_STACK_SIZE_WORDS               256
+
+#ifndef __ASSEMBLER__
+    #ifdef __cplusplus
+extern "C" void lab_assert_fail( const char * file, int line );
+    #else
+void lab_assert_fail( const char * file, int line );
+    #endif
+    #define configASSERT( condition ) do { if( !( condition ) ) { lab_assert_fail( __FILE__, __LINE__ ); } } while( 0 )
+#else
+    #define configASSERT( condition )
+#endif
+#endif

include/freertos/event_group.hpp

@@ -0,0 +1,151 @@
+#ifndef FREERTOS_CPP_EVENT_GROUP_HPP
+#define FREERTOS_CPP_EVENT_GROUP_HPP
+
+#include <stdint.h>
+#include <type_traits>
+
+extern "C"
+{
+#include "FreeRTOS.h"
+#include "event_groups.h"
+}
+
+namespace freertos
+{
+
+enum class WaitMode : uint8_t
+{
+    any,
+    all
+};
+
+enum class ClearMode : uint8_t
+{
+    keep,
+    clear_on_exit
+};
+
+template< typename Bit >
+class EventMask final
+{
+    static_assert( std::is_enum< Bit >::value,
+                   "EventMask requires an enum bit type" );
+
+public:
+    constexpr EventMask() noexcept = default;
+    explicit constexpr EventMask( Bit bit ) noexcept
+        : value_ { static_cast< EventBits_t >( bit ) }
+    {
+    }
+
+    [[nodiscard]] static constexpr EventMask from_raw(
+        EventBits_t value ) noexcept
+    {
+        return EventMask { value, RawTag {} };
+    }
+
+    [[nodiscard]] constexpr EventBits_t raw() const noexcept { return value_; }
+    [[nodiscard]] constexpr bool contains( EventMask other ) const noexcept
+    {
+        return ( value_ & other.value_ ) == other.value_;
+    }
+
+    friend constexpr EventMask operator|( EventMask left,
+                                          EventMask right ) noexcept
+    {
+        return from_raw( left.value_ | right.value_ );
+    }
+
+private:
+    struct RawTag {};
+    constexpr EventMask( EventBits_t value, RawTag ) noexcept : value_ { value } {}
+    EventBits_t value_ {};
+};
+
+template< typename Bit >
+struct WaitResult final
+{
+    EventMask< Bit > observed {};
+
+    [[nodiscard]] constexpr bool satisfied( EventMask< Bit > wanted,
+                                            WaitMode mode ) const noexcept
+    {
+        const EventBits_t matched = observed.raw() & wanted.raw();
+        return mode == WaitMode::all ? matched == wanted.raw() : matched != 0U;
+    }
+};
+
+struct StaticEventGroupStorage final
+{
+    StaticEventGroup_t control {};
+};
+
+template< typename Bit >
+class EventGroup final
+{
+    static_assert( std::is_enum< Bit >::value,
+                   "EventGroup requires an enum bit type" );
+
+public:
+    explicit EventGroup( StaticEventGroupStorage & storage ) noexcept
+        : handle_ { xEventGroupCreateStatic( &storage.control ) }
+    {
+    }
+
+    ~EventGroup() noexcept
+    {
+        if( handle_ != nullptr ) vEventGroupDelete( handle_ );
+    }
+
+    EventGroup( const EventGroup & ) = delete;
+    EventGroup & operator=( const EventGroup & ) = delete;
+    EventGroup( EventGroup && ) = delete;
+    EventGroup & operator=( EventGroup && ) = delete;
+
+    [[nodiscard]] bool valid() const noexcept { return handle_ != nullptr; }
+
+    [[nodiscard]] EventMask< Bit > set( EventMask< Bit > bits ) noexcept
+    {
+        return EventMask< Bit >::from_raw(
+            xEventGroupSetBits( handle_, bits.raw() ) );
+    }
+
+    [[nodiscard]] EventMask< Bit > clear( EventMask< Bit > bits ) noexcept
+    {
+        return EventMask< Bit >::from_raw(
+            xEventGroupClearBits( handle_, bits.raw() ) );
+    }
+
+    [[nodiscard]] EventMask< Bit > bits() const noexcept
+    {
+        return EventMask< Bit >::from_raw( xEventGroupGetBits( handle_ ) );
+    }
+
+    [[nodiscard]] WaitResult< Bit > wait( EventMask< Bit > wanted,
+                                          WaitMode mode,
+                                          ClearMode clear,
+                                          TickType_t timeout ) noexcept
+    {
+        const EventBits_t result = xEventGroupWaitBits(
+            handle_, wanted.raw(),
+            clear == ClearMode::clear_on_exit ? pdTRUE : pdFALSE,
+            mode == WaitMode::all ? pdTRUE : pdFALSE,
+            timeout );
+        return { EventMask< Bit >::from_raw( result ) };
+    }
+
+    [[nodiscard]] EventGroupHandle_t native_handle() const noexcept
+    {
+        return handle_;
+    }
+
+private:
+    EventGroupHandle_t handle_ {};
+};
+
+static_assert( !std::is_copy_constructible<
+               EventGroup< WaitMode > >::value );
+
+} // namespace freertos
+
+#endif

include/freertos/isr_drivers.hpp

@@ -0,0 +1,278 @@
+#ifndef FREERTOS_ISR_DRIVERS_HPP
+#define FREERTOS_ISR_DRIVERS_HPP
+
+#include <cstddef>
+#include <cstdint>
+#include <type_traits>
+
+extern "C"
+{
+#include "FreeRTOS.h"
+#include "queue.h"
+#include "task.h"
+}
+
+namespace freertos
+{
+
+class IsrContext final
+{
+public:
+    void merge_wake_request( BaseType_t local_request ) noexcept
+    {
+        if( local_request != pdFALSE )
+        {
+            higher_priority_task_woken_ = pdTRUE;
+        }
+    }
+
+    [[nodiscard]] bool wake_requested() const noexcept
+    {
+        return higher_priority_task_woken_ != pdFALSE;
+    }
+
+    [[nodiscard]] std::uint32_t yield_calls() const noexcept
+    {
+        return yield_calls_;
+    }
+
+    [[nodiscard]] bool yield_if_needed() noexcept
+    {
+        ++yield_calls_;
+        bool const requested = wake_requested();
+        portYIELD_FROM_ISR( higher_priority_task_woken_ );
+        return requested;
+    }
+
+private:
+    BaseType_t higher_priority_task_woken_{ pdFALSE };
+    std::uint32_t yield_calls_{ 0U };
+};
+
+enum class IsrSendResult
+{
+    queued,
+    dropped_newest
+};
+
+template< typename T, std::size_t Capacity >
+class StaticIsrQueue final
+{
+    static_assert( Capacity > 0U );
+    static_assert( std::is_trivially_copyable_v< T > );
+
+public:
+    StaticIsrQueue( StaticQueue_t & control, std::uint8_t * bytes ) noexcept
+        : handle_( xQueueCreateStatic( static_cast< UBaseType_t >( Capacity ),
+                                       static_cast< UBaseType_t >( sizeof( T ) ),
+                                       bytes,
+                                       &control ) )
+    {
+    }
+
+    StaticIsrQueue( const StaticIsrQueue & ) = delete;
+    StaticIsrQueue & operator=( const StaticIsrQueue & ) = delete;
+
+    [[nodiscard]] bool valid() const noexcept
+    {
+        return handle_ != nullptr;
+    }
+
+    [[nodiscard]] IsrSendResult send_from_isr( const T & item,
+                                               IsrContext & context ) noexcept
+    {
+        BaseType_t local_wake = pdFALSE;
+        BaseType_t const result = xQueueSendFromISR( handle_, &item, &local_wake );
+        context.merge_wake_request( local_wake );
+        return result == pdPASS ? IsrSendResult::queued
+                                : IsrSendResult::dropped_newest;
+    }
+
+    [[nodiscard]] bool receive( T & item, TickType_t timeout ) noexcept
+    {
+        return xQueueReceive( handle_, &item, timeout ) == pdPASS;
+    }
+
+private:
+    QueueHandle_t handle_;
+};
+
+class TaskNotificationRef final
+{
+public:
+    explicit constexpr TaskNotificationRef( TaskHandle_t task ) noexcept
+        : task_( task )
+    {
+    }
+
+    [[nodiscard]] bool give_from_isr( IsrContext & context ) const noexcept
+    {
+        BaseType_t local_wake = pdFALSE;
+        vTaskNotifyGiveFromISR( task_, &local_wake );
+        context.merge_wake_request( local_wake );
+        return true;
+    }
+
+private:
+    TaskHandle_t task_;
+};
+
+struct UartRegisters
+{
+    volatile std::uint32_t status;
+    volatile std::uint32_t rx_data[ 2 ];
+    volatile std::uint32_t rx_count;
+    volatile std::uint32_t control;
+};
+
+class UartTaskView final
+{
+public:
+    explicit constexpr UartTaskView( UartRegisters & registers ) noexcept
+        : registers_( &registers )
+    {
+    }
+
+    void enable_rx_irq() const noexcept { registers_->control = 1U; }
+
+    void inject_rx_pair_for_test( std::uint8_t first,
+                                  std::uint8_t second ) const noexcept
+    {
+        registers_->rx_data[ 0 ] = first;
+        registers_->rx_data[ 1 ] = second;
+        registers_->rx_count = 2U;
+        registers_->status = 1U;
+    }
+
+private:
+    UartRegisters * registers_;
+};
+
+class UartIsrView final
+{
+public:
+    explicit constexpr UartIsrView( UartRegisters & registers ) noexcept
+        : registers_( &registers )
+    {
+    }
+
+    [[nodiscard]] bool rx_ready_from_isr() const noexcept
+    {
+        return ( registers_->status & 1U ) != 0U &&
+               registers_->rx_count != 0U;
+    }
+
+    [[nodiscard]] std::uint8_t read_rx_from_isr() const noexcept
+    {
+        configASSERT( rx_ready_from_isr() );
+        std::uint8_t const byte =
+            static_cast< std::uint8_t >( registers_->rx_data[ 0 ] );
+        registers_->rx_data[ 0 ] = registers_->rx_data[ 1 ];
+        --registers_->rx_count;
+        if( registers_->rx_count == 0U )
+        {
+            registers_->status = 0U;
+        }
+        return byte;
+    }
+
+private:
+    UartRegisters * registers_;
+};
+
+class Uart final
+{
+public:
+    explicit constexpr Uart( UartRegisters & registers ) noexcept
+        : registers_( &registers ) {}
+
+    [[nodiscard]] UartTaskView task_view() const noexcept
+    {
+        return UartTaskView{ *registers_ };
+    }
+
+    [[nodiscard]] UartIsrView isr_view() const noexcept
+    {
+        return UartIsrView{ *registers_ };
+    }
+
+private:
+    UartRegisters * registers_;
+};
+
+struct GpioRegisters
+{
+    volatile std::uint32_t direction;
+    volatile std::uint32_t data;
+    volatile std::uint32_t edge_status;
+};
+
+class GpioTaskView final
+{
+public:
+    explicit constexpr GpioTaskView( GpioRegisters & registers ) noexcept
+        : registers_( &registers ) {}
+
+    void configure_output( std::uint32_t mask ) const noexcept
+    {
+        registers_->direction |= mask;
+    }
+
+    void write_output( std::uint32_t mask, bool high ) const noexcept
+    {
+        if( high ) { registers_->data |= mask; }
+        else { registers_->data &= ~mask; }
+    }
+
+    void inject_edge_for_test( std::uint32_t mask ) const noexcept
+    {
+        registers_->edge_status |= mask;
+    }
+
+private:
+    GpioRegisters * registers_;
+};
+
+class GpioIsrView final
+{
+public:
+    explicit constexpr GpioIsrView( GpioRegisters & registers ) noexcept
+        : registers_( &registers ) {}
+
+    [[nodiscard]] bool edge_pending_from_isr( std::uint32_t mask ) const noexcept
+    {
+        return ( registers_->edge_status & mask ) != 0U;
+    }
+
+    void clear_edge_from_isr( std::uint32_t mask ) const noexcept
+    {
+        registers_->edge_status &= ~mask;
+    }
+
+private:
+    GpioRegisters * registers_;
+};
+
+class GpioPin final
+{
+public:
+    explicit constexpr GpioPin( GpioRegisters & registers ) noexcept
+        : registers_( &registers ) {}
+
+    [[nodiscard]] GpioTaskView task_view() const noexcept
+    {
+        return GpioTaskView{ *registers_ };
+    }
+
+    [[nodiscard]] GpioIsrView isr_view() const noexcept
+    {
+        return GpioIsrView{ *registers_ };
+    }
+
+private:
+    GpioRegisters * registers_;
+};
+
+} // namespace freertos
+
+#endif

include/freertos/kernel.hpp

@@ -0,0 +1,132 @@
+#ifndef FREERTOS_CPP_KERNEL_HPP
+#define FREERTOS_CPP_KERNEL_HPP
+
+#include <stdint.h>
+#include <type_traits>
+
+extern "C"
+{
+#include "FreeRTOS.h"
+#include "task.h"
+}
+
+#if defined( __GNUC__ )
+    #define FREERTOS_CPP_ALWAYS_INLINE inline __attribute__( ( always_inline ) )
+#else
+    #define FREERTOS_CPP_ALWAYS_INLINE inline
+#endif
+
+namespace freertos
+{
+
+enum class SchedulerState : uint8_t
+{
+    suspended,
+    not_started,
+    running
+};
+
+class Scheduler final
+{
+public:
+    Scheduler() = delete;
+
+    static FREERTOS_CPP_ALWAYS_INLINE void start() noexcept
+    {
+        vTaskStartScheduler();
+    }
+
+    static FREERTOS_CPP_ALWAYS_INLINE SchedulerState state() noexcept
+    {
+        const BaseType_t raw = xTaskGetSchedulerState();
+        if( raw == taskSCHEDULER_RUNNING )
+        {
+            return SchedulerState::running;
+        }
+        if( raw == taskSCHEDULER_NOT_STARTED )
+        {
+            return SchedulerState::not_started;
+        }
+        return SchedulerState::suspended;
+    }
+
+    static FREERTOS_CPP_ALWAYS_INLINE void suspend() noexcept
+    {
+        vTaskSuspendAll();
+    }
+
+    [[nodiscard]] static FREERTOS_CPP_ALWAYS_INLINE bool resume() noexcept
+    {
+        return xTaskResumeAll() != pdFALSE;
+    }
+};
+
+namespace this_task
+{
+
+FREERTOS_CPP_ALWAYS_INLINE TaskHandle_t current() noexcept
+{
+    return xTaskGetCurrentTaskHandle();
+}
+
+FREERTOS_CPP_ALWAYS_INLINE TickType_t tick_count() noexcept
+{
+    return xTaskGetTickCount();
+}
+
+FREERTOS_CPP_ALWAYS_INLINE void yield() noexcept
+{
+    taskYIELD();
+}
+
+} // namespace this_task
+
+class CriticalSection final
+{
+public:
+    FREERTOS_CPP_ALWAYS_INLINE CriticalSection() noexcept
+    {
+        taskENTER_CRITICAL();
+    }
+
+    FREERTOS_CPP_ALWAYS_INLINE ~CriticalSection() noexcept
+    {
+        taskEXIT_CRITICAL();
+    }
+
+    CriticalSection( const CriticalSection & ) = delete;
+    CriticalSection & operator=( const CriticalSection & ) = delete;
+    CriticalSection( CriticalSection && ) = delete;
+    CriticalSection & operator=( CriticalSection && ) = delete;
+};
+
+class SchedulerSuspendGuard final
+{
+public:
+    FREERTOS_CPP_ALWAYS_INLINE SchedulerSuspendGuard() noexcept
+    {
+        Scheduler::suspend();
+    }
+
+    FREERTOS_CPP_ALWAYS_INLINE ~SchedulerSuspendGuard() noexcept
+    {
+        ( void ) Scheduler::resume();
+    }
+
+    SchedulerSuspendGuard( const SchedulerSuspendGuard & ) = delete;
+    SchedulerSuspendGuard & operator=( const SchedulerSuspendGuard & ) = delete;
+    SchedulerSuspendGuard( SchedulerSuspendGuard && ) = delete;
+    SchedulerSuspendGuard & operator=( SchedulerSuspendGuard && ) = delete;
+};
+
+static_assert( !std::is_default_constructible< Scheduler >::value );
+static_assert( !std::is_copy_constructible< CriticalSection >::value );
+static_assert( !std::is_move_constructible< CriticalSection >::value );
+static_assert( !std::is_copy_constructible< SchedulerSuspendGuard >::value );
+static_assert( !std::is_move_constructible< SchedulerSuspendGuard >::value );
+
+} // namespace freertos
+
+#undef FREERTOS_CPP_ALWAYS_INLINE
+
+#endif

include/freertos/queue.hpp

@@ -0,0 +1,148 @@
+#ifndef FREERTOS_CPP_QUEUE_HPP
+#define FREERTOS_CPP_QUEUE_HPP
+
+#include <stddef.h>
+#include <stdint.h>
+#include <type_traits>
+
+extern "C"
+{
+#include "FreeRTOS.h"
+#include "queue.h"
+}
+
+namespace freertos
+{
+
+template< typename T >
+class Queue final
+{
+    static_assert( std::is_trivially_copyable< T >::value,
+                   "Queue<T> requires T to be trivially copyable" );
+
+public:
+    explicit Queue( UBaseType_t capacity ) noexcept
+        : handle_ { xQueueCreate( capacity, sizeof( T ) ) },
+          capacity_ { capacity }
+    {
+    }
+
+    ~Queue() noexcept
+    {
+        if( handle_ != nullptr )
+        {
+            vQueueDelete( handle_ );
+        }
+    }
+
+    Queue( const Queue & ) = delete;
+    Queue & operator=( const Queue & ) = delete;
+    Queue( Queue && ) = delete;
+    Queue & operator=( Queue && ) = delete;
+
+    [[nodiscard]] bool valid() const noexcept { return handle_ != nullptr; }
+
+    [[nodiscard]] bool send( const T & item,
+                             TickType_t timeout = 0U ) noexcept
+    {
+        return handle_ != nullptr &&
+               xQueueSend( handle_, &item, timeout ) == pdPASS;
+    }
+
+    [[nodiscard]] bool receive( T & item,
+                                TickType_t timeout = 0U ) noexcept
+    {
+        return handle_ != nullptr &&
+               xQueueReceive( handle_, &item, timeout ) == pdPASS;
+    }
+
+    [[nodiscard]] UBaseType_t size() const noexcept
+    {
+        return handle_ == nullptr ? 0U : uxQueueMessagesWaiting( handle_ );
+    }
+
+    [[nodiscard]] UBaseType_t capacity() const noexcept { return capacity_; }
+    [[nodiscard]] QueueHandle_t native_handle() const noexcept { return handle_; }
+
+private:
+    QueueHandle_t handle_ {};
+    const UBaseType_t capacity_;
+};
+
+template< typename T, size_t Capacity >
+struct StaticQueueStorage final
+{
+    static_assert( std::is_trivially_copyable< T >::value,
+                   "Queue<T> requires T to be trivially copyable" );
+    static_assert( Capacity > 0U, "StaticQueue capacity must be positive" );
+
+    StaticQueue_t control {};
+    alignas( T ) uint8_t bytes[ Capacity * sizeof( T ) ] {};
+};
+
+template< typename T, size_t Capacity >
+class StaticQueue final
+{
+    static_assert( std::is_trivially_copyable< T >::value,
+                   "Queue<T> requires T to be trivially copyable" );
+    static_assert( Capacity > 0U, "StaticQueue capacity must be positive" );
+
+public:
+    explicit StaticQueue( StaticQueueStorage< T, Capacity > & storage ) noexcept
+        : handle_ { xQueueCreateStatic(
+              static_cast< UBaseType_t >( Capacity ), sizeof( T ),
+              storage.bytes, &storage.control ) },
+          storage_ { storage }
+    {
+    }
+
+    ~StaticQueue() noexcept
+    {
+        if( handle_ != nullptr )
+        {
+            vQueueDelete( handle_ );
+        }
+    }
+
+    StaticQueue( const StaticQueue & ) = delete;
+    StaticQueue & operator=( const StaticQueue & ) = delete;
+    StaticQueue( StaticQueue && ) = delete;
+    StaticQueue & operator=( StaticQueue && ) = delete;
+
+    [[nodiscard]] bool valid() const noexcept { return handle_ != nullptr; }
+
+    [[nodiscard]] bool send( const T & item,
+                             TickType_t timeout = 0U ) noexcept
+    {
+        return handle_ != nullptr &&
+               xQueueSend( handle_, &item, timeout ) == pdPASS;
+    }
+
+    [[nodiscard]] bool receive( T & item,
+                                TickType_t timeout = 0U ) noexcept
+    {
+        return handle_ != nullptr &&
+               xQueueReceive( handle_, &item, timeout ) == pdPASS;
+    }
+
+    [[nodiscard]] UBaseType_t size() const noexcept
+    {
+        return handle_ == nullptr ? 0U : uxQueueMessagesWaiting( handle_ );
+    }
+
+    static constexpr size_t capacity() noexcept { return Capacity; }
+    static constexpr size_t item_size() noexcept { return sizeof( T ); }
+    [[nodiscard]] QueueHandle_t native_handle() const noexcept { return handle_; }
+    [[nodiscard]] const StaticQueueStorage< T, Capacity > & storage() const noexcept
+    {
+        return storage_;
+    }
+
+private:
+    QueueHandle_t handle_ {};
+    StaticQueueStorage< T, Capacity > & storage_;
+};
+
+} // namespace freertos
+
+#endif

include/freertos/software_timer.hpp

@@ -0,0 +1,117 @@
+#ifndef FREERTOS_SOFTWARE_TIMER_HPP
+#define FREERTOS_SOFTWARE_TIMER_HPP
+
+#include <type_traits>
+
+extern "C"
+{
+#include "FreeRTOS.h"
+#include "timers.h"
+}
+
+namespace freertos
+{
+
+enum class TimerPolicy
+{
+    one_shot,
+    periodic
+};
+
+enum class TimerCommand
+{
+    rejected = 0,
+    accepted = 1
+};
+
+template< typename Context, TimerPolicy Policy >
+class SoftwareTimer final
+{
+public:
+    SoftwareTimer( StaticTimer_t & storage,
+                   const char * name,
+                   TickType_t period,
+                   Context & context ) noexcept
+        : handle_( xTimerCreateStatic( name,
+                                       period,
+                                       Policy == TimerPolicy::periodic ? pdTRUE : pdFALSE,
+                                       &context,
+                                       &SoftwareTimer::trampoline,
+                                       &storage ) )
+    {
+    }
+
+    SoftwareTimer( const SoftwareTimer & ) = delete;
+    SoftwareTimer & operator=( const SoftwareTimer & ) = delete;
+    SoftwareTimer( SoftwareTimer && ) = delete;
+    SoftwareTimer & operator=( SoftwareTimer && ) = delete;
+
+    [[nodiscard]] bool valid() const noexcept
+    {
+        return handle_ != nullptr;
+    }
+
+    [[nodiscard]] TimerCommand start( TickType_t queue_wait = 0U ) noexcept
+    {
+        return command_result( xTimerStart( handle_, queue_wait ) );
+    }
+
+    [[nodiscard]] TimerCommand reset( TickType_t queue_wait = 0U ) noexcept
+    {
+        return command_result( xTimerReset( handle_, queue_wait ) );
+    }
+
+    [[nodiscard]] TimerCommand change_period( TickType_t period,
+                                               TickType_t queue_wait = 0U ) noexcept
+    {
+        return command_result( xTimerChangePeriod( handle_, period, queue_wait ) );
+    }
+
+    [[nodiscard]] TimerCommand stop( TickType_t queue_wait = 0U ) noexcept
+    {
+        return command_result( xTimerStop( handle_, queue_wait ) );
+    }
+
+    [[nodiscard]] bool active() const noexcept
+    {
+        return xTimerIsTimerActive( handle_ ) != pdFALSE;
+    }
+
+    [[nodiscard]] TickType_t period() const noexcept
+    {
+        return xTimerGetPeriod( handle_ );
+    }
+
+    [[nodiscard]] TimerHandle_t native_handle() const noexcept
+    {
+        return handle_;
+    }
+
+private:
+    static TimerCommand command_result( BaseType_t result ) noexcept
+    {
+        return result == pdPASS ? TimerCommand::accepted : TimerCommand::rejected;
+    }
+
+    static void trampoline( TimerHandle_t timer ) noexcept
+    {
+        auto * const context = static_cast< Context * >( pvTimerGetTimerID( timer ) );
+        configASSERT( context != nullptr );
+        context->on_timer( timer );
+    }
+
+    TimerHandle_t handle_;
+};
+
+template< typename Context >
+using OneShotTimer = SoftwareTimer< Context, TimerPolicy::one_shot >;
+
+template< typename Context >
+using PeriodicTimer = SoftwareTimer< Context, TimerPolicy::periodic >;
+
+static_assert( !std::is_copy_constructible_v< OneShotTimer< int > > );
+static_assert( !std::is_move_constructible_v< OneShotTimer< int > > );
+
+} // namespace freertos
+
+#endif

include/freertos/task_storage.hpp

@@ -0,0 +1,183 @@
+#ifndef FREERTOS_CPP_TASK_STORAGE_HPP
+#define FREERTOS_CPP_TASK_STORAGE_HPP
+
+#include <stddef.h>
+#include <stdint.h>
+#include <type_traits>
+
+extern "C"
+{
+#include "FreeRTOS.h"
+#include "task.h"
+}
+
+#ifndef FREERTOS_STORAGE_CHECKPOINT
+#define FREERTOS_STORAGE_CHECKPOINT( point, object ) \
+    do                                                \
+    {                                                 \
+        ( void ) ( point );                           \
+        ( void ) ( object );                          \
+    } while( 0 )
+#endif
+
+namespace freertos
+{
+
+enum class StorageTaskState : uint8_t
+{
+    constructed,
+    ready,
+    running,
+    completed,
+    start_failed
+};
+
+template< typename Derived >
+class DynamicTask
+{
+public:
+    constexpr DynamicTask( const char * name,
+                           configSTACK_DEPTH_TYPE stack_words,
+                           UBaseType_t priority ) noexcept
+        : name_ { name }, stack_words_ { stack_words }, priority_ { priority }
+    {
+    }
+
+    DynamicTask( const DynamicTask & ) = delete;
+    DynamicTask & operator=( const DynamicTask & ) = delete;
+    DynamicTask( DynamicTask && ) = delete;
+    DynamicTask & operator=( DynamicTask && ) = delete;
+
+    bool start() noexcept
+    {
+        static_assert( std::is_base_of< DynamicTask< Derived >,
+                                        Derived >::value );
+        if( state_ != StorageTaskState::constructed )
+        {
+            return false;
+        }
+        state_ = StorageTaskState::ready;
+        const BaseType_t result = xTaskCreate(
+            &DynamicTask::trampoline, name_, stack_words_,
+            static_cast< Derived * >( this ), priority_, &handle_ );
+        if( result != pdPASS )
+        {
+            handle_ = nullptr;
+            state_ = StorageTaskState::start_failed;
+            return false;
+        }
+        FREERTOS_STORAGE_CHECKPOINT( 2U, this );
+        return true;
+    }
+
+    TaskHandle_t native_handle() const noexcept { return handle_; }
+    StorageTaskState state() const noexcept { return state_; }
+
+private:
+    static void trampoline( void * context )
+    {
+        auto * const derived = static_cast< Derived * >( context );
+        auto & base = *static_cast< DynamicTask * >( derived );
+        base.state_ = StorageTaskState::running;
+        FREERTOS_STORAGE_CHECKPOINT( 5U, derived );
+        derived->run();
+        base.state_ = StorageTaskState::completed;
+        base.handle_ = nullptr;
+        FREERTOS_STORAGE_CHECKPOINT( 7U, derived );
+        vTaskDelete( nullptr );
+        for( ;; ) {}
+    }
+
+    TaskHandle_t handle_ {};
+    const char * const name_;
+    const configSTACK_DEPTH_TYPE stack_words_;
+    const UBaseType_t priority_;
+    volatile StorageTaskState state_ { StorageTaskState::constructed };
+};
+
+template< size_t StackWords >
+struct StaticTaskStorage final
+{
+    StaticTask_t tcb {};
+    StackType_t stack[ StackWords ] {};
+};
+
+template< typename Derived, size_t StackWords >
+class StaticTask
+{
+public:
+    static_assert( StackWords > 0U, "static task needs stack storage" );
+
+    constexpr StaticTask( const char * name,
+                          UBaseType_t priority,
+                          StaticTaskStorage< StackWords > & storage ) noexcept
+        : name_ { name }, priority_ { priority }, storage_ { storage }
+    {
+    }
+
+    StaticTask( const StaticTask & ) = delete;
+    StaticTask & operator=( const StaticTask & ) = delete;
+    StaticTask( StaticTask && ) = delete;
+    StaticTask & operator=( StaticTask && ) = delete;
+
+    bool start() noexcept
+    {
+        static_assert( std::is_base_of< StaticTask< Derived, StackWords >,
+                                        Derived >::value );
+        if( state_ != StorageTaskState::constructed )
+        {
+            return false;
+        }
+        state_ = StorageTaskState::ready;
+        handle_ = xTaskCreateStatic(
+            &StaticTask::trampoline,
+            name_,
+            static_cast< configSTACK_DEPTH_TYPE >( StackWords ),
+            static_cast< Derived * >( this ),
+            priority_,
+            storage_.stack,
+            &storage_.tcb );
+        if( handle_ == nullptr )
+        {
+            state_ = StorageTaskState::start_failed;
+            return false;
+        }
+        FREERTOS_STORAGE_CHECKPOINT( 4U, this );
+        return true;
+    }
+
+    TaskHandle_t native_handle() const noexcept { return handle_; }
+    StorageTaskState state() const noexcept { return state_; }
+    const StaticTask_t * tcb_storage() const noexcept { return &storage_.tcb; }
+    const StackType_t * stack_storage() const noexcept { return storage_.stack; }
+    static constexpr size_t stack_words() noexcept { return StackWords; }
+    static constexpr size_t stack_bytes() noexcept
+    {
+        return StackWords * sizeof( StackType_t );
+    }
+
+private:
+    static void trampoline( void * context )
+    {
+        auto * const derived = static_cast< Derived * >( context );
+        auto & base = *static_cast< StaticTask * >( derived );
+        base.state_ = StorageTaskState::running;
+        FREERTOS_STORAGE_CHECKPOINT( 6U, derived );
+        derived->run();
+        base.state_ = StorageTaskState::completed;
+        base.handle_ = nullptr;
+        FREERTOS_STORAGE_CHECKPOINT( 8U, derived );
+        vTaskDelete( nullptr );
+        for( ;; ) {}
+    }
+
+    TaskHandle_t handle_ {};
+    const char * const name_;
+    const UBaseType_t priority_;
+    StaticTaskStorage< StackWords > & storage_;
+    volatile StorageTaskState state_ { StorageTaskState::constructed };
+};
+
+} // namespace freertos
+
+#endif

include/freertos_risc_v_chip_specific_extensions.h

@@ -0,0 +1,15 @@
+#ifndef FREERTOS_RISC_V_CHIP_SPECIFIC_EXTENSIONS_H
+#define FREERTOS_RISC_V_CHIP_SPECIFIC_EXTENSIONS_H
+
+/* Hazard3 adds no architectural registers to the base RV32I context. */
+#define portasmHAS_MTIME                  1
+#define portasmHAS_SIFIVE_CLINT           0
+#define portasmADDITIONAL_CONTEXT_SIZE    0
+
+.macro portasmSAVE_ADDITIONAL_REGISTERS
+.endm
+
+.macro portasmRESTORE_ADDITIONAL_REGISTERS
+.endm
+
+#endif

include/hazard3_csr.h

@@ -0,0 +1,66 @@
+#ifndef _HAZARD3_CSR_H
+#define _HAZARD3_CSR_H
+
+#ifndef __ASSEMBLER__
+#include "stdint.h"
+#endif
+
+#define hazard3_csr_dmdata0    0xbff // Debug-mode shadow CSR for DM data transfer
+
+#define hazard3_csr_meiea      0xbe0 // External interrupt pending array
+#define hazard3_csr_meipa      0xbe1 // External interrupt enable array
+#define hazard3_csr_meifa      0xbe2 // External interrupt force array
+#define hazard3_csr_meipra     0xbe3 // External interrupt priority array
+#define hazard3_csr_meinext    0xbe4 // Next external interrupt
+#define hazard3_csr_meicontext 0xbe5 // External interrupt context register
+
+#define hazard3_csr_msleep     0xbf0 // M-mode sleep control register
+
+#define hazard3_csr_pmpcfgm0   0xbd0 // Non-locking M-mode enables for PMP regions
+
+#define _read_csr(csrname) ({ \
+  uint32_t __csr_tmp_u32; \
+  __asm__ volatile ("csrr %0, " #csrname : "=r" (__csr_tmp_u32)); \
+  __csr_tmp_u32; \
+})
+
+#define _write_csr(csrname, data) ({ \
+	__asm__ volatile ("csrw " #csrname ", %0" : : "r" (data)); \
+})
+
+#define _set_csr(csrname, data) ({ \
+  __asm__ volatile ("csrs " #csrname ", %0" : : "r" (data)); \
+})
+
+#define _clear_csr(csrname, data) ({ \
+  __asm__ volatile ("csrc " #csrname ", %0" : : "r" (data)); \
+})
+
+#define _read_write_csr(csrname, data) ({ \
+  uint32_t __csr_tmp_u32; \
+  __asm__ volatile ("csrrw %0, " #csrname ", %1" : "=r" (__csr_tmp_u32) : "r" (data)); \
+  __csr_tmp_u32; \
+})
+
+#define _read_set_csr(csrname, data) ({ \
+  uint32_t __csr_tmp_u32; \
+  __asm__ volatile ("csrrs %0, " #csrname ", %1" : "=r" (__csr_tmp_u32) : "r" (data)); \
+  __csr_tmp_u32; \
+})
+
+#define _read_clear_csr(csrname, data) ({ \
+  uint32_t __csr_tmp_u32; \
+  __asm__ volatile ("csrrc %0, " #csrname ", %1" : "=r" (__csr_tmp_u32) : "r" (data)); \
+  __csr_tmp_u32; \
+})
+
+// Argument macro expansion layer
+#define read_csr(csrname)             _read_csr(csrname)
+#define write_csr(csrname, data)      _write_csr(csrname, data)
+#define set_csr(csrname, data)        _set_csr(csrname, data)
+#define clear_csr(csrname, data)      _clear_csr(csrname, data)
+#define read_write_csr(csrname, data) _read_write_csr(csrname, data)
+#define read_set_csr(csrname, data)   _read_set_csr(csrname, data)
+#define read_clear_csr(csrname, data) _read_clear_csr(csrname, data)
+
+#endif

include/hazard3_irq.h

@@ -0,0 +1,100 @@
+#ifndef _HAZARD3_IRQ_H
+#define _HAZARD3_IRQ_H
+
+#include "hazard3_csr.h"
+#include "stdint.h"
+#include "stdbool.h"
+
+// Should match processor configuration in testbench:
+#define NUM_IRQS 32
+#define MAX_PRIORITY 15
+
+// Declarations for irq_dispatch.S
+extern uintptr_t _external_irq_table[NUM_IRQS];
+extern uint32_t _external_irq_entry_count;
+
+#define h3irq_array_read(csr, index) (read_set_csr(csr, (index)) >> 16)
+
+#define h3irq_array_write(csr, index, data) (write_csr(csr, (index) | ((uint32_t)(data) << 16)))
+#define h3irq_array_set(csr, index, data) (set_csr(csr, (index) | ((uint32_t)(data) << 16)))
+#define h3irq_array_clear(csr, index, data) (clear_csr(csr, (index) | ((uint32_t)(data) << 16)))
+
+static inline void h3irq_enable(unsigned int irq, bool enable) {
+	if (enable) {
+		h3irq_array_set(hazard3_csr_meiea, irq >> 4, 1u << (irq & 0xfu));
+	}
+	else {
+		h3irq_array_clear(hazard3_csr_meiea, irq >> 4, 1u << (irq & 0xfu));
+	}
+}
+
+static inline bool h3irq_pending(unsigned int irq) {
+	return h3irq_array_read(hazard3_csr_meipa, irq >> 4) & (1u << (irq & 0xfu));
+}
+
+static inline void h3irq_force_pending(unsigned int irq, bool force) {
+	if (force) {
+		h3irq_array_set(hazard3_csr_meifa, irq >> 4, 1u << (irq & 0xfu));
+	}
+	else {
+		h3irq_array_clear(hazard3_csr_meifa, irq >> 4, 1u << (irq & 0xfu));
+	}
+}
+
+static inline bool h3irq_is_forced(unsigned int irq) {
+	return h3irq_array_read(hazard3_csr_meifa, irq >> 4) & (1u << (irq & 0xfu));
+}
+
+// -1 for no IRQ
+static inline int h3irq_get_current_irq() {
+	uint32_t meicontext = read_csr(hazard3_csr_meicontext);
+	return ( meicontext & 0x8000u ) != 0U
+		? -1
+		: ( int ) ( ( meicontext >> 4 ) & 0x1ffu );
+}
+
+static inline void h3irq_set_priority(unsigned int irq, uint32_t priority) {
+	// Don't want read-modify-write, but no instruction for atomically writing
+	// a bitfield. So, first drop priority to minimum, then set to the target
+	// value. It should be safe to drop an IRQ's priority below its current
+	// even from within that IRQ (but it is never safe to boost an IRQ when
+	// it may already be in an older stack frame)
+	h3irq_array_clear(hazard3_csr_meipra, irq >> 2, 0xfu << (4 * (irq & 0x3)));
+	h3irq_array_set(hazard3_csr_meipra, irq >> 2, (priority & 0xfu) << (4 * (irq & 0x3)));
+}
+
+static inline void h3irq_set_handler(unsigned int irq, void (*handler)(void)) {
+	_external_irq_table[irq] = (uintptr_t)handler;
+}
+
+static inline void global_irq_enable(bool en) {
+	// mstatus.mie
+	if (en) {
+		set_csr(mstatus, 0x8);
+	}
+	else {
+		clear_csr(mstatus, 0x8);
+	}
+}
+
+static inline void external_irq_enable(bool en) {
+	// mie.meie
+	if (en) {
+		set_csr(mie, 0x800);
+	}
+	else {
+		clear_csr(mie, 0x800);
+	}
+}
+
+static inline void timer_irq_enable(bool en) {
+	// mie.mtie
+	if (en) {
+		set_csr(mie, 0x080);
+	}
+	else {
+		clear_csr(mie, 0x080);
+	}
+}
+
+#endif

include/integration_model.hpp

@@ -0,0 +1,80 @@
+#ifndef FREERTOS_INTEGRATION_MODEL_HPP
+#define FREERTOS_INTEGRATION_MODEL_HPP
+
+#include <cstddef>
+#include <cstdint>
+#include <type_traits>
+
+namespace integration
+{
+
+enum class MessageKind : std::uint32_t
+{
+    sample = 1U,
+    end = 2U
+};
+
+struct Sample
+{
+    std::uint32_t sequence;
+    std::uint32_t value;
+    MessageKind kind;
+};
+
+struct Report
+{
+    std::uint32_t sequence;
+    std::uint32_t transformed;
+    MessageKind kind;
+};
+
+enum class TraceStage : std::uint32_t
+{
+    inventory = 1U,
+    barrier = 2U,
+    isr_kick = 3U,
+    producer_kick = 4U,
+    reporter_resume = 5U,
+    timer_callback = 6U,
+    input_queued = 7U,
+    input_dropped = 8U,
+    report_created = 9U,
+    report_received = 10U,
+    end_marker = 11U,
+    final_report = 12U
+};
+
+struct TraceEvent
+{
+    std::uint32_t sequence;
+    std::uint32_t tick;
+    TraceStage stage;
+    std::uint32_t value;
+};
+
+[[nodiscard]] constexpr Report transform( Sample sample ) noexcept
+{
+    return { sample.sequence, sample.value * 2U, sample.kind };
+}
+
+[[nodiscard]] inline std::uint32_t trace_digest( const TraceEvent * events,
+                                                 std::size_t count ) noexcept
+{
+    std::uint32_t hash = 2166136261U;
+    for( std::size_t index = 0U; index < count; ++index )
+    {
+        hash = ( hash ^ events[ index ].sequence ) * 16777619U;
+        hash = ( hash ^ events[ index ].tick ) * 16777619U;
+        hash = ( hash ^ static_cast< std::uint32_t >( events[ index ].stage ) ) *
+               16777619U;
+        hash = ( hash ^ events[ index ].value ) * 16777619U;
+    }
+    return hash;
+}
+
+static_assert( std::is_trivially_copyable_v< Sample > );
+static_assert( std::is_trivially_copyable_v< Report > );
+
+} // namespace integration
+
+#endif

include/stdlib.h

@@ -0,0 +1,11 @@
+#ifndef LAB_FREESTANDING_STDLIB_H
+#define LAB_FREESTANDING_STDLIB_H
+
+/*
+ * The selected FreeRTOS sources include <stdlib.h> for standard types, but the
+ * configuration used by this card does not call hosted stdlib functions.
+ * GCC's freestanding headers provide size_t through <stddef.h>.
+ */
+#include <stddef.h>
+
+#endif

include/string.h

@@ -0,0 +1,17 @@
+#ifndef LAB_FREESTANDING_STRING_H
+#define LAB_FREESTANDING_STRING_H
+
+#include <stddef.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+void * memcpy( void * destination, const void * source, size_t count );
+void * memset( void * destination, int value, size_t count );
+size_t strlen( const char * text );
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif