sched.h

Go to the documentation of this file.

// MIT License
//
// Copyright (c) 2026 Christian Spoo
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all
// copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
// SOFTWARE.
 
#ifndef _MINIOS_SCHED_SCHED_H_
#define _MINIOS_SCHED_SCHED_H_
 
#include <miniOS/types.h>
 
#include <miniOS/arch/x86_64/context.h>
#include <miniOS/arch/x86_64/spinlock.h>
#include <miniOS/fs/vfs.h>
#include <miniOS/signal.h>
 
#define THREAD_STACK_SIZE   16384   /* 16 KB kernel stack per thread */
 
/* SCHED_MAX_THREADS: thread pool size. Must accommodate MAX_CPUS idle threads
   plus user threads. Set to MAX_CPUS + 16 for headroom.
   MAX_CPUS is defined by the build system (arch/kernel CMakeLists.txt),
   defaulting to 8 if not provided at compile time. */
#ifndef MAX_CPUS
#define MAX_CPUS 8
#endif
#define SCHED_MAX_THREADS   (MAX_CPUS + 8)
 
#define USER_STACK_TOP   0x7FFFFFFFE000ULL   /* top of user stack */
#define USER_STACK_PAGES 16                  /* 16 x 4 KiB = 64 KiB user stack */
 
typedef enum {
    THREAD_RUNNABLE    = 0,
    THREAD_RUNNING     = 1,
    THREAD_DEAD        = 2,
    THREAD_WAITING     = 3,   /* blocked in sched_wait() until child exits */
    THREAD_BLOCKED     = 4,   /* not yet ready to run (setup in progress) */
    THREAD_FUTEX_WAIT  = 5,   /* blocked in sys_futex FUTEX_WAIT */
    THREAD_STOPPED     = 6,   /* stopped by SIGSTOP/SIGTSTP; resumes on SIGCONT */
} thread_state_t;
 
typedef void (*thread_func_t)(void *arg);
 
#define MMAP_BASE           0x70000000000ULL  /* anonymous mmap high base; grows downward */
#define MMAP_MAX_REGIONS    64
 
#define MMAP_REGION_ANON   0   /* anonymous private mapping (MAP_ANONYMOUS|MAP_PRIVATE) */
#define MMAP_REGION_FILE   1   /* file-backed private mapping (MAP_PRIVATE, fd >= 3) */
 
typedef struct {
    uint64_t virt_addr;   /* base VA of the mapping; 0 = free slot */
    uint64_t len;         /* length in bytes (multiple of PAGE_SIZE) */
    int      prot;        /* PROT_* flags as passed by caller */
    int      region_type; /* MMAP_REGION_ANON or MMAP_REGION_FILE */
    int      lazy;        /* 1 = pages not yet mapped; allocate on first #PF */
    /* File-backed mapping metadata (MMAP_REGION_FILE + lazy=1 only) */
    uint32_t   file_inode;   /* inode number of the mapped file */
    uint64_t   file_offset;  /* file offset corresponding to virt_addr */
    uint64_t   file_size;    /* bytes of real file data (tail pages zero-padded) */
    vfs_ops_t *file_ops;     /* filesystem ops; stable static pointer */
} mmap_region_t;
 
/* ---- Thread group (shared state for CLONE_VM|CLONE_FILES threads) ---- */
#define THREAD_GROUP_MAX 4
 
typedef struct thread_group {
    int           in_use;
    int           ref_count;   /* number of threads pointing at this group */
    spinlock_t    lock;
    vfs_file_t    *fd_table;
    uint64_t      brk;
    uint64_t      brk_base;    /* lower bound of heap (ELF image end); set once at execve */
    uint64_t      mmap_next;
    mmap_region_t *mmap_regions;
    char          cwd[VFS_PATH_MAX];
    uint64_t      pml4_phys;   /* shared address space (vmm_new_address_space()) */
} thread_group_t;
 
extern thread_group_t thread_group_pool[THREAD_GROUP_MAX];
 
struct thread {
    uint32_t           tid;
    thread_state_t     state;
    struct task_cpu_context ctx;   /* saved register state (used when not running) */
    uint8_t           *stack_base; /* kmalloc'd kernel stack buffer base */
    struct thread     *next;       /* intrusive linked list for run queue */
 
