前言¶

概述

本文分别从硬件环境准备、软件环境准备等方面介绍Demo板PCIe级联操作的相关指导，同时介绍了PCIe的基础知识、PCIe级联的业务实现和PCIe MPI接口函数等，可为用户在使用PCIe级联功能时提供参考。

说明：

未有特殊说明，下文中的ssxx表示的解决方案包含SS528V100、SS625V100、SS928V100、SS927V100、SS626V100。

未有特殊说明，SS927V100与SS928V100内容完全一致。

产品版本

与本文档相对应的产品版本如下。

产品名称	产品版本
SS928	V100
SS626	V100
SS528	V100
SS625	V100
SS927	V100

读者对象

本文档（本指南）主要适用于以下工程师：

技术支持工程师
软件开发工程师

符号约定

在本文中可能出现下列标志，它们所代表的含义如下。

符号	说明
	表示如不避免则将会导致死亡或严重伤害的具有高等级风险的危害。
	表示如不避免则可能导致死亡或严重伤害的具有中等级风险的危害。
	表示如不避免则可能导致轻微或中度伤害的具有低等级风险的危害。
	用于传递设备或环境安全警示信息。如不避免则可能会导致设备损坏、数据丢失、设备性能降低或其它不可预知的结果。 “须知”不涉及人身伤害。
	对正文中重点信息的补充说明。 “说明”不是安全警示信息，不涉及人身、设备及环境伤害信息。

修订记录

修订记录累积了每次文档更新的说明。最新版本的文档包含以前所有文档版本的更新内容。

文档版本	发布日期	修改说明
00B01	2025-09-15	第1次临时版本发布。

Demo板PCIe级联操作指南¶

硬件环境准备¶

PCIe级联调测，需要准备两块或多块硬件板卡，两片或多片板卡通过PCIe级联使用：

其中一片工作在PCIe主模式（主片RC (Root-Complex)模式）。
其他片工作在PCIe从模式（从片EP (End-Point)模式）。

多片通过PCIe进行级联时，主片通过PCIe桥与多个从片进行级联。需要为板卡正确连接电源线、串口线、网线以及视频输入输出线。

软件环境准备¶

解决方案需要的boot、内核以及文件系统可参考发布包sdk/osdrv目录下的《readme》文件及sdk/osdrv/components/pcie_mcc中的《主片引导从片启动方法》来编译相关镜像和驱动。

主从片均采用Flash启动方式：

按照非PCIe模式的烧写方式，烧写主/从片上的u-boot、内核以及文件系统即可。
主从片Flash启动方式下，启动文件清单如表1所示。

表 1 启动文件清单（主从片均采用Flash启动）

项目		文件名称	描述
主片	ARM	u-boot-xxx.bin或boot_image.bin	烧写到主片Flash
		uImage_xxx	烧写到主片Flash
		rootfs_xxx.ubifs	烧写到主片Flash
从片	ARM	u-boot-xxx.bin或boot_image.bin	烧写到从片Flash
		uImage_xxx	烧写到从片Flash
		rootfs_xxx.ubifs	烧写到从片Flash

主片采用Flash启动方式，从片采用由主片进行引导DDR启动方式，启动文件清单如表2所示。

表 2 启动文件清单（主片采用Flash启动，从片采用DDR启动）

项目		文件名称	描述
主片	ARM	u-boot-xxx.bin或boot_image.bin	烧写到主片Flash
		uImagexxx	烧写到主片Flash
		rootfs_xxx.ubifs	烧写到主片Flash
从片	ARM	u-boot.bin 或boot_image.bin	由主片导入从片DDR内存
		uImage	由主片导入从片DDR内存
		cramfs.initrd.img	由主片导入从片DDR内存

说明：

上文中的xxx并不代表具体的文件名称，真正的文件名称以实际编译出并选择的文件为准。

上文中的u-boot.bin为快速启动的uboot镜像；boot_image.bin为非快速启动（非安全/安全启动）的boot镜像。

主片及从片启动¶

主片和从片启动有以下2种方式：

主从片均采用Flash启动方式。

按照非PCIe模式的启动方式启动，保证从片在主片之前启动即可。
主片采用Flash启动方式，从片采用DDR启动方式，由主片来引导。

详细操作请参考其发布包中sdk/osdrv/components/ pcie_mcc/目录下的《主片引导从片启动方法》。

须知： 一旦程序出现异常需要重启单板，则主从片均要重新启动。

PCIV功能验证¶

依赖的驱动说明¶

PCIV为基于PCIe驱动和解决方案媒体驱动的上层业务模块，依赖的驱动包括PCIe底层驱动、PCIe消息驱动（即MCC）和所有MPP媒体驱动。

PCIe底层驱动包括vendor_dev_host.ko、vendor_dev_slv.ko、pcit_dma_host.ko、pcit_dma_slv.ko、irq_map_host.ko和irq_map_slv.ko；
PCIe消息驱动包括mcc_drv_host.ko、mcc_usrdev_host.ko、mcc_drv_slv.ko和mcc_usrdev_slv.ko；
MPP媒体驱动：load_ssxx脚本中所有需要加载的模块驱动；
PCIV模块本身的相关驱动：

仅支持单系统模式，加载ssxx_pciv.ko和ssxx_pciv_fmw.ko；

SDK发布包中已有相关脚本（主片加载使用load_ssxx_master，从片加载使用 load_ssxx_slave）来加载以上所有驱动。

验证操作步骤¶

验证PCIV功能的样例代码位于SDK发布包的mpp/sample/pciv目录下，包括主片和从片分别使用的Sample代码、封装的消息通讯代码和封装的数据通讯代码。

须知： 执行以下验证操作前，请先使用Sample目录下的Makefile编译生成相关可执行文件。

在硬件、软件环境准备好后，执行完整的PCIV功能验证（其中的脚本内容请直接阅读SDK发布包中相应脚本）的步骤如下：

主从片分别进入mpp /ko目录，从片执行脚本load_ssxx_slave，主片执行脚本load_ssxx_master，加载PCIe相关ko和MPP相关ko。
从片进入mpp/sample/pciv/目录，执行从片的Sample程序sample_pciv_slave，此时终端上将打印start check pci target id:x……并被阻塞，等待主片启动。
主片进入mpp/sample/pciv/目录，执行主片的Sample程序sample_pciv_host，完成与从片的握手过程后，即启动从片与主片之间的数据传输业务。
如果需要停止Sample程序，可以在主片上按回车键，主片会发消息给从片销毁相关业务，并退出本片程序；从片接收消息并在销毁相关业务后退出。
须知： 编写从片加载ko脚本需注意：
- 如果使用flash启动方式，从片指定pcie消息空间，以及window空间，这两者之间，以及与其他mmz之间的空间不能重叠
- 如果使用从启动方式，从片镜像会占用一部分内存，具体占用位置，参考./components/pcie_mcc/multi_boot/example/中boot_test.h和boot_test.c相关定义。

Demo板从启动硬件及软件配置¶

从启动硬件配置¶

BOOT源选择为PCIe启动，要求将PCIE_SLV_BOOT_MODE，配置为1。

PCIe从启动时，注意时钟硬件选择管脚的设置：

表 1 PCIe时钟源选择

解决方案	信号	方向	功能
SS528V100 SS625V100	PCIE0_REFCLK_SEL PCIE1_REFCLK_SEL	I	PCIe0/1参考时钟源选择（内部下拉）。 0：内部时钟； 1：外部时钟。
SS928V100	PCIE_REFCLK_SEL	I	PCIe参考时钟源选择（内部下拉）。 0：内部时钟； 1：外部时钟。
SS626V100	PCIE0_REFCLK_SEL PCIE1_REFCLK_SEL	I	PCIe0/1参考时钟源选择（内部下拉）。 0：内部时钟； 1：外部时钟。

解决方案

信号

方向

功能

SS528V100

SS625V100

PCIE0_REFCLK_SEL

PCIE1_REFCLK_SEL

PCIe0/1参考时钟源选择（内部下拉）。

0：内部时钟；

1：外部时钟。

SS928V100

PCIE_REFCLK_SEL

PCIe参考时钟源选择（内部下拉）。

0：内部时钟；

1：外部时钟。

SS626V100

PCIE0_REFCLK_SEL

PCIE1_REFCLK_SEL

PCIe0/1参考时钟源选择（内部下拉）。

0：内部时钟；

1：外部时钟。

在级联场景时钟设计注意事项¶

SS528V100/SS625V100¶

PCIe差分时钟PCIE0/1_REFCLKM和PCIE0/1_REFCLKP为电压型信号，当差分时钟信号需要输出给外部设备时，差分时钟信号在靠近末端串联51Ω电阻，不需要加下拉电阻，以SS528V100为例，如图1所示。

图 1 SS528V100 PCIe时钟图
PCIe选择为外部时钟输入时，差分时钟信号的匹配方式取决于输出设备，且只支持HCSL电平，不支持交流耦合。

须知： 时钟选择错误将导致从片PCIe无法使用外部时钟模式。

各种PCIE组合如图2所示。

图 2 PCIe模式图

以SS528V100为例，以下为几种典型的PCIe级联示意图。

两片PCIe X1级联，如图3所示。

