Storport SD Controller架构（三）：其他关键架构设计要点

Windows驱动
,

Storport SD Controller 架构（三）：其他关键架构设计要点

日期: 2026-03-21
系列: Storport SD Controller 架构解析
适用: Windows 驱动开发者、存储系统工程师

1. DMA 架构设计

1.1 DMA 子系统架构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
┌─────────────────────────────────────────────────────────────────────┐
│                    DMA 子系统架构                                       │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌───────────────────────────────────────────────────────────────┐   │
│  │                    DMA Transcation API Layer                      │   │
│  │                                                                │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │   │
│  │  │  DMA API   │  │  DMA API   │  │  DMA API   │        │   │
│  │  │  (Alloc)   │  │  (Map)     │  │  (Unmap)   │        │   │
│  │  └─────────────┘  └─────────────┘  └─────────────┘        │   │
│  └───────────────────────────────────────────────────────────────┘   │
│                              │                                        │
│                              ▼                                        │
│  ┌───────────────────────────────────────────────────────────────┐   │
│  │                    DMA Transfer Layer                            │   │
│  │                                                                │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │   │
│  │  │   SDMA     │  │  ADMA2     │  │  ADMA3     │        │   │
│  │  │  (简单DMA) │  │ (高级DMA2) │  │ (高级DMA3) │        │   │
│  │  └─────────────┘  └─────────────┘  └─────────────┘        │   │
│  └───────────────────────────────────────────────────────────────┘   │
│                              │                                        │
│                              ▼                                        │
│  ┌───────────────────────────────────────────────────────────────┐   │
│  │                    Host Controller Layer                        │   │
│  │                                                                │   │
│  │  ┌─────────────────────────────────────────────────────┐    │   │
│  │  │  SD Host Controller (PCIe BAR0/BAR1)                │    │   │
│  │  │                                                      │    │   │
│  │  │  ┌──────────┐  ┌──────────┐  ┌──────────┐        │    │   │
│  │  │  │ DMA Engine│  │ SDMA Reg │  │ ADMA Reg │        │    │   │
│  │  │  └──────────┘  └──────────┘  └──────────┘        │    │   │
│  │  └─────────────────────────────────────────────────────┘    │   │
│  └───────────────────────────────────────────────────────────────┘   │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

1.2 DMA 缓冲区管理

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
// basic.h
typedef struct dma_buf_s {
    void *va;           // 虚拟地址
    phy_addr_t pa;      // 物理地址
    u32 len;            // 缓冲区长度
    u32 align;          // 对齐要求
} dma_buf_t;

// DMA 描述符缓冲区
typedef struct dma_desc_buf_s {
    void *va;           // 描述符表虚拟地址
    phy_addr_t pa;      // 描述符表物理地址
    u32 len;             // 描述符表长度
    u32 align;           // 对齐要求
    u32 desc_cnt;        // 描述符数量
} dma_desc_buf_t;

// 设备扩展中的 DMA 资源
typedef struct {
    // Uncached Extension (用于 Descriptor Table)
    dma_desc_buf_t dma_buff;

    // Scatter-Gather List
    void *sgl_va;
    phy_addr_t sgl_pa;
} bht_dma_resources_t;

1.3 IOVA 与 PA 转换

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
// winapi.c - DMA 地址管理
static phy_addr_t os_get_phy_addr32l(phy_addr_t addr)
{
    // 取低 32 位
    return (phy_addr_t)(addr.QuadPart & 0xFFFFFFFF);
}

static phy_addr_t os_get_phy_addr32h(phy_addr_t addr)
{
    // 取高 32 位
    return (phy_addr_t)((addr.QuadPart >> 32) & 0xFFFFFFFF);
}

// 获取 SRB DataBuffer 的物理地址
phy_addr_t os_get_srb_buffer_phy(bht_dev_ext_t *pdx, srb_ext_t *srb_ext)
{
    PVOID virtual_addr = srb_ext->req.srb_buff;
    ULONG length;

    // ★ 关键: 使用 StorPortGetPhysicalAddress 获取地址
    // Storport 会处理 IOMMU 映射
    STOR_PHYSICAL_ADDRESS pa;

    pa = StorPortGetPhysicalAddress(
        pdx,
        srb_ext->psrb,       // SRB 上下文
        virtual_addr,           // 数据缓冲区虚拟地址
        &length                // 返回长度
    );

    return pa;
}

