Package: anasymod
anasymodanasymodis a tool for running FPGA emulations of mixed-signal systems.  It supports digital blocks described with Verilog or VHDL and synthesizable analog models created usingmsdslandsvreal.InstallationFrom PyPI>pipinstallanasymodIf you get a permissions error when running one of thepipcommands, you can try adding the--userflag to thepipcommand.  This will causepipto install packages in your user directory rather than to a system-wide location.From GitHubIf you are a developer ofanasymod, it is more convenient to clone and install the GitHub repository:>gitclonehttps://github.com/sgherbst/anasymod.git
>cdanasymod>pipinstall-e.Testing the InstallationCheck to see if theanasymodcommand-line script is accessible by running:>anasymod-hIf theanasymodscript isn't found, then you'll have to add the directory containing it to the path.  On Windows, a typical location isC:\Python3*\Scripts, while on Linux or macOS you might want to check~/.local/bin(particularly if you used the--userflag).Prerequites to run the examplesThe examples included withanasymoduseIcarus Verilogfor running simulations,Xilinx Vivadofor running synthesis and place-and-route, andGTKWavefor viewing the simulation and emulation results.  The instructions for setting up these tools are included below for various platforms.WindowsInstall Xilinx Vivado by going to thedownloads page.  Scroll to the latest version of the "Full Product Installation", and download the Windows self-extracting web installer.  Launch the installer and follow the instructions.  You'll need a Xilinx account (free), and will have to select a license, although the free WebPACK license option is fine you're just planning to work with small FPGAs like the one on the Pynq-Z1 board.GTKwave and Icarus Verilog can be installed at the same time using the latest Icarus binaryhere.LinuxInstall Xilinx Vivado by going to thedownloads page.  Scroll to the latest version of the "Full Product Installation", and download the Linux self-extracting web installer.  Then, in a terminal:>sudo./Xilinx_Vivado_SDK_Web_*.binA GUI will pop up and guide you through the rest of the installation.  Note that you'll need a Xilinx account (free), and that you can select the free WebPACK license option if you're planning to work with relatively small FPGAs like the one on the Pynq-Z1 board.Next, the Xilinx cable drivers must be installed (AR #66440):>cd<YOUR_XILINX_INSTALL>/data/xicom/cable_drivers/lin(32|64)/install_script/install_drivers
>sudo./install_driversFinally, some permissions cleanup is required (AR #62240)>cd~/.Xilinx/Vivado
>sudochown-R$USER*
>sudochmod-R777*
>sudochgrp-R$USER*Installing GTKWave and Icarus Verilog is much simpler; just run the following in a terminal:>sudoapt-getinstallgtkwaveiverilogmacOSThe simulation part of this example should work if you install Icarus Verilog and GTKWave:>brewinstallicarus-verilog
>brewinstall--caskgtkwaveUnfortunately Xilinx Vivado does not run natively on macOS.  However, running Vivado on a Windows or Linux virtual machine on macOS does seem to work.Running a SimulationFrom within the folderunittests, run>anasymod-ibuck--models--sim--viewThis will generate a synthesizable model for a buck converter, run a simulation, and display the results.Command-line optionsHere's a breakdown of what the options mean:The-i buckoption indicates that the folderbuckcontains the emulation files--modelsmeans thatanasymodshould look for a file calledgen.pyand run it.  In this case thegen.pyscript usesmsdslto generate a synthesizable model for the buck converter.--simmeans that a simulation should be run on the computer, rather than building the emulator bitstream.  This is helpful for debugging.  You can also pass the option--simulator_name NAMEto specify which simulator should be used.  Currently supported simulators areicarus,vivado, andxrun(Cadence Xcelium),--viewmeans that the resuls should be displayed after running the simulation.  The viewer can be specified with the--viewer_name NAMEoption.  Onlygtkwaveis supported at the moment.  When a file calledview.gtkwis in the folder with emulator sources,anasymodwill load it to configure the GTKWave display.  You can generate your ownview.gtkwfile usingFile→Write Save Filein GTKWave.Source filesLooking into thebuckfolder, you'll notice there are a bunch of files.  Some have special meanings for theanasymodtool (i.e., if you have a file with one of these names, itanasymodwill treat it in a certain way)gen.py: Generates synthesizable emulation models.anasymodexpects to run this as a command-line script that has arguments-o(output directory) and-dt(fixed timestep).anasymodfills those arguments based on user settings when it runsgen.py.prj.yaml: YAML file containing settings for the project, like the FPGA board to use, build options, emulator control infrastructure to use, etc.  In this case, one of the key options isdt, which indicates that each emulator cycle corresponds to a fixed timestep of 50 ns.simctrl.yaml: YAML file containing signals to probe.  The signals indicated will be probed for both simulation and emulation (in the latter case, using a Xilinx Integrated Logic Analyzer instance).  This file can also specify signals to be written and read in interactive tests.tb.sv: Top-level file for simulation and synthesis, representing a synthesizable testbench.anasymodhas other special files (e.g., ``clks.yaml` for controlling clock generation), but they are not used in this example.Running an EmulationAt this point, we have run a simulation of the emulator design, but haven't built a bitstream of programmed the FPGA.  This section shows how to run those tasks.For this test to work as-is, you'll need aPynq-Z1board.  However, if you uncomment theboard_nameoption inprj.yaml, you can specify a different board; currently supported options arePYNQ_Z1,ARTY_A7,VC707,ZC702,ZC706,ZCU102, andZCU106.  We are always interested to add support for new boards, so please let us know if your board isn't listed here (feel free to file a GitHub Issue).Go to the folderunittestsand run the following command.  It will take about 11 minutes to build the bitstream.>anasymod-ibuck--models--buildIf you are using the Pynq-Z1 board, then please make sure it is set up correctly:Jumper JP4 should be set for "JTAG"Jumper "JP5" should be set for "USB"
Then, plug the Pynq board into your computer using a micro USB cable.  Move the Pynq board power switch to "ON".Run the emulation and view the results with the following command:>anasymod-ibuck--emulate--viewFor now, there is a separate*.gtkwfile used when viewing emulation results, which isview_fpga.gtkw.Timestep ManagementThe example considered so far used a fixed timestep, but for optimal emulator performance, some systems benefit from an event-driven approach, where various blocks make timestep requests, resulting in a variable timestep emulator.Withanasymod, an emulation model can make a timestep request (dt_req), which is passed to an auto-generated time manager.  The time manager takes the minimum of all timestep requests, and passes the result (emu_dt) back to models that need that information.This system is configured through a file calledclks.yaml.  For an example, seeunittests/multi_clock, which represents a system where two independent oscillators are running at different frequencies, and each is making its own timestep requests.If you look in the top-level file (tb.sv), you'll see that there are two oscillator instances,osc_0andosc_1.  These are referenced inclks.yaml, which says thatanasymodshould wire up the timestep request from each (dt_req) as well as the emulator timestep (emu_dt).  It also connects up the emulator clock (emu_clk) and reset signals (emu_rst).This brings us to a point about postprocessing: when you run a simulation or emulation, the raw data produced is dumped to a folder calledraw_results, and includes a timestamp at each emulation cycle.  To make the results easier to visualize,anasymodpost-processes the raw data, applying timestamps to all signals.  The post-processed result is placed in a folder calledvcd; that waveform is what is displayed when you invoke the--viewoption.  However, for debugging timestep issues, it can be useful to examine theraw_resultsfolder, too.Clock GenerationThe sameclks.yamlfile also handles the generation of new clock signals.anasymodautomatically generates an emulator clock signal, but typically there are one or more "real" clocks in the design that need to be generated as well.This takes some care to avoid timing issues, and the strategy taken byanasymodis to make sure the rising and falling edges of all generated clocks are aligned to a rising edge of the emulator clock.  For a block that wants to generate a new clock signal, it produces a clock request (gated_clk_req) in the preceding emulator cycle, like a clock enable signal, andanasymodpasses the generated clock signal (gated_clk) back to the block.  The generated clock is properly aligned and routed through FPGA clock infrastructure to ensure good performance.You can see an example of this configuration by examing theclk_0andclk_1entries inclks.yamlof themulti_clockexample: the oscillator models each produce a clock request, and each clock request is used to generate one clock signal.FirmwareRather than writing tests entirely in RTL, or controlling tests entirely from a host computer, it is often a good compromise to use firmware running on the FPGA to receive commands from the host computer and implement them at a lower level when interacting with the code intb.sv.For FPGAs that contain a Processing System (PS),anasymodautomates much of this process by automatically instantiating the PS and generating firmware to interact with it.  An example can be seen inunittests/custom_firmware, where user code, written inmain.cinvokesGETandSETcommands from the auto-generatedgpio_funcs.hheader.The signals to be set up for reading and writing are specified insimctrl.yaml, just as they would be for VIO-based control.  However, thefpga_sim_ctrlsetting inprj.yamlindicates that VIO control should not be used, and that the FPGA should instead using PS firmware to interact with the DUT.By default,anasymodwill generate amain.cfile, but if you want to use your own, as in this example, setcustom_zynq_firmwaretoTrueinprj.yaml, and then specify the location of themain.cfile insource.yaml(underfirmware_files).Interactive TestsIt's often important to be able to interact with the emulator from Python while it is running, is order to steer the high-level direction of the tests.  This is supported through theAnalysisobject provided by theanasymodPython package, which provides a programmatic way to access all of the features of the command-lineanasymodtool.As an example, consider the example inunittests/rc, which is an RC filter whose input and output are accessible for interactive testing (as specifed in itssimctrl.yamlfile).With theanasymodprogrammatic interface, it's possible to build a bitstream, program the FPGA, and interact with the emulator with a fairly small number of lines of code:fromanasymod.analysisimportAnalysisana=Analysis('path/to/rc')ana.set_target('fpga')ana.build()# build bitstreamctrl=ana.launch()# program FPGActrl.stall_emu()ctrl.set_param(name='v_in',value=1.0)ctrl.set_reset(1)ctrl.set_reset(0)for_inrange(25):ctrl.refresh_param('vio_0_i')v_out=ctrl.get_param('v_out')t=ctrl.get_emu_time()print(f't:{t}, v_out:{v_out}')ctrl.sleep_emu(0.1e-6)In real-world use, it's unlikely that you would want to rebuild the FPGA bitstream before every emulation run, but we have have included the command here just for reference.  As long as the FPGA bitstream is built, you could comment out that line, and everything should still work.This example illustrates howanasymodprovides commands for interacting with emulator time (stall_emu,get_emu_time,sleep), as well as reading/writing emulator values (set_param,get_param).  Emulator I/O works for both digital values and analog values; in the analog case, it automatically converts real numbers to the format being used by the emulator.ContributingTo improve the quality of the software, users are encouraged to share modifications, enhancements or bug fixes with Infineon Technologies AG underGabriel.Rutsch@infineon.com.