图 3 两片PCIe X1级联示意图
两片PCIe X2级联，如图4所示。

图 4 两片PCIe X2级联示意图

SS928V100/SS927V100¶

PCIe差分时钟PCIE_REFCLKM和PCIE_REFCLKP为电流型信号，以SS928V100为例，当差分时钟信号需要输出给外部设备时，在差分时钟输出端对地加49.9Ω电阻，如图1所示。

图 1 SS928V100 PCIe时钟图
SS928V100各种PCIE组合如图2所示。

图 2 PCIe模式图
SS928V100 两片PCIe X1级联，如图3所示。

图 3 两片PCIe X1级联示意图

SS626V100¶

SS626V100 PCIe差分时钟PCIE_REFCLKM和PCIE_REFCLKP为电流型信号，当差分时钟信号需要输出给外部设备时，在差分时钟输出端对地加49.9Ω电阻，如图1所示。

图 1 SS626V100 PCIe时钟图
SS626V100各种PCIE组合如图2所示。

图 2 PCIe模式图
SS626V100 两片PCIe X1级联，如图3所示。

图 3 两片PCIe X1级联示意图

从启动软件配置¶

PCIe时钟选择模式配置¶

SS528V100/SS625V100请参考芯片手册文档“13.7.5.1 时钟和复位时钟设置”章节的相关描述。
SS928V100请参考芯片手册文档“14.8.5.1 时钟和复位”章节的相关描述。
SS626V100请参考芯片手册文档“13.7.5.1 时钟和复位”章节的相关描述。

PCIE_MCC驱动配置¶

pcie_mcc目前只使用一个PCIe控制器，PCIE_MCC驱动的默认配置已在PCIE_MCC驱动代码的./vendor_dev/arch/config.h文件中进行设置，不需要修改。

PCIe基础知识¶

概述¶

PCIe是外围设备互连（Peripheral Component Interconnect Express）的简称，作为一种通用的总线接口标准，在目前的计算机系统中得到了非常广泛的应用。PCIe总线的时钟频率一般使用2.5GHz，在32bit系统中，最基本的PCI Express x1模式理论极限速度可以达500MB/s（2.5Gbps x (1 B/8bit) x (8b/10b) x 2）；但PCIe无法一直维持在峰值传输的状态，一般只能保持在50～60％的传输效率，即250MB/s～300MB/s的速度。如果需要更高的传输速度，可以使用PCI Express x 2、x 4、x 8或x 16模式，数据理论传输速率分别达到1GBps、2GBps、4GBps和8GBps。

PCIe设备上有三种地址空间，对应三种PCIe总线命令，具体如表1所示。

说明： CPU可以访问PCIe设备上的所有地址空间。

表 1 PCIe地址空间和命令

地址空间	描述	命令	说明
I/O空间	供给设备驱动程序使用	I/O操作命令	对设备对应的I/O地址空间进行访问，此类访问不可预取。
存储空间	供给设备驱动程序使用	Memory操作命令	对设备的Memory空间进行访问，其中Memory操作命令又可分为Prefechable（可预取）和Non-prefechable（不可预取）两种类型。
配置空间	提供Linux内核中的PCIe初始化代码使用	配置访问命令	对设备的配置空间进行读写访问，用来初始化设备，给设备分配资源。

内核在启动时负责对所有PCIe设备进行初始化，配置所有的PCIe设备，包括中断号以及I/O基址，并在文件/proc/bus/pci/devices中列出所有找到的PCIe设备，以及这些设备的参数和属性。

请查阅有关PCIe规范的资料获取PCIe协议详细说明。本文重点介绍关注业务应用中常用的知识。

PCIe DMA方式数据传输¶

PCIe模块内建DMAC，可直接由PCIe接口发起DMA操作，此时不需要ARM的干预，可获得更好的系统性能。

支持PCIe从到主、主到从的DMA读写传输，主要用于传输预览图像、解码图像以及码流等数据。预览图像和解码图像的传输由PCIV模块在内核态调用接口完成，而码流数据的传输则需要用户调用PCIV模块封装的接口来完成。

软件提供的DMA写操作时传输接口需要以下输入参数：

目标物理地址（即PCIe地址）
源物理地址（即AHB地址）
传输长度

从到主的DMA写操作：源地址使用从片的AHB地址（即DDR地址），目标地址使用主片的DDR地址（即其PCIe地址）。

主到从的DMA写操作：源地址使用主片的AHB地址（即DDR地址），目标地址使用从片的窗口PF地址空间对应的PCIe地址。

软件提供的DMA读操作时传输接口需要以下输入参数：

目标物理地址（即AHB地址）
源物理地址（即PCIe地址）
传输长度

从到主的DMA读操作：源地址使用主片的DDR地址（即其PCIe地址），目标地址使用从片的AHB地址（即DDR地址）。

主到从的DMA读操作：源地址使用从片的窗口PF地址空间对应的PCIe地址，目标地址使用主片的AHB地址（即DDR地址）。

PCIe共享内存方式数据传输¶

作为PCIe Host的一端可以通过AHB-PCIe window实现ARM core对PCIe总线上的其它设备的访问。

AHB-PCIe window上存在三种地址空间，分别是：

非可预取内存空间（NP Memory）
可预取内存空间（PF Memory）
IO空间（IO）

PCIe主设备由操作系统统一分配从设备配置空间中的BAR0，BAR1，BAR2寄存器的基址，并通过配置空间访问写入；从设备则可以在AHB总线上通过寄存器配置NP Memory和PF Memory的AHB侧基地址以及范围大小（最大8M）。因此主设备上看到的各个从设备的窗口的PCIe地址与从设备本身的AHB侧基地址一一对应，即可使用Window中的可预取内存空间实现主从片间的内存共享，具体如图1和图2所示。

如图1所示，1个PCIe控制器，主片的PCIe地址0x30800000与从片1上的AHB地址0xDF000000可以认为存在映射关系，在主片上对0x30800000区域的读写访问可以通过PCIe总线反应到从片的0xDF000000区域；主片上的PCIe基址0x30800000是通过读取从片1的BAR0寄存器而得到（用户程序可以通过PCIV模块封装的接口获取），而从片上的AHB基址0xDF000000是由驱动程序写入到PCIe iATU寄存器组中的目标地址低位寄存器（PCIe支持64位地址操作，目标地址高位寄存器写0），用户可以在加载vendor_dev_slv.ko模块时通过修改模块参数来更改此AHB基址。

图 1 PCIe地址与AHB侧地址的映射关系图

如图2所示，2个PCIe控制器，主片的PCIe地址0x28800000与从片1上的AHB地址0xDF000000可以认为存在映射关系，主片的PCIe地址0x38800000与从片2上的AHB地址0xDF000000可以认为存在映射关系。

图 2 PCIe地址与AHB侧地址的映射关系图

须知： PF Memory在从片上的地址范围是可以不断移动的（即窗口的移动），但鉴于整个系统的稳定性以及PCIe消息模块对NP基址的依赖性，不建议在从片启动后再移动窗口。

PCIe MCC消息应用¶

PCIe MCC消息模块基于PCIe的Window窗口机制以及系统全局软中断，实现PCIe主从设备间的消息通讯功能。

用户态接口包括：获取PCIe本地以及对端的ChipId号，主从片间的相互检测机制（即通讯握手），消息端口的打开、关闭，消息的读和写、以及Select接口等。

从MCC模块获取到的ChipId号，在PCIe主设备上为0，在PCIe从设备上则为PCIe slot号（由于PCIV模块内部的消息通讯也基于MCC，因此PCIV中的ChipId与此一致）。

MCC的消息缓存池使用PCIe窗口中的可预取内存空间，且固定使用前1M的地址范围，例如加载vendor_dev_slv.ko模块时，配置窗口范围为0xDF000000的8M地址范围，则从0xDF000000开始的1M空间分配给MCC模块使用，用户程序不应该再去使用它。

PCIe级联业务实现¶

视频预览¶

视频预览主要用于多片之间级联，视频预览是将从片的VI图像传送到PCIe总线上的主片的VO设备上显示。基本的数据流处理如图1所示。

图 1 视频预览数据流处理流程

数据流的控制和传输由MPP系统在内核态完成，用户只需要调用MPI接口完成相应配置、使用PCIe消息机制完成部分命令的传递。传输通路建立以后，正常图像传输则不需用户干预。

说明：

PCIV相关接口的详细说明和注意事项请参见“PCIV开发参考”。

PCIe消息的相关接口则使用mcc模块提供的ioctl命令。

从片在送PCIV之前，建议先通过VPSS模块进行所需处理。

当任务压力过大时，mcc模块会通过串口打印错误日志："Too many DMA data write tasks!"。串口打印会阻塞送帧的中断或进程，可通过调整printk打印等级忽略打印(mcc使用默认等级打印，忽略打印修改/proc/sys/kernel/printk中的第一个数字为4或以下即可)。

码流传输¶

码流传输是将设备上的视频编码码流数据或者解码码流数据传送到PCIe总线上的其他设备。基本的数据流处理如图1所示。

图 1 码流传输数据流处理流程

