Features and usage scenarious

Full list of arguments might be achieved by

$ fromco -h

You can start fromco on single systemverilog file just typing

$ fromco --file <FILE>

Some preprocessor, parse, and name resolution checks will be performed.

Messages will be printed into stdout with coloring. For example:

error:4e4419: Pipeline_scoreboarding/Control_scoreboard.sv:207:1: [-Wname-resolution]
    could not to find declaration of coder
    |
207 | coder #(.INPUT_WIDTH(4)) exec_pos_coder (
    | ^

Each error message contains severity, location, message type, piece of the source code and hash which can be used for waivers.

Filelists

Fromco supports next expressions in verilog file list:

+incdir+directory
+define+SOME_DEFINE
+define+SOME_DEFINE_IS=12
+define+SOME_DEFINE_IS_WHATEVER=whatever
path/to/verilog/source/file
-v path/to/verilog/source/file
-f path/to/another/filelist
-y path/to/directory/with/verilog/sources (all of them will be read: .v .vh .sv .svh)
// Comments
${ENV_VARIBALE}/path // Environment variables are also supported

Other statements will be ignored.

You may start fromco with filelist using -F <filelist path> cli option.

$ fromco -F <filelist path>

KNOWN ISSUES:

fromco will crash if file at filelist is not exist (will be fixed later)

Focus option

Focus option is usually used with other options.

$ fromco -F <filelist path> --focus hier.path.[entity1,entity2]

Dump-json

Internal data structures after name resulution may be dumped into json with some pre-computations. This feature uses --focus options for specifying entities to dump.

Some kinds of entities are supported:

port
portgroup
struct
enum
interface
paramgroup

Example:

module demo #
(
    parameter X = 4
)(
    input [X-1:0] a, // Some description of a
                     // Might be multiline

    // Description of b
    output        b  // Inline comment has lower priority
);

endmodule

$ fromco --file demo.sv --focus demo.[a,b] --dump-json portgroup

Such output will be produced (in file fromco-json.out)

{
  "enBody": {
    "pgPorts": [
      {
        "pDirection": "input",
        "pSignal": {
          "sDescription": "Some description of a\nMight be multiline",
          "sName": "a",
          "sRange": "3..0",
          "sType": null,
          "sWidth": "4"
        }
      },
      {
        "pDirection": "output",
        "pSignal": {
          "sDescription": "Description of b",
          "sName": "b",
          "sRange": "",
          "sType": null,
          "sWidth": "1"
        }
      }
    ]
  },
  "enHead": "EkPortGroup"
}

Widths of a signals were calculated to the numbers. You can dump parameters as symbols (localparams will be calculated as numbers):

$ fromco --file demo.sv --focus demo.[a,b] --dump-json portgroup --symbolic

Which gives you

{
  "enBody": {
    "pgPorts": [
      {
        "pDirection": "input",
        "pSignal": {
          "sDescription": "Some description of a\nMight be multiline",
          "sName": "a",
          "sRange": "(X-1)..0",
          "sType": null,
          "sWidth": "(X)"
        }
      },
      {
        "pDirection": "output",
        "pSignal": {
          "sDescription": "Description of b",
          "sName": "b",
          "sRange": "",
          "sType": null,
          "sWidth": "1"
        }
      }
    ]
  },
  "enHead": "EkPortGroup"
}

Localparams declared at imported packages may be converted to symbols using --params-imported option.

This feature may be used for documentation generation. There is a script which accepts a list of entities and produces a long .tex or .adoc file with tables which are ready to be included to your documentation (see scripts/fromco-dump.py). You can play with demo of documentation building pipeline (see examples/dump-json/).

Sizecheck

Fromco is intented to be a tool which helps to write reusable parametrized SystemVerilog code. It supports number of signal width checks with symbolic interpretation of parameter values.

Symbolic width checks

Fromco supports parameter agnostic width check. Each parameter (and localparam from imported package) is interpreted as symbolic value. Width check is generalized and perfomed over symbolic sizes of variables.

parameter  X = 5;
localparam Y = X;
localparam Z = 5;

logic [4:0]   a;
logic [X-1:0] x;
logic [Y-1:0] y;
logic [Z-1:0] z; 

assign a = x; // Warning: 5 vs X
assign y = a; // Warning: Y vs 5
assign z = a; // OK
assign y = x; // OK

Symbolic parameters can be narrowed to exact values using conditional statements.

if (X == Z)
  assign z = x; // OK
else

Parameter values can be bounded using assumptions.

initial X_assumption : assume (X == Z);

assign z = x; // OK

It may compute complex expression over symbolic parameter values, but now it is not 100% accurate (TBD).

Clock gating warning

In ASIC design it is nessesary to provide enable signal for large flip-flops. Fromco will warn NBA without enable signal when width of the flip-flop is parametrized or has large number of bits.

parameter X;
logic         a;
logic [4:0]   b;
logic [X-1:0] x;

always_ff (@posedge clk)
begin
  a <= a_next; // OK
  b <= b_next; // Warning
  x <= x_next; // Warning
end

always_ff (@posedge clk)
if (a) begin
  b <= b_next; // OK
  x <= x_next; // OK
end

Signal naming checks

Might be invoked with:

$ fromco -F <filelist path> --style

Uses common postfixes for signals:

_i for inputs
_o for outputs
_ff for flip-flops
_en for enables

Keyboard shortcuts

fromco