# MVGAL Kernel Module Interface Specification

**Version:** 1.0  
**Date:** May 2026  
**Status:** Implementation Phase

---

## 1. Overview

This document specifies the interface between the MVGAL kernel module (`mvgal.ko`) and its consumers (userspace runtime, vendor backend shims). The kernel module provides:

1. PCI GPU topology discovery and enumeration
2. Character device interface (`/dev/mvgal0`) for ioctl communication
3. Sysfs interface (`/sys/class/mvgal/`) for runtime control
4. DMA-BUF coordination primitives
5. Cross-vendor fence and synchronization

---

## 2. Device Interface

### 2.1 Character Device

```
Path:    /dev/mvgal0
Type:    Character device (dynamic major)
GPL License
```

### 2.2 File Operations

```c
struct file_operations mvgal_fops = {
    .owner          = THIS_MODULE,
    .open           = mvgal_open,
    .release        = mvgal_release,
    .unlocked_ioctl = mvgal_ioctl,
    .compat_ioctl   = compat_ptr_ioctl,
    .llseek         = noop_llseek,
};
```

---

## 3. IOCTL Interface

### 3.1 UAPI Header

```c
/* include/mvgal/mvgal_uapi.h */

#define MVGAL_UAPI_VERSION_MAJOR 0U
#define MVGAL_UAPI_VERSION_MINOR 1U
#define MVGAL_UAPI_VERSION_PATCH 0U

#define MVGAL_DEVICE_NAME "mvgal0"
#define MVGAL_UAPI_MAX_GPUS 32U
```

### 3.2 IOCTL Command Definitions

```c
#define MVGAL_IOC_MAGIC 'M'

#define MVGAL_IOC_QUERY_VERSION        _IOR(MVGAL_IOC_MAGIC, 0x00, struct mvgal_uapi_version)
#define MVGAL_IOC_GET_GPU_COUNT        _IOR(MVGAL_IOC_MAGIC, 0x01, struct mvgal_uapi_gpu_count)
#define MVGAL_IOC_GET_GPU_INFO         _IOWR(MVGAL_IOC_MAGIC, 0x02, struct mvgal_uapi_gpu_query)
#define MVGAL_IOC_ENABLE               _IO(MVGAL_IOC_MAGIC, 0x03)
#define MVGAL_IOC_DISABLE              _IO(MVGAL_IOC_MAGIC, 0x04)
#define MVGAL_IOC_GET_STATS            _IOR(MVGAL_IOC_MAGIC, 0x05, struct mvgal_uapi_stats)
#define MVGAL_IOC_GET_CAPS             _IOR(MVGAL_IOC_MAGIC, 0x06, struct mvgal_uapi_caps)
#define MVGAL_IOC_RESCAN               _IO(MVGAL_IOC_MAGIC, 0x07)
#define MVGAL_IOC_EXPORT_DMABUF        _IOWR(MVGAL_IOC_MAGIC, 0x10, struct mvgal_uapi_dmabuf_request)
#define MVGAL_IOC_IMPORT_DMABUF        _IOWR(MVGAL_IOC_MAGIC, 0x11, struct mvgal_uapi_dmabuf_request)
#define MVGAL_IOC_ALLOC_CROSS_VENDOR   _IOWR(MVGAL_IOC_MAGIC, 0x12, struct mvgal_uapi_cross_vendor_alloc)
#define MVGAL_IOC_FREE_CROSS_VENDOR    _IOW(MVGAL_IOC_MAGIC, 0x13, __u64)
```

### 3.3 Data Structures

#### Version Query

```c
struct mvgal_uapi_version {
    __u32 major;
    __u32 minor;
    __u32 patch;
    __u32 feature_flags;
};

/* Feature Flags */
#define MVGAL_UAPI_FEATURE_ENUMERATION        (1U << 0)
#define MVGAL_UAPI_FEATURE_PCI_TOPOLOGY       (1U << 1)
#define MVGAL_UAPI_FEATURE_HOTPLUG_MONITOR    (1U << 2)
#define MVGAL_UAPI_FEATURE_RESCAN             (1U << 3)
#define MVGAL_UAPI_FEATURE_READ_ONLY_SKELETON (1U << 4)
#define MVGAL_UAPI_FEATURE_FUTURE_DMABUF      (1U << 5)
#define MVGAL_UAPI_FEATURE_FUTURE_SUBMISSION  (1U << 6)
```

