1. 为什么视频叠加字幕这件事值得单独写一篇踩坑记录

做FPGA视频处理的人，迟早会碰到一个需求：把一路视频流上叠加一层静态字幕或者OSD信息。听起来简单得不行——不就是把两路像素数据按某个规则混一下吗？我一开始也是这么想的，结果从设计到仿真跑通，前后折腾了将近一周，中间踩的坑一个比一个隐蔽。

这篇文章面向的是已经有一定FPGA基础、正在做或者准备做视频叠加类项目的朋友。我会把整个链路拆开讲：从Video Mixer的架构选型，到AXI VIP仿真环境的搭建，再到Vivado里那些让人抓狂的时序和仿真问题。关键词里的FPGA、Video Mixer、AXI VIP、Vivado、Zynq这些都会覆盖到，但我不打算写成手册式的教程，而是按照我实际踩坑的顺序来还原整个过程。

先说清楚这个项目的核心目标：输入是一路视频流（假设是RGB888或者YUV422格式），需要在上面叠加一层静态字幕（比如"Camera 01"这样的文字），输出仍然是同样格式的视频流。字幕本身是静态的，不需要动态刷新，但位置和透明度要可配置。这个需求在安防监控、工业相机、医疗内窥镜等场景里非常常见。

为什么说它值得单独写一篇？因为"叠加"这个动作背后涉及的问题远比想象中多：像素对齐、时序匹配、跨时钟域处理、AXI Stream握手协议的细节、仿真环境的搭建、Vivado综合时的资源优化……每一个环节都可能让你卡住半天。而且这些问题在仿真阶段和上板阶段的表现还不一样，仿真过了不代表上板没问题，上板跑通了也不代表仿真环境搭对了。

我这次用的是Zynq平台，PL端做视频处理，PS端负责配置寄存器。开发工具是Vivado 2020.2，仿真用的是Vivado自带的Simulator配合AXI VIP。选这个组合的原因很简单：Zynq的PS-PL架构天然适合这种"配置+处理"的场景，AXI VIP则是Xilinx官方提供的验证IP，能大幅简化AXI Stream接口的仿真工作。

2. Video Mixer的架构选择：为什么我最终没用Alpha Blending

2.1 两种叠加方案的对比

视频叠加字幕，最直觉的做法是Alpha Blending——把字幕层和视频层按照透明度系数混合。公式很简单：Output = Video × (1 - α) + Subtitle × α。但实际做下来，我发现这个方案在FPGA上有一个很尴尬的问题：乘法器资源消耗。

假设视频是RGB888，每个像素3个分量，每个分量8bit。Alpha Blending需要3个乘法器（每个分量一个），如果像素时钟是148.5MHz（1080p60），那这三个乘法器必须在一个时钟周期内完成计算。在Zynq-7020这种中低端器件上，3个8×8乘法器跑148.5MHz虽然不算太难，但如果你还要做其他处理（比如缩放、去噪），资源就会很紧张。

我最终选择的方案是"查表+选择"的方式。具体来说，字幕层不是半透明的，而是二值的——要么显示字幕像素，要么显示视频像素。字幕的"透明度"通过一个预先生成的Alpha Mask来实现，Mask的每个bit对应一个字幕像素位置，1表示显示字幕，0表示显示视频。这样叠加逻辑就变成了一个简单的多路选择器：