1.4 Scatter-Gather List 处理

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
// tagqueue/tqadma2.c - ADMA2 描述符构建
void tq_adma2_build_desc_table(
    tag_queue_t *queue,
    node_t *node
)
{
    srb_ext_t *srb_ext = node->srb_ext;
    u32 sg_len = srb_ext->req.srb_sg_len;

    // 获取 Scatter-Gather List
    PSGLIST_GROW buffer_array[MAX_SGL_RANGE];
    u32 array_len = StorPortGetScatterGatherList(
        pdx,
        srb_ext->psrb,
        buffer_array,
        sizeof(buffer_array)
    );

    // 构建 ADMA2 描述符
    adma2_desc_t *desc = (adma2_desc_t *)queue->dma_desc_buf.va;
    u32 desc_idx = 0;

    for(u32 i = 0; i < sg_len; i++)
    {
        // 设置描述符
        desc[desc_idx].addr = buffer_array[i].Address;
        desc[desc_idx].len = buffer_array[i].Length;
        desc[desc_idx].type = ADMA2_TYPE_TRAN;  // 数据传输
        desc[desc_idx].attr = ADMA2_ATTR_VALID;

        // 最后一个描述符
        if(i == sg_len - 1)
            desc[desc_idx].attr |= ADMA2_ATTR_END;

        desc_idx++;
    }

    // 写入 ADMA2 地址寄存器
    sdhci_writel(host, SDHCI_ADMA_ADDRESS,
                  os_get_phy_addr32l(queue->dma_desc_buf.pa));
}

2. 电源管理架构

2.1 电源状态定义

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
// basic.h
typedef enum {
    // 设备电源状态
    PM_STATE_D0 = 0,         // 完全工作
    PM_STATE_D1,              // D1 (一般不用)
    PM_STATE_D2,              // D2 (一般不用)
    PM_STATE_D3_HOT,          // D3 (有电)
    PM_STATE_D3_COLD,         // D3 (完全断电)
    PM_STATE_RTD3,           // Runtime D3 (运行时低功耗)

    // 系统电源状态
    PM_STATE_S0IX,            // Modern Standby
    PM_STATE_S3,              // 休眠 (Suspend to RAM)
    PM_STATE_S4,              // 休眠 (Suspend to Disk)
    PM_STATE_S5,              // 关机
} e_pm_state;

// 电源管理结构
typedef struct {
    bool rtd3_en;                    // Runtime D3 使能
    e_pm_state current_state;           // 当前状态
    e_pm_state target_state;            // 目标状态
    bool d3_entered;                  // D3 已进入
    bool s3s4_entered;                // S3/S4 已进入
    bool d3_cold_supported;           // D3Cold 支持
    u32 idle_timeout_ms;              // 空闲超时 (ms)
} pm_state_t;

