Add missing new C++ API to C interface.

Fix MemoryAllocator::Stats::allocate_count/free_count are not updated.

Author: dmitrykos

interop/c/include/stk_c.h

@@ -352,6 +352,27 @@ void stk_kernel_suspend_task(stk_kernel_t *k, stk_task_t *task, bool *suspended)
 */
 void stk_kernel_resume_task(stk_kernel_t *k, stk_task_t *task);
 
+/*! \brief     Suspend scheduling (tickless idle entry point).
+    \param[in] k: Kernel handle.
+    \return    Number of ticks available for the suspension period, determined by the
+               nearest pending wake-up deadline across all sleeping tasks. The caller
+               may program a hardware timer with this value to suppress SysTick wakeups.
+    \note      ISR-safe. Pair every call with stk_kernel_resume().
+    \note      Only meaningful when the kernel was created with KERNEL_TICKLESS mode.
+    \see       stk_kernel_resume, STK_KERNEL_STATE_SUSPENDED
+*/
+int32_t stk_kernel_suspend(stk_kernel_t *k);
+
+/*! \brief     Resume scheduling after a prior stk_kernel_suspend() call.
+    \param[in] k: Kernel handle.
+    \param[in] elapsed_ticks: Number of ticks that elapsed during the suspended period.
+               The kernel uses this value to advance internal time counters and wake tasks
+               whose sleep deadlines have expired.
+    \note      ISR-safe.
+    \see       stk_kernel_suspend
+*/
+void stk_kernel_resume(stk_kernel_t *k, int32_t elapsed_ticks);
+
 /*! \brief     Enumerate all currently active tasks.
     \param[in]  k: Kernel handle.
     \param[out] tasks: Caller-allocated array of opaque task pointers.  Each element is a
@@ -362,6 +383,25 @@ void stk_kernel_resume_task(stk_kernel_t *k, stk_task_t *task);
 */
 size_t stk_kernel_enumerate_tasks(stk_kernel_t *k, stk_task_t **tasks, size_t max_count);
 
+/*! \brief     Manually deliver one scheduler tick to the kernel.
+    \param[in] k: Kernel handle.
+    \note      Use this when the platform driver's built-in SysTick handler is disabled
+               (STK_SYSTICK_HANDLER = _STK_SYSTICK_HANDLER_DISABLE in stk_config.h) and
+               the application provides its own tick source. Call from your custom tick ISR
+               at the rate matching the tick period configured in stk_kernel_init().
+    \note      ISR-safe.
+*/
+void stk_kernel_process_tick(stk_kernel_t *k);
+
+/*! \brief     Trigger a kernel hard fault (safe-state handler).
+    \param[in] k: Kernel handle.
+    \note      Normally invoked automatically by the kernel when an HRT task misses its
+               deadline. Exposed here for custom fault handlers or test harnesses that need
+               to force a controlled system halt via the platform driver's fault path.
+    \note      This call does not return.
+*/
+void stk_kernel_process_hard_fault(stk_kernel_t *k);
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Task creation
 // ─────────────────────────────────────────────────────────────────────────────
@@ -411,6 +451,22 @@ void stk_task_set_priority(stk_task_t *task, uint8_t priority);
 */
 void stk_task_set_name(stk_task_t *task, const char *tname);
 
+/*! \brief     Get human-readable task name previously set with stk_task_set_name().
+    \param[in] task: Task handle.
+    \return    Null-terminated name string, or NULL if not set.
+    \note      ISR-safe (reads a stored pointer, no kernel call).
+*/
+const char *stk_task_get_name(const stk_task_t *task);
+
+/*! \brief     Get the unique identifier of a task.
+    \param[in] task: Task handle.
+    \return    Task identifier (stk_tid_t). Equivalent to the value stk_tid() returns
+               when called from within that task.
+    \note      ISR-safe.
+    \see       stk_tid
+*/
+stk_tid_t stk_task_get_id(const stk_task_t *task);
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Services available from inside tasks
 // ─────────────────────────────────────────────────────────────────────────────
@@ -563,6 +619,15 @@ void stk_sleep_until(int64_t ts);
 */
 void stk_yield(void);
 
+/*! \brief     Cancel the sleep of a task, waking it immediately.
+    \param[in] tid: Identifier of the task to wake (obtained from stk_tid() or
+               stk_task_get_id()).
+    \note      No-op if the target task is not currently sleeping.
+    \note      ISR-safe.
+    \see       stk_sleep, stk_sleep_ms, stk_sleep_until
+*/
+void stk_sleep_cancel(stk_tid_t tid);
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Dynamic cleanup
 // ─────────────────────────────────────────────────────────────────────────────

interop/c/include/stk_c_memory.h