码流发送端首先从VENC通道中获取编码码流数据，将其拷贝至准备好的stream buffer中，然后通过PCIe的DMA将码流数据发送到PCIe对端的stream buffer中，对端再将码流取出通过网络发送或存文件，每次传输的读写位置信息可以通过PCIe消息发送到对端以便进行发送和接收的同步控制。发送端和接收端的stream buffer需要用户自行实现，推荐采用不定长的循环buffer，每次传输多帧数据。

说明：

PCIe DMA的传输使用PCIV模块提供的相应接口。

PCIe消息则使用MCC模块提供的相应接口。

注意：码流的发送和接收都需要四字节对齐。

详细操作及流程可以参考SDK中的样例程序。

解码回放图像显示¶

解码回放图像是将设备上的VDEC 解码后图像传送到PCIe总线上的其他设备的VO设备上显示。基本的数据流处理如图1所示。

图 1 解码回放图像数据流处理流程

具体的数据流处理和接口调用与PCIe预览流程类似，主要区别如下：

用户需要创建解码通道并向其发送码流进行解码；
PCIV相应传输通路建立后，PCIV模块可以接收VDEC通道解码后图像数据，处理后通过PCIe DMA发送到对端；也可接收VPSS处理后的图像数据，通过PCIe DMA发送到对端。

对端的数据接收及VO显示与预览流程一致。

说明：

从片在送PCIV之前，建议先通过VPSS模块进行所需处理。

如VO显示高清图像，需要在主片在VO之前调用VPSS进行处理。

图视频预览数据流处理流程~图解码回放图像数据流处理流程中的Slave和Master不代表实际的PCIe模式，以具体的使用场景为准。

内存配置¶

与PCIe业务相关的内存配置时，需要注意以下事项：

PCIe从设备加载mcc_drv_slv.ko模块时，配置窗口PF地址范围最大为8M。需要注意，前1M固定分配给MCC模块。
图像或码流的传输过程中，使用的源地址和目标地址都是由MMZ管理，用户可通过MMZ的VideoBuffer相关接口获取。其中图像的传输由PCIV模块内部从VideoBuff中获取内存，而码流传输需要用户在用户态调用接口获取VideoBuffer内存。
从到主的DMA数据传输（包括图像和码流）时，源地址和目标地址都可以是各自DDR上的任意可用地址。
主到从或者从到从的DMA数据传输时，目标地址必须使用PCIe窗口映射的PCIe地址。

以主到从的码流传输为例，主片上的码流发送buffer可位于DDR上任意有效地址空间（可以使用VideoBuffer相关接口分配内存）；而从片上的码流接收buffer则必须在PCIe窗口的PF Memory空间范围内，获取其内存可以调用PCIV相应接口：首先调用ss_mpi_pciv_create_window_vb创建基于window mmz的缓存池，然后调用ss_mpi_pciv_malloc_window_buf接口从其中获取缓存块。

如图1所示，命名为window的MMZ区域位于整个PF窗口区域的后7M范围内，此MMZ区域是在从片的初始化加载脚本中创建，基址为0xDF100000，对应的整个从片PCIe窗口的PF基址是0xDF000000，如果用户需要修改PCIe窗口PF基址，则必须同时修改window MMZ的基址。

图 1 PCIe窗口PF区域和MMZ区域的示意

PCIV开发参考¶

PCIV概述¶

PCIV模块主要提供PCIe多片间图像数据传输等相关MPI接口。具体包括：

预览图像的传输：图像发送端绑定VI通道或者绑定VPSS通道，图像接收端绑定VO通道或者VENC通道或者VPSS通道，发送端和接收端进行相应配置并启动后，即可将发送端的图像发送到接收端的VO通道进行显示或者送给VPSS/VENC进行后续处理。
解码回放图像的传输：图像发送端绑定VDEC通道或者绑定VPSS通道，图像接收端绑定VO通道或者VENC通道或者VPSS通道，发送端和接收端进行相应配置并启动后，即可将VDEC通道解码后图像发送到接收端的VO通道进行显示或者送给VPSS/VENC进行后续处理。
码流数据的传输：提供启动PCIe DMA传输的MPI接口，用户可以调用此接口将编码码流或者解码码流或者其他数据通过PCIe DMA传输到PCIe对端。

说明：

PCIV模块不提供PCIe消息通讯、编码与PCIV通道的绑定等接口，这些接口由其他模块提供或者由用户实现。用户实现PCIe消息通信时，80号端口已被PCIV内部传输使用，请不要重复使用。

采用绑定方式时，建议PCIV属性配置与前端的保持一致，否则PCIV需要调用VGS处理进行响应处理，需要额外的开销。

如果使用不同解决方案级联，媒体传输部分的数据可能会有差异而导致异常，建议这种场景下，只使用PCIV的DMA功能进行数据传输。

PCIV MPI参考¶

本模块所有MPI接口需要在完整，正确的级联环境下调用，否则可能会引发不可预知的异常。本功能模块提供以下MPI：

ss_mpi_pciv_malloc_chn_buf：分配PCIV通道内存。
ss_mpi_pciv_free_chn_buf：释放PCIV通道内存。
ss_mpi_pciv_create_chn：创建PCIV通道。
ss_mpi_pciv_destroy_chn：销毁PCIV通道。
ss_mpi_pciv_start_chn：启动PCIV通道。
ss_mpi_pciv_stop_chn：停止PCIV通道。
ss_mpi_pciv_set_chn_attr：设置PCIV通道属性。
ss_mpi_pciv_get_chn_attr：获取PCIV通道属性。
ss_mpi_pciv_show_chn：显示(传输)PCIV通道图像。
ss_mpi_pciv_hide_chn：隐藏(不传输)PCIV通道图像。
ss_mpi_pciv_create_window_vb：创建PCIV窗口专用缓存池。
ss_mpi_pciv_destroy_window_vb：销毁PCIV窗口专用缓存池。
ss_mpi_pciv_malloc_window_buf：分配PCIV缓存。
ss_mpi_pciv_free_window_buf：释放PCIV缓存。
ss_mpi_pciv_dma_task：发起PCIV DMA任务。
ss_mpi_pciv_get_local_id：获取自身PCIe节点设备id。
ss_mpi_pciv_enum_chip：获取与此节点相连接的其他节点设备id。
ss_mpi_pciv_get_window_base：获取PCIe控制器窗口信息。

ss_mpi_pciv_malloc_chn_buf¶

【描述】

分配PCIV通道内存。

用于分配接收方PCIV通道的相关内存，可以一次分配多块指定大小的内存块。

【语法】

td_s32 ss_mpi_pciv_malloc_chn_buf(ot_pciv_chn chn, td_u32 blk_size, td_u32 blk_cnt, td_phys_addr_t phys_addr[]);

【参数】

参数名称	描述	输入/输出
chn	PCIV通道号。取值范围：[0, OT_PCIV_MAX_CHN_NUM)	输入
blk_size	内存块大小。	输入
blk_cnt	内存块个数。取值范围：[1, OT_PCIV_MAX_BUF_NUM]	输入
phys_addr	物理地址数组。 td_phys_addr_t定义请参考《MPP媒体处理软件V5.0开发参考》“系统控制”章节。	输出

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。

【需求】

头文件：ot_common_pciv.h、ss_mpi_pciv.h
库文件：libss_mpi.a libss_pciv.a

【注意】

在PCIe主片上调用此接口时，直接从MPP的公共VB池中分配缓存块。需要保证公共VB池中有足够满足条件的缓存块，否则返回失败，公共VB池池的相关概念请参见《MPP 媒体处理软件Vx.0开发参考》中的“系统控制”章节相关内容。
在创建该通道号对应的通道之前，需调用此接口分配该通道号对应的通道内存。
在PCIe从片上不需要分配通道内存，因此该接口只能在主片上调用，在从片上调用此接口时，返回失败。
当接口分配内存失败时，会将传出参数phys_addr所指向的数组中的元素都置为0，用来防止用户使用已经释放了的内存。
此接口需要用户保证输入的地址数量参数blk_cnt与地址数组phys_addr长度匹配。
此接口需与接口ss_mpi_pciv_free_chn_buf配合使用，在未释放的情况下重新分配接口返回失败。

【举例】

无。

【相关主题】

ss_mpi_pciv_free_chn_buf
ss_mpi_pciv_create_chn

ss_mpi_pciv_free_chn_buf¶

【描述】

释放PCIV通道内存。

【语法】

td_s32 ss_mpi_pciv_free_chn_buf(ot_pciv_chn chn, td_u32 blk_cnt);

【参数】

参数名称

描述

输入/输出

chn

PCIV通道号。

取值范围：[0, OT_PCIV_MAX_CHN_NUM)

输入

blk_cnt

内存块个数。

取值范围：[1, OT_PCIV_MAX_BUF_NUM]

输入

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。

【需求】

头文件：ot_common_pciv.h、ss_mpi_pciv.h
库文件：libss_mpi.a libss_pciv.a

【注意】

通道启动状态下，不允许调用此接口释放通道号对应的通道内存，否则返回失败。
此接口需与接口ss_mpi_pciv_malloc_chn_buf配合使用，未分配就释放或重复释放返回失败。
blk_cnt参数必须与调用接口ss_mpi_pciv_malloc_chn_buf时的blk_cnt参数相同，否则会造成释放失败或程序异常。
本模块只支持从片传输图像到主片，因此只需要主片分配通道内存，从片调用此接口返回失败。

