优化版 HTML：已添加侧边目录、章节锚点、响应式表格、打印样式和离线 CSS。

#CSI040 控制模块详细设计文档

#1. 文档范围

本文档描述 CSI040 ASIC 控制模块的 RTL 设计，覆盖以下文件：

• c64_pro.srcs/sources_1/rtl/csi040/csi040_ctrl.v
• c64_pro.srcs/sources_1/rtl/csi040/csi040_spi_master.v
• c64_pro.srcs/sources_1/rtl/csi040/csi040_ctrl_tb.v

该模块在 FPGA/PL 侧提供一组 BRAM 风格的控制寄存器。上位逻辑或 PS 通过写这些寄存器来触发 CSI040 ASIC 的 SPI 读写、通道参数配置、模式解锁、触发控制等操作。

#2. 总体结构

PS / 软件
   |
   | BRAM 风格寄存器访问
   v
+------------------+
| csi040_ctrl      |
|                  |
| 软件寄存器映射   |
| shadow 寄存器    |
| seq 序列控制器   |
| 状态/错误锁存    |
+--------+---------+
         |
         | cmd_valid / cmd_ready / cmd_addr / cmd_wdata / cmd_len
         v
+---------------------+
| csi040_spi_master   |
|                     |
| SPI 组帧            |
| SCK/CSN/SI/SO 时序  |
+----------+----------+
           |
           | asic_csn / asic_sck / asic_si / asic_so
           v
       CSI040 ASIC

csi040_ctrl 是上层可见的控制模块，负责接收 BRAM 写操作、保存软件配置、发起高层命令序列，并把命令转换为 SPI master 的抽象命令接口。

csi040_spi_master 是底层 SPI 引擎，负责把 opcode、ASIC 地址和数据字节按 SPI 时序移出，并在读操作时采样 asic_so。

#3. 模块参数

#3.1 csi040_ctrl

#3.2 csi040_spi_master

#4. 顶层接口

#4.1 时钟复位

注意：虽然接口里有 bram_clk，但当前实现没有使用它。因此 BRAM 控制访问应与 clk 同步。如果后续接真实 AXI BRAM Controller 且时钟不同，需要补 CDC 或改成 bram_clk 域逻辑。

#4.2 BRAM 风格控制口

RTL 中访问判定为：