@@ -104,8 +104,11 @@ extern "C" {
 
 /*! \def     STK_BLOCKPOOL_STORAGE_DECL(name, capacity, raw_block_size)
     \brief   Declare a correctly sized and aligned external storage array.
-    \details Expands to a \c static \c stk_word_t_t array with the required size and
+    \details Expands to a \c static \c stk_word_t array with the required size and
              pointer-sized alignment. Intended for file-scope or function-scope use.
+             \c STK_BLOCKPOOL_ALIGN_BLOCK_SIZE() guarantees the total byte count is
+             always an exact multiple of \c sizeof(stk_word_t), so the integer
+             division in the array dimension is lossless by construction.
     \param   name: C identifier for the array variable.
     \param   capacity: Number of blocks the pool will hold.
     \param   raw_block_size: Raw per-block size in bytes.
@@ -142,6 +145,9 @@ typedef struct stk_blockpool_t stk_blockpool_t;
                Forwarded to \c ITraceable::SetTraceName().
     \return    Pool handle, or \c NULL if the static slot pool is exhausted
                (\c STK_C_BLOCKPOOL_MAX reached).
+               A non-NULL handle does \b not guarantee the backing storage was
+               successfully heap-allocated; always call \c stk_blockpool_is_storage_valid()
+               immediately after creation when operating without exceptions.
     \note      Not ISR-safe.
     \see       stk_blockpool_is_storage_valid(), stk_blockpool_destroy()
 */
@@ -180,6 +186,9 @@ stk_blockpool_t *stk_blockpool_create_static(size_t      capacity,
     \warning   Destroying a pool while tasks are blocked in \c stk_blockpool_alloc()
                or \c stk_blockpool_timed_alloc() is a logic error and triggers an
                assertion in debug builds.
+    \warning   Set the pool pointer to \c NULL after this call to prevent accidental
+               use-after-destroy (the handle slot may be reused by a subsequent
+               \c stk_blockpool_create() call).
     \note      Not ISR-safe.
 */
 void stk_blockpool_destroy(stk_blockpool_t *pool);
@@ -272,7 +281,10 @@ size_t stk_blockpool_get_block_size(const stk_blockpool_t *pool);
     \param[in] pool: Pool handle.
     \return    Point-in-time snapshot. May be stale immediately after return in a
                multi-task environment.
-    \note      ISR-safe on targets where a 16-bit aligned read is atomic.
+    \note      ISR-safety depends on target ABI: the counter is a 16-bit value, so a
+               single-instruction atomic read is guaranteed on 32-bit Cortex-M (aligned
+               halfword load) but not on 8-bit targets where two bus cycles may be needed.
+               Treat the result as advisory in all multi-core or 8-bit contexts.
 */
 size_t stk_blockpool_get_used_count(const stk_blockpool_t *pool);
 

interop/c/include/stk_c_time.h

@@ -39,6 +39,9 @@ extern "C" {
 
 /*! \def   STK_C_TIMER_MAX
     \brief Maximum number of concurrent \a stk_timer_t instances per core (default: 32).
+           The total pool size is \a STK_C_TIMER_MAX × \a STK_C_CPU_COUNT slots, shared
+           across all cores.  When the pool is exhausted \a stk_timer_create() asserts
+           in debug builds and returns NULL in release builds.
     \note  Increase if your application needs more simultaneous timers.
 */
 #ifndef STK_C_TIMER_MAX
@@ -130,9 +133,12 @@ int64_t stk_timerhost_get_time_now(const stk_timerhost_t *host);
 /*! \brief     Allocate a timer from the static pool.
     \param[in] callback: Function to call when the timer expires (must not be NULL).
     \param[in] user_data: Opaque pointer forwarded to \a callback on expiration.
-    \return    Timer handle, or NULL if the pool is exhausted (\a STK_C_TIMER_MAX reached).
+    \return    Timer handle, or NULL if the pool is exhausted
+               (\a STK_C_TIMER_MAX × \a STK_C_CPU_COUNT slots total).
     \note      The returned handle is valid until \a stk_timer_destroy() is called.
                It must not be active (i.e. not currently started) when destroyed.
+    \note      The pool is shared across all CPU cores. Total capacity is
+               \a STK_C_TIMER_MAX * \a STK_C_CPU_COUNT.
 */
 stk_timer_t *stk_timer_create(stk_timer_callback_t callback, void *user_data);
 
@@ -301,11 +307,11 @@ typedef struct stk_periodic_trigger_t stk_periodic_trigger_t;
     \param[in] memory: Pointer to the caller-supplied memory container.
     \param[in] memory_size: Size of the container in bytes (must be >= sizeof(stk_periodic_trigger_mem_t)).
     \param[in] period: Trigger period in ticks. Must be > 0.
-    \param[in] started: \a true to create instance in a started state, \a false otherwise.
+    \param[in] started: \c true to create the instance in a started state (first firing occurs
+               no earlier than \a period ticks after construction); \c false to create it in a
+               stopped state (call \a stk_periodic_trigger_restart() before polling).
     \return    Trigger handle on success, or \c NULL if \a memory is \c NULL
                or \a memory_size is too small.
-    \note      The trigger is created in a stopped state.
-               Call \a stk_periodic_trigger_restart() before polling.
 */
 stk_periodic_trigger_t *stk_periodic_trigger_create(stk_periodic_trigger_mem_t *memory,
                                                     uint32_t                   memory_size,

interop/c/src/stk_c.cpp

@@ -220,7 +220,7 @@ bool stk_kernel_is_schedulable(const stk_kernel_t *k)
     STK_ASSERT(k != nullptr);
 
     return SchedulabilityCheck::IsSchedulableWCRT<STK_C_KERNEL_MAX_TASKS>(
-            reinterpret_cast<stk::IKernel *>(const_cast<stk_kernel_t *>(k))->GetSwitchStrategy());
+        reinterpret_cast<stk::IKernel *>(const_cast<stk_kernel_t *>(k))->GetSwitchStrategy());
 }
 
 void stk_kernel_add_task(stk_kernel_t *k, stk_task_t *task)
@@ -293,6 +293,37 @@ size_t stk_kernel_enumerate_tasks(stk_kernel_t *k, stk_task_t **tasks, size_t ma
     return n;
 }
 
+int32_t stk_kernel_suspend(stk_kernel_t *k)
+{
+    STK_ASSERT(k != nullptr);
+
+    return static_cast<int32_t>(
+        reinterpret_cast<stk::IKernel *>(k)->GetPlatform()->Suspend());
+}
+
+void stk_kernel_resume(stk_kernel_t *k, int32_t elapsed_ticks)
+{
+    STK_ASSERT(k != nullptr);
+    STK_ASSERT(elapsed_ticks >= 0);
+
+    reinterpret_cast<stk::IKernel *>(k)->GetPlatform()->Resume(
+        static_cast<stk::Timeout>(elapsed_ticks));
+}
+
+void stk_kernel_process_tick(stk_kernel_t *k)
+{
+    STK_ASSERT(k != nullptr);
+
+    reinterpret_cast<stk::IKernel *>(k)->GetPlatform()->ProcessTick();
+}
+
+void stk_kernel_process_hard_fault(stk_kernel_t *k)
+{
+    STK_ASSERT(k != nullptr);
+
+    reinterpret_cast<stk::IKernel *>(k)->GetPlatform()->ProcessHardFault();
+}
+
 void stk_kernel_add_task_hrt(stk_kernel_t *k,
                              stk_task_t *task,
                              int32_t periodicity_ticks,
@@ -358,6 +389,20 @@ void stk_task_set_name(stk_task_t *task, const char *tname)
     task->handle.SetName(tname);
 }
 
+const char *stk_task_get_name(const stk_task_t *task)
+{
+    STK_ASSERT(task != nullptr);
+
+    return task->handle.GetTraceName();
+}
+
+stk_tid_t stk_task_get_id(const stk_task_t *task)
+{
+    STK_ASSERT(task != nullptr);
+
+    return task->handle.GetId();
+}
+
 void stk_task_destroy(stk_task_t *task)
 {
     STK_ASSERT(task != nullptr);
@@ -368,22 +413,23 @@ void stk_task_destroy(stk_task_t *task)
 // ---------------------------------------------------------------------------
 // Kernel services (available inside tasks)
 // ---------------------------------------------------------------------------
-stk_tid_t stk_tid(void)               { return stk::GetTid(); }
-int64_t   stk_ticks(void)             { return stk::GetTicks(); }
-int32_t   stk_tick_resolution(void)   { return stk::GetTickResolution(); }
-int64_t   stk_time_now_ms(void)       { return stk::GetTimeNowMs(); }
+stk_tid_t stk_tid(void)                   { return stk::GetTid(); }
+int64_t   stk_ticks(void)                 { return stk::GetTicks(); }
+int32_t   stk_tick_resolution(void)       { return stk::GetTickResolution(); }
+int64_t   stk_time_now_ms(void)           { return stk::GetTimeNowMs(); }
 int64_t   stk_ticks_from_ms(int64_t msec) { return stk_ticks_from_ms_r(msec, stk::GetTickResolution()); }
-uint64_t  stk_sys_timer_count(void)   { return stk::GetSysTimerCount(); }
-uint32_t  stk_sys_timer_frequency(void) { return stk::GetSysTimerFrequency(); }
-uint64_t  stk_hires_cycles(void)      { return stk::hw::HiResClock::GetCycles(); }
-uint32_t  stk_hires_frequency(void)   { return stk::hw::HiResClock::GetFrequency(); }
-int64_t   stk_hires_time_us(void)     { return stk::hw::HiResClock::GetTimeUs(); }
-void      stk_delay(uint32_t ticks)   { stk::Delay(ticks); }
-void      stk_sleep(uint32_t ticks)   { stk::Sleep(ticks); }
-void      stk_delay_ms(uint32_t ms)   { stk::DelayMs(ms); }
-void      stk_sleep_ms(uint32_t ms)   { stk::SleepMs(ms); }
-void      stk_sleep_until(int64_t ts) { stk::SleepUntil(ts); }
-void      stk_yield(void)             { stk::Yield(); }
+uint64_t  stk_sys_timer_count(void)       { return stk::GetSysTimerCount(); }
+uint32_t  stk_sys_timer_frequency(void)   { return stk::GetSysTimerFrequency(); }
+uint64_t  stk_hires_cycles(void)          { return stk::hw::HiResClock::GetCycles(); }
+uint32_t  stk_hires_frequency(void)       { return stk::hw::HiResClock::GetFrequency(); }
+int64_t   stk_hires_time_us(void)         { return stk::hw::HiResClock::GetTimeUs(); }
+void      stk_delay(uint32_t ticks)       { stk::Delay(ticks); }
+void      stk_sleep(uint32_t ticks)       { stk::Sleep(ticks); }
+void      stk_delay_ms(uint32_t ms)       { stk::DelayMs(ms); }
+void      stk_sleep_ms(uint32_t ms)       { stk::SleepMs(ms); }
+void      stk_sleep_until(int64_t ts)     { stk::SleepUntil(ts); }
+void      stk_sleep_cancel(stk_tid_t tid) { stk::SleepCancel(tid); }
+void      stk_yield(void)                 { stk::Yield(); }
 
 // ---------------------------------------------------------------------------
 // Thread-Local Storage (TLS) API

interop/c/src/stk_c_memory.cpp

@@ -19,6 +19,18 @@
 using namespace stk;
 using namespace stk::memory;
 
+// Guard against divergence between the C macro STK_BLOCKPOOL_ALIGN_BLOCK_SIZE and
+// the C++ BlockMemoryPool::AlignBlockSize() function.  Both must produce identical
+// results; if this assertion fires, update one of the two definitions.
+static_assert(
+    STK_BLOCKPOOL_ALIGN_BLOCK_SIZE(1)  == BlockMemoryPool::AlignBlockSize(1)  &&
+    STK_BLOCKPOOL_ALIGN_BLOCK_SIZE(3)  == BlockMemoryPool::AlignBlockSize(3)  &&
+    STK_BLOCKPOOL_ALIGN_BLOCK_SIZE(4)  == BlockMemoryPool::AlignBlockSize(4)  &&
+    STK_BLOCKPOOL_ALIGN_BLOCK_SIZE(7)  == BlockMemoryPool::AlignBlockSize(7)  &&
+    STK_BLOCKPOOL_ALIGN_BLOCK_SIZE(16) == BlockMemoryPool::AlignBlockSize(16),
+    "STK_BLOCKPOOL_ALIGN_BLOCK_SIZE and BlockMemoryPool::AlignBlockSize() have diverged. "
+    "Keep both definitions in sync.");
+
 // Returns a size of memory in stk::Word elements required for object allocation.
 template <typename T> static constexpr size_t StkGetWordCountForType()
 {
@@ -179,6 +191,9 @@ void stk_blockpool_destroy(stk_blockpool_t *pool)
 void *stk_blockpool_alloc(stk_blockpool_t *pool)
 {
     STK_ASSERT(pool != nullptr);
+    // stk_blockpool_alloc() blocks indefinitely and must never be called from an ISR.
+    // Use stk_blockpool_try_alloc() or stk_blockpool_timed_alloc(..., STK_NO_WAIT) instead.
+    STK_ASSERT(!hw::IsInsideISR());
 
     return pool->handle.Alloc();
 }

stk/include/memory/stk_memory_allocator.h

@@ -90,6 +90,7 @@ struct MemoryAllocator
         void RecordAllocate(size_t size)
         {
             allocated += size;
+            ++allocate_count;
             min_ever_free = Min(GetAvailable(), min_ever_free);
         }
 
@@ -101,6 +102,7 @@ struct MemoryAllocator
             STK_ASSERT(allocated >= size);
 
             allocated -= size;
+            ++free_count;
         }
     };