2.2 RTD3 (Runtime D3) 状态机

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
┌─────────────────────────────────────────────────────────────────────┐
│                    Runtime D3 状态机                                        │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │                         Idle Timer 超时                              │   │
│  │  (adapter_idle_timeout)                                         │   │
│  └──────────────────────────────────────────────────────────────┘   │
│                              │                                        │
│                              ▼                                        │
│  ┌─────────────┐  PoFx 回调  ┌─────────────────┐                     │
│  │    D0      │────────────►│  PoFxIdle()     │                     │
│  │  (工作)    │             │  (准备进入空闲)   │                     │
│  └─────────────┘             └─────────────────┘                     │
│                                    │                               │
│                                    ▼                               │
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │                    req_enter_d3()                                   │   │
│  │                         │                                          │   │
│  │  1. 完成所有 SRB 请求                                         │   │
│  │  2. 停止卡时钟                                                │   │
│  │  3. 关闭卡电源                                                │   │
│  │  4. 保存控制器状态                                            │   │
│  └──────────────────────────────────────────────────────────────┘   │
│                                    │                               │
│                                    ▼                               │
│                           ┌─────────────────┐                        │
│                           │     D3/RTD3     │                        │
│                           │    (低功耗)      │                        │
│                           └─────────────────┘                        │
│                                    │                               │
│                                    │ PoFx 回调                      │
│                                    │ PoFxWake()                    │
│                                    ▼                               │
│                           ┌─────────────────┐                        │
│                           │  req_enter_d0()  │                        │
│                           │  (唤醒恢复)      │                        │
│                           └─────────────────┘                        │
│                                    │                               │
│                                    ▼                               │
│                           ┌─────────────────┐                        │
│                           │    Resume       │                        │
│                           │  (恢复卡状态)    │                        │
│                           └─────────────────┘                        │
│                                    │                               │
│                                    ▼                               │
│                              ┌─────────┐                            │
│                              │   D0    │                            │
│                              └─────────┘                            │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

2.3 PoFx 组件电源管理

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
// winscsientry.c - PoFx 组件定义
void init_pofx_component(bht_dev_ext_t *pdx)
{
    // 组件 0: 主存储组件
    pdx->os.AdptPoFxDevice.Components[0].Version = STOR_POFX_COMPONENT_VERSION_V1;
    pdx->os.AdptPoFxDevice.Components[0].Size = STOR_POFX_COMPONENT_SIZE;
    pdx->os.AdptPoFxDevice.Components[0].FStateCount = 1;  // 只有 F0
    pdx->os.AdptPoFxDevice.Components[0].DeepestWakeableFState = 0;  // F0 可唤醒
    pdx->os.AdptPoFxDevice.Components[0].Id = STORPORT_POFX_ADAPTER_GUID;

    // F0 状态配置
    pdx->os.AdptPoFxDevice.Components[0].FStates[0].Version =
        STOR_POFX_COMPONENT_IDLE_STATE_VERSION_V1;
    pdx->os.AdptPoFxDevice.Components[0].FStates[0].Size =
        STOR_POFX_COMPONENT_IDLE_STATE_SIZE;
    pdx->os.AdptPoFxDevice.Components[0].FStates[0].TransitionLatency = 0;
    pdx->os.AdptPoFxDevice.Components[0].FStates[0].ResidencyRequirement = 0;
}

// PoFx 空闲回调
void StorPortPoFxIdleCallback(
    PVOID DeviceExtension,
    PSTOR_POFX_DEVICE PowerDevice,
    PSTOR_POFX_COMPONENT Component
)
{
    bht_dev_ext_t *pdx = (bht_dev_ext_t *)DeviceExtension;

    DbgInfo(MODULE_OS_ENTRY, FEATURE_PM_TRACE, NOT_TO_RAM,
             "PoFxIdleCallback enter\n");

    // 进入低功耗状态
    req_enter_d3(pdx);

    DbgInfo(MODULE_OS_ENTRY, FEATURE_PM_TRACE, NOT_TO_RAM,
             "PoFxIdleCallback exit\n");
}

// PoFx 唤醒回调
void StorPortPoFxWakeCallback(
    PVOID DeviceExtension,
    PSTOR_POFX_DEVICE PowerDevice,
    PSTOR_POFX_COMPONENT Component
)
{
    bht_dev_ext_t *pdx = (bht_dev_ext_t *)DeviceExtension;

    DbgInfo(MODULE_OS_ENTRY, FEATURE_PM_TRACE, NOT_TO_RAM,
             "PoFxWakeCallback enter\n");

    // 恢复到工作状态
    req_enter_d0(pdx);

    DbgInfo(MODULE_OS_ENTRY, FEATURE_PM_TRACE, NOT_TO_RAM,
             "PoFxWakeCallback exit\n");
}

3. 错误恢复机制

