Netlist.pm

#** @file Netlist.pm
# @verbatim
#-------------------------------------------------------------------------------
#  University of Applied Sciences Technikum Wien
#
#  Department of Embedded Systems
#  http://embsys.technikum-wien.at
#
#  Josef Ressel Center for Verification of Embedded Computing Systems
#  http://vecs.technikum-wien.at
#
#-------------------------------------------------------------------------------
#  File:              Netlist.pm
#  Created on:        29.04.2015
#  $LastChangedBy$
#  $LastChangedDate$
#
#  Description:
#
#  FIJI Netlist class: Functions to instrument & export a Verilog::Netlist
#-------------------------------------------------------------------------------
# @endverbatim
#*

## @file Netlist.pm
# @brief Contains class \ref FIJI::Netlist

## @class FIJI::Netlist
# @brief Functions to instrument & export a Verilog::Netlist
package FIJI::Netlist;

use strict;
use warnings;

use Log::Log4perl qw(get_logger :easy);

use Verilog::Netlist 99.415;
use Verilog::Language 99.415;
use Data::Dumper;

use FIJI::VHDL;

use constant HIERSEP               => "|";
use constant FIJI_PORT_PREFIX      => "fiji_";
use constant FIJI_PORT_IN_POSTFIX  => "_inj_i";
use constant FIJI_PORT_OUT_POSTFIX => "_ori_o";

use constant FIJI_LOGO => <<logo_end;
//  FIJIFIJIFIJIFIJIFIJIFIJIFIJIFIJIFIJIFIJI
//  FIJIFIJIFIJIFIJIF   FIJIFIJIFIJIFIJIFIJI
//  FIJIFIJIFIJIFIJ    IFIJIFIJIFIJIFIJIFIJI
//  FIJIF       FI           IJIFIJIFIJIFIJI
//  FIJIFIJIFI            JIFIJIFIJIFIJIFIJI
//  FIJIFIJI            FIJIFIJIFIJIFIJIFIJI
//  FIJIFI     I   IFI   IJIFIJIFIJIFIJIFIJI
//  FIJIF         JIFIJ   JIFIJIFIJIFIJIFIJI
//  FIJIFIJIFI   IJIFIJI   IFIJIFIJIFIJIFIJI
//  FIJIFIJIF    IJIFIJIFIJIFIJIFIJIFIJIFIJI
//  FIJIFIJI    FIJIFIJIFIJIFIJIFIJIFIJIFIJI
//  FIJIFIJ     FIJIF           FIJIFIJIFIJI
//  FIJIFI     IFI      Fault      IFIJIFIJI
//  FIJIF             InJection     FIJIFIJI
//  FIJ              Instrumenter    IJIFIJI
//  F                                    IJI
//  FIJIFIJIFIJIFIJIFIJIFIJIFIJIFIJIFIJIFIJI
logo_end

## @function public new ()
# @brief creates a new FIJI::Netlist object
#
# @returns the newly created FIJI::Netlist object
sub new {

    my ($class) = @_;

    my $self = {};
    bless $self, $class;

    $self->{'nl'} = new Verilog::Netlist(

        # options => $opt,
        # keep_comments => 1, # include comments in netlist
        link_read_nonfatal => 1,    # do not fail if module description not found
        use_vars           => 1,
    );
    return $self;
}

## @method public read_file ($filename)
# @brief Tries to read a Verilog netlist from the given file
#
# @param filename    The Verilog file to read
#
# @returns 1   if an error occurred
# @returns 0   if successful
sub read_file {
    my $logger = get_logger("");
    my ($self, $filename) = @_;

    ## Netlist synthesized from VHDL could contain SV keywords at this point.
    Verilog::Language::language_standard("1364-2001");

    $logger->info("Reading in netlist from file \"$filename\".");
    eval {
        $self->{'nl'}->read_file(filename => $filename);    # read Verilog file
        $self->{'nl'}->link();                              # Read in any sub-modules
    };

    if ($self->{'nl'}->errors() != 0 || $@) {
        $logger->error("Could not parse $filename!", $@ ? "\n" . $@ : "");
        return 1;
    }

    $self->{'filename'} = $filename;

    $logger->info("Successfully read in netlist from file \"$filename\".");
    return 0;
}