always @(posedge pixel_clk) begin if (alpha_mask[addr] == 1'b1) video_out <= subtitle_pixel; else video_out <= video_pixel; end

这个方案的好处是资源消耗极低，一个LUT就能搞定。坏处是字幕边缘会有锯齿，因为二值Mask没有抗锯齿能力。但对于静态字幕来说，这个问题可以通过在生成Mask时做预抗锯齿来解决——把边缘像素的Alpha值预先算好，存到Mask里，运行时直接查表。

2.2 字幕数据的存储方式

字幕数据存哪里？这是个容易被忽略但很关键的问题。我一开始想的是用Block RAM存字幕位图，但算了一下：一个1920×1080的字幕层，如果每个像素1bit，那就是2Mbit，需要占用大量的BRAM资源。而且大部分区域是空白的，浪费严重。

后来改成了"字符ROM+位置索引"的方式。字幕内容固定为几个字符（比如"Camera 01"），每个字符用8×16的点阵表示，总共10个字符就是10×8×16=1280bit。这些数据存在一个很小的ROM里，运行时根据字符位置和行号查表输出。这样BRAM消耗从2Mbit降到了不到2Kbit，几乎可以忽略不计。

位置索引则通过寄存器配置，PS端可以随时修改字幕的起始坐标。这个设计的好处是灵活——你可以随时改字幕内容（只要重新生成ROM），也可以随时改位置（通过寄存器）。

2.3 跨时钟域问题的处理

视频像素时钟和AXI Stream的时钟通常不是同一个。在我的设计里，视频输入是148.5MHz（像素时钟），AXI Stream输出是150MHz（PL端AXI时钟）。这两个时钟域之间的数据传递必须做同步处理。

我用的方案是异步FIFO。视频数据写入FIFO的写端口（148.5MHz），AXI Stream从读端口读出（150MHz）。FIFO的深度设为512，足够缓冲一行视频数据。这里有一个坑：FIFO的读写使能信号必须严格遵循AXI Stream的握手协议，否则会出现数据丢失或重复。

具体来说，AXI Stream的TREADY信号来自下游，TVALID来自上游。FIFO的读使能应该是TREADY && TVALID，而不是简单的TREADY。我一开始就是在这里搞错了，导致仿真时数据偶尔会少一个像素，查了好久才发现是握手信号的问题。

3. AXI VIP仿真环境的搭建：那些文档里不会告诉你的细节

3.1 为什么选择AXI VIP而不是自己写Testbench

自己写AXI Stream的Testbench不是不行，但工作量很大。你需要手动实现TVALID/TREADY的握手逻辑、TLAST的生成、TKEEP的处理等等。而且一旦协议细节写错了，仿真结果就不可信。AXI VIP是Xilinx官方提供的验证IP，它把协议细节都封装好了，你只需要配置几个参数就能用。

但AXI VIP的文档写得比较简略，很多细节需要自己摸索。我在这里踩的坑最多，下面逐个说。

3.2 VIP实例化时的参数配置陷阱

AXI VIP的实例化需要配置大量参数，其中最容易出错的是这几个：

我一开始把C_AXI_TDATA_WIDTH设成了8，结果仿真时每个像素被拆成了3个beat，TLAST的位置全乱了。后来改成24（RGB888）才正常。

另一个坑是C_AXI_HAS_TKEEP。如果你的视频数据是24bit，但AXI Stream的位宽是32bit，那TKEEP就必须启用，用来标识哪3个字节是有效的。我一开始没启用TKEEP，结果VIP把无效字节也当成了有效数据，导致字幕位置偏移。

3.3 VIP的时钟和复位配置

AXI VIP需要独立的时钟和复位信号。时钟频率必须与你的设计匹配，否则仿真会报时序错误。复位信号必须是同步复位，且至少保持一个时钟周期。

这里有一个隐蔽的坑：VIP的复位信号极性。默认情况下，VIP的复位是高电平有效，但很多FPGA设计的复位是低电平有效。如果你直接连过去，VIP会一直处于复位状态，仿真根本跑不起来。我在这里卡了半天，后来查了VIP的文档才发现需要配置C_AXI_ARESETN_POLARITY参数。

3.4 仿真脚本的编写技巧

Vivado的Simulator支持TCL脚本控制仿真流程。我建议把仿真脚本写成独立的TCL文件，而不是在GUI里手动操作。这样每次修改设计后只需要重新跑脚本，不用重复点击。

脚本的核心逻辑是：创建VIP实例→配置参数→加载激励文件→运行仿真→检查结果。激励文件可以用CSV或者十六进制格式，我习惯用CSV，因为可读性好，方便调试。

# 创建VIP实例 create_bd_cell -type ip -vlnv xilinx.com:ip:axi_vip axi_vip_0 # 配置参数 set_property -dict [list \ CONFIG.C_AXI_DATA_WIDTH {24} \ CONFIG.C_AXI_TDATA_WIDTH {24} \ CONFIG.C_AXI_HAS_TLAST {1} \ CONFIG.C_AXI_HAS_TKEEP {1} \ ] [get_bd_cells axi_vip_0] # 运行仿真 launch_simulation run all

4. Vivado综合与实现阶段的资源优化实战

4.1 视频叠加逻辑的资源消耗分析

综合完成后，我第一件事就是看资源报告。Video Mixer的核心逻辑消耗了多少LUT、FF和BRAM？结果让我有点意外：LUT消耗比预期多了30%。

排查后发现，问题出在字幕位置的计算上。我原本用了一个乘法器来计算字幕的起始地址（行号×行宽+列号），但Vivado把这个乘法器综合成了多个LUT的组合逻辑。后来改成移位加法（行号×1920 = 行号<<10 + 行号<<8 + 行号<<7），LUT消耗立刻降了下来。

这个经验告诉我：在FPGA里，乘法器不是不能用，但要用在刀刃上。对于常数乘法，移位加法几乎总是更优的选择。

4.2 时序收敛的常见问题

视频处理设计的时序收敛通常比较困难，因为像素时钟频率高，逻辑层级深。我遇到的主要问题是建立时间违例（Setup Violation），出现在字幕地址计算和像素选择之间的路径上。

解决方法有两个：一是插入流水线寄存器，把组合逻辑切成两级；二是优化地址计算逻辑，减少逻辑层级。我两个都用了，最终时序余量从-0.5ns变成了+0.3ns。

这里有一个经验：Vivado的时序报告里，WNS（Worst Negative Slack）是最关键的指标。如果WNS是负数，说明有时序违例，必须解决。TNS（Total Negative Slack）则反映了违例的严重程度。我的建议是WNS至少要有0.2ns的余量，否则上板后可能会因为温度或电压变化而出现偶发错误。

4.3 BRAM的配置优化

字幕ROM用的是BRAM，但Vivado默认会把ROM综合成分布式RAM（LUTRAM），消耗大量LUT。我手动把它改成了Block RAM，LUT消耗立刻降了200多个。

改的方法是在Verilog里用(* ram_style = "block" *)属性：

(* ram_style = "block" *) reg [7:0] subtitle_rom [0:1279];

这个属性告诉Vivado用BRAM来实现这个存储器，而不是LUTRAM。对于容量大于64bit的存储器，BRAM通常是更好的选择。

5. 上板调试：仿真过了不代表万事大吉

5.1 ILA的配置和使用技巧

上板调试离不开ILA（Integrated Logic Analyzer）。我在视频数据路径上插了三个ILA：一个抓输入视频的TVALID/TREADY/TDATA，一个抓字幕叠加后的输出，一个抓AXI Stream的握手信号。

ILA的采样深度设成了4096，足够抓一帧视频的关键片段。触发条件设成TLAST的上升沿，这样每次触发都能抓到一帧的结尾，方便检查帧边界是否正确。

这里有一个坑：ILA的采样时钟必须与被抓信号的时钟域一致。我一开始把ILA的时钟设成了系统时钟（100MHz），但视频像素时钟是148.5MHz，结果抓到的数据全是乱的。后来把ILA时钟改成像素时钟才正常。

5.2 字幕位置偏移问题的排查

上板后第一个问题是字幕位置偏了，往右偏移了大约20个像素。仿真时明明是对的，为什么上板就偏了？

排查过程是这样的：先用ILA抓字幕起始地址的寄存器值，发现PS端写入的值是对的。再抓字幕ROM的输出，发现数据也是对的。最后抓像素选择器的输出，发现字幕像素确实出现在了错误的位置。

问题出在地址计算上。仿真时用的是理想时钟，上板后像素时钟有抖动，导致地址计算逻辑在某个时钟周期内出现了竞争冒险。解决方法是在地址计算路径上插入一级寄存器，把组合逻辑和时序逻辑分开。

5.3 PS端寄存器配置的注意事项

Zynq的PS端通过AXI-Lite配置PL端的寄存器。这里有一个容易忽略的问题：AXI-Lite的写操作是异步的，PS端写完寄存器后，PL端不一定立即生效。如果PL端在PS端写入的同时正在使用这个寄存器，就会出现亚稳态。

解决方法是在PL端对寄存器做两级同步。具体来说，每个配置寄存器都经过两个触发器同步后再使用：

always @(posedge pixel_clk) begin reg_sync1 <= reg_from_ps; reg_sync2 <= reg_sync1; end

这样虽然会增加一个时钟周期的延迟，但能保证寄存器的值稳定可靠。

6. 几个让我印象深刻的坑和最终解决方案

6.1 AXI VIP的BVALID信号问题

AXI VIP的BVALID信号是写响应通道的有效信号。在仿真时，我发现BVALID偶尔会莫名其妙地拉高，导致仿真报错。查了很久才发现，这是因为VIP的写响应通道没有正确初始化。

解决方法是在仿真开始前，手动给VIP的BVALID信号一个初始值（低电平），并在复位期间保持。具体来说，在Testbench里加一段初始化代码：

initial begin axi_vip_0.inst.bvalid <= 1'b0; axi_vip_0.inst.bready <= 1'b0; #100; // 释放复位 end

这个问题的根源是VIP的内部状态机在复位后没有正确初始化，导致BVALID信号处于不确定状态。虽然文档里没有明确说明，但这是实际使用中必须处理的问题。

6.2 Vivado生成比特流失败的排查

Vivado生成比特流时失败，报错信息是"Error when launching Vivado"。这个错误很笼统，可能的原因有很多。我遇到的是DRC（Design Rule Check）错误，具体是某个IO引脚没有分配。

排查方法是打开Vivado的TCL Console，输入report_drc -checks all，会列出所有的DRC违例。根据违例信息逐个解决即可。常见的DRC问题包括：IO标准不匹配、时钟约束缺失、BRAM初始化冲突等。

6.3 仿真与上板结果不一致的通用排查思路

仿真过了但上板不对，这是FPGA开发中最让人头疼的问题。我的排查思路是：

1. 先确认时钟和复位是否正确。用ILA抓时钟信号，确认频率和占空比符合预期。
2. 再确认数据路径是否一致。用ILA抓关键节点的数据，与仿真波形对比。
3. 最后确认配置寄存器是否正确。用PS端读回寄存器值，确认写入生效。

大部分问题都能通过这三步定位。如果还找不到原因，那就检查时序约束是否完整，特别是跨时钟域的约束。

7. 一些可以复用的经验总结

7.1 视频叠加设计的通用架构

经过这次项目，我总结了一个通用的视频叠加架构，适用于大多数静态字幕/OSD场景：

• 输入视频经过异步FIFO进入像素处理时钟域
• 字幕ROM根据位置索引输出字幕像素
• Alpha Mask控制像素选择
• 输出经过异步FIFO回到AXI Stream时钟域
• PS端通过AXI-Lite配置字幕位置和内容

这个架构的优点是资源消耗低、时序容易收敛、可扩展性好。如果需要动态字幕，只需要把字幕ROM换成双端口RAM，PS端动态更新内容即可。

7.2 仿真环境的搭建清单

如果你也要用AXI VIP做仿真，以下是我建议的检查清单：

• VIP的DATA_WIDTH和TDATA_WIDTH是否与设计匹配
• TLAST和TKEEP是否启用
• 复位极性是否正确
• 时钟频率是否与设计一致
• BVALID信号是否初始化
• 激励文件格式是否正确

7.3 上板调试的必备工具

• ILA：至少两个，一个抓输入，一个抓输出
• VIO：用于动态修改寄存器值，方便调试
• 串口打印：PS端打印关键日志，辅助定位问题

我在实际使用中发现，VIO特别有用。它可以在不重新综合的情况下修改寄存器值，大大加快了调试速度。比如字幕位置偏了，用VIO改一下坐标就能立刻看到效果，不用每次都重新跑综合。

7.4 关于Vivado版本的选择

我这次用的是Vivado 2020.2，整体比较稳定。有朋友问我要不要升级到2025.1，我的建议是：如果你的设计已经稳定运行，不要轻易升级。新版本虽然功能更多，但可能会引入新的bug，而且IP核的兼容性也需要重新验证。除非你需要新版本特有的功能，否则保持现有版本就好。

另外，Vivado的安装路径不要有中文和空格，否则会出现各种奇怪的问题。我见过有人因为路径里有空格导致综合失败的案例，排查了半天才发现是路径问题。

7.5 工程清理的重要性

Vivado工程用久了会变得很大，因为每次综合都会生成大量中间文件。定期清理工程可以节省磁盘空间，也能加快打开速度。清理的方法是删除工程目录下的.Xil文件夹和*.jou、*.log文件，但不要删除.srcs和.xpr文件。

如果工程已经无法正常打开，可以尝试删除.Xil文件夹后重新打开，Vivado会自动重建索引。

8. 写在最后的个人体会

这个项目从设计到仿真跑通，再到上板调试，前后花了大约一周时间。其中大部分时间不是在写代码，而是在排查各种意想不到的问题。AXI VIP的BVALID信号、字幕位置偏移、时序违例……每一个问题都让我对FPGA视频处理有了更深的理解。

如果让我给正在做类似项目的朋友一个建议，那就是：仿真环境一定要搭好，不要跳过仿真直接上板。虽然搭仿真环境很麻烦，但它能帮你提前发现80%的问题。剩下的20%上板问题，大部分也能通过ILA和VIO快速定位。

另外，不要迷信文档。AXI VIP的文档里没有提到BVALID初始化的问题，Vivado的文档里也没有说清楚BRAM的ram_style属性怎么用。这些细节只能通过实际踩坑来积累。我写这篇文章的目的，就是希望后来者能少走一些弯路。

最后分享一个小技巧：在Vivado里用TCL脚本自动化常用操作，比如生成比特流、导出硬件、启动SDK等。这样每次修改设计后只需要跑一个脚本，不用重复点击菜单。脚本可以保存成.tcl文件，通过source命令执行。这个习惯能帮你节省大量时间，特别是在频繁迭代的阶段。