TBW(1) Retro Project Manual TBW(1) NNAAMMEE tbw - wrapper script to start GHDL-based VHDL test benches SSYYNNOOPPSSIISS ttbbww _T_B_P_R_O_G [_O_P_T_I_O_N]... [_F_I_L_E_D_E_F]... [_G_H_D_L_-_O_P_T_I_O_N]... ttbbww ----hheellpp DDEESSCCRRIIPPTTIIOONN Executes the gghhddll-based test bench _T_B_P_R_O_G in an environment defined by the descriptor file _t_b_w_._d_a_t and the _F_I_L_E_D_E_F arguments. Any additional options _G_H_D_L_-_O_P_T_I_O_N_S are passed on to the test bench executable. BBaacckkggrroouunndd The VHDL implementation in gghhddll has no direct support for passing com- mand-line arguments to the VHDL code. All test benches in the Retro project use, therefore, fixed build-in generic file names. By conven- tion, they refer to symlinks (see ssyymmlliinnkk(7)) which are set up by ttbbww to point to a specific file prior to the execution of the test bench. DDeeffaauulltt bbeehhaavviioorr In the simplest case, ttbbww assumes a test bench with a single stimulus file which is opened by convention as '_stim'. The default stimulus file is named '_stim.dat'. ttbbww will simply define '_stim' as a symlink referring to '_stim.dat', or if defined to _F_I_L_E_D_E_F, and execute _T_B_P_R_O_G. In essence ln -s -f _stim.dat _stim UUssiinngg aa _t_b_w_._d_a_t ccoonnffiigguurraattiioonn ffiillee When the generic file name or the stimulus file name does not follow the simple default pattern or more than one input file is required a configuration file can be used to define the setup. It has the fixed name _t_b_w_._d_a_t and is searched in the directory of the test bench program _T_B_P_R_O_G. The format is described in section FILES. In this case, the _F_I_L_E_D_E_F argument can be specified as 'tag=value' pairs where 'tag' refers to a generic name and 'value' gives the con- crete file name. Useful when several input files are to be specified. UUssiinngg iinnlliinnee ccoonnffiigguurraattiioonnss A _F_I_L_E_D_E_F argument can have the form 'tag={line1;line2;...}'. In that case, a temporary file is created with the given lines and the name of the temporary file is associated with the tag as described above. This is often used in conjunction with the tag referring to the configura- tion file. This mechanism allows for rlink based test benches to spec- ify '.scntl', '.sdata', 'rlmon', 'rbmon', and '.wait' startup commands on the ttbbww command line and is for example used by ttbbrruunn__ttbbwwrrrrii(1). The '-sxon' option of ttbbrruunn__ttbbwwrrrrii(1) creates for example _conf={.sdata 08 0002;.sdata 10 0002;} which generates two 'simbus' configuration cycles before the simulation body starts. TTeesstt bbeenncchheess ccoonnttrroolllleedd wwiitthh ttii__rrrrii In this case, the communication between the test bench and the control- ling ttii__rrrrii is done via two named pipes (see ffiiffoo(7)). The test bench might open in addition a configuration file. This setup is also defined via the _t_b_w_._d_a_t file, for details see section FILES. OOPPTTIIOONNSS The options --ffiiffoo, --vveerrbboossee, and --nnoorruunn are processed by ttbbww itself. They must be the first options after _T_B_P_R_O_G. --ffiiffoo Forces usage of rlink_cext fifo in case no _t_b_w_._d_a_t is found or no section matching _T_B_P_R_O_G is found in tbw.dat. --vveerrbboossee Show the used tag,value settings before execution --nnoorruunn Start simulator in interactive mode. The default for _XSim or _ISim tb's is to ensure that the simulation runs till the end, as for gghhddll. Therefore a '-R' option for XSim or a 'run all' command for ISim is generated. The -norun option suppresses this. GGHHDDLL OOPPTTIIOONNSS All options are passed on to the test bench executable. The list of available options for a gghhddll-generated executable can be inquired with the "----hheellpp" option. Some especially useful options are: ----wwaavvee==_f_i_l_e dump signal values into a wave file (use file type .ghw). Far superior to the VCD format and allows for inspecting all VHDL records and all data types with ggttkkwwaavvee(1). ----ssttaacckk--mmaaxx--ssiizzee=_n set maximum stack size. Very helpful in the case of very large models. A value of _n=16384 is in general enough for all gener- ated models, which usually have a large number of very simple processes. ----ssttoopp--ttiimmee_=_t stop the simulation at time _t (in VHDL notation, e.g. 100ns). ----ddiisspp--ttiimmee display time as simulation advances. ----ttrraaccee--pprroocceesssseess display process name before each cycle. EENNVVIIRROONNMMEENNTT TTBBWW__GGHHDDLL__OOPPTTSS Additional options that are passed to gghhddll-based simulations. Of particular value are ----iieeeeee--aasssseerrttss==ddiissaabbllee--aatt--00 suppresses assertion warnings from the ieee libraries at startup time (t=0ns). ----uunnbbuuffffeerreedd sets output at all files (_s_t_d_o_u_t, _s_t_d_e_r_r, and files opened for write) to unbuffered mode. This is very helpful to keep output from the gghhddll simulation and other programs in a co-simulation environment in synch. Note: only available for GHDL 0.34dev after merge of Jonsba/master #100 on 2016-06-26. FFIILLEESS _._/_t_b_w_._d_a_t This configuration file is searched for in the directory of the test bench program _T_B_P_R_O_G and holds associations between generic file names and concrete file names for one or more test bench exe- cutables. It contains sections of the format [_T_B_P_R_O_G] = = UUssaaggee wwiitthh SSttiimmuulluuss ffiillee bbaasseedd tteesstt bbeenncchheess ttbbww will create a ssyymmlliinnkk(7) with the generic name which refers to the given concrete file name. A typical example is [tb_nx_cram_memctl_as] tb_nx_cram_memctl_stim = tb_nx_cram_memctl_stim.dat UUssaaggee wwiitthh tteesstt bbeenncchheess ccoonnttrroolllleedd wwiitthh ttii__rrrrii The special token _<_f_i_f_o_> indicates that a named pipe is used rather than a normal file. In this case, ttbbww will create a ffiiffoo(7) rather than a symlink. Another special token is _<_n_u_l_l_>, it simply translates to _/_d_e_v_/_n_u_l_l and can be used as a default value for configuration files. Currently, all rrlliinnkk- based test benches use the same generic names and have a setup like [tb_w11a_n3] rlink_cext_fifo_rx = rlink_cext_fifo_tx = rlink_cext_conf = EEXXAAMMPPLLEESS SSttiimmuulluuss ffiillee bbaasseedd tteesstt bbeenncchheess Test benches are usually self-checking and produce a comprehensive log file. For each checked response, the line contains the word "CHECK" and either an "OK" or a "FAIL", in the latter case in general with an indication of what's wrong. Other unexpected behavior, like timeouts, will also result in a line containing the word "FAIL". When the simu- lation stops a line with the word "DONE" is printed. These test benches are usually run like tbw [stimfile] | tbfilt --tee where - ttbbww sets up the stimulus file and runs the test bench executable - ttbbffiilltt ensures that the full log is saved and the PASS/FAIL crite- ria are extracted The convenience script ttbbrruunn__ttbbww(1) can be used in many cases to create such a pipeline. TTeesstt bbeenncchheess ccoonnttrroolllleedd wwiitthh ttii__rrrrii In these cases, the test bench is started via ttii__rrrrii using the ----rruunn and ----ffiiffoo options. Also here usually a pipe with ttbbffiilltt(1) is used, a typical example is ti_rri --run="tbw tb_tst_rlink_n3" --fifo --logl=3 -- \ "package require tst_rlink" \ "tst_rlink::setup" "tst_rlink::test_all" |\ tbfilt --tee=tb_tst_rlink_n3_bsim.log The convenience script ttbbrruunn__ttbbwwrrrrii(1) can be used in many cases to create these sometimes rather lengthy constructs. SSEEEE AALLSSOO ttbbrruunn__ttbbww(1), ttbbffiilltt(1), ttii__rrrrii(1), ttbbrruunn__ttbbwwrrrrii(1), ggttkkwwaavvee(1), ssyymm-- lliinnkk(7), ffiiffoo(7) AAUUTTHHOORR Walter F.J. Mueller Retro Project 2016-10-02 TBW(1)