Deshab-OS/CODE/sdk/include/deshab/kernel_api.h

/* deshab/kernel_api.h - dkm_kernel_api ABI 单一定义来源
 *
 * 整合 CODE/UTSM/include/utsm/dkm.h 与 CODE/DKM/dkm_shared.h 的 ABI 结构体，
 * 消除驱动本地重复定义 dkm_kernel_api 的隐患（CONTRIBUTING.md 硬约束）。
 *
 * 约定：
 *   - 字段顺序/类型不可调整，UTSM 端按固定偏移填充。
 *   - 新增字段只允许追加在结构末尾（尾部追加保持 ABI 兼容）。
 *   - 结构体同时提供 typedef 名与 struct 标签，兼容两种引用方式。
 *
 * 偏移常量（供不便解引用 kernel_api 指针的场景使用，消除硬编码）：
 *   DSB_KAPI_OFF_NET    0x48   net API 指针
 *   DSB_KAPI_OFF_BLOCK  0xA8   block API 指针
 */
#ifndef DESHAB_KERNEL_API_H
#define DESHAB_KERNEL_API_H

#include "types.h"

#define DKM_KERNEL_API_VERSION 1u

/* ---- 网卡链路/能力标志 ---- */
#define DKM_NET_F_LINK_UP  (1u << 0)
#define DKM_NET_F_TX_READY (1u << 1)
#define DKM_NET_F_RX_READY (1u << 2)
#define DKM_NET_F_WIRELESS (1u << 3)

/* ---- WiFi 扫描加密类型 ---- */
#define DKM_NET_SEC_OPEN   0u
#define DKM_NET_SEC_WEP    1u
#define DKM_NET_SEC_WPA    2u
#define DKM_NET_SEC_WPA2   3u
#define DKM_NET_SEC_WPA3   4u

/* ---- log API ---- */
typedef struct dkm_log_api {
    void (*info)(const char *msg);
    void (*warn)(const char *msg);
    void (*error)(const char *msg);
    void (*panic)(const char *msg);
} dkm_log_api;

/* ---- DMA API ---- */
typedef struct dkm_dma_buffer {
    void *virt;
    u64   phys;
    u64   size;
} dkm_dma_buffer;

typedef struct dkm_dma_api {
    int (*alloc_pages)(u64 page_count, u64 alignment, u64 max_phys, dkm_dma_buffer *out);
} dkm_dma_api;

/* ---- net API ---- */
typedef struct dkm_net_scan_result {
    char ssid[33];
    u8   bssid[6];
    u8   channel;
    i8   rssi;
    u8   security;
} dkm_net_scan_result;

typedef struct dkm_net_device_desc {
    const char *name;
    u8   mac[6];
    u32  flags;
    void *ctx;
    int (*tx)(void *ctx, const void *packet, u32 length);
    int (*rx_poll)(void *ctx, void *buffer, u32 capacity, u32 *out_length);
    /* 无线扩展回调（有线驱动置 NULL，向后兼容）。 */
    int (*scan_start)(void *ctx);
    int (*scan_count)(void *ctx);
    int (*scan_result)(void *ctx, u32 n, dkm_net_scan_result *out);
    int (*is_wireless)(void *ctx);
} dkm_net_device_desc;

typedef struct dkm_net_stats {
    u64 tx_ok;
    u64 tx_err;
    u64 rx_ok;
    u64 rx_err;
    u64 rx_overflow;
    u64 link_changes;
} dkm_net_stats;

typedef struct dkm_net_api {
    int  (*register_device)(const dkm_net_device_desc *desc);
    u32  (*device_count)(void);
    int  (*device_info)(u32 index, void *out);
    int  (*tx)(u32 index, const void *packet, u32 length);
    int  (*rx_poll)(u32 index, void *buffer, u32 capacity, u32 *out_length);
    int  (*scan_start)(u32 index);
    int  (*scan_count)(u32 index);
    int  (*scan_result)(u32 index, u32 n, dkm_net_scan_result *out);
    int  (*is_wireless)(u32 index);
    /* 无线关联（dispatch 到 wlan 驱动回调；尾部追加，ABI 兼容。
     * 槽位布局必须与 UTSM include/utsm/net.h 镜像一致：
     * connect @0x48, disconnect @0x50, device_stats @0x58）。 */
    int  (*connect)(u32 index, const char *ssid, const char *password);
    int  (*disconnect)(u32 index);
    int  (*device_stats)(u32 index, dkm_net_stats *out);
} dkm_net_api;

