/*
 * 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;

/*
 * Logical privilege level for a task.
 *
 * Higher numeric values are more privileged:
 *   USER   (0) – least privileged
 *   DRIVER (1) – mid-level, can talk to hardware-facing subsystems
 *   KERNEL (2) – most privileged, core kernel and management threads
 *
 * All tasks still execute in ring 0 today; this is a software
 * hierarchy used for access control decisions and future paging work.
 */
typedef enum {
    TASK_PRIV_USER   = 0,
    TASK_PRIV_DRIVER = 1,
    TASK_PRIV_KERNEL = 2,
} TaskPrivilege;

/* ================================================================
 *  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        */
    TaskPrivilege privilege;            /* logical privilege level        */
    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           */

/* Spawn a new task with a specific privilege level. */
Task  *task_create_with_priv(const CHAR16 *name,
                             TaskEntryFn entry,
                             void *arg,
                             TaskPrivilege privilege);

/* Backwards-compatible helper: creates a kernel-privileged task. */
Task  *task_create(const CHAR16 *name,
                   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  */
TaskPrivilege task_get_privilege(Task *t);
void          task_set_privilege(Task *t, TaskPrivilege privilege);
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 */