3.1 错误分类与处理

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// host/cardcommon.h
typedef enum {
    // 命令错误
    CMD_ERR_NONE = 0,
    CMD_ERR_TIMEOUT,
    CMD_ERR_CRC,
    CMD_ERR_END_BIT,
    CMD_ERR_DATA_TIMEOUT,
    CMD_ERR_DATA_CRC,
    CMD_ERR Busy_TIMEOUT,  // 注意: 拼写错误 'Busy'
    CMD_ERR_AUTO_CMD12,

    // 数据错误
    DATA_ERR_NONE,
    DATA_ERR_TIMEOUT,
    DATA_ERR_CRC,
    DATA_ERR_EMMC_SWITCH,

    // 卡错误
    CARD_ERR_NOT_PRESENT,
    CARD_ERR_INIT_FAILED,
    CARD_ERR_SWITCH_FAILED,
    CARD_ERR_LOCK_UNLOCK_FAILED,
} e_card_error;

3.2 错误恢复状态机

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
┌─────────────────────────────────────────────────────────────────────┐
│                    错误恢复状态机                                         │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  正常传输                                                           │
│      │                                                             │
│      │ error_occurred()                                           │
│      ▼                                                             │
│  ┌─────────────┐                                                  │
│  │  ERROR_1    │ ←── 第一次错误 (可恢复)                           │
│  └─────────────┘                                                  │
│      │                                                             │
│      │ retry_count < MAX_RETRY                                    │
│      ▼                                                             │
│  ┌─────────────┐                                                  │
│  │  RETRY_1    │ ←── 重试传输                                    │
│  └─────────────┘                                                  │
│      │                                                             │
│      │ error_occurred()                                           │
│      ▼                                                             │
│  ┌─────────────┐                                                  │
│  │  ERROR_2    │ ←── 第二次错误                                   │
│  └─────────────┘                                                  │
│      │                                                             │
│      │ is_recoverable_error()                                     │
│      ▼                                                             │
│  ┌─────────────┐                                                  │
│  │  RECOVERY   │ ←── 执行恢复流程                                 │
│  └─────────────┘                                                  │
│      │                                                             │
│      │ 1. 重新初始化卡                                            │
│      │ 2. 恢复卡状态                                              │
│      │ 3. 重试传输                                                │
│      │                                                             │
│      ▼                                                             │
│  ┌─────────────┐                                                  │
│  │  SUCCESS    │ ←── 恢复成功                                     │
│  └─────────────┘                                                  │
│      │                                                             │
│      │ error_occurred()                                           │
│      ▼                                                             │
│  ┌─────────────┐                                                  │
│  │   FAILED    │ ←── 最终失败                                    │
│  └─────────────┘                                                  │
│      │                                                             │
│      ▼                                                             │
│  完成 SRB (错误状态)                                                │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

3.3 错误恢复流程实现

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
// card/cardcommon.c
bool card_recovery_flow(sd_card_t *card, e_card_error error)
{
    int retry = 0;
    bool success = FALSE;

    DbgInfo(MODULE_OS_ENTRY, FEATURE_ERROR_TRACE, NOT_TO_RAM,
             "card_recovery_flow: error=%d\n", error);

    while(retry < MAX_RECOVERY_RETRY)
    {
        // 1. 关闭卡电源
        card_power_off(card, TRUE);

        // 2. 等待一段时间
        os_msleep(card->host, 100);

        // 3. 重新上电
        card_power_on(card);

        // 4. 重新初始化
        success = card_init(card, 1, FALSE);
        if(success)
        {
            DbgInfo(..., "card_recovery success at retry %d\n", retry);
            return TRUE;
        }

        retry++;
    }

    DbgErr("card_recovery_flow: failed after %d retries\n", retry);
    return FALSE;
}

// 完整错误处理
void handle_transfer_error(bht_dev_ext_t *pdx, node_t *node)
{
    srb_ext_t *srb_ext = node->srb_ext;
    e_card_error error = node->error;

    // 1. 检查是否可恢复
    if(!is_recoverable_error(error))
    {
        // 不可恢复错误
        complete_srb_with_error(pdx, srb_ext, error);
        return;
    }

    // 2. 检查重试次数
    if(node->retry_count >= MAX_RETRY)
    {
        DbgErr("max retry reached\n");
        complete_srb_with_error(pdx, srb_ext, error);
        return;
    }

    // 3. 执行恢复
    node->retry_count++;

    if(card_recovery_flow(&pdx->card, error))
    {
        // 4. 重新构建并执行传输
        tag_rebuild_io(pdx, node);
        tag_start_io(pdx, node);
    }
    else
    {
        complete_srb_with_error(pdx, srb_ext, error);
    }
}