assign bram_wr_valid = bram_en && (bram_we == 4'hF);
assign bram_rd_valid = bram_en && (bram_we == 4'h0);

因此当前模块不支持 byte enable 局部写。如果软件侧产生 bram_we = 4'h1/4'h3 之类的写操作，该写不会被模块识别。

#4.3 状态输出

#4.4 ASIC 侧引脚

#5. BRAM 寄存器映射

所有地址均为字节地址。

#5.1 STATUS 字段

RTL 返回表达式为：

bram_dout <= {16'd0, seq_id, seq_step, error_busy, done_latched, spi_cmd_ready, ctrl_busy};

该拼接宽度为 26 bit，赋值给 32 bit 时左侧补 0。因此软件侧实际可按低位理解：

#5.2 状态清除

写 BRAM_ADDR_STATUS 时：

#6. 高层命令序列设计

模块内部用 seq_id + seq_step + seq_active 控制多拍或多 SPI 帧操作。

#6.1 Busy 机制

模块忙信号定义：

ctrl_busy = seq_active || spi_busy || spi_cmd_valid;
busy      = ctrl_busy;

对所有会启动 SPI 的 BRAM 写操作，RTL 都先检查 !ctrl_busy。若忙时写入命令寄存器：

• 不启动新命令；
• error_busy <= 1'b1；
• 该错误保持到软件写 STATUS[1] 清除。

推荐软件流程：

1. 轮询 busy == 0 或 STATUS[5] == 0。 2. 写命令寄存器。 3. 等待 done_latched == 1 或等待固定时间。 4. 如有读操作，读取 SPI_RDATA。 5. 写 STATUS[0] = 1 清除 done 标志。

#6.2 写控制寄存器

写 BRAM_ADDR_CONTROL：

1. control_shadow <= bram_din[7:0] 2. 启动 SEQ_WRITE_CONTROL 3. 产生 1 个 SPI write：

ASIC addr = CSI_REG_CONTROL = 0x0002
data      = control_shadow
length    = 1 byte

testbench 中写：

write_bram(13'h0020, 32'h00000010)

期望 SPI 帧：

0x02_0002_10

#6.3 写通道使能

写 BRAM_ADDR_CH_ENABLE：

1. ch_enable_shadow <= bram_din[15:0] 2. 启动 SEQ_CH_ENABLE 3. 分两步写 ASIC：

seq_step 0: addr 0x0007, data ch_enable_shadow[7:0]
seq_step 1: addr 0x0008, data ch_enable_shadow[15:8]

testbench 中写 0xA55A，期望两帧：

0x02_0007_5A
0x02_0008_A5

#6.4 写触发命令

写 BRAM_ADDR_TRIGGER 启动 SEQ_TRIGGER，SPI 写：

ASIC addr = CSI_REG_STIM_TRIGGER = 0x0110
data      = 8'hAA

注意：该 SPI trigger 与 asic_trig 引脚是两个不同路径。asic_trig 只受 PIN_CTRL[1] 控制。

#6.5 特殊序列 SEQ_CMD

写 BRAM_ADDR_SEQ_CMD 时，RTL 按 bit 优先级解析：

若多个 bit 同时为 1，优先级从 bit0 到 bit4。

#6.6 通道参数写

通道地址由函数 ch_addr 计算：

ch_addr = CSI_CH_BASE + (ch * CSI_CH_STRIDE) + offset;

默认：

CSI_CH_BASE   = 0x0010
CSI_CH_STRIDE = 0x0010

所以：

ASIC channel register address = 0x0010 + ch_index * 0x0010 + ch_offset

示例：

CH_INDEX = 3
写 CH_CUR_A = 0x7F
offset = 0x1
ASIC addr = 0x0010 + 3 * 0x0010 + 0x1 = 0x0041
SPI frame = 0x02_0041_7F

当前所有通道参数写都只发送 bram_din[7:0]。

#6.7 Direct SPI 访问

Direct SPI 用于软件直接访问任意 ASIC 寄存器。

操作流程：

1. 写 SPI_ADDR，设置 ASIC 地址。 2. 若是写操作，写 SPI_WDATA。 3. 写 SPI_CTRL 启动 SPI：

SPI_CTRL[0]    = direct_write, 1 为写，0 为读
SPI_CTRL[15:8] = direct_len，单位 byte；0 会被转换为 1

direct_len 在 SPI master 内部被限制到 1..MAX_BURST_BYTES。

读操作完成后：

• last_rdata <= spi_cmd_rdata[31:0]
• 软件读 SPI_RDATA 获取数据
• 软件读 LAST_ADDR 获取最近访问地址

testbench 中直接读 Part ID：

SPI_ADDR = 0x011D
SPI_CTRL = 0x00000100  // write=0, len=1
期望帧 = 0x03_011D_00
读回 = 0x28

#7. SPI Master 设计

csi040_spi_master 接收抽象命令，并转换成 SPI bit 流。

#7.1 命令接口

#7.2 SPI 帧格式

默认 ADDR_BYTES = 2，帧格式为：

byte0   opcode
byte1   address high byte
byte2   address low byte
byte3+  payload bytes

1 字节写示例：

opcode = 0x02
addr   = 0x0002
data   = 0x10
frame  = 0x02_0002_10

地址字节按 MSB first 输出。payload 来自：

cmd_wdata[8*n +: 8]

即 cmd_wdata[7:0] 是第一个 payload byte。

#7.3 SPI 状态机

SPI 时钟频率：

f_sck = f_clk / (2 * CLK_DIV)

testbench 中：

f_clk = 100 MHz
CLK_DIV = 2
f_sck = 25 MHz

该值用于加速仿真。实际硬件中应根据 CSI040 SPI 时序要求重新设置 SPI_CLK_DIV。

#7.4 读数据采样

SPI master 在 header 发送完之后开始采样 so：

HEADER_BITS = 8 * (1 + ADDR_BYTES)

默认地址 2 字节时，header 为 24 bit。读数据从第 25 个 bit 开始采样，采样结果移入 rx_shift，帧结束时赋给 cmd_rdata。

#8. 复位行为

rst_n = 0 时，csi040_ctrl 主要寄存器复位如下：

csi040_spi_master 复位后：

csn  = 1
sck  = 0
si   = 0
done = 0
busy = 0
state = IDLE_ST

#9. 当前 Testbench 覆盖

csi040_ctrl_tb 实例化 DUT 时重载：

.SPI_CLK_DIV      ( 2 ),
.SPI_OPCODE_WRITE ( 8'h02 ),
.SPI_OPCODE_READ  ( 8'h03 )

testbench 使用 100 MHz clock，复位 8 个周期后开始测试。

覆盖场景：

testbench 中 SPI monitor 的行为：

• negedge asic_csn 清空 bit 计数和 shift 寄存器；
• posedge asic_sck 采样 asic_si；
• posedge asic_csn 锁存完整帧；
• 在读数据阶段从 asic_so 返回 read_response = 8'h28。

#10. 仿真与波形

已验证的命令：

& 'C:\Xilinx\Vivado\2023.1\bin\xvlog.bat' `
  c64_pro.srcs/sources_1/rtl/csi040/csi040_spi_master.v `
  c64_pro.srcs/sources_1/rtl/csi040/csi040_ctrl.v `
  c64_pro.srcs/sources_1/rtl/csi040/csi040_ctrl_tb.v

& 'C:\Xilinx\Vivado\2023.1\bin\xelab.bat' csi040_ctrl_tb -debug typical -snapshot csi040_ctrl_tb_sim_dbg

& 'C:\Xilinx\Vivado\2023.1\bin\xsim.bat' csi040_ctrl_tb_sim_dbg -runall

当前仿真结果：

$finish called at time : 10940 ns

未触发 testbench 中的 ERROR ... $stop。

打开 GUI：

& 'C:\Xilinx\Vivado\2023.1\bin\xsim.bat' csi040_ctrl_tb_sim_dbg -gui

GUI 中可用：

log_wave -r /csi040_ctrl_tb/*
run all

建议观察信号：

/csi040_ctrl_tb/bram_addr
/csi040_ctrl_tb/bram_din
/csi040_ctrl_tb/bram_dout
/csi040_ctrl_tb/bram_en
/csi040_ctrl_tb/bram_we
/csi040_ctrl_tb/busy
/csi040_ctrl_tb/spi_done
/csi040_ctrl_tb/error_busy
/csi040_ctrl_tb/asic_csn
/csi040_ctrl_tb/asic_sck
/csi040_ctrl_tb/asic_si
/csi040_ctrl_tb/asic_so
/csi040_ctrl_tb/frame_in
/csi040_ctrl_tb/frame_bits
/csi040_ctrl_tb/dut/seq_id
/csi040_ctrl_tb/dut/seq_step
/csi040_ctrl_tb/dut/seq_active
/csi040_ctrl_tb/dut/spi_cmd_valid
/csi040_ctrl_tb/dut/spi_cmd_ready
/csi040_ctrl_tb/dut/spi_cmd_addr
/csi040_ctrl_tb/dut/spi_cmd_wdata
/csi040_ctrl_tb/dut/spi_cmd_len
/csi040_ctrl_tb/dut/u_csi040_spi_master/cstate
/csi040_ctrl_tb/dut/u_csi040_spi_master/tx_shift
/csi040_ctrl_tb/dut/u_csi040_spi_master/rx_shift
/csi040_ctrl_tb/dut/u_csi040_spi_master/sampled_bits

#11. 软件使用建议

典型写配置流程：

1. 轮询 STATUS[5] == 0
2. 写目标 BRAM 命令寄存器
3. 轮询 STATUS[7] == 1
4. 如是读命令，读取 SPI_RDATA
5. 写 STATUS[0] = 1 清除 done_latched
6. 如 STATUS[8] = 1，记录错误并写 STATUS[1] = 1 清除 error_busy

注意事项：

• 忙时不要写命令寄存器，否则命令会被丢弃，并置位 error_busy。
• PIN_CTRL 是直接引脚控制，不会自动生成 SPI。
• TRIGGER 是 SPI 写 ASIC trigger register，不等同于 asic_trig 引脚。
• SPI_CTRL[15:8] 为直接 SPI payload 长度，最大有效值受 MAX_BURST_BYTES 限制。
• 当前 BRAM 接口只支持全字写。

#12. 后续可改进点

• 明确 bram_clk/bram_rst 的设计意图：要么真正使用它们，要么在接口说明中标记为 unused。
• 增加 byte enable 写支持，方便接 AXI BRAM Controller。
• 为 STATUS 位定义软件头文件常量，避免软件侧硬编码 bit 位置。
• 扩展 testbench：
• 忙时写命令，检查 error_busy；
• PIN_CTRL 读写；
• TRIGGER SPI 序列；
• Test unlock 和 mode exit；
• Direct SPI 多字节 burst；
• cmd_len=0、超过 MAX_BURST_BYTES 的边界行为；
• SPI read 多字节返回数据。
• 增加 SystemVerilog assertion，用来约束命令重入、SPI 帧长度和 csn/sck 时序。