    /* User-mode stack -- NULL/0 for kernel-only threads */
    uint64_t   user_stack_phys_base; /* physical base of first user stack page (for cleanup) */
    uint64_t   user_stack_virt_top;  /* virtual address of stack top (passed in RSP via iretq) */
    uint8_t    user_stack_pages;     /* number of pages allocated (USER_STACK_PAGES) */
 
    /* Per-task open file table (VFS) */
    vfs_file_t  *fd_table;
 
    /* Fork/wait support */
    uint32_t   parent_tid;    /* tid of parent thread; 0 if none */
    int        exit_code;     /* exit code set by SYS_exit, read by parent's SYS_wait */
 
    /* POSIX process identity */
    uint32_t   pid;   /* process ID — equals tid at task creation */
    uint32_t   ppid;  /* parent process ID — parent->pid at fork, 0 for root tasks */
    uint32_t   pgid;  /* process group ID — default = pid; mutable via SYS_setpgid */
    uint32_t   sid;   /* session ID — default = pid at creation; set via SYS_setsid */
 
    /* Saved user-mode registers across context switches (used for fork child sysret) */
    uint64_t   saved_user_rsp;   /* user RSP at syscall entry */
    uint64_t   saved_user_rip;   /* user RIP at syscall entry (rcx from SYSCALL) */
    uint64_t   saved_user_rfl;   /* user RFLAGS at syscall entry (r11 from SYSCALL) */
 
    /* Callee-saved user registers at syscall entry (SYSCALL doesn't save these;
     * fork_child_trampoline must restore them so the child's stack frame is intact) */
    uint64_t   saved_user_rbp;
    uint64_t   saved_user_rbx;
    uint64_t   saved_user_r12;
    uint64_t   saved_user_r13;
    uint64_t   saved_user_r14;
    uint64_t   saved_user_r15;
 
    /* Argument registers for execve: set to argc/argv before sysretq to ELF entry.
     * Zero-initialised by sched_create_user_task; set by SYS_execve. */
    uint64_t   saved_user_rdi;   /* argc for new process */
    uint64_t   saved_user_rsi;   /* pointer to argv array for new process */
    uint64_t   saved_user_rdx;   /* pointer to envp array for new process */
 
    /* Heap break for SYS_brk / Newlib malloc support.
     * Initialised to 0; set to ELF load end by SYS_execve.
     * sys_brk() maps pages up to this address on each call. */
    uint64_t   brk;
    uint64_t   brk_base;  /* ELF image end = lowest valid heap VA; set once at task creation */
 
    /* Anonymous mmap region tracking.
     * mmap_next is the allocation cursor, initialised to MMAP_BASE at task creation.
     * Grows downward: each new mapping is placed below the previous one.
     * mmap_regions[] tracks up to MMAP_MAX_REGIONS active mappings; virt_addr==0 = free slot. */
    uint64_t      mmap_next;
    mmap_region_t *mmap_regions;
 
    /* Signal delivery */
    uint32_t        pending_signals;      /* bitmask: bit N set if signal N is pending (signals 1-31) */
    mini_sigaction_t signal_actions[32];  /* per-signal disposition; index 0 unused; default = SIG_DFL */
 
    /* Interval timer — ITIMER_REAL */
    uint64_t      itimer_real_deadline_ticks;  /* lapic tick count when alarm fires; 0 = inactive */
    uint64_t      itimer_real_interval_ticks;  /* reload interval in ticks; 0 = one-shot */
    uint8_t       itimer_real_active;          /* 1 = armed, 0 = disarmed */
 