## @method public get_toplevel_port_names ()
# @brief retrieves the port names of all toplevel modules
#
# @returns an array of Verilog::Port references
sub get_toplevel_port_names {
    my ($self, $dir) = @_;
    my $ports_ref = [];
    foreach my $mod ($self->{'nl'}->top_modules_sorted) {
        foreach my $port ($mod->ports) {
            if (   !defined($dir)
                || ($dir eq "o" && $port->direction eq "out")
                || ($dir eq "i" && $port->direction eq "in"))
            {
                push @{$ports_ref}, $port->name;
            }
        }
    }
    return $ports_ref;
}

## @method public get_toplevel_module ()
# @brief retrieves the port names of all toplevel modules
#
# @returns a Verilog::Module reference
sub get_toplevel_module {
    my ($self) = @_;
    my @m      = $self->{'nl'}->top_modules_sorted;
    my $n      = @m;
    return $m[0] if ($n == 1);
    return "More than one toplevel module present in netlist." if ($n > 1);
    return "No toplevel module found.";
}

## @method public get_nets ()
# @brief retrieves all nets in the netlist
#
# @returns an array of hashes for all nets containing:
# 'name' the name of the net
# 'path' the hierarchical path of the net
# 'net'  the Verilog::Netlist::Net reference to the net
sub get_nets {
    my ($self) = @_;

    # my $nets_ref = {'metadata' => [], 'names' => [], 'nets' => []};
    my $nets_ref = [];
    my $hier     = "";
    foreach my $mod ($self->{'nl'}->top_modules_sorted) {
        $self->_get_subnets($nets_ref, $mod, $hier);
    }
    return $nets_ref;
}

#** @method private _get_subnets ($nets_ref,$mod,$hier)
# @brief retrieves all nets in the given module
#
# @param nets_ref    the central reference to push found nets (name,path,netref) to
# @param mod         the module to search
# @param hier        a string representing the current hierarchy level, separated
#                    be HIERSEP
sub _get_subnets {

    my $logger = get_logger("");
    my ($self, $nets_ref, $mod, $hier) = @_;

    my $thishier = $hier;
    $thishier .= HIERSEP if $thishier ne "";
    $thishier .= $mod->name;

    foreach my $n ($mod->nets) {
        if (defined $n->msb && $n->lsb) {
            my $low = $n->lsb;
            my $high = $n->msb;
            # msb might be lower than lsb if index range is "upto"
            if ($n->msb < $n->lsb) {
                $low = $n->msb;
                $high = $n->lsb;
            }
            for (my $sub = $low ; $sub <= $high ; $sub++) {
                my $thisnet_ref = {name => $n->name . "[$sub]", path => $thishier, net => $n, index => $sub};
                push(@{$nets_ref}, $thisnet_ref);
            }
        } else {
            my $thisnet_ref = {name => $n->name, path => $thishier, net => $n};
            push(@{$nets_ref}, $thisnet_ref);
        }

    }

    foreach my $cell ($mod->cells) {
        if (defined($cell->submod)) {
            $self->_get_subnets($nets_ref, $cell->submod, $thishier);
        }
    }
}

## @function private _check_name_in_hierarchy ($startmod,$name)
# @brief checks if a given name exists
# checks if the $name exists as port, net, or cell name in the instantiation tree.
#
# @param startmod    the module to start with
# @param name        the name to check against
sub _check_name_in_hierarchy {

    my $logger = get_logger("");
    my ($startmod, $name) = @_;
    my $nl = $startmod->netlist;

    $logger->debug("Checking " . $startmod->name . " for name $name");

    # check if a net is named the same
    for my $net ($startmod->nets) {
        if ($net->name eq $name) {
            my $msg = "Name $name does already exist as net in " . $startmod->name;
            return $msg;
        }
    }

    # check if a port is named the same
    for my $port ($startmod->ports) {
        if ($port->name eq $name) {
            my $msg = "Name $name does already exist as port in " . $startmod->name;
            return $msg;
        }
    }

    for my $cell ($startmod->cells) {
        if ($cell->name eq $name) {
            my $msg = "Name $name does already exist as cell in " . $startmod->name;
            return $msg;
        }
    }

    # find any module instantiating the current start module
    foreach my $mod ($nl->modules) {
        foreach my $cell ($mod->cells) {
            if (defined $cell->submod && $cell->submod == $startmod) {
                my $msg = _check_name_in_hierarchy($mod, $name);
                return $msg if defined $msg;
            }
        }
    }

    return undef;
}

