> ## 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.

# Device Manager API — Hardware Devices in MVH Kernel

> MVH Kernel device manager reference: device_manager_init, device_register, device_list, device_count, and device_type_name. Supports up to 32 devices.

The device manager maintains a registry of up to 32 hardware devices. Each entry records a numeric ID, a device type drawn from a fixed enumeration, a human-readable name (up to 27 characters), and an online flag indicating whether the device is currently active. You interact with the registry through the five functions described below.

## Constants

| Constant          | Value | Meaning                                                                     |
| ----------------- | ----- | --------------------------------------------------------------------------- |
| `DEVICE_MAX`      | `32`  | Maximum number of devices that can be registered                            |
| `DEVICE_NAME_MAX` | `28`  | Size of the `name` buffer in `device_info_t`, including the null terminator |

## Types

### `device_type_t`

An enumeration of all recognised device classes.

```c theme={null}
typedef enum {
    DEVICE_CPU,         /* Processor                     */
    DEVICE_INTERRUPT,   /* Interrupt controller (e.g. APIC / PIC) */
    DEVICE_TIMER,       /* Interval timer (e.g. PIT, HPET)        */
    DEVICE_INPUT,       /* Input device (keyboard, mouse, …)      */
    DEVICE_DISPLAY,     /* Display / framebuffer                   */
    DEVICE_SERIAL,      /* Serial port (e.g. 8250 UART)           */
    DEVICE_CLOCK,       /* Real-time or monotonic clock            */
    DEVICE_BUS,         /* System bus (PCI, ISA, …)               */
    DEVICE_FILESYSTEM   /* Storage / filesystem layer              */
} device_type_t;
```

### `device_info_t`

A snapshot of a single registered device.

```c theme={null}
typedef struct {
    uint32_t      id;                   /* Unique device identifier            */
    device_type_t type;                 /* Device class                        */
    uint8_t       online;               /* 1 = online / active, 0 = offline    */
    char          name[DEVICE_NAME_MAX];/* Null-terminated display name        */
} device_info_t;
```

<ResponseField name="id" type="uint32_t">
  A kernel-assigned identifier that is unique for the lifetime of the registry. IDs are assigned sequentially starting from 0 and are never reused within a single boot.
</ResponseField>

<ResponseField name="type" type="device_type_t">
  The device class. Use `device_type_name()` to convert this value to a printable string.
</ResponseField>

<ResponseField name="online" type="uint8_t">
  `1` if the device is online and available; `0` if it has been registered but is not yet active or has failed.
</ResponseField>

<ResponseField name="name" type="char[28]">
  A null-terminated UTF-8 display name supplied at registration time. Maximum usable length is 27 characters.
</ResponseField>

***

## Functions

### `device_manager_init`

```c theme={null}
void device_manager_init(void);
```

Initialise the device manager. You must call this function exactly once during kernel startup, before calling any other device API function. Calling it a second time resets the registry and discards all previously registered devices.

***

### `device_register`

```c theme={null}
int device_register(const char *name, device_type_t type, uint8_t online);
```

Register a new device with the given name, type, and initial online state.

<ParamField path="name" type="const char *" required>
  A null-terminated display name for the device. The name is copied into the registry; you do not need to keep the pointer alive after the call. Maximum length is 27 characters — longer names are truncated to fit `DEVICE_NAME_MAX`.
</ParamField>

<ParamField path="type" type="device_type_t" required>
  The device class. Must be one of the `device_type_t` enumerators listed above.
</ParamField>

<ParamField path="online" type="uint8_t" required>
  Pass `1` to mark the device as online immediately, or `0` to register it in an offline state.
</ParamField>

<ResponseField name="return" type="int">
  Returns `0` on success. Returns `-1` if the registry is full (i.e. `DEVICE_MAX` devices are already registered).
</ResponseField>

***

### `device_count`

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

Return the number of devices currently registered.

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

***

### `device_list`

```c theme={null}
uint32_t device_list(device_info_t *devices, uint32_t capacity);
```

Copy registered device records into a caller-supplied array.

<ParamField path="devices" type="device_info_t *" required>
  Pointer to an array of `device_info_t` that will receive the device 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 `DEVICE_MAX` to guarantee that every registered device is captured.
</ParamField>

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

***

### `device_type_name`

```c theme={null}
const char *device_type_name(device_type_t type);
```

Return a human-readable string for a device type enumerator.

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

<ResponseField name="return" type="const char *">
  A pointer to a null-terminated string such as `"CPU"`, `"INTERRUPT"`, `"TIMER"`, `"INPUT"`, `"DISPLAY"`, `"SERIAL"`, `"CLOCK"`, `"BUS"`, or `"FILESYSTEM"`. The pointer refers to a static string — do not free or modify it. Returns `"UNKNOWN"` for unrecognised values.
</ResponseField>

***

## Shell Command

The built-in `devices` shell command prints a formatted table of every registered device, including its ID, type, name, and online state:

```
devices
```

***

## Example

The following example registers two custom devices, then iterates the registry and prints each entry.

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

void enumerate_devices(void) {
    /* Initialise the registry once at boot. */
    device_manager_init();

    /* Register a virtual serial port (online) and a stub bus (offline). */
    if (device_register("com1", DEVICE_SERIAL, 1) != 0) {
        /* Registry is full — handle gracefully. */
        return;
    }
    device_register("pci-stub", DEVICE_BUS, 0);

    /* Allocate a buffer large enough for every possible device. */
    device_info_t list[DEVICE_MAX];
    uint32_t count = device_list(list, DEVICE_MAX);

    for (uint32_t i = 0; i < count; i++) {
        device_info_t *d = &list[i];
        printf("[%2u] %-12s  type=%-12s  online=%u\n",
               d->id,
               d->name,
               device_type_name(d->type),
               d->online);
    }
}
```