【举例】

无。

【相关主题】

ss_mpi_pciv_malloc_chn_buf

ss_mpi_pciv_create_chn¶

【描述】

创建PCIV通道。

【语法】

td_s32 ss_mpi_pciv_create_chn(ot_pciv_chn chn, const ot_pciv_attr *attr);

【参数】

参数名称	描述	输入/输出
chn	PCIV通道号。取值范围：[0, OT_PCIV_MAX_CHN_NUM)。	输入
attr	PCIV通道属性。	输入

参数名称

描述

输入/输出

chn

PCIV通道号。

取值范围：[0, OT_PCIV_MAX_CHN_NUM)。

输入

attr

PCIV通道属性。

输入

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。

【需求】

头文件：ot_common_pciv.h、ss_mpi_pciv.h
库文件：libss_mpi.a libss_pciv.a

【注意】

创建PCIV通道之前需要调用ss_mpi_pciv_malloc_chn_buf分配图像缓冲块。
PCIV通道属性包含以下参数：
- 目标图像属性（pic_attr）：配置通道图像的宽、高、像素格式等信息。
- 图像缓冲块大小（blk_size）：每块图像缓冲块应该与一帧目标图像大小一致。
- 图像缓冲块个数（blk_cnt）：取值范围为1～OT_PCIV_MAX_BUF_NUM。建议缓冲块的个数为5个，同时可以根据传输业务适当的增加或者减少。
- 图像缓冲块物理地址（phys_addr）：图像接收方的buffer中每块缓冲块的物理地址，即ss_mpi_pciv_malloc_chn_buf得到的物理地址（只能使用该地址，使用其他地址则返回失败），用户可以通过PCIe消息传输将地址信息传递给图像发送方。
- 对端PCIe设备信息（remote_obj）：与当前本地PCIe通道绑定的对端PCIe 设备id号及PCIV通道号。不允许从片绑定从片，多个通道绑定到同一个通道，同一个通道绑定到多个通道，即遵守从片到主片的通道一一对应的原则。
- 在SS528V100/ SS625V100作为从片通过PCIV绑定与其他解决方案进行级联时，如果传输的是LINE压缩格式，需要留意，如果发现图像显示异常(UV反转)，需要在从片上多经过一次VGS或VPSS进行处理。
用户创建PCIV通道时，需要具有绑定关系的PCIV通道都进行创建，否则会造成业务异常。
主从片在创建PCIV通道的时候，需要用户保证主从片间有绑定关系的PCIV通道属性除了remote_obj之外保持一致。
重复创建通道会返回失败，重新创建需要与ss_mpi_pciv_destroy_chn配合使用。

【举例】

无。

【相关主题】

ss_mpi_pciv_malloc_chn_buf
ss_mpi_pciv_destroy_chn

ss_mpi_pciv_destroy_chn¶

【描述】

销毁PCIV通道。

【语法】

td_s32 ss_mpi_pciv_destroy_chn(ot_pciv_chn chn);

【参数】

参数名称	描述	输入/输出
chn	PCIV通道号。取值范围：[0, OT_PCIV_MAX_CHN_NUM)。	输入

参数名称

描述

输入/输出

chn

PCIV通道号。

取值范围：[0, OT_PCIV_MAX_CHN_NUM)。

输入

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。

【需求】

头文件：ot_common_pciv.h、ss_mpi_pciv.h
库文件：libss_mpi.a libss_pciv.a

【注意】

如果未创建通道，直接返回成功。
若通道已启动，销毁通道前必须先停止通道，否则返回失败。

【举例】

无。

【相关主题】

ss_mpi_pciv_stop_chn
ss_mpi_pciv_create_chn

ss_mpi_pciv_start_chn¶

【描述】

启动PCIV通道。

【语法】

td_s32 ss_mpi_pciv_start_chn(ot_pciv_chn chn);

【参数】

参数名称	描述	输入/输出
chn	PCIV通道号。取值范围：[0, OT_PCIV_MAX_CHN_NUM)。	输入

参数名称

描述

输入/输出

chn

PCIV通道号。

取值范围：[0, OT_PCIV_MAX_CHN_NUM)。

输入

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。

【需求】

头文件：ot_common_pciv.h、ss_mpi_pciv.h
库文件：libss_mpi.a libss_pciv.a

【注意】

启动通道前必须先创建通道，否则返回失败。
如果已经启动通道，则直接返回成功。
启动通道的具体行为取决于其绑定的通道类型：
- 从片前端绑定的是VI/VPSS/VDEC/虚拟VO：先将图像加工处理为配置的目标图像，然后通过PCIe发送到对端。
- 主片后端绑定的是VPSS/VO/VENC：接收到从片发送过来的图像后，将图像送入后端进行其他操作。

【举例】

无。

【相关主题】

ss_mpi_pciv_create_chn

ss_mpi_pciv_stop_chn¶

【描述】

停止PCIV通道。

【语法】

td_s32 ss_mpi_pciv_stop_chn(ot_pciv_chn chn);

【参数】

参数名称	描述	输入/输出
chn	PCIV通道号。取值范围：[0, OT_PCIV_MAX_CHN_NUM)。	输入

参数名称

描述

输入/输出

chn

PCIV通道号。

取值范围：[0, OT_PCIV_MAX_CHN_NUM)。

输入

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。

【需求】

头文件：ot_common_pciv.h、ss_mpi_pciv.h
库文件：libss_mpi.a libss_pciv.a

【注意】

如果未启动通道，则直接返回成功。

【举例】

无。

【相关主题】

ss_mpi_pciv_create_chn

ss_mpi_pciv_set_chn_attr¶

【描述】

设置PCIV通道的属性。

【语法】

td_s32 ss_mpi_pciv_set_chn_attr(ot_pciv_chn chn, const ot_pciv_attr *attr);

【参数】

参数名称	描述	输入/输出
chn	PCIV通道号。取值范围：[0, OT_PCIV_MAX_CHN_NUM)。	输入
attr	PCIV通道属性结构体指针。	输入

参数名称

描述

输入/输出

chn

PCIV通道号。

取值范围：[0, OT_PCIV_MAX_CHN_NUM)。

输入

attr

PCIV通道属性结构体指针。

输入

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。

【需求】

头文件：ot_common_pciv.h、ss_mpi_pciv.h
库文件：libss_mpi.a libss_pciv.a

【注意】

设置属性前必须先创建通道。
如果通道已经启动，则不允许设置通道属性。
若需要更改缓存块，则需要调用ss_mpi_pciv_free_chn_buf即可释放以后重新调用ss_mpi_pciv_malloc_chn_buf进行分配。
在设置PCIV通道属性时，用户保证主从片间有绑定关系的PCIV通道同步设置，且通道属性除了remote_obj之外保持一致，否则可能会造成业务异常或错误。

【举例】

无。

【相关主题】

ss_mpi_pciv_stop_chn
ss_mpi_pciv_create_chn

ss_mpi_pciv_get_chn_attr¶

【描述】

获取PCIV通道的属性。

【语法】

td_s32 ss_mpi_pciv_get_chn_attr(ot_pciv_chn chn, ot_pciv_attr *attr);

【参数】

参数名称	描述	输入/输出
chn	PCIV通道号。取值范围：[0, OT_PCIV_MAX_CHN_NUM)。	输入
attr	PCIV通道属性结构体指针。	输出

参数名称

描述

输入/输出

chn

PCIV通道号。

取值范围：[0, OT_PCIV_MAX_CHN_NUM)。

输入

attr

PCIV通道属性结构体指针。

输出

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。

【需求】

头文件：ot_common_pciv.h、ss_mpi_pciv.h
库文件：libss_mpi.a libss_pciv.a

【注意】

必须先创建通道，才能获取通道属性。
创建通道时会设置默认属性。

【举例】

无。

【相关主题】

ss_mpi_pciv_create_chn
ss_mpi_pciv_set_chn_attr

ss_mpi_pciv_show_chn¶

【描述】

显示（传输）PCIV图像。

与ss_mpi_pciv_hide_chn接口配合使用，用于控制是否通过DMA传输图像数据到PCIe对端设备。

【语法】

td_s32 ss_mpi_pciv_show_chn(ot_pciv_chn chn);

【参数】

参数名称	描述	输入/输出
chn	PCIV通道号。取值范围：[0, OT_PCIV_MAX_CHN_NUM)。	输入

参数名称

描述

输入/输出

chn

PCIV通道号。

取值范围：[0, OT_PCIV_MAX_CHN_NUM)。

输入

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。

【需求】

头文件：ot_common_pciv.h、ss_mpi_pciv.h
库文件：libss_mpi.a libss_pciv.a

【注意】

PCIV通道创建时默认为显示PCIV图像，即发送端会传输实际图像数据到接收端。

【举例】

无。

【相关主题】

ss_mpi_pciv_hide_chn

ss_mpi_pciv_hide_chn¶

【描述】

隐藏（不传输）PCIV图像。

与ss_mpi_pciv_show_chn接口配合使用，用于控制是否通过DMA传输图像数据到PCIe对端设备。

【语法】

td_s32 ss_mpi_pciv_hide_chn(ot_pciv_chn chn);

