Centaur Books — README

# Centaur Books |

### Introduction

The Centaur Books are a free set of ACL2 libraries for formal hardware verification.

They include:

- VL — a Verilog parser and simplification tool.
- E — a deeply embedded hardware description language with a well-defined semantics.
- ESIM — a symbolic simulator for E modules.
- GL — a symbolic simulator for ACL2 functions and framework for bit-blasting ACL2 theorems.
- Many supporting libraries, e.g., for representing Boolean or four-valued logic expressions, debugging ESIM runs with waveforms, reasoning about arithmetic, and so forth.

Centaur Technology is a small company in Austin, TX. We design x86 processors for our parent company, VIA Technologies. We have used these books to prove correctness properties of several execution units, and to develop other tools such as an equivalence checker, a linter, etc.

### Prerequisites

Warning: We expect these books to be much less stable than ordinary ACL2 books because we are actively using them and often need to extend them.

Recommended Hardware
  You will at least want a fast dual-core machine with 8 GB of memory. Having additional cores is very useful for quickly re-certifying books in parallel, but careful here: with more cores you'll need even more memory to avoid swapping death. A good target might be at least 4 GB per core.
  We used to recommend even more memory than this. Ample memory was especially important when we carried out large proofs using BDDs, but these days we often use SAT instead, and SAT is far less memory intensive. Even so, today many of our real hardware proofs are made faster (or possible) by having 32 or more GB of memory. Also, many of our tools, e.g., our Verilog parser, are written in a memory-hungry way because that's just the kind of environment we work in.
Recommended Operating System
  We use 64-bit Linux. Other unix derivatives like Darwin, FreeBSD, etc., might work reasonably well, but Linux is our main platform. Windows probably won't work. You will need ordinary tools like perl, make, etc.
Clozure Common Lisp Configuration
  We use 64-bit Clozure Common Lisp. Other Lisps probably won't work.
  We usually use a fairly recent SVN snapshot.
  CCL Configuration before building ACL2: We use ccl-config.lsp to do some extra configuration that increases the stack sizes and tunes the garbage collector for better performance.
  We configure our `PATH` so that we can launch CCL by typing `ccl`.
ACL2(h) Configuration
  You will need to build ACL2 with Hons enabled. The recommended way to build is, with:

      $ # rebuild ccl using ccl-config.lsp
      $ cd [...]/acl2/
      $ make LISP=ccl ACL2_HONS=h ACL2_SIZE=3000000

  Using a large `ACL2_SIZE` can help avoid performance problems due to filling up the ACL2 package with too many symbols.
  We configure our `PATH` so that we can launch ACL2(h) by typing `acl2`.
cert.pl Configuration
  We generally use `cert.pl` to certify books. This script is located in the `acl2/books` directory. We recommend that you configure your `PATH` so you can invoke it by just typing `cert.pl`.
(Optional) GTKWave Configuration
  You can skip this if you aren't doing hardware verification.
  We often use GTKWave for debugging waveforms. Other VCD file viewers may also work.
  We configure our `PATH` so that we can run GTKWave by typing `gtkwave`.
(Optional) Glucose Configuration
  We often use the Glucose Sat Solver.
  We configure out `PATH` so that we can run Glucose (sometimes called `glucose.sh`) by typing `glucose`.
(Optional) Lingeling Configuration
  We sometimes use the Lingeling Sat Solver.
  We configure our path so that we can run the Lingeling executable by typing `lingeling`.

### Building the Books

Once you have the above prerequisites, you will be ready to certify the ACL2 books. The preferred command to do this is:

    $ # get ccl, reconfigure it, build acl2, set up your path as explained above.
    $ cd [...]/acl2/books/
    $ make USE_QUICKLISP=1 -j 4    # -j 4 for a quad-core processor

The USE_QUICKLISP=1 instructs `make` to download and install Quicklisp, which is sort of a Common Lisp equivalent to CPAN for Perl, RubyGems for Ruby, etc. This is necessary for certain books.

Depending on your hardware this may take ten minutes up to hours. For reference, it takes about an hour on an 8-core AMD-FX8350 with 32 GB of memory running FreeBSD, using -j 8.

### Next Steps

After building the books with the `make` command above, you should obtain an XDOC Manual with documentation for the Centaur books, and also has the regular documentation for ACL2 and other Community Books like str, osets, ihs, etc.

To view the manual, point your web browser at manual/index.html—this link will be broken until you generate the manual. (We also keep a public copy of the manual on our web site, but we only update it at each ACL2 release, so it's generally best to use a local copy that matches your specific version of the books.)

If you are specifically interested in hardware verification, there is also a preliminary tutorial that walks through the verification of a trivial ALU module. To get started, see:

    books/centaur/tutorial/intro.lisp

### Contact Information

If you have questions, comments, or bug reports about these books, please email Jared Davis and Sol Swords, `{jared,sswords}@centtech.com`.

Unfortunately we can't offer any serious technical support. We may be able to answer some questions on an informal, "low bandwidth" basis, in our spare time.

### License Information

Copyright © 2008-2013 Centaur Technology and others (see **)

Contact Information
  Centaur Technology Formal Verification Group
  7600-C N. Capital of Texas Highway, Suite 300, Austin, TX 78731, USA.
  http://www.centtech.com/
Copyright Notice
  This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Suite 500, Boston, MA 02110-1335, USA.

** All of the Centaur books are licensed under the GPL "2 or later." Most are copyright by Centaur Technology, but some are copyrights of others, e.g., the books in ubdds/ are copyright by Bob Boyer and Warren Hunt; see the individual headers on each file for more information. Many of these books also depend on other ACL2 libraries that are copyright by their respective owners. To the best of our knowledge, we believe all libraries we include are also licensed under the GPL "2 or later" or compatible licenses.