    /* SA_RESTART syscall replay state */
    uint64_t  syscall_restart_nr;           /* syscall number of interrupted syscall */
    uint64_t  syscall_restart_args[6];      /* all 6 arguments at syscall entry */
    uint64_t  syscall_restart_saved_rip;    /* user RIP to restore in sigreturn */
    uint8_t   syscall_restart_pending;      /* 1 = interrupted syscall may restart */
    uint8_t   syscall_last_signal;          /* signal number dispatched, for SA_RESTART lookup */
    uint8_t   _restart_pad[6];             /* pad to 8-byte boundary */
    uint64_t  signal_trampoline_va;         /* userspace trampoline VA, set by SYS_register_sigtrampoline */
    /* Snapshot of syscall_restart_* taken at ring3_invoke_handler() time.
     * SYS_sigreturn uses these so syscalls inside the handler cannot corrupt
     * the pre-handler return state. */
    uint64_t  signal_ctx_rip;               /* saved_user_rip at handler-dispatch time */
    uint64_t  signal_ctx_rsp;               /* saved_user_rsp at handler-dispatch time (restored by sigreturn) */
    uint64_t  signal_ctx_restart_rip;       /* copy of syscall_restart_saved_rip */
    uint64_t  signal_ctx_restart_nr;        /* copy of syscall_restart_nr */
    uint64_t  signal_ctx_restart_args[6];   /* copy of syscall_restart_args */
    uint8_t   signal_ctx_restart_pending;   /* copy of syscall_restart_pending */
    uint8_t   _signal_ctx_pad[7];           /* pad to 8-byte boundary */
 
    /* Current working directory.
     * Initialized to "/" at task creation; updated by SYS_chdir.
     * Inherited (copied) by sched_fork(). Max length: VFS_PATH_MAX-1 chars. */
    char          cwd[VFS_PATH_MAX];
 
    /* Thread group (CLONE_VM|CLONE_FILES threads). NULL = single-threaded. */
    struct thread_group *tg;
    uint32_t  tgid;          /* thread group ID (= pid of group leader); 0 if not in group */
    uint32_t  _tg_pad;
 
    /* Per-process address space (vmm_new_address_space()). Every thread not in a
     * group owns its own; grouped threads share tg->pml4_phys via THREAD_PML4(). */
    uint64_t  pml4_phys;
 
    /* futex: uaddr being waited on, NULL if not in FUTEX_WAIT */
    volatile uint32_t *futex_uaddr;
 
    /* clone CLONE_CHILD_CLEARTID / set_tid_address: clear this VA on exit then FUTEX_WAKE 1 */
    volatile uint32_t *clear_tid_addr;
 
    /* /proc/<pid> support. comm = basename of the exec'd binary (TASK_COMM_LEN-style,
     * truncated). cmdline = NUL-separated argv as execve() received it, cmdline_len
     * bytes total (including each arg's NUL). utime_ticks = LAPIC ticks charged to
     * this thread while it was cpu->current_thread (approximate; no user/kernel split). */
    char      comm[16];
    char      cmdline[128];
    uint32_t  cmdline_len;
    uint64_t  utime_ticks;
 
    /* Job control: signal number that put this thread into THREAD_STOPPED
     * (SIGSTOP or SIGTSTP), for WSTOPSIG() via wait4's status word. Also
     * used for ptrace stops (always SIGTRAP) — wait4's existing THREAD_STOPPED
     * reporting path is shared by both job control and ptrace. */
    uint8_t   stop_signal;
 
    /* ptrace(2) — PTRACE_TRACEME only (no PTRACE_ATTACH to an unrelated running
     * process). ptrace_traced/ptrace_tracer_tid identify the tracer; a traced
     * thread's SYS_execve raises an initial PTRACE_EVENT_EXEC-equivalent stop
     * (see syscall_proc.c). ptrace_trace_syscalls arms PTRACE_SYSCALL
     * entry/exit stops in syscall_dispatch(). ptrace_stop_reason records why
     * the thread is (or was last) THREAD_STOPPED for ptrace's benefit, and
     * ptrace_syscall_nr/ptrace_syscall_ret let GETREGS report orig_rax/rax at
     * a syscall stop (rax otherwise never leaves the CPU register file at
     * that point — syscall_restart_nr/args capture the entry-time values). */
    uint8_t   ptrace_traced;
    uint8_t   ptrace_trace_syscalls;
    uint8_t   ptrace_stop_reason;   /* PTRACE_STOP_* below */
    uint32_t  ptrace_tracer_tid;
    uint64_t  ptrace_syscall_nr;
    int64_t   ptrace_syscall_ret;
 