#### GPU Information

```c
struct mvgal_gpu_info {
    __u32 index;
    __u32 vendor_id;          /* PCI vendor ID (0x1002, 0x10DE, 0x8086, 0x1ED5) */
    __u32 device_id;          /* PCI device ID */
    __u32 subsystem_vendor_id;
    __u32 subsystem_device_id;
    __u32 pci_domain;
    __u32 pci_bus;
    __u32 pci_slot;
    __u32 pci_function;
    __u32 class_code;
    __u32 numa_node;
    __u32 pcie_link_gen;
    __u32 pcie_link_width;
    __u32 flags;
    __u64 largest_prefetchable_bar_bytes;
    __u64 largest_mmio_bar_bytes;
    char name[MVGAL_UAPI_NAME_LEN];
    char driver[MVGAL_UAPI_DRIVER_LEN];
    char bdf[MVGAL_UAPI_BDF_LEN];
};

/* GPU Flags */
#define MVGAL_UAPI_GPU_FLAG_DISPLAY_CLASS    (1U << 0)
#define MVGAL_UAPI_GPU_FLAG_PCIE             (1U << 1)
#define MVGAL_UAPI_GPU_FLAG_DRIVER_BOUND     (1U << 2)
#define MVGAL_UAPI_GPU_FLAG_MULTIFUNCTION    (1U << 3)
#define MVGAL_UAPI_GPU_FLAG_VIRTUAL_FUNCTION (1U << 4)
#define MVGAL_UAPI_GPU_FLAG_INTEGRATED_GUESS (1U << 5)
```

#### Capability Profile

```c
struct mvgal_uapi_caps {
    __u32 enabled;
    __u32 gpu_count;
    __u32 vendor_mask;
    __u32 topology_generation;
    __u32 max_pcie_link_gen;
    __u32 max_pcie_link_width;
    __u32 feature_flags;
    __u64 largest_prefetchable_bar_bytes;
    __u64 largest_mmio_bar_bytes;
    __u8 p2p_matrix[MVGAL_UAPI_MAX_GPUS * MVGAL_UAPI_MAX_GPUS];
};

/* P2P Values */
#define MVGAL_UAPI_P2P_NONE 0U
#define MVGAL_UAPI_P2P_DMA  1U
#define MVGAL_UAPI_P2P_P2P  2U
```

#### Statistics

```c
struct mvgal_uapi_stats {
    __u64 open_count;
    __u64 release_count;
    __u64 ioctl_count;
    __u64 rescans;
    __u64 hotplug_events;
    __u64 unsupported_dmabuf_exports;
    __u64 unsupported_dmabuf_imports;
    __u64 unsupported_cross_vendor_allocs;
    __u64 dma_buf_export_count;
    __u64 dma_buf_import_count;
    __u64 cross_vendor_alloc_count;
    __u64 p2p_transfer_count;
    __u64 host_staging_transfer_count;
};
```

#### DMA-BUF Request/Response

```c
struct mvgal_uapi_dmabuf_request {
    __s32 fd;              /* Input/Output: file descriptor */
    __s32 gpu_index;       /* Input: source/destination GPU */
    __u32 flags;           /* Input: allocation flags */
    __u32 reserved0;
    __u64 size;            /* Input: buffer size */
    __u64 reserved[4];
};
```

---

## 4. Sysfs Interface

### 4.1 Device Attributes

```
/sys/class/mvgal/mvgal0/
├── gpu_count           - Number of detected GPUs (read-only)
├── topology_generation - Incremented on rescan (read-only)
└── rescan              - Trigger GPU rescan (write: echo 1 > rescan)
```

### 4.2 Per-GPU Attributes

