ruby_abc ruby C extension

ruby_abc is a ruby C extension wrapping the Berkeley logic synthesis system abc.

abc is a system for sequential synthesis and verification, developped at the University of California, Berkeley. abc documentation can be found on its website:
http://people.eecs.berkeley.edu/~alanmi/abc/

The source code of abc is included in this gem, it was cloned on 2017/11/22 from :
https://bitbucket.org/alanmi/abc

Goal

The abc program is a command line interface: the user issues commands and adjust them according to the results he gets back. For example, the user can iterrate through minimization commands, and stops when the number of nodes of the logic network stops decreasing.

To automate this process, it is possible to give abc a predefined sequence of commands. In this case, however, the number of minimization command can be too short, and the resulting network will be bigger than it could be. The number of minimization command can also be too big, and the process will take more time than needed to execute.

In order to solve this process, ruby_abc allows to retreive some information on the current logic network in ruby, such as the number of nodes or its logic level, to allow automation. In the example of the minimization of a logic network, minimization commands are sent to abc in a ruby loop which breaks when the number of nodes stops decreasing.

Example

require 'ruby_abc'

## Load a netlist ##
ABC.read 'test/generic_netlist.blif'

## Print informations on the logic network ##
ABC.print_stats
puts ABC.nb_nodes

## Minimize the network ##
ABC.optimize # itera through minimization commands and stops when the number of nodes reach a plateau

## Retime the network ##
ABC.retime

## Map the network to 4-intpu LUTs (break the network in logic functions not exceeding 4 inputs) ##
n_nodes = ABC.nb_nodes
loop do
    ABC.run_command 'choice; if -K 4; ps'
    break if ABC.nb_nodes == n_nodes
    n_nodes = ABC.nb_nodes
end
# is equivalent to:
ABC.map 4

## Write the network to an output file ##
ABC.write 'mapped_netlist.blif'

Installation

To install ruby_abc from the git repository:

git clone https://gitlab.ensta-bretagne.fr/argen/ruby_abc.git
cd ruby_abc
gem build ruby_abc.gemspec
gem install ruby_abc.<version>.gem

Alternatively, ruby_abc gem is also hosted on RubyGems (https://rubygems.org/gems/ruby_abc). So you can simply type:

gem install ruby_abc

This will build abc and the ruby_abc extension, and install it. Building abc may take quite some time. To speed up the build, you may export MAKEFLAGS=' -j8 ' before installing the gem.

As this gem includes a C extension, building it requires the ruby developpement headers. On Debian, you can get them with:

sudo apt-get install ruby-dev 

Executable

To use ruby_abc directly from a terminal or a Makefile, this gem also include the ruby_abc executable script, which uses command line arguments.

$ ruby_abc --help
Usage: ruby_abc [options] -i <input_file> -o <output_file>
    -i, --input FILE       Input file
    -o, --output FILE      Write processed netlist to FILE
    -s, --sweep            Sweep logic network to remove dangling nodes
    -k, --lut-inputs K     Map to K-input LUTs.
    -a, --area             Optimize in area
    -r, --retime           Retime netlist
    -l, --lcorr            Computes latch correspondence using 1-step induction
    -z, --zero             Set latches initial value to zero
    -e, --echo             Echo commands sent to ABC
    -q, --quiet            Do not print netlist statistics during synthesis
    -m, --map [GATE_LIB]   Map the netlist to the logic gate library defined in GATE_LIB.
                             osu:       pseudo standard cell library inspired from OSU018,
                             simple:    simple library with only BUF, INV, AND, OR, XOR, NAND, NOR and XNOR,
                             file name: path of a library file in the GNELIB format.
                             Defaults to 'osu'.
    -h, --help             Display this help

Bash completion

If you want to have bash completion in your terminal for the ruby_abc command, copy the file share/bash_completion/ruby_abc.bash-completion.sh to your /etc/bash_completion.d/ directory.

Documentation

Documentation of ruby_abc is available at rubydoc.info.

You can also build the documentation yourself using YARD:

# Install Yard if you do not have it yet
gem install yard
# Call yard in the ruby_abc directory
yard
# View the generated documentation
firefox doc/index.html

This documentation covers only the API of ruby_abc, not abc itself. abc documentation can be found on http://people.eecs.berkeley.edu/~alanmi/abc/. Also, available abc commands can be retreived ith ABC.help (in ruby), and specific command documentation can be seen with ABC.run_command('<command_name> -h') (in ruby).