1. Parsers API

This section describes the Parsers API providing public classes and methods to parse OpenFPGA, Yosys and VPR generated output files, as presented in Fig. 1.1.

_images/openfpga-softcores-io-files.svg

Fig. 1.1 Output generated files by the OpenFPGA framework, parsed by the OpenFPGA-Softcores platform.

1.1. Yosys Parsers

blif_parser

This Python library parses a Berkeley Logic Interchange Format (BLIF) and Extended BLIF (EBLIF) files, and generate a Python object for convenient use. A BLIF file can contain many models and references to models described in other BLIF files. A model is a flattened hierarchical circuit. For a detailed description of the BLIF file format, see the BLIF documentation.

In this library, the BlifParser object is a list of BlifModel objects.

>>> parser = BlifParser("<blif_filename>")
>>> model = parser[0]           # get the first model in the file
>>> model.get_instance("a[0]")  # get the instance name of the point "a[0]"
>>> model.get_pin("a[0]")       # get the pin name of the point "a[0]"
>>> model.subckts               # list() type
>>> model.names                 # dict() type
>>> model.latches               # dict() type
class parsers.blif_parser.BlifModel(name, **kwargs)

Object to store model properties of a design and its hierarchical elements. For a given point, it returns the equivalent pin name of an element, and the Verilog netlist instance name when the element type is a .subckt.

Variables

  • name (str) – Name of the BLIF model.

  • inputs (list) – All input signals used by the model.

  • outputs (list) – All output signals used by the model.

  • names (dict) – All logic-gate (LUT) elements describe in the model.

  • latches (dict) – All generic-latch elements describe in the model.

  • subckts (list) – All model-reference elements describe in the model.

  • conns (dict) – All direct-connection elements describe in the model.

Parameters

  • name (str) – Name of the BLIF model.

  • inputs (list, optional) – All input signals used by the model.

  • outputs (list, optional) – All output signals used by the model.

get_instance(point_name)

Get the Verilog instance name of a .subckt element.

Note

Works only when the --cname option is enabled when Yosys generates its output BLIF file with the write_blif command.

Parameters

point_name (str) – Point name of the subckt element to be found.

Returns

str – instance name found, None: otherwise.

get_pin(point_name, element_type=None)

Get the pin name of any element type.

