> ## Documentation Index
> Fetch the complete documentation index at: https://kernel.mvhcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MVH Kernel Task Registry — PID and Execution State

> Reference for the MVH Kernel task registry: task_init, task_count, task_list, and task_state_name. Tracks up to 16 tasks by PID, priority, and state.

The task registry tracks up to 16 kernel tasks, each identified by a PID and carrying priority, execution state, creation tick, and display name metadata. This is a **registry, not a scheduler** — MVH Kernel runs on a single processor without preemptive multitasking or context switching. The registry exists to give you a consistent view of which logical tasks the kernel has created and what state each one is in.

<Note>
  The task registry is informational. There is no scheduler or context switching in the current release. Task states are updated by the kernel itself; you cannot forcibly suspend or resume a task through this API.
</Note>

## Constants

| Constant        | Value | Meaning                                                                   |
| --------------- | ----- | ------------------------------------------------------------------------- |
| `TASK_MAX`      | `16`  | Maximum number of tasks the registry can hold                             |
| `TASK_NAME_MAX` | `24`  | Size of the `name` buffer in `task_info_t`, including the null terminator |

## Types

### `task_state_t`

An enumeration of all possible task execution states.

```c theme={null}
typedef enum {
    TASK_UNUSED   = 0, /* Slot is free — no task occupies it       */
    TASK_RUNNING  = 1, /* Task is currently executing              */
    TASK_READY    = 2, /* Task is ready and waiting to be run      */
    TASK_SLEEPING = 3, /* Task is waiting for a timer or event     */
    TASK_STOPPED  = 4  /* Task has terminated or been stopped      */
} task_state_t;
```

### `task_info_t`

A snapshot of a single registered task.

```c theme={null}
typedef struct {
    uint32_t     pid;                   /* Process / task identifier           */
    uint8_t      priority;              /* Scheduling priority hint            */
    task_state_t state;                 /* Current execution state             */
    uint64_t     created_tick;          /* Kernel tick at creation time        */
    char         name[TASK_NAME_MAX];   /* Null-terminated display name        */
} task_info_t;
```

<ResponseField name="pid" type="uint32_t">
  A kernel-assigned numeric identifier that is unique within a single boot session. PIDs are assigned sequentially and are never reused.
</ResponseField>

<ResponseField name="priority" type="uint8_t">
  A priority hint in the range `[0, 255]`, where higher values indicate higher priority. Because there is no preemptive scheduler in the current release, this field is informational only.
</ResponseField>

<ResponseField name="state" type="task_state_t">
  The current execution state. Use `task_state_name()` to convert this value to a printable string.
</ResponseField>

<ResponseField name="created_tick" type="uint64_t">
  The value of the kernel tick counter at the moment the task was registered. Use this to determine task age relative to other tasks or to the current tick.
</ResponseField>

<ResponseField name="name" type="char[24]">
  A null-terminated display name assigned at registration. Maximum usable length is 23 characters.
</ResponseField>

***

## Functions

### `task_init`

```c theme={null}
void task_init(uint64_t tick);
```

Initialise the task registry. You must call this function once during kernel startup, before calling any other task API function. Pass the current kernel tick value so that the first task's `created_tick` is anchored to a meaningful timestamp.

<ParamField path="tick" type="uint64_t" required>
  The current kernel tick at the time of initialisation. Typically this is the tick value read from the hardware timer immediately before calling `task_init`.
</ParamField>

***

### `task_count`

```c theme={null}
uint32_t task_count(void);
```

Return the number of tasks currently registered (including tasks in any state other than `TASK_UNUSED`).

<ResponseField name="return" type="uint32_t">
  The number of active task entries, in the range `[0, TASK_MAX]`.
</ResponseField>

***

### `task_list`

```c theme={null}
uint32_t task_list(task_info_t *tasks, uint32_t capacity);
```

Copy registered task records into a caller-supplied array. Only slots whose state is not `TASK_UNUSED` are included.

<ParamField path="tasks" type="task_info_t *" required>
  Pointer to an array of `task_info_t` that will receive the task records. The array must be large enough to hold at least `capacity` elements.
</ParamField>

<ParamField path="capacity" type="uint32_t" required>
  The maximum number of records to write. Pass `TASK_MAX` to guarantee that every active task is captured.
</ParamField>

<ResponseField name="return" type="uint32_t">
  The number of records written to `tasks`. This is `min(task_count(), capacity)`.
</ResponseField>

***

### `task_state_name`

```c theme={null}
const char *task_state_name(task_state_t state);
```

Return a human-readable string for a task state enumerator.

<ParamField path="state" type="task_state_t" required>
  Any `task_state_t` value.
</ParamField>

<ResponseField name="return" type="const char *">
  A pointer to a null-terminated static string: `"UNUSED"`, `"RUNNING"`, `"READY"`, `"SLEEPING"`, or `"STOPPED"`. Returns `"UNKNOWN"` for unrecognised values. Do not free or modify the returned pointer.
</ResponseField>

***

## Shell Command

The built-in `ps` shell command prints a formatted table of every registered task, showing its PID, priority, state, creation tick, and name:

```
ps
```

***

## Example

The following example initialises the task registry, then lists all tasks and prints their state alongside their PID and name.

```c theme={null}
#include <mvh/task.h>
#include <stdio.h>

void print_task_list(uint64_t current_tick) {
    /* Initialise the registry once at boot, anchored to the current tick. */
    task_init(current_tick);

    /* Allocate a buffer large enough for every possible task. */
    task_info_t tasks[TASK_MAX];
    uint32_t count = task_list(tasks, TASK_MAX);

    printf("%-6s  %-4s  %-10s  %-20s  %s\n",
           "PID", "PRI", "STATE", "NAME", "CREATED_TICK");

    for (uint32_t i = 0; i < count; i++) {
        task_info_t *t = &tasks[i];
        printf("%-6u  %-4u  %-10s  %-20s  %llu\n",
               t->pid,
               t->priority,
               task_state_name(t->state),
               t->name,
               (unsigned long long)t->created_tick);
    }
}
```