UVM基础之---------Reporting Classes
Reporting 类提供了一组工具用于格式化报告输出
report机制大概包括四个主要的类uvm_report_object，uvm_report_handler， uvm_report_server，uvm_report_catcher，UVM reporting主要的接口是uvm_report_object（这是一个接口类），这是uvm_components的父类。uvm_report_object通过内部的function调用uvm_report_handler的function来执行大部分的工作。uvm_report_handler存储了对消息的显示和处理的一些配置信息，他对消息的处理进行决策，并对消息进行一些格式化，过滤等。最终消息被将被uvm_report_handler送到uvm_report_server。而uvm_report_catcher实际上就是一个uvm_report_cb，他对特定的uvm_report_object发出的消息进行抓取。
下图是reporting类的继承关系：
uvm_report_object:
1. 通过此接口,组件发起发生在仿真过程中的各种message。 Users can configure what actions are taken and what file(s) are output for individual messages from a particular component or for all messages from all components in the environment
2. uvm_report_object大多数方法委派给uvm_report_handler一个内部实例, 在uvm_report_handler中存储报告应该显示配置，然后根据配置决定是否发布消息，如果决定发布消息，uvm_report_handler将这个工作委派给uvm_report_server。
3. 一个uvm的report由下列部分组成id string, severity, verbosity level, and the textual，filename and line number；如果消息的verbosity level超过了一个report被配置的最大verbosity level那么这个消息将被过滤掉。如果消息通过了过滤，那么以后的行为都是确定的，如果被配置为输出到一个文件，那么该消息最后将被输出的该文件中
4. report的actions定义了对各个级别的消息采取的行动，该行动针对severity or id，或者(severity, id)对。可采取的行动包括显示，推出，计数，UVM_DISPLAY | UVM_COUNT|UVM_EXIT，可以使用 set_*_action替换这些action
5. default actions：
UVM_INFO - UVM_DISPLAY
UVM_WARNING - UVM_DISPLAY
UVM_ERROR - UVM_DISPLAY | UVM_COUNT
UVM_FATAL - UVM_DISPLAY | UVM_EXIT
6. 文件描述符，可以设定默认的文件描述符，通过severity, id, (severity, id)设定文件描述符。这些文件描述符必须使用者自己负责进行开关维护
7. 默认的文件句柄是0，即标准输出默认的文件句柄可以通过set_*_file来改写
8. uvm_report_object的第一个对象是uvm_report_handler m_rh该句柄在new函数中实例化，uvm_report_object的所以消息都委派给handler处理
Reporting Function:
6. virtual function void uvm_report_info( string id,
string message,
int verbosity = UVM_MEDIUM,
string filename = "",
int line = 0);
该函数直接调用m_rh.report函数，没有过多内容。函数中的参数在1中也做了解释
m_rh.report(UVM_INFO, get_full_name(), id, message, verbosity,
filename, line, this);
7. virtual function void uvm_report_warning( string id,
string message,
int verbosity = UVM_MEDIUM,
string filename = "",
int line = 0);
该函数直接调用m_rh.report函数，没有过多内容。函数中的参数在1中也做了解释
8. virtual function void uvm_report_error( string id,
string message,
int verbosity = UVM_LOW,
string filename = "",
int line = 0);
该函数直接调用m_rh.report函数，没有过多内容。函数中的参数在1中也做了解释
9. virtual function void uvm_report_fatal( string id,
string message,
int verbosity = UVM_NONE,
string filename = "",
int line = 0);
函数直接调用m_rh.report函数，没有过多内容。函数中的参数在1中也做了解释
NOTE
id a unique id for the report or report group that can be used for identification and therefore targeted filtering. You can configure an individual report’s actions and output file(s) using this id string.
message the message body, preformatted if necessary to a single string.
verbosity the verbosity of the message, indicating its relative importance. If this number is less than or equal to the effective verbosity level, see set_report_verbosity_level, then the report is issued, subject to the configured action and file descriptor settings. Verbosity is ignored for warnings, errors, and fatals. However, if a warning, error or fatal is demoted to an info message using the uvm_report_catcher, then the verbosity is taken into account.
filename/line (Optional) The location from which the report was issued. Use the predefined macros, `__FILE__ and `__LINE__. If specified, it is displayed in the output.
Callbacks Function:
virtual function bit report_info_hook(
string id, string message, int verbosity, string filename, int line);
virtual function bit report_error_hook(
string id, string message, int verbosity, string filename, int line);
virtual function bit report_warning_hook(
string id, string message, int verbosity, string filename, int line);
virtual function bit report_fatal_hook(
string id, string message, int verbosity, string filename, int line);
virtual function bit report_hook(
string id, string message, int verbosity, string filename, int line);//一个总的hook
1. These hook methods can be defined in derived classes to perform additional actions when reports are issued. They are called only if the UVM_CALL_HOOK bit is specified in the action associated with the report. The default implementations return 1, which allows the report to be processed. If an override returns 0, then the report is not processed.
virtual function void report_header(UVM_FILE file = 0);//打印 version and copyright information，如果file!=0就打印到对应文件。调用m_rh.report_header(file)
virtual function void report_summarize(UVM_FILE file = 0);//打印统计信息，调用m_rh.summarize(file);
virtual function void die();//该函数被report_server调用，如果满足退出条件或者需要采取退出的行动。如果是在component中，那么将只把本仿真phase结束，如果不是component，那么仿真将直接介绍，并嗲用12中的函数显示总结信息
Configuration function:
16. function void set_report_id_action (string id, uvm_action action);
function void set_report_severity_action (uvm_severity severity,
uvm_action action);
function void set_report_severity_id_action (uvm_severity severity,
string id, uvm_action action);
//对给定的id, severity 或者(id, severity）对设置ACTIONS,在2中介绍，都是调用handler中对应的函数来实现
17. function void set_report_severity_override(uvm_severity cur_severity,
uvm_severity new_severity);//改写14中的设定，调用handler对应函数实现
18. function void set_report_severity_id_override(uvm_severity cur_severity,
string id,
uvm_severity new_severity); //改写(severity,id)对的severity值，调用handler内函数实现
19.function void set_report_default_file ( UVM_FILE file);//设置默认的输出文件，调用handler相应函数实现
20.function void set_report_severity_file (uvm_severity severity, UVM_FILE file););//设置默认的severity级别的消息的输出文件，调用handler相应函数实现
21.function void set_report_id_file (string id, UVM_FILE file);););//设置默认的ID级别的消息的输出文件，调用handler相应函数实现
22. function void set_report_severity_id_file (uvm_severity severity, string id,
UVM_FILE file););););//设置默认的(ID，severity)级别的消息的输出文件，调用handler相应函数实现
23. function int get_report_verbosity_level(uvm_severity severity=UVM_INFO, string id="");//返回(ID，severity)的verbosity值，调用handler对应的函数实现
24.function int get_report_action(uvm_severity severity, string id);//返回(ID，severity)的action值，调用handler对应的函数实现
25.function int get_report_file_handle(uvm_severity severity, string id);//返回(ID，severity)的report file值，调用handler对应的函数实现
26. function int uvm_report_enabled(int verbosity,
uvm_severity severity=UVM_INFO, string id="");//测试(ID，severity)对，如果他们对应的verbosity比report的verbosity低，或者对应的action=UVM_NO_ACTION那么返回失败，否则返回1
27. function void set_report_max_quit_count(int max_count);//如果UVM_COUNT actions达到max_count，将调用die；调用handler的函数实现
Setup Function:
28.function void set_report_handler(uvm_report_handler handler);//m_rh = handler;
29.function uvm_report_handler get_report_handler();// return m_rh;
30.function void reset_report_handler;// m_rh.initialize;让m_rh达到初始状态
31.function uvm_report_server get_report_server();//return m_rh.get_server();
32.function void dump_report_state();//m_rh.dump_state();对handler的内部状态进行一个报告
33.function int uvm_get_max_verbosity();// return m_rh.m_max_verbosity_level;
34.protected virtual function uvm_report_object m_get_report_object();//return this;
uvm_report_handler:
uvm_report_handler是report_object的代理，许多对消息的配置信息和处理函数都在这个类里边实现。report—object和report_handler的关系是一 一对应的，当然也可以多个report_object对应一个report_handler（set_report_handler）.handler到server的关系是多对一
1. uvm_report_handler 保存verbosity，actions，以及file这些可以影响报告处理方式的变量。
2. report handler并不能直接使用，
3. 这个类里面的属性：
int m_max_verbosity_level;//记录report_object的容许verbosity,超过这个值的将被过滤掉
uvm_action severity_actions[uvm_severity];//每个severity对应的action如显示，丢掉，计数等
uvm_id_actions_array id_actions;//每个id对应的action，是一个uvm_pool
1. 可以精细化控制每个ID的action
uvm_id_actions_array severity_id_actions[uvm_severity];//每个(id，severity)对应一个action
uvm_id_verbosities_array id_verbosities;//每个id对应一个verbosity
修改某些ID 的verbosity，关闭这些ID的打印
uvm_id_verbosities_array severity_id_verbosities[uvm_severity];//每个(id，severity)对应一个verbosity
uvm_sev_override_array sev_overrides;//记录每个severity被改写的情况
uvm_sev_override_array sev_id_overrides [string];//每个(id，severity)的severity被改写的情况
UVM_FILE default_file_handle;
UVM_FILE severity_file_handles[uvm_severity];//每个severity对应的输出文件
uvm_id_file_array id_file_handles=new;//每个id对应的输出文件
uvm_id_file_array severity_id_file_handles[uvm_severity];//每个(id，severity)的输出文件
4. 主要的方法函数：
1. function new();//实例化类中的东西并调用initialize创建类实例
set_default_file(0)
m_max_verbosity_level=UVM_MEDIUM
function void set_defaults();
set_severity_action(UVM_INFO, UVM_DISPLAY);
set_severity_action(UVM_WARNING, UVM_DISPLAY);
set_severity_action(UVM_ERROR, UVM_DISPLAY | UVM_COUNT);
set_severity_action(UVM_FATAL, UVM_DISPLAY | UVM_EXIT);
set_severity_file(UVM_INFO, default_file_handle);
set_severity_file(UVM_WARNING, default_file_handle);
set_severity_file(UVM_ERROR, default_file_handle);
set_severity_file(UVM_FATAL, default_file_handle);
endfunction
2. virtual function bit run_hooks(uvm_report_object client,
uvm_severity severity,
string id,
string message,
int verbosity,
string filename,
int line);//运行report中的相应hooks
1. The run_hooks method is called if the UVM_CALL_HOOK action is set for a report. It first calls the client’s uvm_report_object::report_hook method, followed by the appropriate severity-specific hook method. If either returns 0, then the report is not processed.
2. 这个run_hooks在uvm_servers中进行调用，本function里面调用的report_info_hook在client的uvm_report_object中进行声明。
3. function int get_verbosity_level(uvm_severity severity=UVM_INFO, string id="" );//返回verbosity，返回的顺序和9中的一样
4. function uvm_action get_action(uvm_severity severity, string id);//返回action，返回的顺序和9中一样
5. function UVM_FILE get_file_handle(uvm_severity severity, string id);//返回文件句柄，返回的顺序和9中的一样
6. virtual function void report(
uvm_severity severity,
string name,
string id,
string message,
int verbosity_level,
string filename,
int line,
uvm_report_object client
);//report_object中就是调用这个方法来report_warning/error/fatal/info的，先是查找对应的severity被覆盖情况，然后调用server
主要的工作：
1. uvm_report_server srvr;
srvr = uvm_report_server::get_server(); 拿到srvr句柄
2. 判断传入的client是否为NULL，为NULL则指向uvm_top
3. Check for severity overrides and apply them before calling the server. An id specific override has precedence over a generic severity override
4. 调用srvr的report function
其他函数作为uvm_report_handler的服务函数：
1. function uvm_report_server get_server();获取server的singleton
2. function void set_max_quit_count(int max_count);//把max_count设置到server中
3. function void summarize(UVM_FILE file = 0);//调用server的summarize进行报告
4. function void report_header(UVM_FILE file = 0);//调用server的f_display显示一些版本信息等
5.function void initialize();//设置一些输出文件，及一些默认的配置，变量等
6. local function UVM_FILE get_severity_id_file(uvm_severity severity, string id);//返回一个文件句柄，先返回（severity, id)对中的，然后是id相关的，最后是severity相关的，最后是默认的，这样的返回顺序
7. function void set_verbosity_level(int verbosity_level);设置m_max_verbosity_level
8. srvr.report(severity,name,id,message,verbosity_level,filename,line,client);进行显示
9. function string format_action(uvm_action action);//把action的枚举类型名改为字符串
10. function void set_severity_action(input uvm_severity severity,
input uvm_action action);//为severity设定action
11. function void set_id_action(input string id, input uvm_action action);//为id设定action
12. function void set_severity_id_action(uvm_severity severity,
string id,
uvm_action action);//为severity和id对设定action
13.function void set_id_verbosity(input string id, input int verbosity);//为id设定verbosity
14. function void set_severity_id_verbosity(uvm_severity severity,
string id,
int verbosity);//为(severity，id）对设定action
15. function void set_default_file (UVM_FILE file);//设置默认输出文件
16.function void set_severity_file (uvm_severity severity, UVM_FILE file);//为severity设置输出文件
17. function void set_id_file (string id, UVM_FILE file);//为id设置输出文件
18. function void set_severity_id_file(uvm_severity severity,
string id, UVM_FILE file);//为(severity,id)对设置输出文件
19. function void set_severity_override(uvm_severity cur_severity,
uvm_severity new_severity);//为severity设置覆盖的severity
20. function void set_severity_id_override(uvm_severity cur_severity,
string id,
uvm_severity new_severity);//为（severity,id）对设置覆盖的severity
21.function void dump_state();//调用server的f_display方法对handler中的状态信息，内容进行显示
uvm_report_server:
1. uvm_report_server是全局的server处理所有的由uvm_report_handler产生出来的reports。uvm_report_server的code都不会被normal的testbench调用，虽然在一些环境中，process_report 和compose_uvm_info会被子类重载。
变量：
local int max_quit_count;
local int quit_count;
local int severity_count[uvm_severity];
protected int id_count[string];//
bit enable_report_id_count_summary=1;
方法：
new
1. Creates the central report server, if not already created.
static function void set_server(uvm_report_server server);
1. Sets the global report server to use for reporting.
2. m_global_report_server = server;
get_server
1. Gets the global report server. 返回当前report server的一个valid handle
2. 返回m_global_report_server
process_report Calls compose_message to construct the actual message to be output.
compose_message
1. Constructs the actual string sent to the file or command line from the severity, component name, report id, and the message itself.
2. 可以重写compose_message对打印的log进行重写
一些服务函数：
set_max_quit_count
get_max_quit_count Get or set the maximum number of COUNT actions that can be tolerated before an UVM_EXIT action is taken.
set_quit_count
get_quit_count
incr_quit_count
reset_quit_count Set, get, increment, or reset to 0 the quit count, i.e., the number of COUNT actions issued.
is_quit_count_reached If is_quit_count_reached returns 1, then the quit counter has reached the maximum.
set_severity_count
get_severity_count
incr_severity_count
reset_severity_counts Set, get, or increment the counter for the given severity, or reset all severity counters to 0.
set_id_count
get_id_count
incr_id_count Set, get, or increment the counter for reports with the given id.
summarize See uvm_report_object::report_summarize method.
dump_server_state Dumps server state information.
get_server Returns a handle to the central report server.
uvm_report_catcher://这是一个uvm_report_object的一个callback类，
1. 用于捕获uvm_report_server发起的message,
2. Catchers are uvm_callbacks#(uvm_report_object,uvm_report_catcher) objects, so all factilities in the uvm_callback and uvm_callbacks#(T,CB) classes are available for registering catchers and controlling catcher state.
3. The uvm_callbacks#(uvm_report_object,uvm_report_catcher) class is aliased to uvm_report_cb to make it easier to use. Multiple report catchers can be registered with a report object.
4. The catchers can be registered as default catchers which catch all reports on all uvm_report_object reporters, or catchers can be attached to specific report objects
5. User extensions of uvm_report_catcher must implement the catch method in which the action to be taken on catching the report is specified.
6. The catch method can return CAUGHT, in which case further processing of the report is immediately stopped, or return THROW in which case the (possibly modified) report is passed on to other registered catchers. The catchers are processed in the order in which they are registered.
7. On catching a report, the catch method can modify the severity, id, action, verbosity or the report string itself before the report is finally issued by the report server. The report can be immediately issued from within the catcher class by calling the issue method.
对cacher的主要的用法如下：本例的目的是为了将MY_ID的error_report改为uvm_info
class my_error_demoter extends uvm_report_catcher;
function new(string name="my_error_demoter");
super.new(name);
endfunction
//This example demotes "MY_ID" errors to an info message
function action_e catch();
if(get_severity() == UVM_ERROR && get_id() == "MY_ID")
set_severity(UVM_INFO);
return THROW;
endfunction
endclass
my_error_demoter demoter = new;
initial begin
// Catchers are callbacks on report objects (components are report
// objects, so catchers can be attached to components).
// To affect all reporters, use null for the object
uvm_report_cb::add(null, demoter);
// To affect some specific object use the specific reporter
uvm_report_cb::add(mytest.myenv.myagent.mydriver, demoter);
// To affect some set of components using the component name
uvm_report_cb::add_by_name("*.*driver", demoter);
end
具体的实现将会在uvm_callback中进行介绍。
