Documentation

User Guide

ZamiaCAD is advanced RTL debug and analysis framework with integrated VHDL editor.

• User Guide
  • Getting started
  • Editor
  • Ref search
  • Scripting
    • elaboration
    • Simulation, listening for events and reading signal values
    • Other Python examples
  • Applications
  • Tutorials
• Developer Guide

Getting started

Download ZamiaCAD as a product or Update Site plugin. Since we are talking about Java application here, running it requires Java (JRE or JDK).

Note that whenever you create a ZamiaCAD project, you need to provide a BuildPath, which is ZamiaCAD's equivalent of make file. Here is how you specify the toplevel entity in BuildPath. To get started, it may be worth looking at how to edit and simulate VHDL project tutorial.

Editor

The editor provides code entry with lexical coloring of VHDL, Verilog, Python and BuildPath files. It also highlights the string occurrences, which is useful when you do manual identifier renaming (such refactoring is not supported).

It is worth to know some useful hot keys:

• VHDL Editor displays item declaration info when hovering over it with a mouse and hyperlinking (jumping to the declaration) when Ctrl+mouse click on the item.
• Hitting F5 in the editor, adds the signal under cursor into simulator's Waveform, just make sure that Path is set right.
• Alt+Shift+A toggles the block selection mode.
• ZamiaCAD incrementally rebuilds the project and updates the Outline View on Ctrl+S save. except packages. To rebuild VHDL packages, one needs to use full build from the Project > Full Build or Clean. Build checks synthax and semantics of VHDL code and builds IG model ready for code analysis.

Ref search

To find out where signals are driven and/or read, use Static Analysis->Show References... from
the editor's context menu (or simply press CTRL+SHIFT+G) while pointing the cursor on a signal
name. Any occurrence of the signal name will do. Just pay attention that path is set to correct module.

The dialog for the following code

entity LEVEL2 is port (A, in2, B: integer); end entity;
architecture Arch of LEVEL2 is
    signal LEVEL2, L2, L2a: integer; 
begin 
    LEVEL2 <= in2;
    L2 <= in2;
    L2A <= a;
end architecture;  

entity LEVEL1 is port (in1: integer); end entity;
architecture stimuli of LEVEL1 is
begin  
    U2: LEVEL2 port map (1, in1, 2);
end stimuli;

package PKG1 is
    subtype T1 is integer; 
end package;

entity LEVEL0 is end;
use WORK.PKG1.all;
architecture stimuli of LEVEL0 is
    signal TOP: integer; -- signal TOP: WORK.PKG1.T1;   
begin
    U1: LEVEL1 port map (TOP);   
end stimuli;

may look like

Here, local limits the search to the current module only, local+down will search for local references and references in any module instantiated below the current module, global will search for references throughout the design. That is, looking for IN2 drivers locally, yields no results whereas global search produces TOP signal in the topmost LEVEL0 module. That is because global search traces signals through the instantiation ports. You can even see the instantiation labels if do the converse search, for the readers of the TOP signal

In addition to tracing signal passage through ports, it is possible to trace their passage through assignment statements <=. For instance, making the global backward search from signal L2 with path WORK.LEVEL0:U1.U2. yields IN2 and TOP. That is expected because IN2 drives L2 through signal assignment and TOP drives IN2 through a series of ports.

Through signal assignment is more advanced through. It was used to track signal dependencies and, therefore, if we have code

        if A > B then
            C <= 11;
        end if;
        D <= C;

Then backward search on D first yields C and, on the next level, A and B and even constant 11. Thus, through signal assignment search allows to build the cones of influence aka static slices.

Scripting

Zamiacad can be scripted with Python. You need to set up both PYTHONPATH and JYTHONPATH env variables to python library, if you are going to use the scripting. ZamiaCAD distributes the library with sources, in folder share/python/Lib.

Python scripts can be run either from Eclipse environment or your system console. The latter is done using zamiacad.bat or zamiacad.sh (can be found in source code distribution), which initialize a CAD project and give you the Python shell without loading any Eclipse environment. On the other hand, to run the scripts from the Eclipse environment, either select your .py file in ZamiaCAD navigator or make your Python Editor active/focused such that context menu Run As > Python script is enabled

For output, use printf("%s", something) instead of standard python's print since latter is invisible in the Eclipse console.

elaboration

Elaboration is as easy as rebuild(). It will elaborate all top levels specified in the BuildPath.txt. Once elaboration is finished, system is ready for simulation or for the static analysis of the code.

Simulation, listening for events and reading signal values

Running simulator from a Python script is simple

    sim = openSim()
    run(sim, simtime_in_ns)

It is often useful to read some signal values while simulating. Taken from rejuvenation application

    class ClkMonitor(SimData.TraceAddListener):

        def trace(self, SignalPath, time, Value, IsEvent):

            global clocks

            if IsEvent and clk.equals(SignalPath):
                clocks += 1

                for l in module.getContainer().localItems():
                    if isinstance(l, org.zamia.instgraph.IGObject) and l.getCat() == IGObjectCat.SIGNAL:

                        id = l.getId()

                        value = str(sim.getValue(PathName("DUT_GATES." + id)))
                        if len(value) == 1:
                            count(id, value)
                        else:
                            #printf("%s too long value = %s" % (id, value))
                            processARange(l, lambda id, bitvalue: count(id, bitvalue), value)

    #sim = openSim()
    sim = openSim2(tl.getDUUID()) #simulate chosen toplevel

    sim.fData.traceAddListeners.add(ClkMonitor())

    run(sim, simtime)

where count is a function that increments some counter depending on the string value, if it is 0 or 1. Example demonstrates how to define a listener class to capture signal change events and install it using sim.fData.traceAddListeners.add. Sim.getValue(path) is used to read signal value.

Other Python examples

[Python Examples] that were used in our project also serve a good reference. They demonstrate that good understanding of IG Java classes is necessary for scripting ZamiaCAD in Jython.

Applications

[Rejuvenation Application] demonstrates how we used ZamiaCAD to rejuvenate hardware circuits.
Another application, automatic debugging, is referenced in tutorials.

Tutorials

How to Edit and Simulate VHDL (Plasma uP) project

Automatic Debugger shows how to run tests, if you have some tests. Depending on test passed/failed and VHDL code executed, the framework marks suspicious code with red highlights.

Developer Guide

Get involved tutorial explains how to fetch code and build the project.
[Eclipse plugin classes]
[ZamiaCAD core classes]
How to publish the product on the sourceforge server.