4. 平台抽象层 (OSAL)

4.1 平台抽象设计

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
┌─────────────────────────────────────────────────────────────────────┐
│                    平台抽象层 (OSAL) 设计                                │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌───────────────────────────────────────────────────────────────┐   │
│  │                    Application Layer                              │   │
│  │  (业务逻辑 - 独立于平台)                                       │   │
│  │                                                                │   │
│  │  reqmng.c  card.c  host.c  tagqueue.c                       │   │
│  └───────────────────────────────────────────────────────────────┘   │
│                              │                                        │
│                              ▼                                        │
│  ┌───────────────────────────────────────────────────────────────┐   │
│  │                    OS Abstraction Layer (OSAL)                  │   │
│  │                                                                │   │
│  │  ┌─────────────────┐         ┌─────────────────┐             │   │
│  │  │  windows_os/   │         │   linux_os/    │             │   │
│  │  │  (Windows 实现) │         │  (Linux 实现)   │             │   │
│  │  │                 │         │                 │             │   │
│  │  │  winapi.c       │         │  linux_api.c   │             │   │
│  │  │  winmem.c       │         │  linux_mem.c   │             │   │
│  │  │  winintr.c      │         │  linux_intr.c  │             │   │
│  │  │  winthread.c    │         │  linux_thread.c │             │   │
│  │  └─────────────────┘         └─────────────────┘             │   │
│  └───────────────────────────────────────────────────────────────┘   │
│                              │                                        │
│                              ▼                                        │
│  ┌───────────────────────────────────────────────────────────────┐   │
│  │                    Hardware / Platform                         │   │
│  │                                                                │   │
│  │  Windows Kernel (Storport)        Linux Kernel (SCSI/MMC)      │   │
│  │           │                               │                       │   │
│  │           ▼                               ▼                       │   │
│  │  PCIe Device                     PCIe Device                   │   │
│  └───────────────────────────────────────────────────────────────┘   │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

4.2 统一 API 接口

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
// osapi.h - 统一的 OS 抽象接口

// 内存操作
void* os_malloc(u32 size);
void  os_free(void *ptr);
void  os_memcpy(void *dst, const void *src, u32 len);
void  os_memset(void *ptr, int value, u32 len);

// 线程操作
bool  os_create_thread(void *pdx, thread_t *thr, void *param, thread_cb_t func);
void  os_stop_thread(thread_t *thr);
bool  os_thread_should_terminate(thread_t *thr);
void  os_sleep(bht_dev_ext_t *pdx, u32 ms);

// 事件操作
bool  os_init_event(bht_dev_ext_t *pdx, event_t *evt);
void  os_set_event(event_t *evt);
void  os_wait_event(event_t *evt, u32 timeout_ms);
void  os_clear_event(event_t *evt);

// 定时器操作
bool  os_init_timer(bht_dev_ext_t *pdx, timer_t *timer, timer_cb_t cb, void *arg);
void  os_start_timer(timer_t *timer, u32 ms, bool periodic);
void  os_stop_timer(timer_t *timer);

// DMA 操作
bool  os_alloc_dma_buffer(bht_dev_ext_t *pdx, dma_buf_t *buf, u32 size);
void  os_free_dma_buffer(bht_dev_ext_t *pdx, dma_buf_t *buf);

// 中断操作
void  os_enable_irq(irq_t *irq);
void  os_disable_irq(irq_t *irq);
void  os_request_irq(irq_t *irq, irq_handler_t handler);

4.3 Windows 特定实现

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
// windows_os/winapi.c