## @function private _add_port_to_hierarchy ($startmod,$name,$function,$index,$indent)
# @brief adds a port to all modules starting from a leaf node
#
# @param startmod    the module to start with
# @param name        the port name to be generated
# @param function    the function of this port in FIJI (FIJI::VHDL->FIJI_PORTTYPE_xxx)
# @param index       for ORIGINAL,MODIFIED and FAULT_DETECT: the index of this net
# @param indent      optional, needed just for formatting logging output
#
# @returns undef if the given port $name is already found
# @returns Verilog::Port reference to the new port if successful
sub _add_port_to_hierarchy {

    my $logger = get_logger("");
    my ($startmod, $name, $function, $index, $indent) = @_;
    my $nl        = $startmod->netlist;
    my $direction = "undef";
    if (!defined $indent) {
        $indent = "";
    } else {
        $indent .= "  ";
    }

    return undef if ($startmod->find_port($name));

    $logger->debug($indent . "Adding port $name to module " . $startmod->name);

    # decide direction
    if (   $function == FIJI::VHDL->FIJI_PORTTYPE_MODIFIED
        || $function == FIJI::VHDL->FIJI_PORTTYPE_RESET_TO_DUT)
    {
        $direction = "in";
    } else {
        $direction = "out";
    }

    # generate port
    my $np = $startmod->new_port(name => $name, direction => $direction);

    # set port type for wrapper generation
    $np->userdata(FIJI::VHDL->FIJI_USERDATA_PORTTYPE, $function);

    # set indices
    if (   $function == FIJI::VHDL->FIJI_PORTTYPE_MODIFIED
        || $function == FIJI::VHDL->FIJI_PORTTYPE_ORIGINAL)
    {
        $np->userdata(FIJI::VHDL->FIJI_USERDATA_FIU_INDEX, $index);
    } elsif ($function == FIJI::VHDL->FIJI_PORTTYPE_FAULT_DETECTION) {
        $np->userdata(FIJI::VHDL->FIJI_USERDATA_FD_INDEX, $index);
    }

    # let Verilog-Perl create a new net for the new port.
    $startmod->link;

    # find all modules instantiating the current module
    foreach my $mod ($nl->modules_sorted) {
        foreach my $cell ($mod->cells) {
            if (defined $cell->submod && $cell->submod == $startmod) {
                $logger->debug($indent . "Adding pin $name to cell " . $cell->name);
                $logger->debug($indent . "Connecting pin " . $cell->name . HIERSEP . $name . " to port " . $np->module->name . HIERSEP . $np->name);
                $cell->new_pin(
                    name     => $name,
                    portname => $np->name,
                    netnames => [{'netname' => $np->net->name}],
                );

                # let verilog-perl find the net and port.
                # @FIXME sufficient to link "mod" here?
                $mod->link;
                _add_port_to_hierarchy($mod, $name, $function, $index, $indent);
            }
        }
    }

    return $np;
}

## @method public net_add_function($net, $function, $port_name, $index)
# @brief Generate external access to a single net
#
# Performs the following steps:
#    1.  check if the default port name does not yet exist
#    1a. if it exists, generate a new net name
#    2.  add a port through the entire hierarchy
#    3.  assign the net to the port using a contassign statement
#
# @param net         the Verilog::Net object to be used
# @param function    the function out of FIJI::VHDL->FIJI_PORTTYPE_xxx
# @param port_name   how the port shall be named (will be prefixed with "fiji_")
# @param index       for some FIJI_PORTTYPEs, an index is needed (FIU and Fault Detect)
#
# @returns undef
sub net_add_function {
    my $logger = get_logger("");
    my ($self, $net, $function, $port_name, $index) = @_;

    $logger->debug("Adding function to " . $net->module->name . ", net " . $net->name);

    my $prefix = "fiji_";
    while (1) {
        my $msg = _check_name_in_hierarchy($net->module, $prefix . $port_name);
        if (!defined $msg) {
            $port_name = $prefix . $port_name;
            last;
        } else {
            $prefix = sprintf("fiji_%4x_", rand(0xffff));
        }
    }

    $logger->debug($port_name . " can be used as fiji connector");
    my $op = _add_port_to_hierarchy($net->module, $port_name, $function, $index);

    $logger->debug("Connecting Port " . $op->name . " to net " . $net->name);

    # connect the net to the newly created port
    $net->module->new_contassign(
        keyword => "assign",
        lhs     => $op->name,
        rhs     => $net->name,
        module  => $op->module,
        netlist => $op->module->netlist
    );

    return undef;
}