The point name is composed of the unique output name and the pin input or output of the element. Examples of pin name format according to the element type:

  • .names: in[#], out[#]

  • .latch: D[0], Q[0]

  • .subckt: data_out[#], data_in[#], …

Parameters

  • point_name (str) – Point name of element to be found.

  • element_type (str, optional) – Specific element type to search for (names, latch or subckt).

Returns

str – pin name found, None: otherwise.

get_pin_latch(point_name)

Get the pin name for a point of a .latch element.

Parameters

point_name (str) – Point name of element to be found.

Returns

str – pin name found, None: otherwise.

get_pin_names(point_name)

Get the pin name for a point of a .names element.

Parameters

point_name (str) – Point name of element to be found.

Returns

str – pin name found, None: otherwise.

get_pin_subckt(point_name)

Get the pin name for a point of a .subckt element.

Parameters

point_name (str) – Point name of element to be found.

Returns

str – pin name found, :obj:None: otherwise.

class parsers.blif_parser.BlifParser(filename)

Parse a BLIF/EBLIF file (generated by Yosys) using pre-defined regex keywords to create a list of BlifModel objects, which describe the full design. If there is only one model in the BLIF file, then the index zero will be used to access it.

BLIF primitives supported: .model, .inputs, .outputs, .names, .latch, .subckt, .cname, .attr, .conn

BLIF primitives not supported: .cycle, .clock, .clock_event, .area, .delay, .start_kiss, .end_kiss, .i, .o, .p, .s, .exdc, .mlatch, .latch_order, …

Variables

  • filename (str) – File name of the BLIF/EBLIF file.

  • models (list) – Models described in the BLIF/EBLIF file.

Parameters

filename (str) – File name of the BLIF/EBLIF file.

get_instance(point_name)

Get the Verilog instance name of a point across all subckt.

Parameters

point_name (str) – Point name of the subckt element to be found accross all BLIF models in the BLIF file.

Returns

str – instance name found, None: otherwise.

get_pin(point_name, element_type=None)

Get the pin name of a point across all models.

Parameters

  • point_name (str) – Point name of the element to be found accross all BLIF models in the BLIF file.

  • element_type (str, optional) – Specify the type of the element.

Returns

str – pin name found, None: otherwise.

yosys_log_parser

class parsers.yosys_log_parser.YosysLogParser(logger_filename='yosys_output.log', searchdir='run_dir/latest')

Parse Yosys .log file to extract the number of signals and cells used to map the design on the FPGA.

Data extracted from the Yosys parser:

  • number of LUTs,

  • number of internal signals,

  • number of input signals,

  • number of output signals,

  • number of wires,

  • number of public wires,

  • number of bits per wires,

  • number of bits per public wires,

  • total number of cells,

  • detailed count per type of cells.

Parameters

  • logger_filename (str, optional) – File name of the file to parse.

  • searchdir (str, optional) – base path to recursively search for the logger file to parse.

1.2. VPR Parsers

vpr_net_parser

This Python library parses a .net file, generated by the VPR packer. In this library, the VprNetParser object provides methods to retrieve Physical Block (PB) information. Since the XML structure could be consequent, all PB are stored in a Look-Up-Table (LUT) with its associated point to save execution time.

>>> rpt = VprNetParser("<net-filename>")
>>> rpt.get_block("a.in[0]") # return the Element object having the point 'a'
>>> rpt.get_pin("a.in[0]")   # return the pin name of 'in[0]' mapped on the PB
class parsers.vpr_net_parser.VprNetParser(filename, debug=False)

Parse the XML structure describing the mapping of the benchmark design on the FPGA architecture target. Since this object is use collaboratively with the VPR timing report files, points are used to retrieve the block properties, such as id, hierarchy or pin_name.

  • startpoints are outputs, listed in the .place report,

  • endpoints are inputs, listed in the .route report.

Variables

  • filename (str) – XML file name to parse.

  • debug (bool) – Enable the debugging mode.

  • root (Element) – object pointing on the XML root instance.

  • pbs (list) – List of Element refering to all Physical Blocks.

  • lut (dict) – Look-up-table associating of every point name to its Element object for fast-searches.

Parameters

  • filename (str) – XML file name to parse.

  • debug (bool, optional) – Enable the debugging mode (default: None).

get_block(point_name)

Get the block object containing the given point_name.

Parameters

point_name (str) – Point name of the block to be found.

Returns

Element – block object, None otherwise.

get_pin(point_name, block=None)

Get the pin name of block containing the given point_name.

Parameters

  • point_name (str) – Point name of the block to be found.

  • block (Element) – object containing the point and pin. Giving the block as parameter will save execution time.

Returns

tuple (name, direction) – pin description, None otherwise.

print_point(point_name)

Quick & Dirty debugging method to print point properties.

Parameters

point_name (str) – Point name of the block to be printed.

parsers.vpr_net_parser.pdebug(text, print_mesg=True, prefix='[DEBUG] ', retval=None)

Print a debugging message with the right format and return.

vpr_place_parser

This Python library parses a .place file, generated by the VPR placer. In this library, the VprPlaceParser object provide a method to retrieve all physical block position on the FPGA grid.

>>> rpt = VprPlaceParser("<place-filename>")
>>> rpt.get_coordinates("a[0]")  # block coordinates containing the point 'a[0]'
>>> rpt.get_coordinates(10)      # block coordinates of the block ID #10
class parsers.vpr_place_parser.VprPlaceParser(filename)

Parse a .place file (generated by VPR) to extract block placement. This object save private look-up-table where block ID and point name are used as keys to get the block coordinates on the FPGA grid.

Variables

  • filename (str) – VPR .place file name to parse.

  • headers (list) – Column headers of the place file.

  • netlist_file (str) – Original netlist file name (optional).

  • array_size (tuple) – Size of the FPGA device layout.

Parameters

filename (str) – VPR .place file name to parse.

get_coordinates(block_id_or_name)

Get the block coordinates in th FPGA grid.

Parameters

block_id_or_name (int, str) – block identifier (integer) or point name (string) of the block position to be found.

Returns

tuple (x, y, sub) – block coordinates, None otherwise.

vpr_route_parser

This Python library parses a .route file, generated by the VPR router. In this library, the VprRouteParser object contains private look-up-table of Net objects accesible by net name or net identifier keys. Each Net could be iterate as a list to go through all nodes composing the path.

>>> rpt = VprRouteParser("<route-filename>")
>>> rpt.get_net(100)            # Net object, a list of nodes
>>> rpt.get_global_net("clk")   # list of block using the global 'clk' net
class parsers.vpr_route_parser.Net(*args, **kwargs)

Object to store net properties and to manipulate each node as a Python list object.

Variables

  • id (int) – Unique identifier of the net.

  • name (str) – Name of the net, more or less related to the output point name.

Parameters

  • *args – Variable length argument list.

  • **kwargs – Arbitrary keyword arguments.

get_route(start, end)

Trace the net path between nodes.

Parameters

  • start (tuple) – Start node coordinates, usually OPIN type.

  • end (tuple) – End node coordinates, usually IPIN type.

Returns

list, list, str, str – node ID, path (list of tuple (node x, node y)), output pin name, and input pin name, None otherwise.

class parsers.vpr_route_parser.VprRouteParser(filename)

Parse a .route file (generated by VPR) to extract node properties.

Routing segment keywords:

  • CHANX : horizontal channel,

  • CHANY : vertical channel,

  • IPIN : input pin,

  • OPIN : output pin,

  • SINK : sink of a certain input class,

  • SOURCE : source of a certain output pin class.

Variables

  • filename (str) – VPR .route file name to parse.

  • place_file (str) – VPR .place file name used before routing.

  • array_size (tuple) – Size of the FPGA device layout.

Parameters

filename (str) – VPR .route file name to parse.

get_global_net(net_id_or_name)

Get the global net according the net ID or the point name.

Parameters

net_id_or_name (int, str) – Net identifier (integer) or point name (string) of the net to be found.

Returns

Net – list of block where the net is connected to, None otherwise.

get_net(net_id_or_name)

Get the Net object according to the net ID or the point name.

Parameters

net_id_or_name (int, str) – Net identifier (integer) or point name (string) of the net to be found.

Returns

Net – list of nodes, None: otherwise.

print_net(net_id_or_name)

List all node in a given net for debugging purpose.

vpr_report_timing_parser

This Python library parses a report timing file, generated by the VPR placer or router. In this library, the VprReportTimingParser object provides methods to iterate each Path object, which are a list of point.

rpt = VprReportTimingParser("<rpt-timing-filename>")
for path in rpt.paths:      # for each path in the file
    for point in path:      # for each point in the Path object
        print(point)        # print the point (dict type)
class parsers.vpr_report_timing_parser.Path(*args, **kwargs)

Define the Path object to store path properties and manipulate each point composing the path like a Python list object.

Variables

  • id (int) – Unique path identifier.

  • startpoint (str) – First point of the path.

  • endpoint (str) – Last point of the path.

  • type** (str) – Path type (setup or hold).

  • arrival_time (float) – Total arrival delay time.

  • required_time (float) – Total required delay time.

  • slack_time (float) – Total slack time of the path.

class parsers.vpr_report_timing_parser.VprReportTimingParser(filename, nb_paths=None)

Parse a report timing file (generated by VPR) to analyze paths and theirs point through which they pass. This object store each Path object like a list item that could be accessed by iteration. When the paths are grouped, this enables to reconstruct the connection tree of each signal in order to perform the routing congestion of the design.

Note

All paths in the design are listed thanks to the VPR command option: --timing_report_npaths -1.

Variables

  • filename (str) – VPR report timing file name to parse.

  • nb_paths (int) – Save parsing time by reading the first paths.

  • fileinfo (dict) – File description and information.

  • paths (list) – All Path listed in the report timing file.

  • groups (dict) – All group of Path having the same start point.

  • stats (dict) – Statistics of the paths.

Parameters

  • filename (str) – VPR report timing file name to parse.

  • nb_paths (int, optional) – Save parsing time by reading the first paths.

print_groups(debug=False)

Print path grouped by startpoint, to debug.

Parameters

debug (bool) – Enable verbose mode.

print_stats()

Print basic statistic information.

vpr_log_parser

class parsers.vpr_log_parser.VprLogParser(stats_filename='vpr_stat.result', logger_filename='vpr_stdout.log', searchdir='run_dir/latest')

Parse VPR .log and .result files to extract place and routing information when the design is mapped on the FPGA.

Data extracted from the VPR parser:

  • Physical Block (PB) types and their occupation ratio,

  • device grid dimensions,

  • device (best) channel width,

  • maximum design frequency,

  • critical path of the design,

  • average net length,

  • average bends per net,

  • average wire segment per net,

  • maximum segments used by a net,

  • total routing area,

  • total logic block area,

  • total wire length.

Parameters

  • stats_filename (str, optional) – File name of the result file to parse.

  • logger_filename (str, optional) – File name of the logger file to parse.

  • searchdir (str, optional) – base path to recursively search for the logger file to parse.