【参数】

参数名称	描述	输入/输出
chn	PCIV通道号。取值范围：[0, OT_PCIV_MAX_CHN_NUM)。	输入

参数名称

描述

输入/输出

chn

PCIV通道号。

取值范围：[0, OT_PCIV_MAX_CHN_NUM)。

输入

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。

【需求】

头文件：ot_common_pciv.h、ss_mpi_pciv.h
库文件：libss_mpi.a libss_pciv.a

【注意】

PCIV通道创建时默认为显示PCIV图像，即发送端会传输实际图像数据到接收端。
显示/隐藏PCIV图像接口，一般用于接收端进行VO同步回放的应用场景。如果隐藏PCIV图像，发送端仍会从VI或VDEC取图像数据，但图像数据并不通过PCIe传输到接收端，而是只传输时间戳等信息，接收端会将带时间戳的图像信息发送给VO，但此时显示的图像数据不正确，因此此时对应的VO通道应该设置为不显示(ss_mpi_vo_hide_chn)，调用ss_mpi_pciv_show_chn接口恢复显示时，也需要将对应的VO通道设置为显示(ss_mpi_vo_show_chn)。

注：ss_mpi_vo_hide_chn和ss_mpi_vo_show_chn请参考《MPP 媒体处理软件V5.0开发参考》“视频输出”章节。

【举例】

无。

【相关主题】

ss_mpi_pciv_show_chn

ss_mpi_pciv_create_window_vb¶

【描述】

创建PCIV窗口专用缓存池。

用于在PCIe从片上创建一个专用的VideoBuffer缓存池（基于名称为“window”的MMZ区域）。此专用VideoBuffer缓存池与接口ss_mpi_vb_set_cfg配置的缓存池概念类似；创建此缓存池的目的是用于实现主片发起DMA数据传输及共享。

【语法】

td_s32 ss_mpi_pciv_create_window_vb(const ot_pciv_window_vb_cfg *cfg);

【参数】

参数名称	描述	输入/输出
cfg	PCIV缓存池结构体指针。	输入

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。

【需求】

头文件：ot_common_pciv.h、ss_mpi_pciv.h
库文件：libss_mpi.a libss_pciv.a

【注意】

在PCIe主片上不需要创建专用的VideoBuffer缓存池，因此该接口不支持在主片上调用，在主片上调用此接口时，返回失败。
该接口只能调用一次，多次调用返回OT_ERR_PCIV_BUSY。

【举例】

参考ss_mpi_pciv_free_window_buf接口举例。

【相关主题】

无

ss_mpi_pciv_destroy_window_vb¶

【描述】

销毁PCIV窗口专用缓存池。

【语法】

td_s32 ss_mpi_pciv_destroy_window_vb(td_void);

【参数】

无。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。

【需求】

头文件：ot_common_pciv.h、ss_mpi_pciv.h
库文件：libss_mpi.a libss_pciv.a

【注意】

与ss_mpi_pciv_create_window_vb接口配对使用。
与ss_mpi_pciv_create_window_vb接口相同，该接口只能在从片上调用，在主片上调用此接口时，返回失败。

【举例】

参考ss_mpi_pciv_free_window_buf接口举例。

【相关主题】

ss_mpi_pciv_create_window_vb

ss_mpi_pciv_malloc_window_buf¶

【描述】

分配PCIV缓存。

用于分配PCIe主从片间用户DMA数据传输的相关内存，可以一次分配多块指定大小的内存块。

【语法】

td_s32 ss_mpi_pciv_malloc_window_buf(td_u32 blk_size, td_u32 blk_cnt, td_phys_addr_t phys_addr[]);

【参数】

参数名称	描述	输入/输出
blk_size	内存块大小。	输入
blk_cnt	内存块个数。	输入
phys_addr	物理地址数组。	输出

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。

【需求】

头文件：ot_common_pciv.h、ss_mpi_pciv.h
库文件：libss_mpi.a libss_pciv.a

【注意】

为了对称使用，主从片使用PCIV缓存时，统一使用此接口。
- 在PCIe主片上调用此接口时，直接从MPP的公共VideoBuffer中分配缓存块。需要保证VideoBuffer公共缓存池中有足够满足条件的缓存块，否则返回失败，VideoBuffer公共缓存池的相关概念请参见《MPP媒体处理软件Vx.0开发参考》中“系统控制”章节相关内容。
- 在PCIe从片上调用此接口时，从PCIV专用缓存池中分配缓存块，因此必须先调用ss_mpi_pciv_create_window_vb接口创建PCIV专用缓存池（其内存从名为“window”的MMZ空间中分配）。
此接口需要用户保证输入的地址数量参数blk_cnt与地址数组phys_addr长度匹配。
不应重复分配(使用相同的phys_addr重复分配，后面分配的地址会覆盖前面的)，需要与接口ss_mpi_pciv_free_window_buf配合使用，否则会造成释放失败或程序异常。

【举例】

参考ss_mpi_pciv_free_window_buf接口举例。

【相关主题】

ss_mpi_pciv_create_window_vb
ss_mpi_pciv_free_window_buf

ss_mpi_pciv_free_window_buf¶

【描述】

释放PCIV缓存。

【语法】

td_s32 ss_mpi_pciv_free_window_buf(td_u32 blk_cnt, const td_phys_addr_t phys_addr[]);

【参数】

参数名称	描述	输入/输出
blk_cnt	内存块个数，取值范围大于零。	输入
phys_addr	物理地址数组。	输入

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。

【需求】

头文件：ot_common_pciv.h、ss_mpi_pciv.h
库文件：libss_mpi.a libss_pciv.a

【注意】

与接口ss_mpi_pciv_malloc_window_buf配合使用，否则会造成释放失败或程序异常。
释放所有缓存块时输入参数blk_cnt与phys_addr需要保持一致
支持部分释放PCIV缓存，需用户自行对phys_addr进行相应的偏移计算，具体用法参考样例
允许重复释放，返回成功

【举例】

以下样例为从片样例，若主片分配/释放PCIV缓存，则需要去掉vb池创建销毁部分

全部释放

td_s32 ret;
td_u32 blk_size = 1024;
td_u32 blk_cnt  = 3;
td_phys_addr_t phys_addr[3];
ot_pciv_window_vb_cfg cfg;
 
cfg.pool_cnt = 1;
cfg.blk_size[0] = blk_size;
cfg.blk_cnt[0] = blk_cnt;
 
// 创建PCIV窗口专用缓存池
ret = ss_mpi_pciv_create_window_vb(&cfg);
if (ret == TD_SUCCESS) {
         return TD_FAILURE;
}
// 分配PCIV缓存
ret = ss_mpi_pciv_malloc_window_buf(blk_size, blk_cnt, phys_addr);
if (ret == TD_SUCCESS) {
ss_mpi_pciv_destroy_window_vb();
         return TD_FAILURE;
}
 
// 释放全部buffer
ss_mpi_pciv_free_window_buf(blk_cnt, phys_addr);
 
// 销毁PCIV窗口专用缓存池
ss_mpi_pciv_destroy_window_vb();

部分释放

td_s32 ret;
td_u32 blk_size = 1024;
td_u32 blk_cnt  = 3;
td_phys_addr_t phys_addr[3];
ot_pciv_window_vb_cfg cfg;
 
cfg.pool_cnt = 1;
cfg.blk_size[0] = blk_size;
cfg.blk_cnt[0] = blk_cnt;
 
// 创建PCIV窗口专用缓存池
ret = ss_mpi_pciv_create_window_vb(&cfg);
if (ret == TD_SUCCESS) {
         return TD_FAILURE;
}
 
// 分配PCIV缓存
ret = ss_mpi_pciv_malloc_window_buf(blk_size, blk_cnt, phys_addr);
if (ret == TD_SUCCESS) {
ss_mpi_pciv_destroy_window_vb();
         return TD_FAILURE;
}
 
// 释放第一个buffer
ss_mpi_pciv_free_window_buf(1, phys_addr); 
// 从第二个开始，释放两个buffer
ss_mpi_pciv_free_window_buf(2, phys_addr + 1);
 
// 销毁PCIV窗口专用缓存池
ss_mpi_pciv_destroy_window_vb();

【相关主题】

ss_mpi_pciv_malloc_window_buf

ss_mpi_pciv_dma_task¶

【描述】

创建PCIe DMA传输任务。

用于用户发起一次或多次PCIe DMA传输任务。

【语法】

td_s32 ss_mpi_pciv_dma_task(const ot_pciv_dma_task *task);

【参数】

参数名称	描述	输入/输出
task	PCIe任务结构体指针。	输入

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。

【需求】

头文件：ot_common_pciv.h、ss_mpi_pciv.h
库文件：libss_mpi.a libss_pciv.a

【注意】

此接口为阻塞接口，即等到DMA任务完成后接口才返回。
接口返回表示DMA任务完成，发起DMA读之前(对端数据准备)或DMA写之后(对端数据处理)，需要通过pcie消息(参考sample)通知对端进行相应处理。
源地址和目标地址及区间必须是合法的物理地址区间。
- 主片发起DMA任务时，主片合法物理地址区间为主片MPP的合法地址区间，从片的合法物理地址为“window”的MMZ区域的地址空间；
- 从片发起DMA任务时，主从片的合法物理地址区间为对应设备的MPP合法地址区间；
- 建议在ss_mpi_pciv_malloc_window_buf接口分配的内存区间内进行数据传输，否则可能造成内存冲突或返回失败。