## @method public instrument_net($net,$fiu_idx, $driver, $driver_type)
# @brief instruments a single net for fault injection
#
# This method performs the following steps
#   1. tries to determine the driver, or otherwise prompts the user to select it
#   2. generate external access output and input ports
#   3. interconnects these ports to the matching driver and driven cells
#
# @param net             the Verilog::Net to instrument
# @param fiu_idx         the FIU number this external access shall be connected to
# @param driver          the driver of this net (optional)
# @param driver_type     the type of the driver (can be PIN, PORT, ASSIGN)
#
# @returns STRING          if an error occurred
# @returns undef           if successful
sub instrument_net {

    my $logger = get_logger("");
    my ($self, $net, $fiu_idx, $driver, $driver_type) = @_;
    my $msg;

    $logger->info("Instrumenting " . $net->module->name . ", net " . $net->name);

    # VHDL signals must not contain multiple subsequent underscores
    my $output_name = ((FIJI_PORT_PREFIX . $net->name . FIJI_PORT_OUT_POSTFIX) =~ s/__+/_/gr);
    my $input_name  = ((FIJI_PORT_PREFIX . $net->name . FIJI_PORT_IN_POSTFIX) =~ s/__+/_/gr);

    $msg = _check_name_in_hierarchy($net->module, $output_name);
    return $msg if defined $msg;

    $logger->debug($output_name . " will be used as fiji connector (output)");
    my $op = _add_port_to_hierarchy($net->module, $output_name, FIJI::VHDL->FIJI_PORTTYPE_ORIGINAL, $fiu_idx);

    $msg = _check_name_in_hierarchy($net->module, $input_name);
    return $msg if defined $msg;

    $logger->debug($input_name . " will be used as fiji connector (input)");
    my $ip = _add_port_to_hierarchy($net->module, $input_name, FIJI::VHDL->FIJI_PORTTYPE_MODIFIED, $fiu_idx);

    my %connections;
    $self->_get_net_connections($net, \%connections);

    # connecting newly created output to driver
    foreach my $connection (@{$connections{'drivers'}}) {
        my $log = "Original: Connecting ";
        if (ref($connection) eq "Verilog::Netlist::Pin") {

            # if it is a pin of a cell, connect this pin to the newly created net
            $log .= "(output) pin " . $connection->cell->name . HIERSEP . $connection->name;
            for my $netname (@{$connection->netnames}) {

                # @FIXME work to be done for Buses
                $netname->{'netname'} = $op->net->name if $netname->{'netname'} eq $net->name;
            }
            $connection->portname($op->name);

            #$connection->net(undef);     # resolved by link
            $connection->port(undef);    # resolved by link

        } elsif (ref($connection) eq "Verilog::Netlist::Port") {

            # if it is a port of a module, connect this port to the newly created net
            $log .= "(input)  port " . $connection->name;
            $connection->net($op->net);
            $net->module->new_contassign(
                keyword => "assign",
                lhs     => $op->name,
                rhs     => $connection->name,
                module  => $net->module,
                netlist => $net->module->netlist
            );
        } elsif (ref($connection) eq "Verilog::Netlist::ContAssign") {
            $log .= "assignment " . $connection->lhs;
            $connection->rhs($connection->rhs =~ s/^\Q$net->name\E$/oip->net->name/r);
        }
        $log .= " to generated output " . $op->name;
        $logger->debug($log);

        # create interconnections for newly created port/pin
        # @TODO needed here or OK linking once after loop?
        # $net->module->link;
    }

    # exactly the same for the input
    # connecting newly created input to driven cells
    foreach my $connection (@{$connections{'driven'}}) {
        my $log = "Modified: Connecting ";
        if (ref($connection) eq "Verilog::Netlist::Pin") {
            $log .= "(input)  pin " . $connection->cell->name . HIERSEP . $connection->name;
            for my $netname (@{$connection->netnames}) {

                # @FIXME work to be done for Buses
                $netname->{'netname'} = $ip->net->name if $netname->{'netname'} eq $net->name;
            }
            $connection->portname($ip->name);

            #$connection->net(undef);     # resolved by link
            $connection->port(undef);    # resolved by link
        } elsif (ref($connection) eq "Verilog::Netlist::Port") {
            $log .= "(output) port " . $connection->module->name . HIERSEP . $connection->name;
            $net->module->new_contassign(
                keyword => "assign",
                lhs     => $connection->name,
                rhs     => $ip->name,
                module  => $net->module,
                netlist => $net->module->netlist
            );
        } elsif (ref($connection) eq "Verilog::Netlist::ContAssign") {
            $log .= "assignment " . $connection->rhs;
            $connection->lhs($connection->lhs =~ s/\Q$net->name\E)?$/$ip->net->name/r);
        }
        $log .= " to generated input " . $ip->name;
        $logger->debug($log);

        # create interconnections for newly created port/pin
        # @TODO needed here or OK linking once after loop?
        # $net->module->link;
    }

    # create interconnections for newly created ports/pins
    # @TODO OK linking once after loop?
    $net->module->link;

    return undef;
}