    /* Set to the #DB handler's local interrupt-frame pointer while stopped
     * for PTRACE_STOP_SINGLESTEP, NULL otherwise. miniOS has two distinct
     * "return to userspace" paths — sysretq (SYSCALL entry, resumes from
     * saved_user_rip/rfl/rsp) and iretq (interrupt/exception entry, resumes
     * from this per-trap stack-local context) — and a ptrace stop can
     * legitimately happen via either one (a syscall stop always resumes via
     * sysretq; a singlestep #DB stop always resumes via iretq). Whichever
     * one applies, PTRACE_CONT/PTRACE_SINGLESTEP must set the TF flag (or
     * not) on the correct copy, or the resumed thread won't actually
     * single-step. NULL means "resumes via sysretq, use saved_user_rfl".
     * Never dereferenced by anything other than the thread's own #DB
     * handler and its own tracer, and only while genuinely stopped. */
    struct task_cpu_context *ptrace_trap_ctx;
};
 
/* Why a traced thread is (or was last) THREAD_STOPPED. Shared by
 * syscall.c (entry/exit stops), syscall_proc.c (TRACEME's initial exec
 * stop), and the #DB handler in exceptions.c (singlestep stops). */
#define PTRACE_STOP_SYSCALL_ENTRY 1
#define PTRACE_STOP_SYSCALL_EXIT  2
#define PTRACE_STOP_EXEC          3
#define PTRACE_STOP_SINGLESTEP    4
 
/* Resolve the active fd_table, brk, mmap_next, mmap_regions, cwd for thread t.
 * Threads in a group share all these via tg; single-threaded tasks use own fields. */
#define THREAD_FDT(t)           ((t)->tg ? (t)->tg->fd_table    : (t)->fd_table)
#define THREAD_BRK_PTR(t)       ((t)->tg ? &(t)->tg->brk        : &(t)->brk)
#define THREAD_BRK_BASE_PTR(t)  ((t)->tg ? &(t)->tg->brk_base   : &(t)->brk_base)
#define THREAD_MMAP_PTR(t)      ((t)->tg ? &(t)->tg->mmap_next  : &(t)->mmap_next)
#define THREAD_MMAPR(t)         ((t)->tg ? (t)->tg->mmap_regions : (t)->mmap_regions)
#define THREAD_CWD(t)           ((t)->tg ? (t)->tg->cwd          : (t)->cwd)
#define THREAD_PML4(t)          ((t)->tg ? (t)->tg->pml4_phys    : (t)->pml4_phys)
 
/* idle_loop: per-CPU idle function; runs sti;hlt in a loop. Not static so
   sched_init_cpu() can wire it as the per-AP idle thread entry point. */
void __attribute__((noreturn)) idle_loop(void *arg);

void sched_init(void);

void sched_init_cpu(uint32_t cpu_id);

struct thread *sched_create_thread(thread_func_t func, void *arg);

void sched_tick(void);

struct thread *sched_current(void);

struct thread *sched_next(void);

void sched_yield(void);

struct thread *sched_create_user_task(uint64_t entry_rip);

void sched_exit_current(int code);

bool sched_has_user_threads(void);

struct thread *sched_fork(void);

int sched_wait(uint32_t child_tid, int *exit_code);

struct thread *sched_clone(uint64_t child_stack, uint64_t tls, uint32_t *child_tid);

void sched_balance_enqueue(struct thread *t);

void sched_signal_thread(struct thread *t, int sig);

void sched_stop_current(int stop_signal);

void sched_ptrace_stop(int reason);

void sched_wake_tid(uint32_t tid);

void sched_work_steal(void);
 
/* Expose thread_pool for sched_wait iteration */
extern struct thread thread_pool[SCHED_MAX_THREADS];
 
/* sched_tick_count: LAPIC timer ticks since boot, incremented by sched_tick().
 * Used as a coarse jiffies-equivalent (e.g. /proc/stat's "cpu" line). */
extern volatile uint64_t sched_tick_count;
 
/* Exposed for sched_balance.c — guards thread_pool[], run queues, thread_count */
extern spinlock_t thread_pool_lock;

void sched_activate_task(struct thread *t);

extern void context_switch_asm(struct task_cpu_context *old_ctx,
                                struct task_cpu_context *new_ctx);
 
#endif /* _MINIOS_SCHED_SCHED_H_ */