【举例】

无。

【相关主题】

ss_mpi_pciv_malloc_window_buf

ss_mpi_pciv_get_local_id¶

【描述】

获取自身PCIe节点设备id。

【语法】

td_s32 ss_mpi_pciv_get_local_id(td_s32 *id);

【参数】

参数名称	描述	输入/输出
id	PCIe节点设备id。	输出

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。

【需求】

头文件：ot_common_pciv.h、ss_mpi_pciv.h
库文件：libss_mpi.a libss_pciv.a

【注意】

主片的PCIe设备号为0；
从片的PCIe设备号大于0；

【举例】

无。

【相关主题】

无

ss_mpi_pciv_enum_chip¶

【描述】

获取所有与运行此接口的PCIe节点连接其它PCIe节点的设备ID号。

【语法】

td_s32 ss_mpi_pciv_enum_chip(ot_pciv_enum_chip *chips);

【参数】

参数名称	描述	输入/输出
chips	保存与此节点连接的其它PCIe节点的设备信息。	输出

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。

【需求】

头文件：ot_common_pciv.h、ss_mpi_pciv.h
库文件：libss_mpi.a libss_pciv.a

【注意】

在主片上可以获取所有从片的PCIe节点的设备ID号。
在从片上则可以获取与此从片连接的主片的PCIe节点的设备ID号。

【举例】

无

【相关主题】

无

ss_mpi_pciv_get_window_base¶

【描述】

获取PCIe窗口信息。

【语法】

td_s32 ss_mpi_pciv_get_window_base(td_s32 chip_id, ot_pciv_window_base *base);

【参数】

参数名称	描述	输入/输出
chip_id	PCIe 设备ID号。取值范围：[0, OT_PCIV_MAX_CHIP_NUM) 主片设备ID号为0，从片设备ID大于0。	输入
base	PCIe窗口信息结构体指针。	输出

参数名称

描述

输入/输出

chip_id

PCIe 设备ID号。

取值范围：[0, OT_PCIV_MAX_CHIP_NUM)

主片设备ID号为0，从片设备ID大于0。

输入

base

PCIe窗口信息结构体指针。

输出

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。

【需求】

头文件：ot_common_pciv.h、ss_mpi_pciv.h
库文件：libss_mpi.a libss_pciv.a

【注意】

在主片上可以获取所有从片的PCIe窗口信息。
在从片上则只能获取本片的可预取空间的AHB地址信息。
在主片上调用此接口时，chip_id为指定从片的PCIe设备ID号（大于0）,否则返回失败。
在从片上调用此接口时，chip_id必须置为0，否则返回失败。
主片通常先调用ss_mpi_pciv_enum_chip接口获取各从片id后再获取对应窗口基址，从片一般不使用该接口。

【举例】

无。

【相关主题】

ss_mpi_pciv_enum_chip

数据类型¶

PCIV数据类型定义如下：

OT_PCIV_MAX_CHN_NUM：PCIV最大通道数。
OT_PCIV_MAX_BUF_NUM：PCIV最大通道buffer数。
OT_PCIV_MAX_CHIP_NUM：级联系统中最大PCIV设备数。
OT_PCIV_TIMER_EXPIRES：定时器中断等待时长。
OT_PCIV_MAX_DMA_BLK：一次DMA任务最大DMA数据块个数。
OT_PCIV_MAX_VB_CNT：在从片PCIe窗口地址中创建的最多VB池个数。
ot_pciv_chn：定义pciv通道号。
ot_pciv_enum_chip：定义设备枚举信息。
ot_pciv_remote_obj：定义PCIV对端目标结构体。
ot_pciv_pic_attr：定义PCIV图像属性结构体。
ot_pciv_attr：定义PCIV通道属性结构体。
ot_pciv_window_vb_cfg：定义PCIe Window VideoBuffer配置结构体。
ot_pciv_window_base：定义PCIe Window信息结构体。
ot_pciv_dma_blk：定义PCIe DMA数据块结构体。
ot_pciv_dma_task：定义PCIe DMA任务结构体。

OT_PCIV_MAX_CHN_NUM¶

【说明】

PCIV最大通道数。

【定义】

SS528V100/SS625V100/SS626V100：

#define OT_PCIV_MAX_CHN_NUM                128

SS928V100：

#define OT_PCIV_MAX_CHN_NUM                16

【解决方案差异】

解决方案	描述
SS528V100/SS625V100/SS626V100	最多128个通道
SS928V100	最多16个通道

【成员】

无

OT_PCIV_MAX_BUF_NUM¶

【说明】

PCIV最大通道buffer数。

【定义】

#define OT_PCIV_MAX_BUF_NUM    16

【成员】

无

OT_PCIV_MAX_CHIP_NUM¶

【说明】

级联系统中最大PCIV设备数量。

【定义】

#define OT_PCIV_MAX_CHIP_NUM   32

【成员】

无

OT_PCIV_TIMER_EXPIRES¶

【说明】

定时器中断等待时长，单位ms。

【定义】

#define OT_PCIV_TIMER_EXPIRES  10

【成员】

无

OT_PCIV_MAX_DMA_BLK¶

【说明】

一次DMA任务最大DMA数据块个数。

【定义】

#define OT_PCIV_MAX_DMA_BLK    128

【成员】

无

OT_PCIV_MAX_VB_CNT¶

【说明】

在从片PCIe窗口地址中创建的最多VB池个数。

【定义】

#define OT_PCIV_MAX_VB_CNT     8

【成员】

无

ot_pciv_chn¶

【说明】

定义PCIV通道号。

【定义】

typedef td_s32 ot_pciv_chn;

【成员】

无

ot_pciv_enum_chip¶

【说明】

定义PCIV对端目标结构体。

【定义】

typedef struct {
    td_u32 chip_num;  
    td_s32 chip_id[OT_PCIV_MAX_CHIP_NUM]; 
} ot_pciv_enum_chip;

【成员】

成员名称	描述
chip_num	对端设备个数。若为主片：chip_num为连接到主片的从片个数。若为从片：chip_num为1
chip_id	对端设备id。若为主片：chip_id的前chip_num个值为连接到主片的从片的设备id数组。若为从片：chip_id[0] 的值为0

成员名称

描述

chip_num

对端设备个数。

若为主片：chip_num为连接到主片的从片个数。

若为从片：chip_num为1

chip_id

对端设备id。

若为主片：chip_id的前chip_num个值为连接到主片的从片的设备id数组。

若为从片：chip_id[0] 的值为0

【注意事项】

无

ot_pciv_remote_obj¶

【说明】

定义PCIV对端目标结构体。

【定义】

typedef struct {
    td_s32       chip_id;  
    ot_pciv_chn   pciv_chn; 
} ot_pciv_remote_obj;

【成员】

成员名称	描述
chip_id	对端PCIe设备id。取值范围：[0, OT_PCIV_MAX_CHIP_NUM)。
pciv_chn	对端PCIe设备的PCIV通道号。取值范围：[0, OT_PCIV_MAX_CHN_NUM)。

成员名称

描述

chip_id

对端PCIe设备id。

取值范围：[0, OT_PCIV_MAX_CHIP_NUM)。

pciv_chn

对端PCIe设备的PCIV通道号。

取值范围：[0, OT_PCIV_MAX_CHN_NUM)。

【注意事项】

无

ot_pciv_pic_attr¶

【说明】

定义PCIV图像属性结构体。

【定义】

typedef struct {
    td_u32              width;
    td_u32              height;
    td_u32              stride[OT_MAX_COLOR_COMPONENT];
    ot_video_field     field;
    ot_pixel_format    pixel_format;
    ot_dynamic_range   dynamic_range;
    ot_compress_mode   compress_mode;
    ot_video_format    video_format;
} ot_pciv_pic_attr;

【成员】

成员名称	描述
width	图像宽度。取值范围：大于0，2对齐。
height	图像高度。取值范围：大于0，2对齐。
stride	图像跨度。取值范围：stride[0]大于等于width，16对齐。 stride后续参数保留，暂未使用。 OT_MAX_COLOR_COMPONENT具体描述请参见《MPP 媒体处理软件V5.0开发参考》的“系统控制”章节。
field	图像帧场选择。此项保留，暂未使用范围描述请参见《MPP 媒体处理软件V5.0开发参考》的“系统控制”章节。
pixel_format	图像像素格式。目前支持PIXEL_FORMAT_YVU_SEMIPLANAR_420、PIXEL_FORMAT_YVU_SEMIPLANAR_422、PIXEL_FORMAT_YUV_SEMIPLANAR_420、PIXEL_FORMAT_YUV_SEMIPLANAR_422、PIXEL_FORMAT_YUV_400。 ot_pixel_format具体描述请参见《MPP媒体处理软件V5.0开发参考》的“系统控制”章节。
dynamic_range	目标图像动态范围。取值范围：OT_DYNAMIC_RANGE_SDR8 ot_dynamic_range具体描述请参见《MPP媒体处理软件V5.0开发参考》的“系统控制”章节。
compress_mode	目标图像压缩模式。 ot_compress_mode具体描述请参见《MPP媒体处理软件V5.0开发参考》的“系统控制”章节。
video_format	目标图像视频格式。 ot_video_format具体描述请参见《MPP媒体处理软件V5.0开发参考》的“系统控制”章节。