## @method public validate_driver($net_path, $driver_path, $driver_type)
# @brief Check if the given driver is valid for the given net
#
# Check if the driver specified by $driver_type and $driver_path
# is actually connected to the net specified by $net_path
#
# @param net_path        The hierarchical path of the net, separeted by HIERSEP
# @param driver_path     The hierarchical path of the driver object, separated by HIERSEP
# @param driver_type     The type of the driver object, one of {PIN, PORT, ASSIGN}
#
# @returns STRING          if an error occurred
# @returns undef           if successfull
sub _validate_driver {
    my $logger = get_logger("");
    my ($self, $net_path, $driver_path, $driver_type) = @_;

    my $connection_object = $self->get_connection_object($driver_path, $driver_type);
    my $connections       = {};
    $self->_get_net_connections($net_path, $connections);

    my @in_drivers     = grep { $_ == $connection_object } @{$connections->{'drivers'}};
    my @in_connections = grep { $_ == $connection_object } @{$connections->{'connected'}};

    if (@in_drivers == 0 && @in_connections == 0) {
        my $msg = "No possible driver found";
        $logger->error($msg);
        return $msg;
    }

    return undef;
}

## @function private _select_driver($connected,$net)
# @brief Prompt the user to select a driver for a net from a set of given cells/outputs
#
# @param connected       list reference containing connected Verilog::Perl instances
# @param net             the Verilog::Perl::Net instance to select the driver for
#
# @returns STRING          if an error occurred
# @returns Driver object   if successful
sub _select_driver {
    my ($connected, $net) = @_;

    print "Select driver for net " . $net->name . ": \n";
    my $di;
    for ($di = 0 ; $di < @{$connected} ; $di++) {
        printf("[%d] %s\n", $di, FIJI::Netlist->_connection_tostr(@{$connected}[$di]));
    }
    printf("[x] none of the above.\n", $di);
    my $sel;
    while (1) {
        $sel = <STDIN>;
        if ($sel =~ m/[0-9]+/ && defined @{$connected}[$sel]) {
            last;
        } elsif ($sel =~ m/[xX]/) {
            my $msg = "No driver selected for net " . $net->name;
            return $msg;
        } else {
            print "Invalid driver.\n";
        }
    }
    return @{$connected}[$sel];
}

## @method private _connection_tostr ($connection,$conn_str_list_ref)
# @brief Stringifies a connection information
#
# The string is in the format \<TYPE\>: \<PATH|TO|Netname\>
# Where '|' can be any HIERSEP and TYPE is one of {PIN, PORT, ASSIGN}
# and optionally pushes a hash {path=>...,type=>...,} onto the list @$conn_str_list_ref
#
# @param connection          the connection to print
# @param conn_str_list_ref   optional list where a hash describing the connection is pushed
#
# @returns STRING  in the format \<TYPE\>: \<PATH|TO|Netname\>
sub _connection_tostr {
    my ($self, $connection, $conn_str_list_ref) = @_;
    my $path;
    my $type;
    my $str;

    if (ref($connection) eq "Verilog::Netlist::Pin") {
        $path = $connection->cell->module->name . HIERSEP . $connection->cell->name . HIERSEP . $connection->name;
        $type = "PIN";
        $str = $type . ": " . $path
    } elsif (ref($connection) eq "Verilog::Netlist::Port") {
        $path = $connection->module->name . HIERSEP . $connection->name;
        $type = "PORT";
        $str = $type . ": " . $path
    } elsif (ref($connection) eq "Verilog::Netlist::ContAssign") {
        $path = $connection->rhs;
        $type = "ASSIGN";
        $str = $type . ": " . $connection->rhs;
    }
    push @{$conn_str_list_ref}, {path => $path, type => $type} if defined $conn_str_list_ref;
    return $str
}

