Logic Investigator (li) has 2 parts:
- reader(s) - as of 1.2, just Altera's EQN format
- analyzers - as of 1.2, several variations for looking at clock domains and tracing flop to flop paths

Also, this readme file describes the structures used by li.

li EQN reader:
Lacking a description of the Altera EQN format, I inferred what I 
could from sample files. The format defines signals as either as 
an equation of other signals (combinational logic), or the output 
of an instance. Instances include flops (DFFE), memory elements 
(one bit slices), IO pads, BUS elements to join multiple signals 
as an address to memory, tristate elements and many other types. 
I have incorporated as many instance types as I have seen, and 
inferred as much as I can from the connections to them.

Comments are also present in many EQN files that provide name mapping
between original hierarchical names and reduced names used in the
EQN equations.

In the EQN format equations, the following operators are used:
  #: or
  &: and
  !: not
  $: exclusive-or
  also, nets may be enclosed by GLOBAL() to indicate that a global
wire is used for that net.

Instances have implicit order based pin connections. All instances
have just one output, always 1 bit wide except for BUS types. 
They include:
 DFFE/DFFEA: flop. pins are:
    D, clock, async reset, async set, clock enable
    (the clock enable controls a mux that selects between the D input
    and recycling the flop output).
 INPUT: IO pad for a design input - no input pin, used in the form
    example: reset_l = INPUT() ;
 OUTPUT: IO pad for a design output - one input pin is to the pad
    example: dataout_0_ = OUTPUT(dout_internal_0_);
 BIDIR: IO pad for a bidirectional IO signal, similar to OUTPUT,
    but output name will be used in other equations.
 TRI: tristate control for internal or IO signal. pins are:
    data, tristate enable.
 PLL: phase locked loop resource. one input pin is reference clock.
    multiplier/divider/frequency is not indicated in EQN file.
 MEMORY_SEGMENT: one column of memory (1 bit wide). pins are:
    write clock, read clock (may be <null>), (unknown), clock enable for write clock,
    write enable, read enable, async clear?, (unknown), write data, write address (bus),
    read address (bus)
  (actually, write data may be a wide bus, and there may be multiple instances)
 RAM_SLICE: also one column of memory (1 bit wide). pins are:
    write data, write enable, write clock, read clock (may be <null>), (unknown),
    (unknown), (unknown), (unknown), (unknown), write address (bus), read address (bus)
 LVDS_INPUT: negative polarity design input, accompanies a normal INPUT
 LVDS_OUTPUT: negative polarity design ouput, accompanies a normal OUTPUT
 LVDS_TX: Parallel to serial LVDS core. pins are:
    clock1, clock2, wide data. output will propagate to design output. 
 LVDS_RX: Serial to parallel LVDS core. Always in a set of 8 instances, as output of
    instance is 1 bit, but real core has 8 bites of output data. pins are:
    enable, clock1, clock2, signal from IO pad. 
 CARRY: combinational gate for arithmetic operation
 CASCADE: combinational gate for arithmetic operation
 BUS: joins several signals together to form a memory read or write address, or write data.
 DATA: joins several signals together to form a wide signal to a core/
 RD_ADDR: alternate way to join several signals
 WR_ADDR: alternate way to join several signals
 GLOBAL: property for a signal, that it uses global routing resource.
 OPNDRN: property for a design output, that it is an open drain signal.



Data structures for 'li':
Several data structures are used for li:

- For each instance, there is an entry in an associative array (a PERL hash),
with the instance type, a list of input nets, and output nets. The lists for 
inputs and outputs are a pair of entries for each pin, the first being the net 
name, and the second entry being the type of the pin.

- For each net, there is also an entry in an associative array with the
net properties (a number with each bit position representing a property), a
list of driving instances, and a list of receiving instances. Again, the lists
are as pairs of entries for each pin, with the instance name and the pin type.

- EQN files use shorten names, but have comments in which the short
names are mapped to longer names that are more likely to look familiar
to a designer as they have the design hierarchy intact. Two associative
arrays are used to map the shorten names to long names for reports, and
back to allow the designer to specify trace nodes using the long names.

- The actual equations/instances are kept for every signal so they can be
printed for traces.

- A list of all signals connected to flop reset/set pins is kept to be
used for a reset/set check.



Design analysis commands:

excl[usionfile] <exclusion file> - read a file to get pairs of flops to exclude from reports. PERL regular expressions are supported. Names may be either the short or long EQN names.

cross[ing_report] - generate a list of all source flops that propagate to flops in other clock domains (for each source flop, lists all destinations in other domains)

dang[erous_crossings] - only report crossings with multiple sources, multiple destinations, or multiple paths.

io_r[eport] - generate a list of all flops related to every design IO signal, including clock at the flops

io_f[lop_report] - list all IO signals that connect directly to single flops such that the flops are likely to be IO flops.

io_n[otflop_report] - list all IO signals that do NOT connect directly to single flops.

res[et_check] - report any signal that propagates to both set/reset and non-set/reset pins of flops

trace_fwd <start> <end> - report all paths between the start and end points

trace_back <start> <end> - reverse trace, same as trace_fwd.


$Id: readme.li,v 1.3 2003/06/11 03:41:18 cbenz Exp cbenz $

$Log: readme.li,v $
Revision 1.3  2003/06/11 03:41:18  cbenz
touch to match li 1.3

Revision 1.2  2003/06/11 03:38:30  cbenz
matches li 1.2