【注意事项】

PCIV可通过VGS添加OSD或进行缩放，图像格式转换操作，具体能力请参见《MPP媒体处理软件V5.0开发参考》的“视频图形子系统”章节。

ot_pciv_attr¶

【说明】

定义PCIV属性结构体。

【定义】

typedef struct {
    ot_pciv_pic_attr     pic_attr;
    td_u32             blk_size;
    td_u32             blk_cnt;
    td_phys_addr_t     phys_addr[OT_PCIV_MAX_BUF_NUM];
    ot_pciv_remote_obj   remote_obj;
} ot_pciv_attr;

【成员】

成员名称	描述
pic_attr	图像属性。
blk_size	图像缓存块尺寸。取值范围：不应小于所传输图像实际尺寸。为节约性能，可参考《MPP 媒体处理软件V5.0开发参考》的“系统控制”章节下视频缓存池小节中提供的视频缓存池大小计算接口简介所提供的计算方式计算该尺寸。注意：由于部分图像格式数据分布存在差异，需要额外信息才能计算大小，如VDEC输出YUV大小，SS928V100中VPSS输出的紧凑段压缩图像等，PCIV内部对于blk_size的校验可能不准确，请以实际提供的计算公式为准，否则可能出现解压错误，图像不完整等未知错误。
blk_cnt	图像缓存块个数。取值范围：[1, OT_PCIV_MAX_BUF_NUM]
phys_addr	图像缓存块的物理地址。
remote_obj	对端PCIe信息。

【注意事项】

无

ot_pciv_window_vb_cfg¶

【说明】

定义PCIe Window VideoBuffer池结构体。

【定义】

typedef struct {
    td_u32 pool_cnt;
    td_u32 blk_size[OT_PCIV_MAX_VB_CNT];
    td_u32 blk_cnt[OT_PCIV_MAX_VB_CNT];
} ot_pciv_window_vb_cfg;

【成员】

成员名称	描述
pool_cnt	缓存池个数。取值范围：[1，OT_PCIV_MAX_VB_CNT]
blk_size	每个缓存池缓存块大小。取值范围：[1，7M]
blk_cnt	每个缓存池缓存块个数。取值范围：大于0。

成员名称

描述

pool_cnt

缓存池个数。

取值范围：[1，OT_PCIV_MAX_VB_CNT]

blk_size

每个缓存池缓存块大小。

取值范围：[1，7M]

blk_cnt

每个缓存池缓存块个数。

取值范围：大于0。

【注意事项】

总大小不超过7M。

ot_pciv_window_base¶

【说明】

定义PCIe Window信息结构体。

【定义】

typedef struct {
    td_s32           chip_id;
    td_phys_addr_t   np_addr;
    td_phys_addr_t   pf_addr;
    td_phys_addr_t   cfg_addr;
    td_phys_addr_t   pf_ahb_addr;
} ot_pciv_window_base;

【成员】

成员名称	描述
chip_id	PCIe设备的设备序号。取值范围：[0, OT_PCIV_MAX_CHIP_NUM)
np_addr	NP基地址。
pf_addr	PF基地址。
cfg_addr	CFG基地址。
pf_ahb_addr	PF AHB侧基地址。

【注意事项】

无

ot_pciv_dma_blk¶

【说明】

定义PCIe DMA数据块结构体。

【定义】

typedef struct {
    td_phys_addr_t src_addr;
    td_phys_addr_t dst_addr;
    td_u32           size;
} ot_pciv_dma_blk;

【成员】

成员名称	描述
src_addr	源地址，大于0，4对齐的合法物理地址。
dst_addr	目标地址，大于0，4对齐的合法物理地址。
size	数据块大小。主片发起DMA任务时，从片取值范围：(0, 7M]。其他情形取值范围：大于0

成员名称

描述

src_addr

源地址，大于0，4对齐的合法物理地址。

dst_addr

目标地址，大于0，4对齐的合法物理地址。

size

数据块大小。

主片发起DMA任务时，从片取值范围：(0, 7M]。

其他情形取值范围：大于0

【注意事项】

主片发起DMA任务时，从片对应的数据块区间需在名为window的区域范围。

ot_pciv_dma_task¶

【说明】

定义PCIe DMA任务结构体。

【定义】

typedef struct {
    td_u32                blk_cnt;
    td_bool                is_read;
    ot_pciv_dma_blk       ATTRIBUTE *dma_blk;
} ot_pciv_dma_task;

【成员】

成员名称

描述

blk_cnt

任务个数。

取值范围：[1, OT_PCIV_MAX_DMA_BLK]

is_read

是否DMA读操作。

取值范围：[0,1]

dma_blk

DMA数据块结构体指针。

【注意事项】

无

错误码¶

错误代码	宏定义	描述
0xa01a8003	OT_ERR_PCIV_INVALID_CHN_ID	PCIV通道号无效
0xa01a8007	OT_ERR_PCIV_ILLEGAL_PARAM	PCIV参数设置无效
0xa01a8008	OT_ERR_PCIV_EXIST	PCIV通道已经存在
0xa01a8009	OT_ERR_PCIV_UNEXIST	PCIV通道不存在
0xa01a800a	OT_ERR_PCIV_NULL_PTR	输入参数空指针错误
0xa01a800b	OT_ERR_PCIV_NOT_CFG	PCIV通道属性未配置
0xa01a800c	OT_ERR_PCIV_NOT_SUPPORT	操作不支持
0xa01a800d	OT_ERR_PCIV_NOT_PERM	操作不允许
0xa01a8014	OT_ERR_PCIV_NO_MEM	分配内存失败
0xa01a8015	OT_ERR_PCIV_NO_BUF	分配VideoBuffer失败
0xa01a8016	OT_ERR_PCIV_BUF_EMPTY	PCIV缓存为空
0xa01a8017	OT_ERR_PCIV_BUF_FULL	PCIV缓存为满
0xa01a8018	OT_ERR_PCIV_SYS_NOT_READY	系统未初始化
0xa01a8022	OT_ERR_PCIV_BUSY	系统忙
0xa01a8020	OT_ERR_PCIV_TIMEOUT	任务超时

Proc调试信息¶

PCIV¶

【调试信息】

从片PCIV调试信息。

# cat /proc/umap/pciv
 
[PCIV] Version: [V1.0.0.0 B010 Release], Build Time:[Jun  2 2021, 20:43:44]
 
---------------------------pciv channel attr-----------------------------------------------
pciv_chn   width  height  stride   field  pixel_format buf_cnt  buf_size      phys_addr[0]
       0    1920    1080    1920     frm     YVU-SP420       6   3136320          737e6000
       1    1920    1080    1920     frm     YVU-SP420       6   3136320          749d8800
       2    1920    1080    1920     frm     YVU-SP420       6   3136320          75bcb000
       3    1920    1080    1920     frm     YVU-SP420       6   3136320          76dbd800
 
---------------------------pciv channel status-----------------------------------------
pciv_chn is_hide remote_chip  remote_chn     get_cnt    send_cnt    resp_cnt    lost_cnt  notify_cnt          buf_status
       0       N           0           0         758         758         758           0         757         0 0 0 0 0 0
       1       N           0           1         759         759         758           0         757         1 0 0 0 0 0
       2       N           0           2         758         758         758           0         756         1 0 0 0 0 0
       3       N           0           3         757         757         757           0         756         0 0 0 0 0 0
 
--------------------pciv message status---------------------------------------
pciv_chn      rdone_gap  max_rdone_gap  min_rdone_gap      wdone_gap  max_wdone_gap  min_wdone_gap
       0          60005          79992          39985              0              0              0
       1          59999          70016          29992              0              0              0
       2          50001          89978          39944              0              0              0
       3          50002          99988          39981              0              0              0 

主片PCIV调试信息。

# cat /proc/umap/pciv
 
[PCIV] Version: [V1.0.0.0 B010 Release], Build Time:[Jun  2 2021, 20:43:44]
 
-------------------------pciv channel attr-------------------------------------------------
pciv_chn   width  height  stride   field  pixel_format buf_cnt  buf_size      phys_addr[0]
       0    1920    1080    1920     frm     YVU-SP420       6   3136320          737e6000
       1    1920    1080    1920     frm     YVU-SP420       6   3136320          749d8800
       2    1920    1080    1920     frm     YVU-SP420       6   3136320          75bcb000
       3    1920    1080    1920     frm     YVU-SP420       6   3136320          76dbd800
 
--------------------------pciv channel status-------------------------------------------------------------
pciv_chn is_hide remote_chip  remote_chn     get_cnt    send_cnt    resp_cnt    lost_cnt  notify_cnt          buf_status
       0       N           1           0         601         601         601           0           0         0 0 0 0 0 0
       1       N           1           1         601         601         601           0           0         0 0 0 0 0 0
       2       N           1           2         601         601         600           0           0         1 0 0 0 0 0
       3       N           1           3         600         600         600           0           0         0 0 0 0 0 0
 