## @method public get_connection_object ($connection_path,$connection_type)
# @brief Retrieves the connection object specified by path and type
#
# Retrieves a reference to the Verilog::Pin, Verilog::Port or Verilog::ContAssign
# Object specified by the parameters
#
# @param connection_path     the hierarchichal PATH|To|the|object
# @param connection_type     the type of the object {PIN,PORT,ASSIGN}
#
# @returns the Verilog::Pin, Verilog::Port or Verilog::ContAssign Object specified by the parameters
sub get_connection_object {
    my $logger = get_logger("");
    my ($self, $connection_path, $connection_type) = @_;

    my $rv;

    if ($connection_type eq "PIN") {
        if ($connection_path =~ /^(.+)\|(.+)\|(.+)$/) {

            $logger->debug("Looking for pin named $3 in cell $2 of module $1...");

            my $mod  = $self->{'nl'}->find_module($1);
            my $cell = $mod->find_cell($2) if (defined $mod);
            my $pin  = $cell->find_pin($3) if (defined $cell);
            $rv = $pin;
        }
    } elsif ($connection_type eq "PORT") {
        if ($connection_path =~ /^(.+)\|(.+)$/) {

            $logger->debug("Looking for port named $2 in module $1...");

            my $mod = $self->{'nl'}->find_module($1);
            my $port = $mod->find_port($2) if (defined $mod);
            $rv = $port;
        }
    } elsif ($connection_type eq "ASSIGN") {
        if ($connection_path =~ /^(.+)\|(.+)$/) {
            my $lhs = $2;

            $logger->debug("Looking for assignment to $2 in module $1...");
            my $mod = $self->{'nl'}->find_module($1);

            if (defined $mod) {
                my $assign;
                for my $a (grep { ref($_) eq "Verilog::ContAssign" } $mod->statements) {
                    if ($a->lhs eq $lhs) {
                        $assign = $a;
                        $logger->debug("Constant assignment: $assign");
                        last;
                    }
                }
                $rv = $assign;
            }
        }
    }
    $logger->warn("Could not find $connection_type \"$connection_path\"!") if !defined($rv);
    return $rv;
}

## @method private _get_net_connections ($net,$connection_hashref)
# @brief retrieves connections of a given net
#
# gets all pins, ports and assignments a net is connected to
# currently only works for single-bit signals and instantiations not using
# buses and concatenations
#
# @param net                    the net to be examined
# @param connection_hashref     a hashref where the results can be placed
#                               connection_hashref->{'drivers'} contains a list of driver cells
#                               connection_hashref->{'driven'} contains a list of driven cells
#                               connection_hashref->{'connected'} contains a list cells connected to the
#                               net but driver/driven cannot be decided
sub _get_net_connections {
    my $logger = get_logger("");
    my ($self, $net_path, $connection_hashref) = @_;


    my $connections = $connection_hashref;
    my @drivers     = ();
    my @driven      = ();
    my @connected   = ();
    $connections->{'drivers'}   = \@drivers;
    $connections->{'driven'}    = \@driven;
    $connections->{'connected'} = \@connected;

    # @FIXME what to do with bussed nets
    # @FIXME what to do with instantiations like that (concatenated nets):
    # input [5:0] p_nbus_byte_controller_c_state ;
    #  ...
    # .p_nbus_byte_controller_c_state (
    #                     {byte_controller_c_state[5],byte_controller_c_state[3]
    #                      ,byte_controller_c_state[2],byte_controller_c_state[1]
    #                      ,byte_controller_c_state[4],byte_controller_c_state[0]
    #                      })
    #
    # @TODO: can Verilog::Language::split_bus help us here?

    $logger->debug("Net $net_path, connections:");

    my $splitnet = $self->splitnet($net_path);
    return $splitnet if (ref($splitnet) ne "HASH");
    my $net = $splitnet->{net};
    my $mod = $net->module;

    # find nets driven by continuous assignment (e.g., constant or inverter)
    foreach my $statement ($mod->statements) {
        if ($statement->lhs eq $net->name) {
            # continuous assign statement to this net, there can't be another driver
            # FIXME: use that knowledge to fail early (if another iteration matches too)?
            $logger->debug("    assign: " . $mod->name . ": " . $net->name . " = " . $statement->rhs);
            push @drivers, $statement;
        } elsif ($statement->rhs =~ /\Q$net->name\E$/) {
            push @driven, $statement;
        }
    }

    # find nets driven by this module's input ports
    foreach my $port ($mod->ports) {
        if (defined $port->net && ($port->net->name eq $net->name)) {
            $logger->debug("    port:   " . $mod->name . HIERSEP . $port->name);

            # driven from an input, there can't be another driver
            if ($port->direction eq "in") {
                push @drivers, $port;
            } elsif ($port->direction eq "out") {
                push @driven, $port;
            } elsif ($port->direction eq "inout") {
                push @connected, $port;
            }
        }
    }

    # find nets driven by other cells' output pins
    foreach my $cell ($mod->cells) {
        foreach my $pin ($cell->pins) {
            next if defined($pin->port) && $pin->port->direction eq 'in';
            foreach my $netname (@{$pin->netnames}) {
                if ($netname->{'netname'} eq $net->name) {
                    if (!_is_pinrange_in_net($splitnet->{msb}, $splitnet->{lsb}, $net)) {
                        $logger->warn("Out of range (of net ${net->name})\n");
                        next;
                    }
                    $logger->debug("    pin " . $pin->cell->name . HIERSEP . $netname->{'netname'});
                    push @connected, $pin;
                }
            }
        }
    }
    return undef;
}

