1.0 Introduction This document describes how to use Magellan to view a VCD file and how to use Magellan to control an interactive Verilog simulation. It assumes you have installed and enabled the software as described in Magellan Installation & Configuration (README). To run Magellan, the Magellan directory BIN needs to be in the path. You also may need to set these environment variables depending on the software installation: NAVHOME SIMWAVEHOME SSI_LICENSE NAVSIM Please see Magellan Installation & Configuration (README) if these variables are not set in your environment. Magellan provides five graphical interfaces to simplify and accelerate Verilog circuit development and debugging: Simulator Output, Navigator, VDBX+, SimWave, and RTL-Spreadsheet. Each interface is fully Motif compatible and provides complete on-line help. Simulator Output is a graphical front-end for Verilog simulators. It includes user-definable buttons to send commands to the simulator. Navigator is a browser that allows you to quickly navigate a circuit and back-track values. You need only click a button to go up and down the circuit hierarchy or to examine the drivers and loads of a net. VDBX+ is a source-level debugger for Verilog. VDBX+ allows you to control the simulation and examine source files. You set and delete breakpoints, single step through the simulation, and continue the simulation by simply clicking buttons. SimWave is a smart waveform display. Its intuitive interface allows you to quickly zoom in and out, change waveform colors, change the base of buses, and trigger off waveforms. RTL-Spreadsheet is a block diagram viewer. It complements SimWave by displaying simulation output at a higher level of abstraction. Simulation output is displayed in user definable block diagrams that show the flow of information between components. For example, an RTL-Spreadsheet window can show the key registers of a microprocessor and their interconnections. Magellan supports both interactive Verilog simulations and post- simulation debugging. When running interactively with a Verilog simulation, Magellan probes and monitors the simulation using Verilog Programming Language Interface (PLI). When running as a post-simulation debugger, Magellan reads Value Change Dump (VCD) files. However, Magellan is more than just a VCD viewer. It can combine the changes in your VCD file with the connectivity of your Verilog model. This allows you to trace and locate erroneous values with just a VCD file. Magellan is compatible with all leading Verilog simulators. In addition, SimWave and RTL-Spreadsheet can be used with simulators from GenRad, Zycad, EPIC, and META-SOFTWARE. 2.0 Overview This section has a summary of the commands, tasks, and files used by Magellan. 2.1 User interfaces TABLE 1. Simulator Output Graphical front end for Verilog simulator Navigator Hierarchy navigator and value back-tracker VDBX+ Verilog source level debugger SimWave Waveform display and analyzer RTL-Spreadsheet Block diagram viewer TABLE 2. 2.2 Commands navvcd Starts Magellan with a VCD file generated by $dumpvars or a dump file generated by $ssi_navrecord and $ssi_navdump navver Starts Magellan with Cadence's Verilog-XL and FrontLine's BaseLine navvcs Starts Magellan with Chronologic's VCS navfin Starts Magellan with Fintronic's FinSIM 2.3 Data files TABLE 4. verilog.dump ASCII dump file (VCD file) containing a history of the simulation. Created by the $dumpvars task. Use the navvcd command to view it. nav.dbase Data base file created by the Magellan $ssi_navdbase task which is used to show net drivers and loads when viewing VCD files and dump files created by $ssi_navrecord or $ssi_navdump. nav.rec.ix Fast dump file. Created by Magellan $ssi_navrecord task. To view it, use the navvcd nav.rec.ix command. nav.dump Circular dump file. Created by Magellan $ssi_navdump task. To view it, use the navvcd nav.dump command. 2.4 Environment TABLE 5. NAVHOME Environment variable set to location of Magellan installation directory. "$NAVHOME/BIN" should be in your command search path. SIMWAVEHOME Environment variable set to location of SimWave installation directory. NAVSIM Environment variable set to full path name of your Verilog simulator. Used only when running Magellan interactively with your simulator. SSI_LICENSE Environment variable set to full path name of your Systems Science license file. 2.5 Verilog HDL system tasks Magellan tasks for interactive debugging $ssi_navigator Starts the communication link with Magellan GUI's and starts SimWave. $ssi_navrecord Starts the recording of value changes which can be dis- played in SimWave. Saves values changes in either a fast dump file or in memory. $ssi_navconfigure Chooses whether $ssi_navrecord saves values changes in a dump file or in memory. If value changes are stored in a dump file, then used to specify the name and location of the dump file. Magellan tasks for post-simulation debugging $ssi_navdump Stores value changes in a circular dump file. The circular dump file can only be examined after the simulation with Magellan's navvcd command. $ssi_navdbase Creates a data base file which describes the gate level con- nectivity of the Verilog model. For example, it describes the drivers and loads of each net. The data base can be used with the dump files generated by $ssi_navrecord, $ssi_navdump, and $dumpvars. $ssi_navconfigure Used to specify the name and location of the dump file generated by $ssi_navdump. Verilog tasks for post-simulation debugging $dumpvars Stores value changes in a VCD file. VCD stands for Value Change Dump. VCD files are readable ASCII files which can be examined during or after the simulation with Magellan's navvcd command. 3.0 Running with Value Change Dump files 3.1 Loading a VCD file The navvcd command in the "$NAVHOME/BIN" directory starts Magellan with a VCD file. Pass navvcd the name of the VCD you wish to view: navvcd & If "" is omitted, then Magellan will load the data in the verilog.dump file. For a demonstration, go to the "$NAVHOME/SAMPLES" directory and enter: navvcd & The navvcd command also accepts a number of optional command line arguments. TABLE 7. Arguments accepted by the navvcd command -start start loading data at this simulation time -stop stop loading data at this simulation time -dump name of dump file to load, defaults to verilog.dump -dbase name of data base file to load, defaults to nav.dbase -convert converts dump file to fast binary file named, -ignorereals ignore real variables when loading a VCD file -vecwarn warn of bad bit selects when loading a VCD file The -start and -stop arguments allow you to load portions of the VCD file, rather than all value changes in the file. For example, if you only want to view the value changes between simulation time 100000 and simulation time 300000, enter: navvcd -start 100000 -stop 300000 & The -convert argument allows you to convert a VCD file into a fast binary format. Once the data is in the fast binary format, it can be displayed many times faster. For example, to convert verilog.dump into a fast binary file named conv.ix, enter: navvcd -convert conv.ix verilog.dump & The next time you want to look at the data, use navvcd to load the conv.ix file: navvcd conv.ix & 3.2 Connectivity Information If you want connectivity information when viewing a VCD file, so that Magellan can show you the drivers and loads of a net, you must create a special data base file. The data base file is created by the $ssi_navdbase system task. For more information on how to invoke the $ssi_dbase task see Section\x116.4, "Creating the data base file," on page\x1122. The $ssi_navdbase task creates a file named nav.dbase. VCDSim will combine the information in the nav.dbase file along with the value changes in the VCD file. For example, the "$NAVHOME/SAMPLES" directory already contains a verilog.dump file and nav.dbase file for the adder.v example. To run Magellan with this data, go to "$NAVHOME/SAMPLES" and execute: navvcd & The nav.dbase file will be loaded and gate level connectivity information will be available. For example, using the Navigator GUI go to the "top" scope and select the "bus" signal. Clicking on the "Backtrack" button and then selecting bit "0" in the "Backtracking" dialog will show you the drivers of "bus[0]". When no data base file is present, Magellan will notify you that connectivity information will not be available. At this time, the data base file created by Chronologic's VCS and Fintronic's FinSim simulators do not contain all gate level connectivity. When used with a data base file created by VCS, Magellan will show all drivers and loads except those connected by a hierarchical name reference. When used with a data base file created by FinSim, Magellan will show only the drivers and loads in the current scope. 3.3 Setting the time for values The time command sets the simulation time for the values shown in the Navigator windows. For example, if you want to back-track values at simulation time 1000, type this command into the Simulator Output window: time 1000 3.4 Polling for more data The poll command checks if the VCD file has grown. This allows you to view the contents of a VCD file as it is being created. With no arguments the poll command simply reads any new data: poll The poll command can also set a timer to check and read new data automatically. For example, to check and read new data from the VCD file every 120 seconds, type this command into the Simulator Output window: poll 120 4.0 Running interactively with a Verilog simulator. If you want to run Magellan interactively with the Verilog simulator, you must set the NAVSIM environment variable. The NAVSIM variable is set to the location of your customized Verilog executable. This is described in the sections which follow. Magellan uses Verilog PLI when running interactively with a Verilog simulator. It does not use the Verilog VCD ($dumpvars) facility. Because Magellan uses PLI, it is very tightly coupled with the Verilog simulator. It can quickly extract hierarchy and connectivity information from the simulator, allowing you to browse any scope in the Verilog model and to track the propagation of signal values forward and backward through your model. 4.1 Running with Verilog-XL 4.1.1 Creating a Verilog Image To use Magellan interactively with Verilog-XL, you must create a new Verilog image linked with the Magellan system tasks. The "$NAVHOME/INTEGRATION_KIT/README" file describes how to construct a new Verilog image. After you have created a new Verilog image, you must set the NAVSIM environment variable to the full path name of the image. For example, if your Verilog image is named "/cadence/vtools/vlog/exe/verilog", use the command: setenv NAVSIM /cadence/vtools/vlog/exe/verilog You should include this command in your ".login" or ".cshrc" file so that the NAVSIM variable is always set properly. 4.1.2 Starting Magellan The $NAVHOME/BIN/navver command starts Magellan with Verilog-XL. The "$NAVHOME/SAMPLES" directory contains a Verilog source file which demonstrates how to use Magellan with Verilog-XL. For a demonstration, go to the "$NAVHOME/SAMPLES" directory and run Magellan on the adder.v file: navver adder.v & where "" are the options you normally use when running Verilog-XL, e.g. "-a -f /verilog/licenses/passfile". To use Magellan with your own Verilog models, invoke the $ssi_navigator task followed by a $stop task in a top level module. For example, look at the invocation of $ssi_navigator in the adder.v file. After you have added the $ssi_navigator and $stop tasks to your Verilog model, run navver with the same arguments you normally pass to the Verilog image. For example, if you normally run Verilog- XL with the command: verilog -a -f /verilog/licenses/passfile mycircuit.v & Then use this command to run Magellan: navver -a -f /verilog/licenses/passfile mycircuit.v & Magellan will start Verilog-XL, passing to Verilog-XL all the command line arguments that were passed to navver. Once Verilog-XL has entered the interactive mode, you may use the Magellan control panel. The $ssi_navigator task will not effect your normal Verilog-XL simulations. You can run Verilog-XL with or without Magellan on the source files with the $ssi_navigator task. If you have difficulty running Magellan with Verilog-XL, please see Section\x117.0, "Common Questions: Magellan with Verilog-XL," on page\x1125. 4.1.3 Things to avoid Do not stop the simulation with a $stop task before the $ssi_navigator task and do not use the stop option, "-s". This stops the simulation before the $ssi_navigator task can be invoked. If the simulation is stopped before the $ssi_navigator task is invoked, Magellan will lock up. Do not invoke the $ssi_navigator task from within an input/control file. Only invoke the $ssi_navigator task from within a Verilog module. Do not set NAVSIM to the name of a script file which starts Verilog-XL. NAVSIM must be set to the name of the actual binary Verilog image. If you use a script file to start Verilog-XL, we suggest you modify the script file to set the NAVSIM variable and to start navver with the appropriate arguments. 4.2 Running with VCS 4.2.1 Samples The "$NAVHOME/SAMPLES" directory contains a of Verilog source file which demonstrates how to use Magellan with Chronologic's VCS. For a demonstration, go to the "$NAVHOME/SAMPLES" directory and compile the adder.v file with this command: vcs +acc+2 +cli+1 \ -P $NAVHOME/INTEGRATION_KIT/vcspli.tab \ $NAVHOME/INTEGRATION_KIT/libnav.a adder.v Set the NAVSIM environment variable to the name of the compiled simulator: setenv NAVSIM $cwd/simv Start up Magellan with the compiled simulator: navvcs & The "" are the command line options you normally pass to your compiled simulator, i.e. "-f /usr/cad/vcs/licenses/passfile". The Simulator Output and SimWave windows should appear. Once the compiled simulator has entered the interactive mode, you may use the Simulator Output controls. If you have difficultly running Magellan with VCS simulations, please see Section\x118.0, "Common Questions: Magellan with VCS," on page\x1129 4.2.2 Debugging your own designs To use Magellan with your compiled simulator, your Verilog sources should invoke the $ssi_navigator task in a top level module at simulation time 0. Put a $stop task after the $ssi_navigator task. This will bring the simulator to the interactive mode immediately after Magellan has been started. For example, go into "$NAVHOME/SAMPLES" and look at the invocation of $ssi_navigator in the adder.v file. After you have added the $ssi_navigator task to your Verilog sources, link your compiled simulator with the Magellan system tasks. The "$NAVHOME/INTEGRATION_KIT" directory holds the PLI table (vcspli.tab) and library (libnav.a) for the Magellan system tasks. You must also use the "+acc+2" and "+cli+1" options when you compile your simulator. For example, if your Verilog HDL model is in "mycircuit.v", use the following command: vcs +acc+2 +cli+1 \ -P $NAVHOME/INTEGRATION_KIT/vcspli.tab \ $NAVHOME/INTEGRATION_KIT/libnav.a mycircuit.v After you have created a compiled simulator, you must set the NAVSIM environment variable to the name of the image. For example, if your compiled simulator is named "simv", use the command: setenv NAVSIM simv The $NAVHOME/BIN/navvcs command starts Magellan with the compiled simulator. For example, if you normally run the compiled simulation with the command: simv -f /usr/cad/vcs/licenses/passfile & Then use this command to run Magellan: navvcs -f /usr/cad/vcs/licenses/passfile & Magellan will start the simulator, passing to the simulator all the command line arguments that were passed to navvcs. Once the simulator has entered the interactive mode, you may use the Simulator Output control panel. The $ssi_navigator task will not effect your standalone simulations. You can run the compiled simulator either within Magellan or standalone. 4.2.3 Things to avoid Do not stop the simulation with a $stop task before the $ssi_navigator task, and do not use the stop option, "-s". This stops the simulation before the $ssi_navigator task can be invoked. If the simulation is stopped before the $ssi_navigator task is invoked, Magellan will lock up. Do not set NAVSIM to the name of a script file which starts the simulator. NAVSIM must be set to the name of the actual binary image. If you use a script file to start your simulator, we suggest you modify the script file to set the NAVSIM variable and to start navvcs with the appropriate arguments. 4.3 Running with FinSim To run Magellan with FinSim, you need to create a veriuser.o file containing the Magellan system tasks. You can create this file by compiling "$NAVHOME/INTEGRATION_KIT/veriuser.c". If you have your own custom veriuser.c file, then you should merge the declarations in "$NAVHOME/INTEGRATION_KIT/veriuser.c" into your own file. The following describes how to run Magellan interactively with FinSim. It assumes you have created the veriuser.o file from "$NAVHOME/INTEGRATION_KIT/veriuser.c". Go to the $NAVHOME/SAMPLES directory and set the "FINUSERPLILIB" and "FINUSERPLIOBJ" environment variables setenv FINUSERPLILIB $NAVHOME/INTEGRATION_KIT/libnav.a setenv FINUSERPLIOBJ $NAVHOME/INTEGRATION_KIT/veriuser.o Create the makefile: make -f $FINTRONIC/include/MakePLI Compile the simulator for the adder.v model: ./vc -a adder.v $FINTRONIC/bin/gcc/finbuild After you have compiled the simulator, you must set the NAVSIM environment variable to the name of the image. For example, if your compiled simulator is named "TOP.sim", use the command: setenv NAVSIM $cwd/TOP.sim Use the navfin command to start the Magellan with the FinSim simulation: navfin -startPLI & 4.4 Running with BaseLine BaseLine from FrontLine Design Automation is run interactively with Magellan in the exact same manner as Verilog-XL. Please refer to the "Running with Verilog-XL" section. At this time, Magellan does not support the "tracking" feature when running interactively with the BaseLine simulator. 4.5 Recording Value Changes This section describes how to record value changes so that they may be displayed as waveforms in the SimWave window . There are two ways to record a variable. Any variable "added" to SimWave automatically has its value changes recorded. Even if the variable is deleted from the SimWave window, its value changes continue to be recorded. Variables can also be recorded with the $ssi_navrecord task (but without the need to first "add" them to SimWave). The $ssi_navrecord task allows you to record a variable without first displaying it in the SimWave window. When the variable is displayed some time later in the simulation, its recorded changes will appear in the SimWave window. For example, to record every variable in your model, invoke the $ssi_navrecord task without any arguments: $ssi_navrecord; This allows you to display any variable in SimWave, at any time during the simulation, and view all its changes. Value changes which are recorded during the simulation are saved in either a file or in memory. By default, they are stored in a file named nav.rec.ix. For information describing how to rename the nav.rec.ix file, how to store value changes in memory, how to record sub- portions of your Verilog model, and how to turn recording on and off, see Section\x116.1, "Recording Value Changes," on page\x1117. NOTE: If you have not included a $ssi_navrecord task in your Verilog sources, Magellan will pop up a dialog box at the start of the simulation. This gives you the opportunity to record the entire Verilog model. 5.0 Saving the session The "save" item in the Simulator Output "File" menu allows you to save the setup of the current debugging session. It creates a "save file" which contains a list of the signals currently displayed in SimWave. Save files are readable and can be created or modified by the user. There are two ways to display a signal in SimWave. Nets and registers in the VARS column can be selected and displayed in SimWave using the "display" button. Alternatively, if you know in advance which nets and registers you would like to display, you can put their names in a save file and then "restore" from that file. Save files have one command per line with this format: display The "" must be the full path name of a net or register. For example, here is a save file which display two signals: display top.adder.ha16.sum display top.adder.ha16.cout The "restore" item in the "File" menu allows you to restore the setup of a debugging session. It reads the signals listed in a save file and displays those signals in SimWave. If you are running Magellan interactively with Verilog, the "restore" will also start recording value changes for the signals listed. 6.0 Magellan System Tasks 6.1 Recording Value Changes The $ssi_navrecord task records value changes for both interactive simulation and post-simulation processing. It stores the value changes in either a file or in memory. By default it stores the value changes in a special "fast" binary dump file, named nav.rec.ix. The name and location of this file can be changed with the $ssi_navconfigure task. During an interactive simulation, Magellan will read values from the file on demand and display them in SimWave.The file will also contain the values for any signal which was interactively "added" to SimWave. After the simulation has terminated, the values in the file may be viewed with the navvcd command: navvcd nav.rec.ix & The $ssi_navconfigure task can also make $ssi_navrecord store value changes in memory (swap). When values changes are stored in memory, they disappear when the simulation terminates. See Section\x116.3 on page\x1120 for more information. The $ssi_navrecord task is the only task which records value changes for interactive simulation. On the other hand, the $ssi_navrecord, $ssi_navdump, and $dumpvars tasks can all create dump files for post-simulation processing. The $ssi_navrecord task is generally the preferred task for creating dump files. The fast dump file created by $ssi_navrecord can be loaded by navvcd many times faster than a VCD file generated by $dumpvars or a circular dump file generated by $ssi_navdump. However, if you need to limit the size of the dump file, use the $ssi_navdump task. For more information see Section\x116.2 on page\x1119. If simulation speed is your main concern, then you may want to use the $dumpvars task. It will run faster than the $ssi_navrecord and $ssi_navdump tasks, but the file it generates (an ASCII VCD file) takes longer to load and view. Three user system tasks, $ssi_navrecord, $ssi_navrecordoff, and $ssi_navrecordon, control the recording of value changes. The arguments accepted by $ssi_navrecord are: $ssi_navrecord( [ [levels] [,module|var]* ] ); $ssi_navrecord records value changes for hierarchical portions of your Verilog model. If levels is non-zero, it describes the number of levels of hierarchy recorded. If levels is zero, all levels of hierarchy are recorded. If no arguments are specified, everything in the Verilog model is recorded: $ssi_navrecord; $ssi_navrecord may be invoked any number of times, and it has a cumulative effect. For example, to record all value changes at and below the"top.adder" and "top.multiplier" scopes and to record the first 3 levels of "top.io", invoke these tasks: $ssi_navrecord( 0, top.adder. top.multiplier ); $ssi_navrecord( 3, top.io ); Any variable "added" to SimWave also has its value changes recorded (whether or not it was recorded by $ssi_navrecord). In other words, portions of the model may be recorded by $ssi_navrecord and by "adding" variables to SimWave. You can also use "plus args" to specify a file which contains a list of arguments for the task. This allows the VCS user to record different hierarchies without recompiling the simulation. For example, in your Verilog sources include a line like: $ssi_navrecord( "+myreclist" ); When you run your simulator, set the "+myreclist" plus arg to the name of the file which contains the list of arguments for the $ssi_navrecord task. For example, to use the argument list in "/home/cad22/recordlist" start your VCS simulator: simv +myreclist"/home/cad22/recordlist" The "/home/cad22/recordlist" file may contain lines like: 0, top.bench1.test1, top.bench2.test1 5, top.bench3, top.bench4 1, top.bench6, top.bench7 4, top.bench8.alu, top.bench8.io The $ssi_navrecordon and $ssi_navrecordoff tasks control when variables are recorded. For example, variables added to SimWave or recorded by the $ssi_navrecord task have their value changes recorded until a $ssi_navrecordoff task. Recording of value changes will then remain off until a $ssi_navrecordon task. The $ssi_navrecordon and $ssi_navrecordoff tasks take no arguments. NOTE: Recording with $ssi_navrecord can be done even when the Verilog simulation is not running with the Magellan interface. 6.2 Circular Dump File The $ssi_navdump task creates a circular dump file which is intended for regression tests and self testing circuits. If you don't need to limit the size of the dump file, use the $ssi_navrecord task to create a fast dump file instead. The file is called "circular" because its size can be limited. Once the file reaches its maximum size it begins to "wrap" around itself. This allows you save a limited history of a Verilog simulation. For example, if you have a self checking model, you may not want to keep the entire simulation history. Rather, you may want to keep only the last 1 megabyte of value changes. If your test fails, you would then examine the last 1 megabyte of value changes to determine the cause of the failure. To create a 10 megabyte circular dump file named "circ.dump" use the $ssi_navconfigure task and the $ssi_navdump task: $ssi_navconfigure( "-dumpsize 10", "-dumpname circ.dump" ); $ssi_navdump; To view the value changes saved in circ.dump use the navvcd command: navvcd circ.dump & Three user system tasks, $ssi_navdump, $ssi_navdumpoff, and $ssi_navdumpon, control the dumping of value changes. The arguments accepted by $ssi_navdump are: $ssi_navdump( [ [levels] [,module|var]* ] ); The $ssi_navdump task dumps value changes for hierarchical portions of your Verilog model. The $ssi_navdump task may be invoked any number of times during a simulation. If levels is non-zero, it describes the number of levels of hierarchy dumped. If levels is zero, all levels of hierarchy are dumped. If no arguments are specified, everything in the Verilog model is dumped: $ssi_navdump; To dump value changes at and below the "top.adder" and "top.multipliers" scopes and to dump the first 3 levels of "top.io" invoke these tasks: $ssi_navdump( 0, top.adder, top.multiplier ); $ssi_navdump( 3, top.io ); You can also use "plus args" to specify a file which contains a list of arguments for the $ssi_navdump task. This allows the VCS user to dump different hierarchies without recompiling the simulation. For example, in your Verilog sources include a line like: $ssi_navdump( "+mydumplist" ); When you run your simulator, set the "+mydumplist" "plus arg" to the name of the file which contains the list of arguments for the $ssi_navrecord task. For example, to use the argument list in "/home/cad22/dumplist" start your VCS simulator: simv +mydumplist"/home/cad22/dumplist" The "/home/cad22/dumplist" file may contain lines like: 0, top.bench1.test1, top.bench2.test1 5, top.bench3, top.bench4 1, top.bench6, top.bench7 4, top.bench8.alu, top.bench8.io The $ssi_navdumpon and $ssi_navdumpoff tasks control when variables are dumped. After the $ssi_navdump task has been invoked, value changes are dumped until a $ssi_navdumpoff task. Dumping of value changes will then remain off until a $ssi_navdumpon task. The $ssi_navdumpon and $ssi_navdumpoff tasks do not take arguments. 6.3 Configuring the Magellan system tasks The $ssi_navconfigure task configures the way the $ssi_navrecord and $ssi_navdump tasks store value changes files. The $ssi_navconfigure task accepts string parameters which have the form: " " The following table lists the switches accepted by $ssi_navconfigure. TABLE 8. switch value -dumpsize maximum size of circular dump file in megabytes -dumpname name of circular dump file created by $ssi_navdump -dumptypes types of variables recorded by $ssi_navdump, a comma separated list which can include: nets, regs, integers, timevars, realvars, and events -recname name of fast dump file created by $ssi_navrecord -rectypes types of variables recorded by $ssi_navrecord, a comma separated list which can include: nets, regs, integers, timevars, realvars, and events -recmem takes no value, presence of -recmem switch makes $ssi_navrecord task save values changes in memory instead of a file. -recsize maximum number of megabytes for value change storage in memory by $ssi_navrecord (use with -recmem switch). To record value changes in a fast dump file my.rec: $ssi_navconfigure( "-recname my.rec" ); $ssi_navrecord; To record changes for only nets, registers, and time variables: $ssi_navconfigure( "-rectypes nets,regs,timevars" ); $ssi_navrecord; To record changes in memory instead of a file: $ssi_navconfigure( "-recmem" ); $ssi_navrecord; To record only last 10 megabytes of changes in memory $ssi_navconfigure( "-recmem", "-recsize 10" ); $ssi_navrecord; You can also use "plus args" to pass switches to the $ssi_navconfigure task. This allows the VCS user to change the name and location of the dump file without recompiling the simulation. If the value of the "plus arg" starts with a "-", then it is interpreted a single SWITCH. For example, to set the name of the fast dump file to "/home/test/rec1", in your Verilog sources include a line like: $ssi_navconfigure( "+recfilename" ); then start your VCS simulator: simv +recfilename"-recname /home/test/rec1" If the value of the" plus arg" does not start with a "-", then it specifies the NAME of a file which contains one switch/value pair per line. For example, to use the switches in the "/home/test/config" file, in your Verilog sources include a line like: $ssi_navconfigure( "+confilename" ); then start your VCS simulator: simv +confilename"/home/test/config" The "/home/test/config" file may contain lines like: -recname /home/test/rec22 -rectypes nets,regs,integers,timevars 6.4 Creating the data base file If you want connectivity information while viewing a VCD file or a binary dump file (so that Magellan can show you the drivers and loads of a net), you must create a special data base file. The data base file is created by the $ssi_navdbase system task. To create the data base file you must invoke the $ssi_navdbase task in your Verilog sources; the task can appear anywhere in your sources. For example, go to the "$NAVHOME/SAMPLES" directory and look at the invocation of $ssi_navdbase in the adder.v file. By default the $ssi_navdbase task will create a file named nav.dbase. The $ssi_navdbase task has optional arguments: $ssi_navdbase( , []* ); The arguments describe the name of the data base file and the files upon which the data base file depends. If the arguments are omitted, a nav.dbase file will be written each time $ssi_navdbase is invoked. If your model is very large, writing the nav.dbase file may take some time. In this case, you may want to use the optional arguments, so that the data base file is only written when one of the dependency files change. 7.0 Common Questions: Magellan with Verilog-XL 7.1 Checking the setup Make sure these environment variables are set: NAVHOME SIMWAVEHOME NAVSIM SSI_LICENSE Test the value of each environment variable. This command should list the contents of the Magellan installation directory: ls $NAVHOME This command should list the contents of the SimWave installation directory: ls $SIMWAVEHOME This command should indicate an executable binary file: file $NAVSIM This command should indicate a readable text file: file $SSI_LICENSE If the environment variables are set correctly, go to the Magellan samples directory: cd $NAVHOME/SAMPLES Try to run $NAVSIM (your Verilog-XL executable) on the adder.v sample: $NAVSIM adder.v The "" are the command line switches you normally pass to Verilog-XL, e.g. "-x -f /cad/vlog/passcodes". If the $NAVSIM command works, try to run Magellan with the exact same switches: $NAVHOME/BIN/navver adder.v 7.2 Verilog-XL dies immediately You start Magellan, the initial windows pop up, and Verilog-XL immediately exits with zero status. If these symptoms are present: · Verilog-XL is successfully com- pleting the simulation, this indi- cates that the $stop task is not executed. Your Verilog model (your Verilog HDL sources) must contain an invocation of the $ssi_navigator task followed by a $stop task. You start Magellan, the initial windows pop up, and Verilog-XL immediately exits with non-zero status. If these symptoms are present: · Verilog-XL probably exited because of a licensing error, syntax error, or com- mand line error. Run $NAVSIM (your Verilog-XL executable) with the exact same arguments you passed to navver, e.g. "$NAVSIM ". You start Magellan, the initial windows pop up, and Verilog-XL immediately core dumps. If these symptoms are present: · The Verilog-XL/Magellan synchroniza- tion may be corrupted. Make sure the $ssi_navigator task is not invoked in an input file (a file specified on the command line with the "-i" switch). Only, invoke $ssi_navigator from within a Verilog module. · Try using the "-x" switch on the com- mand line. This switch expands vectors and may solve other problems. See the "Vector Net" section later in this docu- ment for a description of other prob- lems solved by the "-x" switch. 7.3 Magellan does not respond after start up You start Magellan, the initial windows pop up, Verilog-XL compiles successfully and prints the prompt, but you can not enter text commands to Verilog-XL. There is no response from Verilog-XL or the browsers, and the pointer inside the Simulator Output window is a watch cursor. If these symptoms are present, there are three things to check: · Make sure you are using a copy of Ver- ilog-XL that is compatible with the ver- sion of Magellan you are using. For example, to use Verilog-XL with Magellan 3.215, your Verilog execut- able must have been compiled with the "magellan3.215/INTEGRATION_KIT/ libnav.a". · Make sure the $ssi_navigator task was invoked before Verilog-XL halted and entered the interactive mode. The $ssi_navigator task must be invoked in your Verilog model before Verilog-XL halts and prints the interactive prompt. · Make sure you are not using the "- s" flag on the command line. Use a $stop after the $ssi_navigator task to halt Verilog-XL initially. 7.4 Verilog-XL dies during navigation Magellan, Verilog-XL, and SimWave all start up successfully, but when you use the Navigator's browsers to go up and down the hierarchy, Verilog-XL dies. If these symptoms are present: · Try using the "-x" switch on the command line. This switch expands vectors and may solve other prob- lems. See the "Vector Net" section later in this document for a descrip- tion of other problems solved by the "-x" switch. 7.5 Verilog PLI problems Systems Science's Magellan software provides interactive graphic simulation control and analysis for Verilog. Magellan is tightly coupled with the Verilog-XL simulator, retrieving information through the Verilog-XL Programming Language Interface (PLI). Unfortunately, Verilog PLI has a number of problems which can adversely affect the operation of Magellan. 7.5.1 Vector Nets Verilog PLI has a problem with the collapsing of vector nets. This can cause Magellan to fail to record value changes on a vector net. If Magellan appears to be not recording value changes, i.e. some vectors are always X or Z (but at other levels of the hierarchy they have correct values), use the "-x" switch. For example: verilog -x mydesign.v The "-x" switch is described in the Verilog-XL Reference Manual section 24.3.15. 8.0 Common Questions: Magellan with VCS 8.1 Checking the setup Make sure these environment variables are set: NAVHOME SIMWAVEHOME NAVSIM SSI_LICENSE Test the value of each environment variable. This command should list the contents of the Magellan installation directory: ls $NAVHOME This command should list the contents of the SimWave installation directory. ls $SIMWAVEHOME This command should indicate an executable binary file: file $NAVSIM This command should indicate a readable text file: file $SSI_LICENSE If the environment variables are set correctly, go to the Magellan samples directory: cd $NAVHOME/SAMPLES Try to run VCS on the adder.v sample: vcs +acc+2 +cli+1 \ -P $NAVHOME/INTEGRATION_KIT/vcspli.tab \ $NAVHOME/INTEGRATION_KIT/libnav.a adder.v setenv NAVSIM $cwd/simv $NAVSIM The "" are the command line switches you normally pass to the compiled simulation, e.g. "-f /usr/cad/vcs/passcodes". If the $NAVSIM command works, try to run Magellan with the exact same switches: $NAVHOME/BIN/navvcs 8.2 Compiled simulation dies immediately You start Magellan, the initial windows pop up, and the compiled simulation immediately exits with zero status. If these symptoms are present: · The compiled simulation is suc- cessfully completing the simula- tion, this indicates that the $stop task is not executed. Your Verilog model (your Verilog HDL sources) must contain an invocation of the $ssi_navigator task followed by a $stop task. You start Magellan, the initial windows pop up, and the compiled simulation immediately exits with non-zero status. If these symptoms are present: · The compiled simulation probably exited because of a licensing error or command line error. Run $NAVSIM (your compiled simulation) with the exact same arguments you passed to navvcs, e.g. "$NAVSIM ". 8.3 Magellan does not respond after start up You start Magellan, the initial windows pop up, the compiled simulation compiles successfully and prints the prompt, but you can not enter text commands to the compiled simulation. There is no response from the compiled simulation or the browsers, and the pointer inside the Simulator Output window is a watch cursor. If these symptoms are present, there are three things to check: · Make sure you are using a copy of the compiled simulation that is compatible with the version of Magellan you are using. For example, to use Magellan 3.215, your compiled simulation must have been linked with "magellan3.215/INTEGRATION_KIT/ libnav.a". · Make sure the $ssi_navigator task was invoked before the compiled simulation halted and entered the interactive mode. The $ssi_navigator task must be invoked in your Verilog model before the compiled simulation halts and prints the interactive prompt. · Make sure you are not using the "-s" flag on the command line. Use a $stop after the $ssi_navigator task to halt the compiled simulation initially. 9.0 Limitations Magellan will only record the first 768 bits of a vector. You may not be able to navigate the connectivity of your circuit if you use the 'remove_gatenames or 'remove_netnames compiler directives. If you use the 'remove_gatenames or 'remove_netnames compiler directives, the Navigator will display "(null)" for gate names and net names. You will not be able to see values for nets removed by the switch-XL algorithm. The switch-XL algorithm is used when you include the "+switchxl" command line switch. Chapter 27.2.3 of the Verilog Language Reference Manual describes which nets are removed by the switch-XL algorithm. Integer and time variables always have their values (in the VARS column) shown in decimal. Warning messages generated by the Magellan/Verilog interface are not flushed to the Simulator Output text window until a carriage return is hit. For example, if you try to record value changes (using the display button) for a net which has been removed by the switch-XL algorithm, the simulator will print a warning. But, this warning will not appear until you hit a carriage return in the text window. Some escaped identifiers are not recognized by Magellan. Escaped identifiers with embedded "." characters may cause navigation problems. Escaped identifiers with "*?{[\" characters may not be displayable in SimWave. Save files and startup files may not work with escaped identifiers. The connectivity data base file nav.dbase may not work with escaped identifiers. Magellan will not allow you to enter multiple-line Verilog XL commands when running VDBX+. For example, lines like the following can not be entered: C1 > if( top.pck == 0 ) > begin > $startstrobing; > end > ; 10.0 Release Notes 10.1 Release notes for version 3.100 10.1.1 Bug Fixes Magellan 3.0 would terminate abnormally when starting VDBX+. This would occur if any of your Verilog source files had path names longer than 31 characters. Magellan 3.0 would not display all of the simulator output in the Navigator text window. Parts of the output generated by $display, $write, $monitor, and $strobe tasks would never appear in the text window. Magellan 3.0 would not display output from VCS simulators (from $display, $write, $monitor, and $strobe tasks) in the Navigator text window until after the simulation had been halted. In Magellan 3.0, the VDBX+ window would not always delete the "break once" icon after the simulation hit the corresponding breakpoint. In Magellan 3.0 , the output of $display, $write, $monitor, and $strobe tasks would not be displayed in the Navigator text window when executing the VDBX+ "next" or "step" button. In Magellan 3.0, starting or restarting the simulation would print error messages similar to: Internal Error: no command queued Magellan versions 1.x and 3.0 would terminate abnormally or display incorrect simulation results when a viewing VCD files that had vectors with more than 768 bits. 10.2 Release notes for version 3.102 10.2.1 Bug Fixes In Magellan 3.0 and 3.100, the Navigator and VDBX+ windows would lock up if you interrupted the simulation twice. This would happen if you hit Control-C or the VDBX+ stop button to halt the simulation and then hit it again before the simulation had actually halted. Magellan 3.0 and 3.100 would terminate abnormally when using input/control files (files which are passed to Verilog-XL using the "-i" command line switch or the "$input" system task). In Magellan 3.100, the "next" button in the VDBX+ window would not maintain focus on the current scope. It acted identically to the "step" button. 10.2.2 Known problems The Navigator's tracking dialog may not display the CANCEL button when running under Sun's Open Windows. To close the tracking dialog: iconify the Navigator window, un-iconify the Navigator window, and choose the "set bus base" item from the "Setup" menu. VDBX+ may require multiple button clicks to set a breakpoint on a source line. This will happen if you had set a "break once" point earlier in the simulation on that same source line. The "BackSpace" and "Del" keys do not work in the VDBX+ dialogs when running under Sun's OpenWindows. 10.3 Release notes for version 3.104 10.3.1 Bug Fixes In Magellan 1.X and 3.X, if you used the connectivity data base along with a partial VCD file (a VCD file which recorded only a subset of your Verilog model), displaying a non-recorded vector caused abnormal termination. 10.4 Release notes for version 3.110 10.4.1 Enhancements Magellan now loads dump files (both VCD and binary files) much faster when using a connectivity data base file (nav.dbase). In previous versions of Magellan, using a connectivity data base file slowed the loading of the dump file substantially. Magellan now allows you to specify the name and location of the binary dump file's symbol table. In previous versions of Magellan, the "$ssi_navdump" task always created a symbol table named "nav.dump.sym" in the current working directory. You can now name the symbol table with the "$ssi_navconfigure" task: $ssi_navconfigure( "-symname /proj/vdac88/nav.dump.sym" ); 10.4.2 Bug Fixes In Magellan 1.X and 3.X, the "$ssi_navrecord" task did not always record value changes when running with Verilog-XL. In the SimWave window, traces for nets (both scalar and vector nets) would show all X's (unknown) even though nets should have been recorded by the $ssi_navrecord task. This behavior was inconsistent; in other parts of the hierarchy, traces for the same signal would show the proper value changes. In Magellan 1.X and 3.X, the $ssi_navrecord and $ssi_navdump tasks would terminate your simulation if your Verilog model contained vectors that had more than 4000 bits. Magellan 1.X and 3.X would terminate abnormally when browsing scopes which contained vectors that had more than 800 bits. This would occur during both interactive and batch usage of Magellan. 10.5 Release notes for version 3.215 10.5.1 Enhancements Changes to the $ssi_navrecord task The $ssi_navrecord task no longer stores values in memory; it stores values in a file named "nav.rec.ix". The name/location of this file can be changed with the $ssi_navconfigure task. The file contains both the values for signals explicitly recorded with $ssi_navrecord and the values for signals which were interactively added to SimWave. During an interactive simulation, Magellan will read values from the file on demand and display them in SimWave. After the simulation has terminated, the values in the file may be viewed with the "navvcd" command. You can also use the $ssi_navrecord task to record changes for post- simulation processing. The file generated by $ssi_navrecord can be loaded by "navvcd" many times faster than an ASCII VCD file (generated by $dumpvars) or a circular dump file (generated by $ssi_navdump). You can now use "plus args" to specify a file which contains a list of arguments for the task. This allows the VCS user to record different hierarchies without recompiling the simulation. For more information see Section\x116.1 on page\x1117. Changes to the $ssi_navdump task The $ssi_navdump task now creates just one file, named "nav.dump". The "nav.dump.sym" file is no longer necessary. Furthermore, $ssi_navdump no longer creates "ping/pong" dump files; instead it creates "circular" dump files. Use the "-dumpsize" argument to tell Magellan when the dump file should start "wrapping" around itself. For example, instead of making two ping/pong files of 100mbytes each: $ssi_navconfigure( "-dumpsize 100", "-dumpname ping,pong" ); $ssi_navdump; make one circular dumpfile of 200mbytes. The resulting "circ.dump" file will always contain the last 200mbytes of changes: $ssi_navconfigure( "-dumpsize 200", "-dumpname circ.dump" ); $ssi_navdump; The $ssi_navdump task may now be invoked as many times as you like. For example, the task may dump two different hierarchies at two different times: $ssi_navdump( 0, testbench1.alu ); #100000 $ssi_navdump( 0, testbench1.io ); You can now use "plus args" to specify a file which contains a list of arguments for the task. This allows the VCS user to dump different hierarchies without recompiling the simulation. For more information see Section\x116.2 on page\x1119. NOTE: The format of the files generated by the $ssi_navdump task have changed. Magellan 3.2XX cannot read dump files generated by older versions of Magellan. If you need to convert your old dump files to the new format, contact Systems Science for a conversion program. Changes to the $ssi_navdbase task NOTE: The format of the files generated by the $ssi_navdbase task have changed. Magellan 3.2XX cannot read data base files generated by older versions of Magellan. If you need to convert your old data base files to the new format, contact Systems Science for a conversion program. Changes to the $ssi_navconfigure task You can use the "-recname" switch to name the fast dump file created by the $ssi_navrecord task. For more information see Section\x116.3 on page\x1120. You can use the "-rectypes" and "-dumptypes" switches to choose the types of variables saved by the $ssi_navrecord and $ssi_navdump tasks. You can use "plus args" to pass switches to the $ssi_navconfigure task. This allows the VCS user to change the name and location of the dump file without recompiling the simulation. Changes for real variables Real variables are now recordable and viewable. If you wish to ignore the real variables in VCD files (because the $dumpvars task stores real parameters, like capacitance coefficients, as real variables in VCD files), use the -ignorereals switch with navvcd: navvcd -ignorereals verilog.dump Changes for named fork blocks Magellan can now navigate into named fork blocks and record variables in named fork blocks. Changes to navvcd "navvcd" can now convert ASCII VCD files (created by $dumpvars) and circular dump files (created by $ssi_navdump) into the fast binary format. Once value changes are in the fast binary format, they can be displayed very quickly. Use the "-convert" switch to specify the name of the new fast binary file. When you want to look at the waveforms in a later session, just run "navvcd" on the new fast binary file. For example, the first time (this generates the dump.ix file): navvcd -convert dump.ix verilog.dump After the first time: navvcd dump.ix 10.5.2 Bug Fixes Magellan now frees memory used for recording value changes when a $reset task is executed. Magellan no longer freezes when polling binary dump files. Earlier version of Magellan would lock up if the user executed the poll command when running navvcd on a dump file created by "$ssi_navdump" 10.6 Release notes for version 5.0 10.6.1 Enhancements For most users, this release is combined with the changes in the Magellan 3.215 release. Release notes for that release should also be read. Magellan now is fully Motif 1.2.4 compliant. Magellan now uses X Resource files instead of the .navigator file to customize Magellan. All user-modifiable parameters are in the $NAVHOME/LIB/app- defaults file. Magellan does not require Motif 1.2.4 or X11R5 be installed on the user systems. To modify these parameters, make a copy of this file and set the environment variable XENVIRONMENT to the full path name of this copy. Magellan now has on-line help available for each window to answer usage questions about each window. Magellan now supports a full 64 bits of simulation time. 10.6.2 Known Problems Warning for users of SunOS 4.1.X OpenWindows There are several serious bugs in SunOS 4.1.X OpenWindows. To avoid crashing OpenWindows, install patch #100444 from Sun. To see if your XNews server has already been patched up, enter: strings $OPENWINHOME/bin/xnews | grep 'Patch #' You should see "X11/NeWS Server - Patch #3000-80". If you don't, you can get this patch by calling Sun, or you can retrieve the patch directly from Sun's patch CDs or via FTP: ftp sunsolve1.sun.com cd /pub/patches binary mget 100444* If you can't get the patch from Sun, contact SSI. Note, even with the patch, OpenWindows will not correctly support the dragging and dropping of text into command entry fields.To avoid applications from crashing randomly, do not drag and drop text into command entry fields (use cut and paste instead). This limitation applies only to text and only to command entry fields, like those at the bottom of the SimWave and Simulation Output windows. You can still drag and drop signals between SimWave windows (by selecting and dragging the names in SimWave's signal list). Warning for users of IBM AIX 3.2.X There is a memory allocation bug in the AIX/Motif libraries, which causes applications to crash. Setting an environment variable as follows, avoids the problem: setenv MALLOCTYPE 3.1 10.7 Release notes for version 5.110 10.7.1 Enhancements A new "-recmem" configuration switch, makes the $ssi_navrecord task store value changes in memory (this was the default behavior in Magellan 1.0 - 3.214). By default, $ssi_navrecord now stores value changes in a file named "nav.rec.ix". When value changes are stored in memory, no dump file is created and the values disappear after the simulation has terminated. See Section\x116.3 on page\x1120 for more information. A new "-recsize" configuration switch limits the amount of memory $ssi_navrecord uses. When $ssi_navrecord runs out of memory, it will free the memory which stores the oldest value changes and use it to store the newest value changes. For example, the following tasks save the last 50 megabytes of value changes in memory: $ssi_navconfigure("-recmem", "-recsize 50"); $ssi_navrecord; 10.7.2 Bug Fixes In Magellan 5.0 - 5.1XX, the waveform display would terminate abnormally when the user tried to display one bit vectors. This would happen with any vector net or vector register that contained only a single bit. 10.8 Release notes for version 5.200 10.8.1 Enhancements Pressing 'Ctrl-C' (SIGINT) in the terminal window that started Magellan interrupts the simulator . The Command entry field in the Simulator Output window now has multiple lines, and its size can be easily adjusted. When reloading the simulator, the user can choose which simulator is started and can change the simulator's command line arguments. 10.8.2 Bug Fixes The dump files generated by the $ssi_navrecord and $ssi_navdump tasks now contain the correct simulation time scale. In previous versions of Magellan, a time scale of 1 second was always used. In Magellan 5.0 - 5.1XX, signals listed in the startup file would not be displayed in the waveform window at startup. Simulator output window would on occasion lose output. Simulator output can now be selected and copied. User's are prevented from backtracking signals with a '-' value (this means that the value was generated by behavioral code). Previous versions would print confusing error messages. Some simulator switches were inadvertently not sent to the simulator. Most notably the '-i' switch. 10.9 Release notes for version 5.300 10.9.1 Enhancements The source level debugger now has a find string capability. The NAVHOME variable is no longer needed, but can be set for ease during the simulator compilation process. The SIMWAVEHOME variable is no longer needed if the SimWave directory is in the same parent directory as the Magellan directory. SSI_LICENSE is not needed if the Systems Science license file is called ssi_license in the same parent directory as the Magellan directory. 10.9.2 Bug Fixes Backtracking window layout and display was corrupted when running under OpenWindows. Magellan would terminate during a drag & drop operation because of an OpenWindows bug. Magellan would not navigate properly into and out of instances with escaped names.