Naja

Naja is an Electronic Design Automation (EDA) project that provides open source data structures and APIs for the development of post logic synthesis EDA algorithms such as: netlist simplification (constant and dead logic propagation), logic replication, netlist partitioning, ASIC and FPGA place and route, ...

The easiest way to get started with Naja is through the najaeda Python package.

najaeda provides a powerful yet simple framework designed to help software AND hardware developers efficiently navigate and manipulate electronic design automation (EDA) workflows.

With najaeda, you can:

• Explore Netlists with Ease:

  • Navigate netlist hierarchy and connectivity effortlessly.
  • Browse at multiple levels of detail:
    • Bit-level or bus-level granularity.
    • Instance-by-instance exploration or flattened views at the primitives level.
    • Localized per-instance connections or comprehensive equipotential views.

• Perform ECO (Engineering Change Order) Transformations:

  • Seamlessly apply and manage changes to your designs.

• Prototype EDA Ideas Quickly:

  • Use an intuitive API to experiment with new EDA concepts and workflows.

• Develop Custom EDA Tools:

  • Build fast, tailored tools for solving specific challenges without relying on costly, proprietary EDA software.

najaeda empowers developers to innovate, adapt, and accelerate their EDA processes with minimal overhead.

Another entry point for Naja is naja-edit, a tool focused on netlist optimization with Dead Logic Elimination (DLE) or constant propagation.

For advanced use cases, EDA developers can build custom tools on top of naja C++ APIs. See some simple examples here.

This project is supported and funded by NLNet through the NGI0 Entrust Fund.

naja_edit, located in the $NAJA_INSTALL/bin directory, is a tool designed for optimizing, editing and translating netlists.

📺 We presented naja_edit’s latest features and results at ORConf 2024. You can watch the full presentation here.

The workflow for naja_edit is outlined in the schema below. It's important to note that the only mandatory step in the process is the initial loading of the input netlist.

• Input/Output format: Supports structural (gate-level) Verilog and SNL Interchange Format. Convert netlists between formats by specifying the input (-f) and output (-t) options.

#translation from verilog to SNL
naja_edit -f verilog -t snl -i input.v -o output.snl

• Python Netlist Manipulation/Editing: Leverage the SNL Python API for netlist manipulations such as browsing, computing stats or direct editing. Scripts can be applied after loading (-e option) or before saving (-z option) the netlist.

#translation from verilog to SNL with intermediate editing
naja_edit -f verilog -t snl -i input.v -o output.snl -e script.py

• Netlist Logic optimizations across hierarchy boundaries: Utilize built-in optimization algorithms to refine the netlist across hierarchical boundaries with minimal uniquification. Available optimizations include:

• All optimizations (option -a all): will apply Dead Logic Elimination (DLE), Constant Propagation and Primitives Optimization.

• Dead Logic Elimination only (option -a dle): will apply only DLE.

# -1: Load input netlist from SNL format.
# -2: Apply pre_edit.py script on the netlist
# -3: Apply Dead Logic Optimization
# -4: Apply post_edit.py on the resulting netlist
# -5: Save netlist in SNL format to output.snl
naja_edit -f snl -t snl -i input.snl -o output.snl -a dle \ 
          -e pre_script.py -z post_edit.py

👉🐍 This page provides a collection of example Python scripts for using the naja_edit API.

naja_edit editing script examples are also available here.

The Naja Regress repository features a collection of examples showcasing extensive use of naja_edit.

Naja contains three primary API components:

1. SNL (Structured Netlist) API housed in this repository.
2. DNL (Dissolved Netlist) API associated to SNL also in this repository.
3. naja-verilog, a data structure independent structural verilog parser.

In most EDA flows, data exchange is done by using standard netlist formats (Verilog, LEF/DEF, EDIF, …) which were not designed to represent data structures content with high fidelity. To address this problem, SNL relies on Cap'n Proto open source interchange format.

DNL provides a uniquified view of SNL, specifically designed for efficient multi-threaded traversal and analysis of netlist data. Key features of DNL include:

