====== AMC: Asynchronous Memory Compiler ======


''AMC'' is an open-source asynchronous pipelined memory compiler. ''AMC'' generates SRAM modules with a bundled-data datapath and quasi-delay-insensitive control. ''AMC'' is a Python-base, flexible, user-modifiable and technology-independent memory compiler that generates fabricable SRAM blocks in a broad range of sizes, configurations and process nodes.
''AMC'' generates GDSII layout data, standard SPICE netlists, Verilog models, DRC/LVS verification reports, timing and power liberty models (.lib), and abstract placement and routing models (.lef).

''AMC'' source code is available on GitHub [[https://github.com/asyncvlsi | AMC]]

====== AMC Usage ======
To use AMC, you must set two environment variable to your .bashrc:
<code>
export AMC_HOME="$HOME/AMC/compiler"
export AMC_TECH="$HOME/AMC/technology"
</code>


In case you are using C shell you must add:

<code>
setenv AMC_HOME "$HOME/AMC/compiler"
setenv AMC_TECH "$HOME/AMC/technology"
</code>


You can run ''AMC'' from the command line using a single configuration file. For example:

<code>
python $AMC_HOME/AMC.py example_config.py
</code>


In //example_config.py//  file you can specify the following parameters: (//example_config_scn3me_subm.py// is included in git repo for 0.5um technology)

<code>

# Data word size, any number greater than 1 is fine
word_size = 16

# Number of rows in each memory bank, acceptable values are 32, 64, 128 or 256
num_rows = 64

# Number of words in each memory row (num_columns = word_size * words_per_row). Acceptable values are 1, 2 or 4
words_per_row = 2

# Number of sub-banks in each bank. Acceptable values are 1, 2, 4 or 8
num_subanks = 8

# Branch factors (number of inner-banks and outer-banks). Acceptable tuple values are (1,1), (1,2), (1,4), (2,4) or (4,4)
branch_factors = (2,4)

# Bank orientations (orientation of inner-banks and outer-banks). 
# Acceptable tuple values are (("H", "H"), (("V", "H"), (("H", "V"), or (("V", "V")
bank_orientations = ("V", "H")

# Output directory for the results. 
output_path = "path_to_AMC_output_files"

# Output file name
name = "AMC_sram"

# Specify the technology name. Default is "scn3me_subm" for SCMOS 0.5um
tech_name = "scn3me_subm"

# Specify the process corners for characterization. 
# Transistors models for these process corners should be provided by user. 
#Transistor models for "scn3me_subm" are available in //AMC/technology/scn3me_subm/models//
process_corners = ["TT", "SF"]

# Voltage corners to characterize
supply_voltages = [5.0, 4.5]

# Temperature corners to characterize
temperatures = [25, 125]

</code>

You can find more configuration options in: //AMC/compiler/options.py//

Some optional arguments to run the ''AMC'' are:

   * -o or --output to specify the output file name prefix
   * -t or --tech to specify the technology name
   * -c or --characterize to disable the characterization
   * -n or --nocheck to disable inline DRC/LVS checks
   * -d or --dontpurge for not purging the content of temporary directory after a successful run
   * -v or --verbose to increase the verbosity level
   * -h or --help to show the help message

''AMC'' puts all output files in a temporary directory (the path of temporary directory is shown in the banner). If ''AMC'' passes, files in temporary directory are deleted. If you don't want to purge the content of temporary directory use //-d// or //--dontpurge//. If it fails, first thing to check is the standard output and error output from DRC/LVC which are .out and .err files in temporary directory. Any problem with your ''Calibre'' setup will be shown in either of those files. In case DRC or LVS fails, then you need to check either doc.result or las.result files. You need a layout viewer to debug DRC/LVS errors. You can use any of the following layout viewers:  
   * [[https://layouteditor.com]]
   * [[http://www.peardrop.co.uk/glade/]]

Also, you can use ''Calibre DESIGNrev'', ''Magic'' ([[http://opencircuitdesign.com/magic/index.html | Magic]]) or ''Cadence Virtuoso'' to stream the output GDS file for debugging. 

To report a bug please submit it to: 
   * [[https://github.com/asyncvlsi/AMC/issues]]

If you are interested in submitting a fix or adding a new feature to ''AMC'' use:
   * [[https://github.com/asyncvlsi/AMC/pulls]]
====== AMC Dependencies ======


''AMC'' is written in ''Python2''. Any Python version higher than 2.7 is acceptable for running the compiler. Python NumPy package ([[https://www.numpy.org | NumPy]]) is also needed.

Default tool for physical verification of generated layouts by ''AMC'' is ''Calibre''. A wrapper file for ''Calibre'' is included in compiler (you can find it at //AMC/compiler/base/calibre.py//). If you are using any other tool for DRC/LVS verification, you can simply add a wrapper file for your tool.

To run the ''AMC'' characterizer or verifying the functionality of SRAM through AMC functional verification tests, you must have access to ''Synopsys HSIM'' and ''Synopsys VCS'' tools. Characterizer and functional tests rely on SPICE simulations.
====== AMC Directory Structure ======

''AMC'' has two main directory:
    ***compiler:** where you can find the source code of compiler itself
    ***technology:** where you can find the technology information for SCMOS 0.5um technology.

compiler directory contains following sub-directories:
    ***base:** contain base data structure modules and base utility functions
    ***characterizer:** contains the functional verification and timing/power charazterization codes.
    ***gdsMill:** GDSII file format reader and writer. You can learn more about gdsMill here: [[http://michaelwieckowski.com/wp-content/uploads/2012/01/GdsMillUserManual.pdf | gdsMill]]
    ***modules:** modules and submodules of SRAM architecture
    ***tests:** unit tests, there is a unit test for each module.

technology directory contains the following sub-directories:
    ***setup_scripts:** you need to add a setup script for each technology node that you port the compiler to. Check the //setup_AMC_scn3me_sumb.py// as an example.The correct format for setup file name is: ''setup_AMC_techname.py'' 
    ***scn3me_subm:** contains all the technology information needed by ''AMC'' to generate/characterize the circuits in SCMOS 0.5um technology node:
        ***gds_lib:** contains the GDS layout of custom library cells 
        ***sp_lib:** contains the SPICE netlist for the custom cells
        ***models:** contains the transistor models for different process corners
        ***tech:** contains a technology file with design rules and layer map information from PDK.
for scn3me_subm you can find two additional sub-directories //mag_lib// and //tf// that contain the Magic layouts and technology file for this technology.These two sub-directories aren't directly used by ''AMC'' and are provided as additional resources for users.
====== Porting AMC to a New Technology ======

We have successfully ported the ''AMC'' to 0.5um and 65nm technology nodes. Therefore, you should be able to port it to your desired process technology, too! Here is the steps you need to follow for porting ''AMC'' to technology X:

    * Make a setup script for technology X. Check //setup_AMC_scn3me_sumb.py// for help.
    * Make a technology sub-directory for technology X in //$AMC_tech/technology//. Your technology sub-directory should include these folders: gds_lib, sp_lib, tech and models. Check //AMC/technology/scn3me_subm// for help.
    * Add the custom layout cell (you need to draw these layouts manually) in technology X to //gds_lib// folder. For list of custom cells check the content of scn3me_subm/gds_lib directory.
    * Add the SPICE netlist of each custom cell in technology X to //sp_lib// folder.
    * Make a technology file that contains the DRC rules, Layer information, and few SPICE informations. Check //scn3me_subm/tech/tech.py// for help. 

**Hint:**

It is highly recommend to use unit tests in //$AMC_HOME/compiler/tests// when porting to a new technology node. Unit tests check the layout format of custom designed cells and are helpful for debugging. For each custom layout, there is an individual test to check all the possible ways that layout may be used in SRAM array. Your custom layout is acceptable by '' AMC'' when it fully passes the test.
 
For example test //09_sense_amp_array_test.py// checks the custom layout for sense amplifier for three possible scenarios:
 
    *when there is one sense amp for each column or when there is no column-muxing
    *when are is one sense amp for every two columns or a 2:1 column-muxing
    *when there is one sense amp for every four columns, a 4:1 column-muxing 

For correct pin-connection and routing, certain rules must be followed in drawing custom layouts. In case of sense_amp, //vdd//, //gnd//, //en// pins are routed horizontally across the layout, //BL// and //BR// are routed vertically across the layout and //dout//, //dout_bar// are placed at the bottom left and bottom right corners. Following these rules the custom layout will pass the unit test and can be connected to other modules through abutment.

====== AMC Characterization and Functionality Verification ======

To get faster verification, AMC adds a functionality unit test (can be run by test 23:// AMC/compiler/tests/23_func_sram_test.py//) that co-simulates the Verilog and SPICE netlists. In this co-simulation Verilog test-bench drives the SPICE netlist and runs the SPICE simulation at transistor level.
The files generated by AMC in functionality verification test are:

    * dut.sp: SPICE netlist of circuit under the test
    * test.sp: HSIM deck containing all the HSIM parameters used in simulation
    * test.v: Verilog test-bench
    * source.v: input-vector pattern generator for data, address and controls
    * cosim.cfg: SPICE-Verilog co-simulation setup file. 
    * Makefile

Different random input vector patterns can be generated simply by modifying the //source.v// file. AMC runs the simulation at batch mode. If simulation fails, first thing to check is the standard output and error output from spice which are //spice_stderr.log// and //spice_stdout.log// files in temporary directory. Any problem with your SPICE setup will be shown in either of those files. A successful simulation generates the following files (some of these files are generated when simulation is complete):
 
    * hsim.fsdb: Cscope/Custom WaveView compatible trace file
    * hsim.mt: measurement results for delay, leakage power, current and energy consumption in txt format.
    * hsim.log and simv.log: simulation progress log files
    * hsim.cap: list of calculated capacitor for all the nodes.
    * hsim.conn: list of dangling nodes (when all nodes are connected this file won't be generated)
    * hsim.csintf: digital to analog and analog to digital conversion channel list and event count

You can learn more about Verilog-HSIM co-simulation here: [[http://www.ece.utah.edu/~kstevens/4900/reports/hsimplus_reference_manual.pdf|HSIM Manual]]

AMC characterization methodology is similar to functionality verification. Characterization will be performed for the specified process-corners, voltages and temperatures (PVT) in //config// file. For each PVT a separate Liberty file (.lib) will be generated. Liberty file is the ASCII representation of timing and power parameters. Liberty file generated by AMC has the standard lookup-table format and can be used for synthesis. Generated tables in Liberty file are 3x3, you can simply increase the size of tables by modifying the table size (adding more load and slew scales) in //AMC/compiler/characterizer/lib.py// file.

**Hint:**

AMC characterization relies on SPICE simulations and for large SRAM arrays, characterization is slow. To reduce the characterization time you can trim the SPICE netlist using //AMC/compiler/characterizer/trim_spice.py// file. By timing the SPICE netlist, portions of SRAM array that are not critical during read/write operation will be removed. Trimed netlists can be used for delay calculations. **DO NOT** use trimed netlist for LVS verification or leakage/energy measurement.
====== AMC Copyright Notice ======

''AMC'' is licensed under GNU General Public License v2.0 ([[https://github.com/asyncvlsi/AMC/blob/master/LICENSE | LICENSE]]). AMC project originated from the OpenRAM code ([[https://github.com/VLSIDA/OpenRAM |OpenRAM]]) version 7b5791b from May 9, 2018, developed by Matthew Guthaus from UC Santa Cruz VLSIDA group as the lead architect and also contributed to by Samira Ataei. AMC developers have made a large number of changes that have to do with changing the memory interface circuits, supporting modern design rules and thin-cell SRAM layout, new partitioning and floorplanning, and different timing and characterization methodology. The organization of the code base mirrors the OpenRAM version 7b5791b. As OpenRAM is under BSD 3-Clause License, portions of code that are derived from OpenRAM remain under BSD license ([[https://github.com/asyncvlsi/AMC/blob/master/LICENSE.OR | LICENSE.OR]]).