# coreboot Threads

## Thread Management

coreboot provides a cooperative threading system that allows for concurrent execution of tasks during the boot process. The thread API is particularly useful for implementing asynchronous operations and managing hardware initialization sequences.

### Thread Creation and Management

#### thread_run

    int thread_run(struct thread_handle *handle, enum cb_err (*func)(void *), void *arg)

Creates and starts a new thread to execute the specified function.

Parameters:

- `handle`: Pointer to a thread handle structure to track thread state (Note: `struct thread_handle` is an opaque structure used by the API to manage the thread’s state.)

- `func`: Function to execute in the new thread

- `arg`: Argument to pass to the function

Returns:

- 0 on success

- < 0 on failure

Example:

    struct thread_handle th;
    enum cb_err thread_func(void *arg) {
        // Thread work here
        return CB_SUCCESS;
    }

    if (thread_run(&th, thread_func, NULL) < 0) {
        printk(BIOS_ERR, "Failed to create thread\n");
    } else {
        // Wait for the thread to complete and check its status
        enum cb_err err = thread_join(&th);
        if (err != CB_SUCCESS) {
            printk(BIOS_ERR, "Thread failed with error %d\n", err);
        }
    }

#### thread_run_until

    int thread_run_until(struct thread_handle *handle, enum cb_err (*func)(void *), void *arg,
                        boot_state_t state, boot_state_sequence_t seq)

Creates a thread that blocks boot state transitions until completion.

Parameters:

- `handle`: Pointer to a thread handle structure

- `func`: Function to execute

- `arg`: Argument to pass to the function

- `state`: Boot state to block

- `seq`: Boot state sequence to block

Returns:

- 0 on success

- < 0 on failure

Example:

    struct thread_handle th;
    enum cb_err init_func(void *arg) {
        // Hardware initialization
        return CB_SUCCESS;
    }

    // Block BS_DEV_ENABLE until initialization completes
    thread_run_until(&th, init_func, NULL, BS_DEV_ENABLE, 0);

### Thread Synchronization

#### thread_join

    enum cb_err thread_join(struct thread_handle *handle)

Waits for a thread to complete and returns its error code.

Parameters:

- `handle`: Thread handle to wait for

Returns:

- Thread’s error code (e.g., `CB_SUCCESS`, `CB_ERR`). See `src/include/cb_err.h` for details.

Example:

    struct thread_handle th;
    // ... create thread ...

    enum cb_err err = thread_join(&th);
    if (err != CB_SUCCESS) {
        printk(BIOS_ERR, "Thread failed with error %d\n", err);
    }

### Thread Yielding

Yielding is crucial in a cooperative multitasking system like coreboot’s. Threads must explicitly yield control using `thread_yield` or `thread_yield_microseconds` to allow other threads to run. Failure to yield can lead to a single thread monopolizing the CPU, preventing other tasks from executing.

#### thread_yield

    int thread_yield(void)

Yields the current thread’s execution to allow other threads to run.

Returns:

- 0 on success

- < 0 if thread cannot yield

Example:

    while (!condition) {
        if (thread_yield() < 0) {
            printk(BIOS_ERR, "Failed to yield thread\n");
            break;
        }
    }

#### thread_yield_microseconds

    int thread_yield_microseconds(unsigned int microsecs)

Yields the current thread for a specified number of microseconds.

Parameters:

- `microsecs`: Number of microseconds to yield

Returns:

- 0 on success

- < 0 if thread cannot yield

Example:

    // Wait for 100 microseconds
    if (thread_yield_microseconds(100) < 0) {
        printk(BIOS_ERR, "Failed to yield thread\n");
    }

### Thread Cooperation Control

#### thread_coop_enable

    void thread_coop_enable(void)

Enables cooperative behavior for the current thread.

Example:

    thread_coop_enable();  // Allow thread to yield

#### thread_coop_disable

    void thread_coop_disable(void)

Disables cooperative behavior for the current thread.

Example:

    thread_coop_disable();  // Prevent thread from yielding

### Thread Mutexes

#### thread_mutex_lock

    void thread_mutex_lock(struct thread_mutex *mutex)

Acquires a mutex lock, waiting if necessary.

Parameters:

- `mutex`: Mutex to lock

Example:

    struct thread_mutex mtx = THREAD_MUTEX_INITIALIZER; // Or = { .locked = false };
    thread_mutex_lock(&mtx);
    // Critical section
    thread_mutex_unlock(&mtx);

#### thread_mutex_unlock

    void thread_mutex_unlock(struct thread_mutex *mutex)

Releases a mutex lock.

Parameters:

- `mutex`: Mutex to unlock

## Best Practices

1. Thread Safety:

   - Use mutexes to protect shared resources

   - Be careful with global variables in threaded code

   - Consider thread cooperation when implementing critical sections

2. Resource Management:

   - Always join threads that you create using `thread_run` to check their completion status and clean up resources. Threads started with `thread_run_until` are implicitly managed by the boot state machine and typically do not require explicit joining.

   - Consistently check return values from thread creation and operation functions (like `thread_run`, `thread_yield`, `thread_join`) to detect errors early.

   - Clean up resources allocated or used within thread functions before they exit.

3. Performance Considerations:

   - Use thread_yield_microseconds for precise timing

   - Minimize time spent in critical sections

   - Consider using thread_run_until for hardware initialization

4. Error Handling:

   - Check thread creation and operation return values (as noted in Resource Management).

   - Implement proper error handling within thread functions, returning appropriate `cb_err` values.

   - Use `thread_join` (for `thread_run` threads) to check the final completion status.

## Common Patterns

### Hardware Initialization

    struct thread_handle init_th;
    enum cb_err init_hardware(void *arg) {
        // Initialize hardware
        if (hardware_init() != 0)
            return CB_ERR;
        return CB_SUCCESS;
    }

    // Run initialization in a thread
    thread_run_until(&init_th, init_hardware, NULL, BS_DEV_ENABLE, 0);

### Asynchronous Operation

    struct thread_handle async_th;
    enum cb_err async_operation(void *arg) {
        // Perform async operation
        while (!operation_complete()) {
            if (thread_yield() < 0)
                return CB_ERR;
        }
        return CB_SUCCESS;
    }

    // Start async operation
    thread_run(&async_th, async_operation, NULL);

### Critical Section Protection

    struct thread_mutex resource_mtx = { .locked = false };

    void access_shared_resource(void) {
        thread_mutex_lock(&resource_mtx);
        // Access shared resource
        thread_mutex_unlock(&resource_mtx);
    }

## Limitations

1. The thread system is cooperative, not preemptive.

2. Threads must explicitly yield to allow other threads to run.

3. Thread operations are typically only available after RAM initialization (in ramstage and later). Check specific environment constraints if unsure.

4. Thread count is limited by the `CONFIG_NUM_THREADS` Kconfig option.

5. Thread stack size is fixed by the `CONFIG_STACK_SIZE` Kconfig option.