OpenTCAM

An open-source Ternary Content Addressable Memory (TCAM) compiler framework.

What is OpenTCAM?

OpenTCAM is an open source Python framework that can be used to create the design (RTL) and layouts (GDS-II) of a customizable SRAM-based TCAM memory to use in FPGA and ASIC designs respectively.

Currently the compilers are using SRAMs generated from OpenRAM Compiler, but the idea is to make a generalized compiler for any SRAM-based TCAM. The idea is to utilize 36KB BRAM blocks of FPGAs and OpenRAM generated 1Kb SRAM blocks (using sky130 nm PDKs) for ASIC to mimic any size of TCAM.

Directory Structure

.
├── compiler
│   ├── configs                         # contains TCAM table map and RTL block config parameters.
│   ├── lib                             # contains TCAM table maps and RTl blocks.
│   │   └── tcam_block_rtl
│   ├── src                             # contains py scripts for code compilation
│   │   ├── mainTableMapping.py         # contains class TableMapping
│   │   ├── mainTcamRTLGenerator.py     # contains main func for class TableMapping
│   │   ├── tableMapping.py             # contains class TcamRtlWrapperGenerator
│   │   └── tcamRtlGenerator.py         # contains main func for class TcamRtlWrapperGenerator
│   └── tests                           # contains unit tests for various py classes 
├── docs                                # contains API generated docs
├── example_design                      # TCAM memory design
├── images                              # logos etc
├── scripts                             # contains bash scripts for compilation, variable storage etc.
├── CHANGELOG.md    
├── CONTRIBUTING.md
├── LICENSE
├── Makefile                            # contains various targets for simulation. Run `make help` for more info.
├── pytest.ini                          # pytest config file
├── README.md       
└── requirements.txt

How to Install

The OpenTCAM compiler requires Python3, Pip3 and MAKE inorder to run properly:

Linux/Debian (Ubuntu)

• Install all pre-requisites softwares using the following commands:

  sudo apt install -y git make python3 python3-pip python3-venv
  sudo python3 -m pip install --user virtualenv 

• If MAKE is already pre installed simply run the command:

  make install_dependencies

How to Use

1. Basic Setup

• To setup and build the python virtual environment required for running the compiler simply run the following command in the project directory. It will automatically setup and install all the required pip packages.

  make venv_opentcam

2. Virtual Environment Basics

NOTE: All commands mentioned below require the use virtual environment created in the previous step. The virtual environment needs to be activated everytime before use and deactivated when done.

1. Activate virtual environment:

   source .pyVenvOpenTcam/bin/activate

2. Deactivate virtual environment:

   deactivate

To learn more about what are python virtual environments and how they work click here.

3. Generating TCAM -> SRAM Memory Tables

• Generate TCAM -> SRAM table map:

  make tcamtablemap \
  TCAMCONFIG=tcamTableX \ # tcam table config name here X=1,2,..
  EXCEL=1/0 \             # generate SRAM table map as excel file
  HTML=1/0 \              # generate SRAM table map as html file
  JSON=1/0 \              # generate SRAM table map as json file
  TXT=1/0 \               # generate SRAM table map as text file
  DEBUG=1/0 \             # debugging on/off
  VERBOSE=1/0             # verbosity on/off    

4. Generating TCAM Memory Blocks

• Generate TCAM memory configs:

  make tcamrtl \			            # generate TCAM memory RTL wrapper
  TCAMWRAPCONFIG=tcamMemWrapper_XxY \ # tcam memory config name
  TIMEUNIT=1ns \                      # set timeunit resolution 
  TIMEPRECISION=1ps \                 # set timeprecision resolution
  DEBUG=1/0 \                         # debugging on/off
  VERBOSE=1/0                         # verbosity on/off

5. Unit Tests

Unit tests are an important part of regression testing to ensure that the code still functions as expected after making changes to the code and helps ensure code stability.

Use the following commands:

• Run a specific test:

  make run_unittest MARKER=test_name

• Run all tests of a specific test class:

  make run_unittest MARKER=test_class_name

• Run all regression tests:

  make run_regression

• Display all test markers:

  make testmarkers

6. Code Coverage

Used to gauge the effectiveness of tests. It can show which parts of your code are being exercised by tests, and which are not.

• To generate code coverage simply run the command:

  make run_coverage

A report will be created in the folder coverage_html. Simply open the file coverage_html/index.html in the web browser of your choice to view a detailed coverage report.

7. Documentation

• To generate API documentation locally.

  make gen_apidocs

8. CleanUp

• Clean all files including tables, bins, logs, etc generated:

  make cleanall

• Clean everything including virtual environment/s. Make sure to deactivate any or all virtual environment/s.

  make deepclean

Get Involved

• Report bugs by submitting GitHub Issues.
• Develop new features (see how to contribute).
• Submit code/fixes using a Github Pull Request.

License

• OpenTCAM is licensed under the Apache License Version 2.0.

Contributors & Acknowledgements

Dr. Ali Ahmed Usman Siddique Sajjad Ahmed Mohammed Abdullah