TBRUN(1) Retro Project Manual TBRUN(1) NNAAMMEE tbrun - test bench driver SSYYNNOOPPSSIISS ttbbrruunn [_O_P_T_I_O_N]... [_D_S_C_F_I_L_E] DDEESSCCRRIIPPTTIIOONN ttbbrruunn organizes the execution of large sets of test benches. It will - read the file _D_S_C_F_I_L_E, which describes the full set of test benches. The top-level _D_S_C_F_I_L_E typically includes other files which allow organizing the description in a well-structured manner. If no _D_S_C_F_I_L_E is specified the file _t_b_r_u_n_._y_m_l in the current work- ing directory is used. - select based on the given ----ttaagg and ----eexxcclluuddee options the tests to be executed in a given run. - determine based on the ----mmooddee option the simulation engine and the simulation type, behavioral or post-synthesis or later. See section MODES for details. - execute the tests which as much parallelism as possible. The ----jjoobbss option specifies the maximal number of jobs and a locking logic prevents more than one test from running in a working directory. OOPPTTIIOONNSS ----ttaagg==_t_l_i_s_t specifies the tags a test must match to be selected for execu- tion. _t_l_i_s_t can be a comma-separated list of tags, a test must match all tags given in _t_l_i_s_t to be selected. ----ttaagg can be specified multiple times and the selections are ored. In effect, a test must match all tags in the _t_l_i_s_t of one of the specified ----ttaagg options. If no ----ttaagg option is given an implicit _-_-_t_a_g_=_d_e_f_a_u_l_t is as- sumed, so all tests with the tag 'default' are executed. ----eexxcclluuddee==_t_l_i_s_t specifies the tags a test must not match. _t_l_i_s_t can again be a comma-separated list, a test that matches all the tags given is excluded. ----eexxcclluuddee can be specified multiple times and the rejections are ored. In effect, a test is rejected if it matches all tags in the _t_l_i_s_t of one of the specified ----eexxcclluuddee options. ----aallll is simply a shortcut for ----ttaagg==""..**"" and selects all tags. Can be combined with ----eexxcclluuddee but not with other ----ttaagg options. ----mmooddee==_m_l_i_s_t determines the simulation engine and the type of simulation. Can be a comma-separated list, if several modes are specified all of them will be executed. If no ----mmooddee is given the default value 'bsim' is used. Note that unlike ----ttaagg and ----eexxcclluuddee only a single ----mmooddee option is processed, if multiple are present only the last one will be used. Each mode specification has the format '[_e_n_g_i_n_e]_[_t_y_p_e]' and follows the model name suffix rules of the build system. If the _e_n_g_i_n_e part is omitted gghhddll(1) is assumed as the default. If the _t_y_p_e part is omitted 'bsim' is assumed as default. Other supported values for _e_n_g_i_n_e are IISSiimm the Xilinx ISE build-in simulator XXSSiimm the Xilinx Vivado build-in simulator The _t_y_p_e part has the following supported values bbssiimm behavioral simulation ssssiimm post-synthesis functional simulation ffssiimm post-map simulation (only ISE) oossiimm post-optimize functional simulation (only Vivado) rrssiimm post-routing functional simulation (only Vivado) eessiimm post-synthesis timing simulation (only Vivado) ppssiimm post-optimize timing simulation (only Vivado) ttssiimm post-routing timing simulation ----jjoobbss==_n_j_o_b specifies the maximal number of parallel jobs. Without the ----jjoobbss option the tests are executed sequentially and the test output is forwarded immediately to _s_t_d_o_u_t. With the ----jjoobbss option a task dispatcher is used which starts the jobs, received and buffers the test output, and forwards it to _s_t_d_o_u_t when the job completes. The test outputs are always in the original selection order, thus not affected by the comple- tion order. The task dispatcher displays also a progress line when _s_t_d_o_u_t is a terminal device of the format #-I: t047: 5l 35.6s; t053: 5l 20.2s (26t,2w,31o) where t***: specifies the current task number **l number of output lines collected for this task *.*s run time (as real time) of the task (running since time) **t number of tasks still waiting for execution *w number of tasks currently running *o number of tasks in the pending output queue Note that ----jjoobbss enables the task dispatcher and thus output buffering and progress line output even when _n_j_o_b is '1' ! ----tteeee==_o_u_t_f_i_l_e if specified all output send to _s_t_d_o_u_t except for the progress line updates is also written in the file _o_u_t_f_i_l_e. This is very convenient in conjunction with the ----jjoobbss option which generates progress line output only when _s_t_d_o_u_t is a terminal device. Us- ing shell pipes and tteeee(1) will therefore prevent progress lines, use the ----tteeee instead to save the output into a file. ----lliisstt list selected tags and quit. ----ddrryy dry run, prints the generated commands, but doesn't execute. When used without the --jobs option a commented list of shell commands is printed which describes the linear execution of the selected tests. When used together with --jobs this option mainly serves to de- bug the task dispatcher. A random wait of 0.2 to 1.8 sec is gen- erated for each selected test. ----ttrraaccee prints additional information on job control. ----nnoommaakkee don't execute make step of the test bench. Will be forwarded to ttbbrruunn__ttbbww(1) and ttbbrruunn__ttbbwwrrrrii(1) based test benches. ----nnoorruunn don't execute run step of the test bench, useful to only execute make step. Will be forwarded to ttbbrruunn__ttbbww(1) and ttbbrruunn__ttbb-- wwrrrrii(1) based test benches. ----rrllmmoonn enable the rlink monitor, will be forwarded to ttbbrruunn__ttbbwwrrrrii(1) based test benches. ----rrbbmmoonn enable the rbus monitor, will be forwarded to ttbbrruunn__ttbbwwrrrrii(1) based test benches. ----bbwwaaiitt==_t_w_a_i_t specifies startup wait for behavioral simulations. _t_w_a_i_t must be an integer, the time unit is 1 ns. Will be forwarded to ttbbrruunn__ttbbwwrrrrii(1)-based test benches. ----sswwaaiitt==_t_w_a_i_t specifies startup wait for post-synthesis and higher simula- tions. _t_w_a_i_t must be an integer, the time unit is 1 ns. Will be forwarded to ttbbrruunn__ttbbwwrrrrii(1)-based test benches. ----hheellpp print short help text. EEXXIITT SSTTAATTUUSS In case of an error, the exit codes are: 11 run time errors, like a bad option, file not found, etc 22 at least one test FAILed, test bench has FAILed EENNVVIIRROONNMMEENNTT TTBBWW__GGHHDDLL__OOPPTTSS Used by ttbbww(1) to define additional options for gghhddll-based simula- tions. Usually set to "--unbuffered --ieee-asserts=disable-at-0", see ttbbww(1) documentation. EEXXAAMMPPLLEESS ttbbrruunn The simplest default case, will use the _t_b_r_u_n_._y_m_l file in the cur- rent working directory, assume _-_-_t_a_g_=_d_e_f_a_u_l_t, and _-_-_m_o_d_e_=_b_s_i_m. This selects all tests tagged with 'default' and runs the behav- ioral simulation with gghhddll(1). Done in simple sequential mode. ttbbrruunn ----jjoobbss==22 ----ttaagg==vviivv,,ssyyss__ww1111aa ----mmooddee==XXSSiimm Will select all tests which have a 'viv' and a 'sys_w11a' tag, use XSim as the simulation engine and run the behavioral simulation. Will use the task dispatcher and will try to run 2 tests in paral- lel. SSEEEE AALLSSOO ttbbrruunn__ttbbww(1), ttbbrruunn__ttbbwwrrrrii(1), ttbbffiilltt(1) AAUUTTHHOORR Walter F.J. Mueller Retro Project 2022-05-02 TBRUN(1)