/*
 * task.h – Cooperative multitasking interface.
 *
 * Provides process control blocks (PCBs), a round-robin scheduler,
 * and voluntary yield/exit primitives.  Context switching is performed
 * by the assembly routine in context_switch.S.
 */

#ifndef TASK_H
#define TASK_H

#include "kernel_types.h"
#include "boot_info.h"

/* ================================================================
 *  Configuration
 * ================================================================ */

#define TASK_MAX         32             /* max concurrent tasks       */
#define TASK_STACK_PAGES 8              /* 32 KB stack per task       */
#define TASK_STACK_SIZE  (TASK_STACK_PAGES * 4096)
#define TASK_NAME_LEN    32             /* max name length (CHAR16)   */

/* ================================================================
 *  Task states
 * ================================================================ */

typedef enum {
    TASK_STATE_FREE = 0,       /* PCB slot is unused                  */
    TASK_STATE_READY,          /* runnable, waiting to be scheduled    */
    TASK_STATE_RUNNING,        /* currently executing on the CPU       */
    TASK_STATE_TERMINATED      /* finished; slot will be recycled      */
} TaskState;

/* ================================================================
 *  Task entry function
 * ================================================================ */

/* Signature for the function a new task begins executing. */
typedef void (*TaskEntryFn)(void *arg);

/* ================================================================
 *  Process Control Block (PCB)
 * ================================================================ */

typedef struct Task {
    UINT32      pid;                    /* unique process ID              */
    TaskState   state;                  /* current lifecycle state        */
    CHAR16      name[TASK_NAME_LEN];    /* human-readable label           */

    /* Context switch state */
    UINT64      saved_rsp;              /* RSP saved by context_switch()  */
    UINT64      stack_base;             /* base phys addr of stack alloc  */
    UINTN       stack_pages;            /* stack size in pages            */

    /* Entry point */
    TaskEntryFn entry;                  /* function pointer               */
    void       *arg;                    /* argument passed to entry()     */

    /* Scheduling metadata */
    UINTN       switches;              /* number of times scheduled       */
} Task;

/* ================================================================
 *  Public API
 * ================================================================ */

void   task_init(BootInfo *Boot);       /* initialise scheduler           */
Task  *task_create(const CHAR16 *name,  /* spawn a new task               */
                   TaskEntryFn entry, void *arg);
void   task_yield(void);               /* voluntarily give up the CPU    */
void   task_exit(void);                /* terminate the current task     */
Task  *task_current(void);             /* return the running task's PCB  */
UINTN  task_count(void);              /* number of non-FREE tasks        */
void   task_print_list(BootInfo *Boot); /* print task table (for `ps`)   */

/* Block the current task until the target task has finished. */
void   task_wait(Task *t);

/* Assembly context switch (defined in context_switch.S). */
extern void context_switch(UINT64 *old_rsp, UINT64 new_rsp);

#endif /* TASK_H */