• Read-only Data Structure: Ensures data integrity and stability during analysis.
• Fast Construction: DNL is quickly built from SNL, facilitating rapid transitions between representations.
• Index-based Minimal Details: Reduces overhead and focuses on essential connectivity information.
• Connectivity Representation: Utilizes equipotentials between terminals to represent connections effectively.

Together, SNL and DNL enhance the fidelity, performance, and efficiency of netlist data handling in EDA workflows.

SNL is engineered with a focus on parallelization, particularly for cloud computing applications. It features a robust object identification mechanism that streamlines the partitioning and merging of data across networks, facilitating efficient EDA applications.

SNL is summarized in below's image.

💁 If you have any questions, please Contact Us

⭐ If you find Naja interesting, and would like to stay up-to-date, consider starring this repo to help spread the word.

👓 Naja's extended and API documentation is available online.

# First clone the repository and go inside it
git clone --recurse-submodules https://github.com/najaeda/naja.git

Mandatory dependencies:

1. Boost
2. cmake: at least 3.22 version. For system-specific cmake installation options, please refer to this link.
3. Python3: for building the SNL Python3 interface. This interface is used to load primitive cells (associated to Verilog parsing) and their associated characteristics (for instance: ressource count, timing characteristics, ...).

Optional dependencies:

1. Doxygen: for the documentation generation.

Embedded dependencies, through git sub modules:

1. naja-verilog: for verilog parsing.
2. google test for unit testing.

On Ubuntu:

sudo apt-get install g++ libboost-dev python3.9-dev capnproto libcapnp-dev libtbb-dev pkg-config bison flex doxygen

Using nix-shell:

nix-shell -p cmake boost python3 doxygen capnproto bison flex pkg-config tbb_2021_8

On macOS, using Homebrew:

brew install cmake doxygen capnp tbb bison flex boost

Ensure the versions of bison and flex installed via Homebrew take precedence over the macOS defaults by modifying your $PATH environment variable as follows:

export PATH="/opt/homebrew/opt/flex/bin:/opt/homebrew/opt/bison/bin:$PATH"

#First define an env variable that points to the directory where you want naja to be installed:
export NAJA_INSTALL=<path_to_installation_dir>
# Create a build dir and go inside it
mkdir build
cd build
cmake <path_to_naja_sources_dir> -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=$NAJA_INSTALL
#For instance: cmake ~/srcs/naja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=$NAJA_INSTALL
make
make test
make install

#make sure that doxygen was available when launching the cmake command
cd build
make docs
make install

Documentation will be installed in $NAJA_INSTALL/doc directory. Starting file to open in browser is: $NAJA_INSTALL/doc/html/index.html.

After building and installing, start by setting up a runtime environment.

export NAJA_INSTALL=<path_to_installation_dir>
#For Naja python interface and in particular primitives loading
export PYTHONPATH=$PYTHONPATH:$NAJA_INSTALL/lib/python

SNL relies on Cap'n Proto for data serialization and streaming. Schema files and C++ implementation can be found here.

Files composing the dump are created in a directory usually named "snl", composed of the following files:

• Manifest File (snl.mf): This file encapsulates essential meta-information such as the schema version and other relevant details.
• Interface Definition File (db_interface.snl): This file outlines the interfaces of modules: terminals and parameters.
• Implementation Specification File (db_implementation.snl): Contained within this file are the detailed implementations of modules: instances, nets and connectivity between them.

SNL files can be examined using the capnp tool.

capnp decode --packed snl_interface.capnp DBInterface < snl/db_interface.snl > interface.txt
capnp decode --packed snl_implementation.capnp DBImplementation < snl/db_implementation.snl > implementation.txt

For Verilog parsing, Naja relies on naja-verilog submodule. Leaf primitives are loaded through the Python primitive loader: SNLPrimitivesLoader. An application snippet can be found here and examples of primitive libraries described using the Python interface can be found in the primitives directory.

A Verilog dumper is included in SNL API. See here.

This snippet shows various SNL API netlist construction, manipulation and browsing examples.

This snippet shows an equivalent example using Python interface.

An application snippet can be found here.

This "app" directory and its contents can be copied to start a new application.

Please use GitHub Issues to create and track requests and bugs.