/*
 * Revera — a real-time kernel with hardware-enforced isolation.
 * Copyright (c) 2026 VIACERTO LLC. All rights reserved.
 *
 * This file is dual-licensed under the PolyForm Noncommercial License 1.0.0 OR
 * a commercial license from VIACERTO LLC. You may choose to use this file under
 * the terms of either license.
 *
 * For the full license terms, see the LICENSE and LICENSE-COMMERCIAL.md files in
 * the root directory of this source tree.
 *
 * SPDX-FileCopyrightText: © 2026 VIACERTO LLC
 * SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0 OR LicenseRef-VIACERTO-Commercial
 */

/*
 * tk_kernel_sync.h — Tier C: the IPC-EXTENSION contract.
 *
 * The block/wake/wait-queue primitives a synchronization object is BUILT from. Included
 * by the kernel's own mutex/sem/cond (tk_sync.c) AND by an application or library adding
 * a NEW primitive (message queue, barrier, event flags). NOT the
 * application API: an app USING a mutex includes tk_mutex.h (Tier A); only one BUILDING a
 * primitive includes this.
 *
 * Discipline: tk_kernel_wait()/tk_kernel_wake_one() MUST be called holding the kernel lock
 * (tk_sched_enter, Tier D) so the object's own check-then-block stays atomic.
 */
#ifndef TK_KERNEL_SYNC_H
#define TK_KERNEL_SYNC_H

#include <stdint.h>

/* Opaque handle to the running thread (the full type is Tier A / Tier D). */
struct tk_tcb;

/* A FIFO queue of threads blocked on a sync object. Owned by the caller's object; holds
 * only thread handles so it stays usable without exposing the TCB layout. The kernel can
 * pull a thread off it when its wait times out. */
struct tk_wait_queue {
    struct tk_tcb* head;
    struct tk_tcb* tail;
};

void tk_wait_queue_init(struct tk_wait_queue* q);

/* Enqueue the caller, block, release the kernel lock, and yield. Returns 0 if woken by
 * tk_kernel_wake_one(), or 1 if timeout_ms elapsed first (0 = wait forever). Kernel lock held. */
int tk_kernel_wait(struct tk_wait_queue* q, uint32_t timeout_ms);

/* Wake the head waiter; returns it (or NULL if empty). Kernel lock held. */
struct tk_tcb* tk_kernel_wake_one(struct tk_wait_queue* q);

/* The currently running thread on this core, or NULL outside thread context. Used to
 * record the blocker / owner. */
struct tk_tcb* tk_kernel_current_thread(void);

#endif /* TK_KERNEL_SYNC_H */