Commit c3498e2c authored by Théotime BOLLENGIER's avatar Théotime BOLLENGIER

add code

parent 7734c9cc

Too many changes to show.

To preserve performance only 1000 of 1000+ files are displayed.

*.o
*.swp
*.log
*.d
ext/Makefile
ext/ruby_abc.so
ext/abc/arch_flags
ext/abc/libabc.so
lib/ruby_abc/ruby_abc.so
doc
ruby_abc-*.gem
MIT License
Copyright (c) 2017 Théotime Bollengier <theotime.bollengier@gmail.com>
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
Directory ext/abc is cloned from https://bitbucket.org/alanmi/abc on 2017-11-22 (hg clone https://bitbucket.org/alanmi/abc)
ABC: System for Sequential Synthesis and Verification
http://www.eecs.berkeley.edu/~alanmi/abc/
Copyright (c) The Regents of the University of California. All rights reserved.
Permission is hereby granted, without written agreement and without license or
royalty fees, to use, copy, modify, and distribute this software and its
documentation for any purpose, provided that the above copyright notice and
the following two paragraphs appear in all copies of this software.
IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR
DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF
THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING,
BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS,
AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE,
SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
--------------------------------------------------------------------------------
ruby_abc: A ruby C extension to use ABC from ruby
https://gitlab.ensta-bretagne.fr/argen/ruby_abc
Copyright (c) 2017 Théotime Bollengier. All rights reserved.
Permission is hereby granted, without written agreement and without license or
royalty fees, to use, copy, modify, and distribute this software and its
documentation for any purpose, provided that the above copyright notice and
the following two paragraphs appear in all copies of this software.
IN NO EVENT SHALL THE AUTHOR BE LIABLE TO ANY PARTY FOR
DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF
THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE AUTHOR
HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
THE AUTHOR SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING,
BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS,
AND THE AUTHOR HAS NO OBLIGATION TO PROVIDE MAINTENANCE,
SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
# ruby_abc
A ruby C extension wrapping the Berkeley synthesis and verification program ABC.
\ No newline at end of file
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/](https://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](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
-------
```ruby
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:
```bash
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](https://rubygems.org/gems/ruby_abc)).
So you can simply type:
```bash
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:
```bash
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.
```lang-none
$ ruby_abc --help
Usage: rubyabc_synthesis [options] -i <input_file> -o <output_file>
-i, --input FILE Input BLIF file
-o, --output FILE Output netlist to FILE
-r, --retime Retime netlist
-z, --zero Set latches initial value to zero
-l, --lcorr Computes latch correspondence using 1-step induction
-a, --area Optimize for area instead of performance (minimize the number of nodes instead of the logic level)
-w, --sweep Sweep logic network to remove dangling nodes
-k, --lut_inputs K Map to K-input LUTs.
-h, --help Display this help
```
The *abc* executable is also included so that it can be used natively without ruby.
Documentation
-------------
Html documentation for *ruby_abc* can be generated with `rake doc`.
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/](https://people.eecs.berkeley.edu/~alanmi/abc/).
Also, available *abc* commands can be retreived with `ABC.help` (in ruby),
and specific command documentation can be seen with `ABC.run_command('<command_name> -h')` (in ruby).
Test
----
`$ rake test` will execute `test/test_ruby_abc.rb`.
This will read a BLIF netlist, optimize it and check the result against a golden model.
require 'rake'
require 'mkmf'
require 'fileutils'
root_path = File.dirname(File.expand_path(__FILE__))
ext_path = File.join(root_path, 'ext')
test_path = File.join(root_path, 'test')
lib_path = File.join(root_path, 'lib')
ilib_path = File.join(lib_path, 'ruby_abc')
abc_path = File.join(ext_path, 'abc')
rubyabcext = File.join(ilib_path, 'ruby_abc.so')
rubyabcsrc = Rake::FileList["#{ext_path}/*.c", "#{ext_path}/*.h"]
abcsrc = Rake::FileList["#{abc_path}/**/*.c", "#{abc_path}/**/*.h"]
libabc = File.join(abc_path, 'libabc.so')
docsrcfiles = Rake::FileList["#{ext_path}/*.c", "#{ext_path}/*.h", "lib/ruby_abc.rb", "README.md"]
desc 'build the gem'
task :default => :compile
desc 'build extension'
task :compile => rubyabcext
desc 'compile extension'
task rubyabcext => ([libabc] + rubyabcsrc) do
wd = Dir.getwd
Dir.chdir ext_path
sh "ruby extconf.rb"
sh "make"
Dir.chdir wd
sh "mkdir -p '#{ilib_path}'"
sh "cp '#{File.join(ext_path, 'ruby_abc.so')}' '#{rubyabcext}'"
end
desc 'compile libabc.so and abc'
task libabc => abcsrc do
abort "Library libpthread was not found" if !have_library('pthread')
abort "Library libdl was not found" if !have_library('dl')
#abort "Library librt was not found" if !have_library('rt') ## librt.a is not on Mac OS
wd = Dir.getwd
Dir.chdir(abc_path)