// Windows 线程创建
bool os_create_thread(
    void *pdx,
    thread_t *thr,
    void *param,
    thread_cb_t func
)
{
    OBJECT_ATTRIBUTES attr;
    NTSTATUS status;

    PDEVICE_OBJECT adpObj = dev_ext_to_dev_obj(pdx);
    InitializeObjectAttributes(&attr, NULL, OBJ_KERNEL_HANDLE, NULL, NULL);

    // ★ 使用 IoCreateSystemThread 创建系统线程
    status = IoCreateSystemThread(
        adpObj,
        &thr->threadHandle,
        THREAD_ALL_ACCESS,
        &attr,
        NULL,
        NULL,
        (PKSTART_ROUTINE)func,
        (PVOID)param
    );

    return (status == STATUS_SUCCESS);
}

// Windows 事件等待
void os_wait_event(event_t *evt, u32 timeout_ms)
{
    LARGE_INTEGER timeout;
    timeout.QuadPart = -((LARGE_INTEGER)timeout_ms * 10000);  // 转为相对时间

    // ★ 使用 KeWaitForSingleObject
    KeWaitForSingleObject(
        evt->kevent,
        Executive,
        KernelMode,
        FALSE,           // 不是警报等待
        &timeout         // 超时
    );
}

5. 配置管理系统

5.1 配置项结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
// cfgmng.h
typedef struct {
    // 芯片相关配置
    cfg_card_item_t card_item;       // 卡配置
    cfg_host_item_t host_item;        // Host 配置
    cfg_issue_fix_item_t issue_fix_item;  // Issue 修复
    cfg_feature_item_t feature_item;   // 功能开关
    cfg_timer_item_t timer_item;      // 定时器配置
    cfg_timeout_item_t timeout_item;   // 超时配置
    cfg_fpga_item_t fpga_item;       // FPGA 配置
    cfg_driver_item_t driver_item;    // 驱动配置
    cfg_pcr_item_t pcr_item;         // PCR 配置
    u32 dmdn_tbl[MAX_FREQ_SUPP];    // 频率表
} cfg_item_t;

// Host 配置项
typedef struct {
    // DMA 模式
    cfg_dma_mode_setting_t test_dma_mode_setting;

    // 时钟配置
    u32 max_clock;                   // 最大时钟频率
    u32 default_clock;               // 默认时钟频率

    // 电压配置
    u32 voltage_18: 1;             // 1.8V 支持
    u32 voltage_33: 1;             // 3.3V 支持

    // 功能开关
    u32 enable_rtd3: 1;            // RTD3 使能
    u32 enable_aes: 1;             // AES 加密
    u32 enable_thermal: 1;         // 热管理
} cfg_host_item_t;

5.2 配置加载流程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
// cfgmng.c - 配置加载
bool cfg_load_from_registry(bht_dev_ext_t *pdx)
{
    PUCHAR buffer;
    ULONG buffer_size;
    CHAR key_path[256];

    // 构建注册表路径
    strcpy(key_path, "Parameters");

    // 读取 DMA 模式配置
    buffer_size = sizeof(cfg_dma_mode_setting_t);
    buffer = StorPortAllocateRegistryBuffer(pdx, &buffer_size);

    if(StorPortRegistryReadAdapterKey(
        pdx,
        key_path,
        "test_dma_mode_setting",
        REG_DWORD,
        &buffer,
        &buffer_size
    ) == STOR_STATUS_SUCCESS)
    {
        pdx->cfg->host_item.test_dma_mode_setting.dma_mode = *(u32*)buffer;
    }

    // 读取其他配置...
    return TRUE;
}

5.3 INF 配置示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
; bhtsddr.inf

[DriverInstallx64.NT.Services]
AddService = bhtsddr, 0x00000002, DriverServicex64

[DriverServicex64]
ServiceType    = 1
StartType      = 3
ErrorControl   = 1
ImagePath      = \SystemRoot\System32\drivers\bhtsddr.sys
AddReg         = Parameters_AddReg

[Parameters_AddReg]
; DMA 模式配置
HKR,Parameters,test_dma_mode_setting,0x00010001,0x00000005  ; ADMA3 模式

