MASC: Modeling Algorithms in SystemC
====================================

Documentation
-------------

  MASC is described in the user's guide to the RTL library, "A Formal Theory
  of Register-Transfer Logic and Computer Arithmetic", Part V:

    www.russinoff.com/libman

Contents of this Directory
--------------------------

  In addition to the two top-level files Makefile and README (this file),
  there are five subdirectories:

    src:
      Makefile
      MASC parser source code
      masc-skel, which generates the masc script
    lisp:
      Makefile
      ACL2 component of the MASC-ACL2 translator
    bin:
      parser executable and masc script (both generated by "make")
    include:
      masc.h, which must be included in any MASC program
    examples
      README
      Two simple examples

Prerequisite: SystemC
---------------------

  MASC requires that SystemC be installed.

  A free, open source implementation of SystemC is available from
  http://accellera.org/downloads/standards/systemc under "Core SystemC
  Language and Examples". After downloading the source code (an archive
  called systemc-2.3.1.tgz, at the time of writing), unpack the archive and
  follow the instructions in systemc-2.3.1/INSTALL.

Compiling MASC
--------------

  Compilation requires ACL2 and a reasonably recent version of g++ (version
  4.8.1 works fine).

  Edit Makefile so that ACL2 points to the local distribution of ACL2 (where
  the saved_acl2 is to be found) and MASC points to the current directory.

  Then,

    make

  After compiling, 'make clean' removes temporary files (lex.yy.c and the like).
  'make veryclean' removes all that was generated - binaries, ACL2 books.

Parsing and pretty-printing MASC programs
-----------------------------------------

  The program 'masc' is invoked in one of the following ways:

    masc prog.cpp

      Check prog.cpp for conformance to the MASC subset and programming
      conventions.

    masc prog.cpp --ctos

      Translate the MASC code in prog.cpp into SystemC code suitable as
      input to the Cadence CtoS HLS tool.

    masc prog.cpp --acl2

      Translate the MASC code in prog.cpp into a set of recursive function
      definitions and certify the definitions as an ACL2 book.

    masc prog.cpp --masc

      Extract the masc code from prog.cpp (between 'Masc begin' and
      'Masc end' delimiters) and pretty-print it. The pretty-printed
      output is not parsable MASC code, but it looks better on slides
      and in documentation.


  The -c, -a and -m options are shorthand for --ctos, --acl2 and --masc.
  The .cpp suffix is optional.
  --output ofile (-o ofile for short) overrides the defaults and sends
  output to the specified file.

Compiling MASC programs for simulation
--------------------------------------

  If the MASC model is in the file prog.cpp and the environment is set up as
  described above,

    g++ prog.cpp -lsystemc

  will do the trick.

Contacts
-------

  David Russinoff     david.m.russinoff@intel.com
  John O'Leary        john.w.oleary@intel.com
