Manifiesto de Arquitectura hwbus-io

Este documento define la estructura de directorios, la organización de las cabeceras y las responsabilidades del código dentro del proyecto hwbus-io.

Visión General de la Arquitectura

El proyecto está diseñado bajo el principio de que el núcleo principal es un controlador de dispositivo del kernel de Linux (driver module). Por esta razón, el código reside de forma predeterminada en el espacio de kernel, mientras que el espacio de usuario se aísla explícitamente dentro de subdirectorios denominados user/.

  • Espacio de Kernel (Driver Core): Implementa la lógica del controlador, acceso a hardware y exposición de interfaces vía sysfs.

  • Espacio de Usuario (Userland/LTP): Proporciona utilidades y herramientas auxiliares para facilitar la ejecución de pruebas automatizadas (Linux Test Project) y diagnóstico.

Estructura del Árbol de Directorios

hwbus-io/
├── include/
│   ├── hwbus-io.h            # Interfaz pública / IOCTL del driver
│   ├── sysfs_driver.h        # Declaraciones nativas del driver para exponencia en sysfs
│   ├── sysfs_pci.h           # Estructuras y macros PCI para el driver
│   └── user/
│       ├── hwbus_error.h     # Cabecera de errores exclusiva para espacio de usuario
│       └── sysfs_utils.h     # Helpers POSIX para herramientas de usuario y tests
│
└── src/
    ├── core/                 # Lógica genérica y utilidades
    │   ├── source.c          # Abstracciones auxiliares genéricas
    │   └── user/             # Implementación C para espacio de usuario (LTP, CLI)
    │       ├── hwbus_error.c
    │       └── sysfs_utils.c
    │
    └── driver/               # CÓDIGO DEL CONTROLADOR (Infraestructura de estudio)
        └── sysfs_driver.c    # Implementación de callbacks y nodos sysfs

Definición de Directorios y Componentes

1. Directorio include/

  • Raíz de include/: Ámbito exclusivo del controlador. Contiene cabeceras que utilizan tipos del kernel de Linux (<linux/...>). No deben incluirse cabeceras de la biblioteca C estándar (glibc).

  • Subdirectorio include/user/: Alojamiento exclusivo para la infraestructura de espacio de usuario.

    • hwbus_error.h: Definición de la interfaz de traducción de errores mediante hwbus_strerror() para espacio de usuario.

    • sysfs_utils.h: Declaración de utilidades POSIX (sysfs_read_*, sysfs_build_path) para inspección de /sys desde tests.

2. Directorio src/

  • src/core/: Almacena la lógica genérica y funciones auxiliares transversales (source.c).

  • src/core/user/: Contiene la implementación en C de las librerías auxiliares de espacio de usuario (hwbus_error.c, sysfs_utils.c). Se compila usando la cadena de herramientas estándar POSIX/glibc.

  • src/driver/: Contiene el código fuente del controlador del kernel relativo a la infraestructura de estudio (PCI, NVMe, Net).

    • Implementa los callbacks show/store y registra los atributos de sysfs en el módulo (sysfs_driver.c).

    • Regla: Queda prohibido hacer #include de archivos ubicados en include/user/.

3. Soporte y Pruebas

  • Scripts/: Scripts de shell para la orquestación del flujo de CI/CD remoto, firma con certificados Secure Boot (kmod-sign-file) y gestión de logs.

  • tests/: Entorno de pruebas y arnés Makefile para la compilación de módulos de test independientes (ej. hello.ko).

Reglas de Estilo y Compilación

  1. Alineación de Punteros: El código C en espacio de kernel y usuario sigue la guía de estilo oficial del Kernel de Linux (Linux Kernel Coding Style). Los punteros se alinean con la variable (char *buf) y no con el tipo.

  2. Aislamiento de Dependencias: Las fuentes bajo src/driver/ se compilan exclusivamente mediante Kbuild contra las cabeceras del kernel objetivo. Las fuentes bajo src/core/user/ se compilan con la biblioteca estándar de C.