```
/sys/class/mvgal/mvgal0/gpu{X}/
├── enabled             - GPU enabled state (read/write: 0/1)
├── pci_path            - PCI BDF string (read-only)
└── power_state         - Power state: auto/on/off (read/write)
```

---

## 5. Data Structures for Vendor Integration

### 5.1 GPU Device Structure

```c
struct mvgal_gpu_device {
    struct list_head node;
    struct pci_dev *pdev;
    struct drm_device *drm;
    
    /* Identity */
    enum mvgal_vendor_id vendor;
    uint16_t pci_vendor_id;
    uint16_t pci_device_id;
    char name[64];
    
    /* Capabilities */
    uint64_t vram_size;
    uint32_t vram_bandwidth;
    uint32_t compute_units;
    uint32_t api_flags;
    uint32_t pcie_gen;
    uint32_t pcie_lanes;
    uint32_t numa_node;
    
    /* State */
    enum mvgal_power_state power_state;
    bool available;
    bool enabled;
    
    /* Statistics */
    uint32_t utilization;
    uint64_t memory_used;
    int32_t temperature;
    uint32_t power_draw;
    
    /* Vendor operations */
    const struct mvgal_vendor_ops *ops;
    void *vendor_priv;
    
    /* Synchronization */
    struct mutex lock;
};
```

### 5.2 Vendor Operations Interface

```c
struct mvgal_vendor_ops {
    /* Lifecycle */
    int  (*init)(struct mvgal_gpu_device *dev);
    void (*fini)(struct mvgal_gpu_device *dev);
    
    /* Command Submission */
    int  (*submit_cs)(struct mvgal_gpu_device *dev, struct mvgal_workload *wl);
    
    /* Memory Management */
    int  (*alloc_vram)(struct mvgal_gpu_device *dev, size_t size, uint64_t *gpu_addr);
    void (*free_vram)(struct mvgal_gpu_device *dev, uint64_t gpu_addr);
    
    /* Idle Detection */
    int  (*wait_idle)(struct mvgal_gpu_device *dev, uint32_t timeout_ms);
    
    /* Power Management */
    int  (*set_power_state)(struct mvgal_gpu_device *dev, enum mvgal_power_state);
    
    /* DMA-BUF Operations */
    struct dma_buf *(*export_dmabuf)(struct mvgal_gpu_device *dev, uint64_t gpu_addr, size_t size);
    int  (*import_dmabuf)(struct mvgal_gpu_device *dev, struct dma_buf *buf, uint64_t *gpu_addr);
    
    /* Telemetry */
    int  (*query_utilization)(struct mvgal_gpu_device *dev, uint32_t *util_percent);
};
```

---

## 6. Capability Flags

### 6.1 API Support Flags

```c
#define MVGAL_API_VULKAN   (1 << 0)
#define MVGAL_API_OPENGL   (1 << 1)
#define MVGAL_API_OPENCL   (1 << 2)
#define MVGAL_API_CUDA     (1 << 3)
#define MVGAL_API_SYCL     (1 << 4)
```

### 6.2 Feature Flags

```c
#define MVGAL_FEATURE_TENSOR_CORES  (1 << 0)
#define MVGAL_FEATURE_RT_CORES      (1 << 1)
#define MVGAL_FEATURE_PEER_ACCESS   (1 << 2)
```

---

## 7. Power States

```c
enum mvgal_power_state {
    MVGAL_POWER_STATE_ACTIVE = 0,     /* Normal operation */
    MVGAL_POWER_STATE_SUSTAINED = 1,  /* Sustained performance */
    MVGAL_POWER_STATE_IDLE = 2,       /* Idle, can throttle */
    MVGAL_POWER_STATE_PARK = 3,       /* Parked, low power */
    MVGAL_POWER_STATE_OFF = 4,        /* Powered off */
};
```

---

## 8. Memory Flags

Used in `mvgal_uapi_dmabuf_request.flags`:

```c
#define MVGAL_MEMORY_FLAG_HOST_VALID    (1 << 0)
#define MVGAL_MEMORY_FLAG_GPU_VALID     (1 << 1)
#define MVGAL_MEMORY_FLAG_CPU_CACHED    (1 << 2)
#define MVGAL_MEMORY_FLAG_CPU_UNCACHED  (1 << 3)
#define MVGAL_MEMORY_FLAG_SHARED        (1 << 4)
#define MVGAL_MEMORY_FLAG_DMA_BUF       (1 << 5)
#define MVGAL_MEMORY_FLAG_P2P           (1 << 6)
#define MVGAL_MEMORY_FLAG_REPLICATED    (1 << 7)
#define MVGAL_MEMORY_FLAG_PERSISTENT    (1 << 8)
#define MVGAL_MEMORY_FLAG_LAZY_ALLOCATE (1 << 9)
```

---

## 9. Error Handling

### 9.1 Standard Error Codes

The kernel module follows standard Linux error conventions:

| Error | Meaning |
|-------|---------|
| `-EINVAL` | Invalid argument |
| `-ENOENT` | No such device/resource |
| `-ENODEV` | No such device |
| `-ENOMEM` | Out of memory |
| `- EOPNOTSUPP` | Operation not supported |
| `-ETIMEDOUT` | Operation timed out |
| `-EFAULT` | Bad address (copy_to/from_user) |
| `-ENOTCONN` | Not connected |

### 9.2 Statistics Tracking

Unsupported operations are tracked in `mvgal_uapi_stats`:
- `unsupported_dmabuf_exports`
- `unsupported_dmabuf_imports`
- `unsupported_cross_vendor_allocs`

---

## 10. Hotplug Support

The kernel module registers a PCI bus notifier to detect GPU hotplug events. When a GPU is added or removed, the `mvgal_pci_bus_notifier()` callback is invoked, which:

1. Increments `stats.hotplug_events`
2. Calls `mvgal_rescan_locked()` to update GPU list
3. Updates sysfs attributes

---

## 11. Build-Time Configuration

### 11.1 Full Stack Mode

When `MVGAL_BUILD_FULL_STACK=1` is defined:

- Enables `MVGAL_FULL_STACK` preprocessor macro
- Includes full aggregation stack initialization
- Enables DMA-BUF and cross-vendor allocation ioctls

### 11.2 Kernel Version Compatibility

The module supports:
- Linux 5.10+ (for PCIe P2P support)
- RHEL 9+
- Fedora 36+
- Ubuntu 22.04+

---

## 12. Usage Example (Userspace)

```c
#include <mvgal/mvgal_uapi.h>
#include <sys/ioctl.h>
#include <fcntl.h>

int main(void) {
    int fd = open("/dev/mvgal0", O_RDWR);
    if (fd < 0) return -1;
    
    struct mvgal_uapi_version ver = {0};
    if (ioctl(fd, MVGAL_IOC_QUERY_VERSION, &ver) < 0) {
        close(fd);
        return -1;
    }
    
    printf("MVGAL version: %u.%u.%u\n", ver.major, ver.minor, ver.patch);
    
    struct mvgal_uapi_gpu_count count = {0};
    if (ioctl(fd, MVGAL_IOC_GET_GPU_COUNT, &count) < 0) {
        close(fd);
        return -1;
    }
    
    printf("Found %u GPUs\n", count.gpu_count);
    
    for (uint32_t i = 0; i < count.gpu_count; i++) {
        struct mvgal_uapi_gpu_query query = {.index = i};
        if (ioctl(fd, MVGAL_IOC_GET_GPU_INFO, &query) < 0) continue;
        
        printf("GPU %u: %s (%04x:%04x)\n",
               i, query.info.name,
               query.info.vendor_id, query.info.device_id);
    }
    
    close(fd);
    return 0;
}
```

---

## 13. ABI Stability

This UAPI is considered **unstable** until version 1.0. Changes may be made:
- `mvgal_uapi.h` version 0.1.x - Experimental
- `mvgal_uapi.h` version 1.0.0 - Stable ABI promise

---

## 14. References

- Linux DRM UAPI: `drivers/gpu/drm/drm_uapi.h`
- DMA-BUF API: `drivers/dma-buf/dma-buf.h`
- PCI subsystem: `drivers/pci/`