/* ---- block API ---- */
typedef int (*dkm_block_read_fn)(void *ctx, u64 lba, u32 count, void *buffer);
typedef int (*dkm_block_write_fn)(void *ctx, u64 lba, u32 count, const void *buffer);

typedef struct dkm_block_device_desc {
    const char *name;
    u64 sector_size;
    u64 sector_count;
    void *ctx;
    int (*read)(void *ctx, u64 lba, u32 count, void *buffer);
    int (*write)(void *ctx, u64 lba, u32 count, const void *buffer);
} dkm_block_device_desc;

typedef struct dkm_block_api {
    int  (*register_device)(const dkm_block_device_desc *desc);
    u32  (*device_count)(void);
    int  (*read)(u32 index, u64 lba, u32 count, void *buffer);
    int  (*write)(u32 index, u64 lba, u32 count, const void *buffer);
    u64  (*sector_size)(u32 index);
    const char *(*device_name)(u32 index);
    int  (*set_write_fn)(u32 index, dkm_block_write_fn fn);
    u64  (*sector_count)(u32 index);  /* 0x38: tail-append, 与 utsm/block.h 同步 */
} dkm_block_api;

/* ---- MMIO / 页表 API ----
 * 与 UTSM/include/utsm/paging.h 布局一致。 */
typedef struct dkm_mmio_api {
    int  (*is_mapped)(u64 vaddr);   /* 返回 0=未映射；1=4K PTE；2=2M PDE；3=1G PDPTE */
    int  (*map_mmio)(u64 phys, u64 size);  /* 映射到 hhdm_offset + phys，返回 0 成功 */
    u64  (*cr3)(void);               /* 当前 CR3 物理地址（诊断用） */
} dkm_mmio_api;

/* ---- SAS-R0-PCQ 调度器服务表（M4/Phase7） ---- */
typedef struct utsm_sched_api {
    u64  (*uptime_ns)(void);
    void (*yield)(void);
    u32  (*current_task_slot)(void);
    int  (*task_create)(u32 process_slot, u32 priority, void (*entry)(void *), void *arg);
    void (*sleep_ms)(u32 ms);
} utsm_sched_api;

/* ---- D3: 内核按名导出表（kapi，只读） ---- */
typedef struct {
    const char *name;   /* 如 "log.info"、"dma.alloc_pages" */
    void *fn;
} dkm_kapi_entry;

typedef struct {
    u32 magic;          /* DKM_KAPI_MAGIC */
    u32 version;        /* DKM_KAPI_VERSION */
    u32 count;
    const dkm_kapi_entry *entries;
    int (*lookup)(const char *name, void **out_fn);   /* miss 返回 -1 */
} dkm_kapi_table;

#define DKM_KAPI_MAGIC   0x4b415049u  /* "KAPI" */
#define DKM_KAPI_VERSION 1u

/* ---- D6 万物互联: 双向服务总线（dkm_bus） ----
 * kapi 是内核→模块单向只读；bus 双向：模块在 driver_init 里注册
 * srv.* 服务，任何模块按名消费。失败策略：
 *   lookup miss = BUS-E04 panic（硬依赖=编程错误）
 *   probe  miss = 返回 -1（能力缺席=设计内双路径）
 * 设计文档: docs/RE/万物互联与服务总线设计.md */
struct dkm_driver_desc;

#define DKM_BUS_MAGIC    0x53425553u  /* "SBUS" */
#define DKM_BUS_VERSION  1u
#define DKM_BUS_MAX_SERVICES 128
#define DKM_BUS_MAX_NAME 48

#define DKM_BUS_F_KERNEL    1u  /* 内核注册，不可注销 */
#define DKM_BUS_F_NO_UNLOAD 2u  /* provider 声明 NO_UNLOAD，注销即 BUS-E05 */

