# MVGAL Technical Debt Analysis

**Version:** 1.0  
**Date:** 2026-06-02  

---

## 1. Build System Technical Debt

### 1.1 Multiple Build Systems

**Issue**: CMake, Meson, and Zig build files all exist with potential drift

**Impact**: Maintenance overhead, potential for inconsistent feature sets

**Location**: Root `CMakeLists.txt`, `meson.build`, `build.zig`

**Recommendation**: 
- Primary: CMake for kernel + userspace builds
- Deprecate or automate Meson/Zig sync
- Use CI to verify all build paths produce identical output

### 1.2 `#ifdef MVGAL_FULL_STACK` Conditionals

**Issue**: Large sections of kernel code conditionally compiled out

**Impact**: Code is difficult to test; feature fragmentation

**Location**: `kernel/mvgal_main.c` (lines 352-366, 732-774)

**Recommendation**:
- Split into separate source files per feature tier
- Use Kconfig-style options for optional features
- Enable full stack in development builds

---

## 2. Code Duplication

### 2.1 Two Daemon Implementations

**Issue**: Both `runtime/daemon/` (C++) and `src/userspace/daemon/` (C) exist

**Impact**: Logic divergence, maintenance complexity

**Recommendation**:
- Consolidate on C++ daemon (`mvgald`) as primary
- Deprecate C daemon implementation
- Map C API to C++ via FFI

### 2.2 Vulkan Layer Duplicates

**Issue**: Both `src/userspace/intercept/vulkan/` and `src/userspace/vulkan_icd/` have overlapping code

**Impact**: Confusion about which path is primary

**Recommendation**:
- Layer = interception (primary)
- ICD = explicit multi-GPU path (secondary)
- Clear documentation on when to use each

---

## 3. Stub Code Without Tests

### 3.1 Kernel Vendor Operations

**Issue**: Vendor ops return fake data

**Location**: `kernel/vendors/mvgal_*.c`

```c
// Example from mvgal_amd.c (synthesized)
static int mvgal_amd_init(struct mvgal_gpu_device *dev)
{
    // Sets fake VRAM size: 0x10000000 (256 MB)
    // Sets fake compute units
    return 0;
}
```

**Impact**: Cannot claim real hardware support

**Recommendation**:
- Connect to real sysfs metrics
- Use `pci_read_config_*` for real BAR sizes
- Implement actual VRAM allocation via GEM

### 3.2 Memory Migration Stubs

**Issue**: `mvgal_ioctl_alloc_memory` always returns `-EOPNOTSUPP`

**Location**: `kernel/mvgal_memory.c`, `kernel/mvgal_main.c` lines 761-773

**Impact**: Memory manager feature incomplete

**Recommendation**:
- Implement DMA-BUF export path first
- Add P2P as progressive enhancement
- Fall back gracefully to host staging

---

## 4. Error Handling Issues

### 4.1 Panic Recovery in Rust FFI

**Issue**: `ffi_catch` returns default values on panic, silently hiding errors

```rust
// safe/fence_manager/src/lib.rs
fn ffi_catch<R: Default>(f: impl FnOnce() -> R) -> R {
    match panic::catch_unwind(AssertUnwindSafe(f)) {
        Ok(v) => v,
        Err(_) => R::default(),  // Silent failure
    }
}
```

**Impact**: Hard to debug; production failures hidden

**Recommendation**:
- Log panic messages to syslog
- Return error codes instead of default values
- Add `mvgal_last_error()` function

### 4.2 Missing Error Propagation

**Issue**: Scheduler doesn't propagate vendor-specific errors

**Location**: `runtime/daemon/scheduler.cpp`

**Impact**: Work marked COMPLETE without actual execution

**Recommendation**:
- Add vendor submission status tracking
- Implement proper error rollback
- Add per-workload error state

---

## 5. Memory Safety Issues

### 5.1 Raw Pointer Management in Vulkan Layer

**Issue**: Manual `malloc`/`free` in `vkQueueSubmit` AFR path

```c
// src/userspace/intercept/vulkan/vk_layer.c lines 872-910
VkSubmitInfo *new_submits = (VkSubmitInfo *)malloc(submitCount * sizeof(VkSubmitInfo));
VkDeviceGroupSubmitInfo *group_infos = (VkDeviceGroupSubmitInfo *)malloc(submitCount * sizeof(VkDeviceGroupSubmitInfo));
// ... manual cleanup required
```

**Impact**: Memory leaks if early return; error-prone

**Recommendation**:
- Use RAII wrappers or goto cleanup pattern
- Consider static allocation for small submit counts
- Add leak detection in tests

### 5.2 Missing Bounds Checks

**Issue**: Some array accesses lack bounds validation

**Location**: Various places in kernel and userspace

**Recommendation**:
- Add `BUILD_BUG_ON` for static arrays
- Runtime bounds checks in debug builds
- Static analysis (clang-analyzer) in CI

---

## 6. Missing Tests

### 6.1 No Kernel Unit Tests

**Issue**: KUnit tests not implemented

**Impact**: Kernel code not validated on real hardware

**Recommendation**:
- Add KUnit tests for ioctls
- Add KUnit tests for P2P matrix calculation
- Add KUnit tests for sysfs attributes

### 6.2 No Integration Tests for Cross-Vendor Paths

**Issue**: Tests exist but no real multi-vendor hardware validation

**Location**: `src/tests/tests/integration/`

**Impact**: Code may not work on actual mixed configurations

**Recommendation**:
- Hardware test matrix in CI
- Self-hosted GPU runners
- Document test procedure for contributors

---

## 7. Documentation Debt

### 7.1 Outdated License References

**Issue**: README states MIT; some files may have GPL conflicts

**Location**: Root `LICENSE`, individual source files

**Recommendation**:
- Verify all files have correct SPDX headers
- Document license split (GPL-2.0 for kernel, MIT for userspace)

### 7.2 README Claims vs Reality

**Issue**: Status badges claim 100% tests but lack hardware validation

**Location**: Root `README.md`

**Recommendation**:
- Distinguish synthetic vs real hardware tests
- Add hardware validation table
- Link to validation report

---

## 8. Configuration Issues

### 8.1 Default config paths hardcoded

**Issue**: `/etc/mvgal/mvgal.conf` hardcoded in multiple places

**Impact**: Difficult to test alternate configurations

**Recommendation**:
- Use `MVGAL_CONFIG_PATH` environment variable
- Add config reload on SIGHUP

---

## 9. Deprecation and Cleanup Needed

### 9.1 Deprecated Driver References

**Issue**: AMDVLK referenced in documentation but discontinued

**Location**: `docs/DRIVER_INTEGRATION.md`

**Recommendation**:
- Focus on RADV/Mesa
- Remove AMDVLK claims

### 9.2 Unused Code Paths

**Issue**: Stubs with `*_disabled` comments

**Location**: Kernel module

**Recommendation**:
- Remove dead code or mark clearly experimental
- Use Kconfig for optional features

---

## 10. Priority Matrix for Technical Debt

| Priority | Debt Item | Effort | Risk |
|----------|-----------|--------|------|
| **Critical** | Kernel stubs (vendor ops, DMA-BUF) | High | Cannot claim cross-vendor support |
| **High** | Panic error handling | Medium | Silent failures in production |
| **High** | Memory leak potential in Vulkan layer | Medium | Resource exhaustion |
| **Medium** | Daemon consolidation | High | Maintenance complexity |
| **Medium** | KUnit tests | Medium | Bug detection |
| **Low** | Build system alignment | Low | Developer experience |
| **Low** | Documentation cleanup | Low | User confusion |