; RTD3 配置
HKR,Parameters,RTD3Enable,0x00010001,1  ; 使能 RTD3

; 时钟配置
HKR,Parameters,MaxClock,0x00010001,200000000  ; 200MHz

; DMA Remapping 兼容
HKR,Parameters,DmaRemappingCompatible,0x00010001,1

6. 热管理 (Thermal Management)

6.1 热管理架构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// card/thermal.h
typedef struct {
    bool enabled;                    // 热管理使能
    u8 current_temp;                 // 当前温度
    u8 warning_threshold;           // 警告阈值
    u8 critical_threshold;           // 临界阈值
    u32 throttle_interval_ms;       // 节流间隔
    u8 current_throttle;            // 当前节流级别
} thermal_t;

// 节流级别
typedef enum {
    THROTTLE_NONE = 0,              // 无节流
    THROTTLE_LOW,                   // 低节流 (降低频率)
    THROTTLE_MEDIUM,               // 中节流
    THROTTLE_HIGH,                 // 高节流
    THROTTLE_CRITICAL              // 临界 (停止传输)
} e_throttle_level;

6.2 热管理策略

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
// card/thermal.c
void thermal_check_and_throttle(thermal_t *thermal)
{
    // 读取当前温度 (从传感器)
    thermal->current_temp = thermal_read_temperature(thermal);

    // 检查阈值
    if(thermal->current_temp >= thermal->critical_threshold)
    {
        // 临界温度 - 停止所有传输
        thermal->current_throttle = THROTTLE_CRITICAL;
        thermal_critical_action(thermal);
    }
    else if(thermal->current_temp >= thermal->warning_threshold)
    {
        // 警告温度 - 降低频率
        thermal->current_throttle = THROTTLE_HIGH;
        thermal_reduce_clock(thermal);
    }
    else
    {
        // 正常温度 - 恢复频率
        thermal->current_throttle = THROTTLE_NONE;
        thermal_restore_clock(thermal);
    }
}

void thermal_critical_action(thermal_t *thermal)
{
    // 1. 停止新的 I/O 请求
    stop_new_requests();

    // 2. 等待当前请求完成
    wait_for_pending_requests();

    // 3. 关闭卡
    card_power_off();

    // 4. 记录日志
    DbgErr("CRITICAL TEMPERATURE: %d°C, stopping card\n",
            thermal->current_temp);
}

7. 调试与日志系统

7.1 调试宏定义

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
// util/debug.h

// 模块枚举
typedef enum {
    MODULE_OS_ENTRY = 0,
    MODULE_OS_API,
    MODULE_PM_TRACE,
    MODULE_SCSICMD_TRACE,
    MODULE_THREAD_TRACE,
    MODULE_TRANS_TRACE,
    MODULE_ERROR_TRACE,
    MODULE_HOST_TRACE,
    MODULE_CARD_TRACE,
    MODULE_DUMP,
    MODULE_MAX
} e_module;

// 特性枚举
typedef enum {
    FEATURE_DRIVER_INIT = 0,
    FEATURE_PM_TRACE,
    FEATURE_SCSICMD_TRACE,
    FEATURE_THREAD_TRACE,
    FEATURE_TRANS_TRACE,
    FEATURE_ERROR_TRACE,
    // ...
    FEATURE_MAX
} e_feature;