typedef struct dkm_bus_service {
    char name[DKM_BUS_MAX_NAME];   /* NUL 终止；kern.* / srv. 前缀 */
    u32 version;                   /* 服务契约版本 */
    u32 flags;                     /* DKM_BUS_F_* */
    void *fn;                      /* 服务入口，签名由服务契约定义 */
    const struct dkm_driver_desc *provider;  /* NULL = 内核 */
} dkm_bus_service;

typedef struct dkm_bus_api {
    u32 magic;
    u32 version;
    /* 注册：模块只能 srv.*（kern.* 仅内核）；BUS-E01/E02/E03 全 panic，成功 0 */
    int (*register_service)(const char *name, u32 version, void *fn);
    /* 注销：仅 provider 本人；违规 BUS-E05 panic */
    int (*unregister_service)(const char *name);
    /* 必存在查找：miss → BUS-E04 panic */
    int (*lookup)(const char *name, void **out_fn, u32 *out_version);
    /* 可选探测：miss 返回 -1（调用方显式处理缺席） */
    int (*probe)(const char *name, void **out_fn, u32 *out_version);
    u32 (*count)(void);
    const dkm_bus_service *(*at)(u32 index);
} dkm_bus_api;

/* ---- kernel_api 主结构 ----
 * 字段顺序/类型不可调整 - UTSM 端按固定偏移填充。
 * DSK 以 api+0xA8 硬偏移读取 block，net_stack 以 api+0x48 读取 net。 */
typedef struct dkm_kernel_api {
    u32 version;
    u32 size;
    u64 feature_bits;

    const dkm_log_api *log;
    const void *mem;
    const void *utsm;
    const void *irq;
    const void *pci;
    const dkm_dma_api *dma;
    const void *vfs;
    const dkm_net_api *net;
    const void *timer;
    const void *drr;

    const void *rsdp_address;   /* ACPI RSDP physical address */
    const void *fb_address;     /* framebuffer base */
    u64 fb_width;
    u64 fb_height;
    u64 fb_pitch;
    u16 fb_bpp;
    const void *boot_modules_response;  /* limine_module_response* */
    int (*irq_register)(u8 irq, void *handler);  /* kernel irq_register */
    u64 hhdm_offset;                               /* physical -> virtual */
    const dkm_block_api *block;                    /* block provider registry */
    const dkm_mmio_api *mmio;                      /* 页表/高位 MMIO 映射服务 */
    /* -- 新增字段只允许追加在末尾 -- */
    void *(*mm_map_mmio)(u64 phys, u64 size);      /* MMIO 独立窗口映射（PCD|PWT），失败返回 0 */
    void (*mm_unmap_mmio)(void *virt, u64 size);   /* 解除 MMIO 独立窗口映射 */
    /* B7 阶段2: LAPIC EOI 钩子注册（apic.drv LAPIC 接管时调用）。 */
    void (*register_apic_eoi)(void (*eoi_fn)(void));
    /* B7 阶段3: 动态 IDT 向量分配器（MSI/MSI-X 用），池 0x40-0xDF。 */
    int  (*irq_vector_alloc)(void);
    void (*irq_vector_free)(int vector);
    /* M4/Phase7-8: 调度器服务（task_create/uptime/sleep/yield）。 */
    const utsm_sched_api *sched;
    /* D3: 内核按名导出表（只读）。 */
    const dkm_kapi_table *kapi;
    /* D6 万物互联: 双向服务总线（kern.* 与 srv.* 按名注册-消费）。 */
    const dkm_bus_api *bus;
} dkm_kernel_api;

/* ---- kernel_api 字段偏移常量（消除散落的硬编码偏移） ----
 * 供不便通过结构体解引用的场景（如早期 boot context 解析）使用。
 * 常规代码应直接通过 api->net / api->block 访问。 */
#define DSB_KAPI_OFF_NET    0x48u   /* const dkm_net_api *net */
#define DSB_KAPI_OFF_BLOCK  0xA8u   /* const dkm_block_api *block */

#endif /* DESHAB_KERNEL_API_H */