## @method public export ($filename,$id)
# @brief Writes the current netlist to the specified file
#
# Writes the netlist to $filename.
# @param filename     the filename for the resulting Verilog file
# @param id           the FIJI id (included in a header comment if defined)
#
sub export {

    my $logger = get_logger("");
    my ($self, $filename, $id) = @_;

    open(my $fh_nl, ">", $filename);

    if (!defined $fh_nl) {
        my $msg = "Could not open $filename for writing: $!";
        return $msg;
    }

    print $fh_nl "//------------------------------------------------------------------------------\n";
    print $fh_nl "// FIJI instrumented netlist\n";
    print $fh_nl "//\n";
    print $fh_nl FIJI_LOGO;
    print $fh_nl "//\n";
    print $fh_nl "//------------------------------------------------------------------------------\n";
    print $fh_nl "// Generated " . localtime() . " by $0\n";
    print $fh_nl "// Netlist ID: 0x" . sprintf("%04x", $id) . "\n" if defined $id;
    print $fh_nl "//------------------------------------------------------------------------------\n\n";

    for my $mod ($self->{'nl'}->modules) {
        $logger->debug("Exporting module " . $mod->name);
        my $verilog_text = $mod->verilog_text;
        print $fh_nl $verilog_text;
    }

    close($fh_nl);
    return undef;
}

sub _is_net_range_valid {
    my ($net) = @_;
    if (defined($net->lsb) && !defined($net->msb)) {
        return 0;
    }
    if (!defined($net->lsb) && defined($net->msb)) {
        return 0;
    }
    return 1;
}

## @method private _is_pin_in_range($pin_msb, $pin_lsb, $net)
# @brief Tests if pin range is contained in the range of a net
sub _is_pinrange_in_net {
    my ($pin_msb, $pin_lsb, $net) = @_;

    return 0 if !_is_net_range_valid($net);

    if (defined($pin_msb)) {
        return 0 if (!defined($net->msb));
         # MSB out of net range
        if ((($pin_msb < $net->lsb) && ($pin_msb < $net->msb)) || # completely below range
            (($pin_msb > $net->lsb) && ($pin_msb > $net->msb))) { # completely above range
            return 0;
        }
    } else {
        if (defined($net->msb)) {
            return 0;
        }
    }
    if (defined($pin_lsb)) {
        return 0 if (!defined($net->lsb));
         # LSB out of net range
        if ((($pin_lsb < $net->lsb) && ($pin_msb < $net->msb)) || # completely below range
            (($pin_lsb > $net->lsb) && ($pin_msb > $net->msb))) { # completely above range
            return 0;
        }
    } else {
        if (defined($net->lsb)) {
            return 0;
        }
    }
    return 1;
}

## @method public splitnet($netpath)
# @brief splits a hierarchical path of a net
# splits a hierarchical path of a net in the form of module1|module2|netname
# to the net object corresponding to "netname" in module "module2"
#
# @param netpath     the hierarchical PATH|TO|netname with '|' as separator
#
# @returns STRING      if an error occurred
# @returns HASHREF     with the keys 'mod', 'net', 'msb' and 'lsb', if successful.