----------------------------pciv message status-----------------------------------------------
pciv_chn   rdone_gap  max_rdone_gap  min_rdone_gap     wdone_gap  max_wdone_gap  min_wdone_gap
       0          0            0            0          55685          75954      41764
       1          0            0            0          55685          75940      27834
       2          0            0            0          55685          90003      41781
       3          0            0            0          55670         104042     41762

【调试信息分析】

记录当前已启用的PCIV通道的属性和工作状态。

【参数说明】

参数		描述
pciv channel attr	pciv_chn	PCIV通道号。
	width	目标图像宽度。
	height	目标图像高度。
	stride	目标图像Stride[0]。
	field	目标图像帧场模式。
	pixel_format	目标图像像素格式。
	buf_cnt	目标图像缓冲块个数。
	buf_size	目标图像缓冲块大小，以字节为单位。
	phys_addr[0]	目标图像第一个缓冲块的起始物理地址。
pciv channel status	pciv_chn	PCIV通道号。
	is_hide	通道是否隐藏：Y隐藏/N显示
	remote_chip	对端PCIe设备序号。
	remote_chn	对端PCIV通道号。
	get_cnt	发送端表示从pciv firmware端获取的图像帧数目；接收端表示通过PCIe DMA 接收到的图像帧数目。
	send_cnt	发送端表示通过PCIe DMA成功发送的图像帧数目；接收端表示将接收的图像发送到pciv firmware的图像帧数目
	resp_cnt	发送端表示PCIe DMA任务回调，发送write done消息次数；接收端表示图像使用完成后的释放图像，成功发送read done消息次数。
	lost_cnt	发送端表示未成功通过PCIe DMA发送的图像帧数目；接收端表示接收到的图像未成功发送到后端的图像帧数目。
	notify_cnt	从片发给主片的图像帧，主片使用完后发给从片的通知次数
	buf_status	发送端表示目标图像缓冲块的空闲状态；接收端表示本地接收图像缓冲块的空闲状态。 0：free状态； 1：busy状态； 2：hold状态。
pciv message status	pciv_chn	PCIV通道号。
	rdone_gap	最后一次发送端收到接收端消息的时间间隔(us)。
	max_rdone_gap	发送端收到接收端消息的最大时间间隔(us)。
	min_rdone_gap	发送端收到接收端消息的最小时间间隔(us)。
	wdone_gap	最后一次接收端收到发送端消息的时间间隔(us)。
	max_wdone_gap	接收端收到发送端消息的最大时间间隔(us)。
	min_wdone_gap	接收端收到发送端消息的最小时间间隔(us)。

PCIV FMW¶

【调试信息】

从片PCIV FMW 调试信息

# cat /proc/umap/pcivfmw
 
[PCIVF] Version: [V1.0.0.0 B010 Release], Build Time:[Jun  2 2021, 20:43:44]
 
---------------------------pciv firmware channel info--------------------------------------
pciv_chn     get_cnt    send_cnt    resp_cnt    lost_cnt      new_do    old_undo  pool_id[0]
       0         759         758         758           0           0           0           0
       1         760         759         758           0           0           0           0
       2         759         758         758           0           0           0           0
       3         758         757         757           0           0           0           0
 
---------------------------pciv firmware channel picture attr info-------------------------
pciv_chn   width  height  stride  pixel_format dynamic  compress      video_format
       0    1920    1080    1920     YVU-SP420    SDR8       SEG            LINEAR
       1    1920    1080    1920     YVU-SP420    SDR8       SEG            LINEAR
       2    1920    1080    1920     YVU-SP420    SDR8       SEG            LINEAR
       3    1920    1080    1920     YVU-SP420    SDR8       SEG            LINEAR
 
------------------------pciv firmware channel queue info--------------------------------
pciv_chn  busy_num  free_num     state   timer_cnt
       0         0         6         0        2187
       1         0         6         0        2185
       2         0         6         0        2184
       3         0         6         0        2182
 
---------------------pciv firmware channel call vgs job info--------------------
pciv_chn   add_job_suc_cnt  add_job_fail_cnt   end_job_suc_cnt  end_job_fail_cnt
       0               759                 0               759                 0
       1               760                 0               760                 0
       2               759                 0               759                 0
       3               758                 0               758                 0
 
-------------------pciv firmware channel call vgs func info-------------------------------
trans_suc_cnt  trans_fail_cnt     osd_suc_cnt    osd_fail_cnt  trans_cb_cnt   osd_cb_cnt
    759               0             759               0             758             758
    760               0             760               0             759             754
    759               0             759               0             758             758
    758               0             758               0             757             757

主片PCIV FMW调试信息

# cat /proc/umap/pcivfmw
 
[PCIVF] Version: [V1.0.0.0 B010 Release], Build Time:[Jun  2 2021, 20:43:44]
 
-------------------pciv firmware channel info----------------------------------------------
pciv_chn     get_cnt    send_cnt    resp_cnt    lost_cnt      new_do    old_undo  pool_id[0]
       0         601         601         601           0           0           0           0
       1         601         601         601           0           0           0           0
       2         601         601         600           0           0           0           0
       3         600         600         600           0           0           0           0
 
---------------------pciv firmware channel picture attr info------------------------
pciv_chn   width  height  stride  pixel_format dynamic  compress    video_format
       0    1920    1080    1920     YVU-SP420    SDR8       SEG            LINEAR
       1    1920    1080    1920     YVU-SP420    SDR8       SEG            LINEAR
       2    1920    1080    1920     YVU-SP420    SDR8       SEG            LINEAR
       3    1920    1080    1920     YVU-SP420    SDR8       SEG            LINEAR
 
------------------pciv firmware channel queue info-------------------
pciv_chn  busy_num  free_num     state   timer_cnt
       0         0         6         0        1591
       1         0         6         0        1589
       2         0         6         0        1588
       3         0         6         0        1586
 
----------------pciv firmware channel call vgs job info--------------------
pciv_chn  add_job_suc_cnt  add_job_fail_cnt   end_job_suc_cnt  end_job_fail_cnt
       0                 0                 0                 0                 0
       1                 0                 0                 0                 0
       2                 0                 0                 0                 0
       3                 0                 0                 0                 0
 
----------------pciv firmware channel call vgs func info-------------------------------
trans_suc_cnt  trans_fail_cnt   osd_suc_cnt  osd_fail_cnt    trans_cb_cnt      osd_cb_cnt
     0               0               0               0               0               0
     0               0               0               0               0               0
     0               0               0               0               0               0
     0               0               0               0               0               0

【调试信息分析】

记录当前已启用的PCIV FMW通道的属性和工作状态。

【参数说明】

参数		描述
pciv firmware channel info	pciv_chn	PCIV通道号。
	get_cnt	发送端表示从VI或VDEC或VPSS或虚拟VO获取的图像帧数目；接收端表示通过PCIe DMA 接收到的图像帧数目。
	send_cnt	发送端表示成功调用VGS进行源图像处理的次数；接收端表示将接收的图像发送到VO/VPSS/VENC的图像帧数目。
	resp_cnt	发送端表示源图像VGS回调次数；接收端表示VO/VPSS/VENC使用完图像后的释放图像帧数目。
	lost_cnt	发送端表示未成功调用VGS处理源图像的次数（分配VB内存失败或者创建VGS任务失败）；接收端表示接收到的图像未成功发送到VO/VPSS/VENC的图像帧数目。
	new_do	发送端vpss query成功的次数。
	old_undo	发送端vpss query失败的次数。
	pool_id[0]	图像缓冲块所在的第一个VideoBuffer缓存池序号。
pciv firmware channel picture attr info	pciv_chn	PCIV通道号。
	width	目标图像宽度。
	height	目标图像高度。
	stride	目标图像stride[0]。
	pixel_format	目标图像像素格式。
	dynamic	目标图像动态范围。
	compress	目标图像压缩模式。
	video_format	目标图像视频格式。
pciv firmware channel queue info	pciv_chn	PCIV通道号。
	busy_num	PCIV通道上busy队列的节点数目
	free_num	PCIV通道上free队列的节点数目
	state	PCIV通道发送解码后图像时的通道状态
	timer_cnt	PCIV通道上，发送解码后图像的定时器运行次数
pciv firmware channel call vgs info（仅图像发送端有效）	pciv firmware channel call vgs job info
	pciv_chn	PCIV通道号。
	add_job_suc_cnt	PCIV成功提交给VGS的job次数
	add_job_fail_cnt	PCIV没有成功提交给VGS的job次数
	end_job_suc_cnt	PCIV结束VGS job成功的次数
	end_job_fail_cnt	PCIV结束VGS job失败的次数
	pciv firmware channel call vgs func info
	pciv_chn	PCIV通道号。
	trans_suc_cnt	PCIV添加VGS 转换数据成功的次数
	trans_fail_cnt	PCIV添加VGS 转换数据失败的次数
	osd_suc_cnt	PCIV添加VGS 打OSD成功的次数
	osd_fail_cnt	PCIV添加VGS打OSD失败的次数
	trans_cb_cnt	PCIV添加VGS 转换任务回调的次数
	osd_cb_cnt	PCIV添加VGS 打OSD任务回调的次数