Implement kernel threading infrastructure

[pbalduino]

Goal

Implement the foundational kernel-level threading infrastructure to support multiple threads within a single process address space.

Context

Currently meniOS supports only single-threaded processes. To enable modern applications and libraries (including text editors like nano/vim, and eventually more complex software), we need kernel-level threading support that can manage multiple execution contexts within a process.

Definition of Done

• Thread Control Blocks (TCB): Data structure for per-thread state
• Thread creation/destruction: Kernel APIs for thread lifecycle management
• Thread scheduling integration: Extend current scheduler to handle threads
• Thread stack management: Separate stacks per thread with guard pages
• Thread ID management: Unique thread identification system
• Thread state management: NEW, READY, RUNNING, BLOCKED, TERMINATED states
• Thread synchronization hooks: Integration points for mutexes/condvars
• Parent/child thread relationships: Thread hierarchy and cleanup

Thread Control Block Design

struct thread_control_block {
    tid_t tid;                    // Thread ID
    pid_t pid;                    // Parent process ID
    void *stack_base;             // Thread stack base address
    size_t stack_size;            // Stack size
    void *stack_pointer;          // Current stack pointer
    struct cpu_context context;   // Saved CPU registers
    enum thread_state state;      // Thread state
    int priority;                 // Thread priority
    struct thread *parent;        // Parent thread
    struct list_head children;    // Child threads
    struct list_head siblings;    // Sibling threads
    void *exit_value;             // Thread exit value
    struct list_head waiting;     // Threads waiting for this one
    unsigned long flags;          // Thread flags
    struct mm_struct *mm;         // Shared memory management
};

Thread States

enum thread_state {
    THREAD_NEW,         // Newly created, not yet scheduled
    THREAD_READY,       // Ready to run
    THREAD_RUNNING,     // Currently executing
    THREAD_BLOCKED,     // Waiting for resource/event
    THREAD_TERMINATED,  // Finished execution
    THREAD_ZOMBIE       // Finished but not yet cleaned up
};

Kernel API Interface

// Thread management
tid_t kthread_create(void (*entry_point)(void *), void *arg, size_t stack_size);
int kthread_exit(void *exit_value);
int kthread_join(tid_t tid, void **exit_value);
int kthread_detach(tid_t tid);
tid_t kthread_self(void);

// Thread control
int kthread_yield(void);
int kthread_sleep(unsigned long milliseconds);
int kthread_kill(tid_t tid, int signal);

// Thread attributes
int kthread_setpriority(tid_t tid, int priority);
int kthread_getpriority(tid_t tid);

Implementation Details

Thread Stack Management

• Default stack size: 8KB with 4KB guard pages
• Stack overflow detection using guard pages
• Automatic stack growth (optional feature)
• Stack cleanup on thread termination
• Stack alignment requirements (16-byte for x86_64)

Thread Scheduling Integration

• Extend current scheduler to handle threads
• Per-CPU thread runqueues (prepare for SMP)
• Thread-aware context switching
• Priority-based thread scheduling
• Time slice allocation per thread

Thread Synchronization Hooks

• Integration points for mutex acquisition/release
• Condition variable wait/signal hooks
• Semaphore operation hooks
• Read-write lock integration
• Priority inheritance support preparation

Memory Management Integration

• Shared virtual memory space per process
• Private thread stacks in shared address space
• Thread-local storage (TLS) preparation
• Copy-on-write optimizations for thread creation
• Memory cleanup on thread termination

Testing Strategy

• Thread creation and destruction stress tests
• Thread scheduling fairness validation
• Stack overflow detection testing
• Thread hierarchy and cleanup testing
• Concurrent thread execution validation
• Thread state transition testing
• Memory leak detection for thread resources

Security Considerations

• Thread isolation within process boundaries
• Stack protection and guard pages
• Thread capability inheritance
• Resource limit enforcement per thread
• Prevention of thread resource exhaustion

Dependencies

• Scheduler foundation: Issue Implement preemptive userland scheduler #34 (CLOSED) - Need preemptive scheduler
• Memory management: Issue Build lightweight virtual memory manager (vm_map/vm_unmap/vm_clone) #57 (CLOSED) - Need VM for thread stacks
• Synchronization primitives: Issue Improve kmutex implementation #36 - Need mutex implementation
• Process management: Issue Implement fork/exec process creation system #93 - Need process infrastructure
• Signal handling: Issue Implement signal handling and delivery system #94 - Need signals for thread communication

Integration Points

• Extend process creation to support threading
• Integrate with existing scheduler framework
• Add thread support to system call interface
• Integrate with memory management subsystem
• Support thread-aware debugging interfaces

Files to Create/Modify

• src/kernel/thread/thread.c - Core threading implementation
• src/kernel/thread/thread.h - Threading interface definitions
• src/kernel/sched/thread_sched.c - Thread scheduling extensions
• include/kernel/thread.h - Kernel threading interface
• src/kernel/thread/stack.c - Thread stack management
• src/kernel/thread/sync.c - Thread synchronization hooks

Performance Goals

• Thread creation latency < 50μs
• Thread context switch < 5μs
• Minimal memory overhead per thread (< 16KB)
• Scalable to 1000+ threads per process
• Low scheduler overhead for thread switching

Error Handling

• EAGAIN for resource exhaustion
• EINVAL for invalid thread parameters
• ESRCH for non-existent threads
• EDEADLK for deadlock detection
• EPERM for permission violations

Advanced Features (Future)

• Thread groups: Process-level thread management
• Thread affinity: CPU binding for performance
• Real-time threads: Real-time scheduling classes
• Thread migration: Moving threads between CPUs
• Thread debugging: GDB integration for threading

Usage Examples

// Create a new thread
tid_t worker_tid = kthread_create(worker_function, work_data, 16384);

// Wait for thread completion
void *result;
kthread_join(worker_tid, &result);

// Detach a thread (fire-and-forget)
kthread_detach(background_tid);

// Thread yields CPU
kthread_yield();

Related Issues

• Foundation for pthread implementation (next phase)
• Enables multithreaded applications
• Required for modern text editors and IDEs
• Critical for server applications and databases
• Enables parallel processing capabilities