8.2 Verilog TF 子程序
功能特性
TF (task/function) 子程序主要用于 Verilog 与用户 C 程序边界的两个方向上的数据传输。
TF 子程序总是以 tf_ 为前缀，定义在头文件 veriuser.h 中。所以用 C 语言写系统任务或函数时，都需要在 C 文件中添加 #include "veriuser.h" 。
TF 子程序用途可划分为：
- 获取系统任务的信息
- 获取参数列表信息
- 获取参数值
- 把参数值回传给系统任务
- 监视参数值的改变
- 获取仿真时间和调度事件的信息
- 算数运算
- 显示信息
- 管理维护任务
- 挂起、终止、保存、恢复等其他任务
完整的 TF 子程序及其简单用法说明参考下一节《8.3 TF 子程序列表》。
TF 子程序举例
PLI 子程序库函数数量繁多，如果一一举例说明需要大量的篇幅去总结。所以建议有需求时再去仔细研究个别子程序。下面只对 TF 中的一些子程序进行举例，主要说明使用 TF 子程序设计 Verilog 系统任务的基本流程。
设计需求
有时候为减小 C 语言文件编译后目的文件的大小，或按一定格式输出调试信息，软件中的打印函数可能不会使用 C 语言自带的 printf 函数，也不使用 TF 子程序里的 io_printf 函数，而是借助 PLI 接口并使用 Verilog 中的系统显示函数 ($display 或 $write) 完成用户自定义的软件打印函数。
本次设计一个软件打印函数，命名为 print_my，输出格式为"字符串+整形"。
设计分析
用户自定义的软件打印函数 print_my 只是一个不好看的皮囊，用来将打印信息传递给软件形参变量。为将打印信息传递到 Verilog 中，还需要一个 TF 子程序组建的系统任务，命名为 $send_my()。
需要说明的是，用 TF 子程序完成的系统任务一般要在 Verilog 代码中调用。软件直接调用该"系统任务"就相当于调用了一个软件函数，和 Verilog 代码中的相关变量的描述没有直接联系。所以在软件函数 print_my 中直接调用"软件函数" send_my 是没有意义的，就需要在 print_my 中加入一些特定的软件行为去触发系统任务 $send_my 被 Verilog 调用。
如果数字系统包含有 CPU，可以使用软件写总线或写 memory 然后 testbench 中监测相关信号变量的方法。本次设计规模较小，可采用另一种方法，即 Verilog 里一直执行系统任务 $send_my，在软件函数 print_my 中置全局变量来控制是否进行信息传输并打印的操作。
软件设计
软件设计代码如下，细节在注释中说明，保存到文件 print_gyc.c 中。
实例
//打印的字符串、整型数据、软件开始打印标志
char *str_mes ;
unsigned int int_mes ;
int flags = 0 ;
//===== define print_my() used in C ======
void print_my ( char * str_send , unsigned int int_send ) {
str_mes = str_send ;
int_mes = int_send ;
flags = 1 ;
}
//打印的字符串对应的ASCII码的字符型数据，原始字符型长度限制为100
//例如字符"1"对应的ASCII码0x31的字符型数据为0x33、0x31
char str_mes_format [ 200 ] ;
//TF 子程序传递字符串类型的数据时，只能传递相关进制格式的数据
//例如能传递"0xc0de1234",却不能传递 "www.xnip.cn"
//所以需要将原始的字符串数据转换为对应的ASCII码的字符型数据
void byte2hexstr ( char * str , char * dest , int len )
{
char tmp ;
int i ;
char stb [ 16 ] = { '0' , '1' , '2' , '3' , '4' , '5' , '6' , '7' , '8' , '9' , 'A' , 'B' , 'C' , 'D' , 'E' , 'F' } ;
for (i = 0 ; i < len ; i ++ ) {
tmp = str [i ] ;
dest [i * 2 ] = stb [tmp >> 4 ] ;
dest [i * 2 + 1 ] = stb [tmp & 15 ] ;
}
return ;
}
//===== define PLI: send_my() =======
void send_my ( ) {
int i = 0 ;
//检测到软件打印开始标志flags
//且系统任务 $send_my 被 Verilog 调用时传入了 3 个参数
if (flags && tf_nump ( ) == 3 ) {
//将打印的字符串数据转为ASCII对应的字符串类型
byte2hexstr (str_mes , str_mes_format , 100 ) ;
//将16进制的字符型数据传递给系统任务 send_my 中的第2个参数
//长度为1600bits，对应100个char、200个ASCII字符型数据
tf_strdelputp ( 2 , 1600 , 'H' , str_mes_format , 0 , 0 ) ;
//将整型数据传递给第3个参数
tf_putp ( 3 , int_mes ) ;
//将硬件打印开始标志传递给第一个参数
tf_putp ( 1 , 1 ) ;
flags = 0 ;
}
}
硬件设计
根据仿真测试可知，软件传递到 Verilog 中的数据，在位宽为 1600bit 寄存器中的存储方式如下图所示。
当寄存器中存有正常数据时，该寄存器从第 799bit（寄存器位宽的一半）开始存储正常的字符数据。低位剩余位宽存储"NULL"（对应数据 0）和系统默认的数据。这两部分数据长度根据存储的正常数据长度的变化而变化。
当寄存器中没有正常数据时，该寄存器会用超过 800bit 的寄存器长度去存储"NULL"（对应数据 0）。剩余位宽存储系统默认的数据。
可以根据以上特性，检测正常的字符串数据，而不用将寄存器中的数据全部打印，以避免打印信息中出现大量的空格信息，影响美观。
硬件 Verilog 代码设计如下，具体细节在注释中说明，保存到文件 test.v 中。
实例
module test ;
reg [ 1599 : 0 ] str_my ;
reg [ 31 : 0 ] int_my ;
reg flag_my ;
//时刻检测硬件打印标志 flagh 确定是否打印
integer i = 1599 ;
integer j = 1599 ;
reg [ 7 : 0 ] str_tmp ; //字符串数据存储寄存器
initial begin
flagh = 0 ;
forever begin
# 20 ;
//调用系统任务，并将数据从软件传递到硬件（Verilog）中
$send_my (flagh , str_my , int_my ) ;
if (flagh ) begin //开始打印信息
# 1 ;
//寄存器位宽有冗余，全部打印会出现大量空格
//这里对未使用到的寄存器进行检测并屏蔽打印显示
for (i = 1599 ; i >= 0 ; i = i - 8 ) begin
if (str_my [i -: 8 ] != 0 )
break ;
end
//一般会用寄存器一半位宽对字符串数据进行存储
//所以字符串传输正确时，从 str_my[799] 开始有数据
$display ( "--DEBUG--- Valid data number: %d" , i ) ;
//如果没有字符串数据，str_my也不会全为空
//但是str_my[799 -: 8]不会有数据
if (i <= 791 ) begin
$display ( "--ERR--- PLEASE INPUT VALID STRING INFO!!!" ) ;
$display ( "--ERR--- Default data number: %d" , i ) ;
$display ( "--ERR--- String data structure: %h" , str_my ) ;
end
else begin
$write ( "---YYY---" ) ;
for (j =i ; j >= 0 ; j = j - 8 ) begin
str_tmp = str_my [j -: 8 ] ;
//再次检测到空字符时停止打印显示
if (str_tmp == "" ) begin
break ;
end
//逐个字符打印
else begin
$write ( "%s" , str_tmp ) ;
end
end
//打印整型数据
$write ( "%h \n" , int_my ) ;
end
/* $display 不支持寄存器向量域中带变量访问
//所以下列描述是不正确的，只能逐次使用 $write 打印
else begin
$display("--YYY--- %s%h", str_my[i : j], int_my);
end
*/
flagh = 0 ;
end
end
end
//停止仿真
initial begin
forever begin
# 10000 ;
if ( $time >= 300 ) $finish ;
end
end
endmodule
软件调用
由于本次设计软件部分不能主动执行，所以再增加一个用 TF 子程序设计的 Verilog 系统任务。该系统任务在 testbench 中执行时，可以调用软件程序中的函数 print_my。
在文件 print_gyc.c 中增加如下 C 代码：
if (tf_getp ( 1 ) == 1 ) //如果系统函数第一个参数值为 1
print_my ( "It's the first successfull print: " , 0x20170714 ) ;
else if (tf_getp ( 1 ) == 2 ) //如果系统函数第二个参数值为 2
print_my ( "2nd: " , 0x09070602 ) ;
else
print_my ( "" , 0x1 ) ; //不传输字符串数据，则报错
}
在文件 test.v 中增加如下 Verilog 代码：
initial begin
# 100 ;
$call_c_print ( 1 ) ;
# 100 ;
$call_c_print ( 2 ) ;
# 100 ;
$call_c_print ( 3 ) ;
end
编译仿真
Linux 下用如下命令对 print_gyc.c 进行编译，输出 print_gyc.o 文件，注意相对路径。
gcc -I ${VCS_HOME}/include -c ../tb/print_gyc.c
使用 VCS 编译，需要创建 VCS 可识别的链接 table 文件，文件命名为 pli_gyc.tab, 内容如下。
$send_my, $call_c_print 是 Verilog 调用的系统任务名字；
call=my_monitor, call=call_c_print 等表示调用软件 C 程序中的函数；
$send_my call=send_my $call_c_print call=call_c_print
VCS 编译时增加如下参数行。
-P ../tb/pli_gyc.tab
仿真结果如下。
由图可知，打印输出正常，没有多余的空格信息。
当打印信息中没有字符串数据时，会报 Error，并输出一些调试信息。
可以修改 testbench 中的一些参数，来进行数据存储格式上的调试学习。
本章节源码下载
Download