// 调试宏
#ifdef DEBUG
    #define DbgInfo(module, feature, dest, fmt, ...) \
        debug_print(module, feature, dest, "[%s] " fmt "\n", \
            __FUNCTION__, ##__VA_ARGS__)

    #define DbgErr(fmt, ...) \
        debug_print(MODULE_OS_ENTRY, FEATURE_ERROR_TRACE, NOT_TO_RAM, \
            "[ERROR][%s:%d] " fmt "\n", __FUNCTION__, __LINE__, ##__VA_ARGS__)
#else
    #define DbgInfo(module, feature, dest, fmt, ...)
    #define DbgErr(fmt, ...)
#endif

// 输出目标
#define NOT_TO_RAM    0  // 不写入 RAM (仅实时输出)
#define TO_RAM        1  // 写入 RAM 缓冲区

7.2 调试 RAM 缓冲区

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
// util/debug.c
typedef struct {
    u32 magic;              // 魔数 0xDEADBEEF
    u32 size;               // 缓冲区大小
    u32 head;               // 写指针
    u32 count;              // 记录数
    char data[DEBUG_BUF_SIZE]; // 调试数据
} debug_buf_t;

// 调试缓冲区初始化
void DbgRamInit(void)
{
    debug_buf_t *buf = (debug_buf_t *)DEBUG_BUF_ADDR;

    buf->magic = 0xDEADBEEF;
    buf->size = DEBUG_BUF_SIZE;
    buf->head = 0;
    buf->count = 0;
}

// 写入调试信息
void debug_print(
    e_module module,
    e_feature feature,
    bool to_ram,
    const char *fmt,
    ...
)
{
    char line[DEBUG_LINE_SIZE];
    va_list args;

    va_start(args, fmt);
    vsnprintf(line, sizeof(line), fmt, args);
    va_end(args);

    // 输出到调试器 (DbgPrint)
    DbgPrint("%s", line);

    // 可选: 写入 RAM 缓冲区
    if(to_ram)
    {
        debug_buf_t *buf = (debug_buf_t *)DEBUG_BUF_ADDR;
        if(buf->magic == 0xDEADBEEF)
        {
            u32 len = strlen(line);
            if(buf->head + len < buf->size)
            {
                memcpy(&buf->data[buf->head], line, len);
                buf->head += len;
                buf->count++;
            }
        }
    }
}

8. 总结

8.1 架构设计要点总结

设计要点 实现方式 优势
分层架构 OSAL 抽象层 跨平台支持
DMA 传输 SDMA/ADMA2/ADMA3 灵活适配不同场景
电源管理 PoFx + RTD3 低功耗待机
错误恢复 多级重试 + 状态恢复 高可靠性
配置管理 注册表/INF 灵活定制
调试系统 RAM 缓冲区 + 调试宏 可追溯性
热管理 温度监控 + 节流 安全性

8.2 核心数据结构关系

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
┌─────────────────────────────────────────────────────────────────────┐
│                    核心数据结构关系图                                      │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌───────────────────────────────────────────────────────────────┐   │
│  │  bht_dev_ext_t (设备扩展 - 根结构)                            │   │
│  │       │                                                     │   │
│  │       ├──► pm_state_t      ←─── 电源管理状态                │   │
│  │       ├──► tag_queue_t    ←─── 标签队列                     │   │
│  │       ├──► os_struct      ←─── OS 抽象                     │   │
│  │       ├──► sd_host_t      ←─── Host 控制器                 │   │
│  │       ├──► sd_card_t      ←─── 存储卡                      │   │
│  │       └──► cfg_item_t     ←─── 配置项                      │   │
│  └───────────────────────────────────────────────────────────────┘   │
│                                                                      │
│  ┌───────────────────────────────────────────────────────────────┐   │
│  │  srb_ext_t (SRB 扩展 - 请求上下文)                           │   │
│  │       │                                                     │   │
│  │       ├──► request_t       ←─── 请求信息                    │   │
│  │       ├──► dma_buf_t      ←─── DMA 缓冲区                  │   │
│  │       ├──► trans_context_t ←── 传输上下文                 │   │
│  │       └──► node_t*        ←── 关联的标签节点              │   │
│  └───────────────────────────────────────────────────────────────┘   │
│                                                                      │
│  ┌───────────────────────────────────────────────────────────────┐   │
│  │  node_t (标签队列节点)                                       │   │
│  │       │                                                     │   │
│  │       ├──► srb_ext_t*     ←─── 关联的 SRB 扩展             │   │
│  │       ├──► tag           ←─── 硬件标签 ID                  │   │
│  │       ├──► status        ←─── 节点状态                     │   │
│  │       └──► trans_ctx      ←─── 传输上下文                 │   │
│  └───────────────────────────────────────────────────────────────┘   │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

文档生成日期: 2026-03-21
驱动版本: BHTSDDR