GSoC 2023 Final Work Submission

gsoc-2023-work-submission.md

GSoC 2023 Project Report

Implementation of a Common Python Framework for OpenFASoC Generators

• Name: Harsh Khandeparkar (@harshkhandeparkar)
• Organization: CHIPS Alliance
• Mentor: Mehdi Saligane (@msaligane)
• Project Repository: OpenFASOC
• Submitted Proposal
• Extended Proposal
• Progress Tracker Issue

Project Overview

OpenFASoC (Fully Open-Source Autonomous SoC Synthesis using Customizable Cell-Based Synthesizable Analog Circuits) is a project focused on a fully automated user specification to GDS generation flow built using open-source tools. OpenFASoC uses tools such as OpenROAD, Yosys, Magic, and Netgen to fully autonomouly choose the best parameters based on the user specification, generate, and simulate circuit blocks which could be used in SoCs. OpenFASoC was inspired by FASoC, built on proprietary tools.

The project consists of multiple modules called "generators," each focused on a particular design. Each generator uses a set of parameters to generate the most suitable design variation according to the user specification. This is done using template source Verilog files with placeholders for the parameters.

This project aimed at creating a common Python module and a consistent, simple, and intuitive templating syntax that could be used across all the generators. Mako library was chosen due to its simple Python-like syntax that is powerful yet easy to read and write in. The same format was used in SPICE templates used for simulation.

Deliverables

• A common Python module that can be used across generators.
• A Mako-based Verilog generation module and updating existing generators to use the new templating format.
• A common Python simulation module and updating existing generators' simulations.
• Documenting the new API and changes made to the generators.
• Implementing regression tests in the CI for the new functionality.
• Implementing the remaining generators from FASoC using the new API.

Work Completed

1. Verilog Generation

Many OpenFASoC generators use Verilog source files. These files are templates and use placeholders for parameters. These parameters are calculated based on the user specification, and the values are inserted to generate the final Verilog files.

In this project, a common Python module was created that exports functions that would be used across generators. The Mako library was used for making Verilog templates. Following is an example Verilog template file from the Temperature Sensor generator.

% for i in range(ninv):
${cell('inv')} a_inv_${i} ( .A(n${i + 1}), .Y(n${i + 2}));
% endfor

The above code generates a chain of inverters (NOT gates). The common module is imported and used in the following way.

from common.verilog_generation import generate_verilog

verilog_gen_dir=os.path.join('flow', 'design', 'src', 'tempsense')
generate_verilog(
    parameters={
        "design_name": designName,
        "ninv": ninv,
        "nhead": nhead
    },
    out_dir=verilog_gen_dir
)

This common Python module was used in the Temperature Sensor, Cryo, LDO, and DC-DC Converter generators.

This module significantly simplifies the generator-specific Python code that was replaced. Using a common module also reduced code duplication and would ease the creation of any future generators.

2. Simulation

The SPICE netlists of generated designs in OpenFASoC are extracted using Netgen to simulate with tools such as Ngspice and Xyce. The SPICE test benches used are also parameterized, and different parameters are inserted in the templates to run simulations under various conditions, such as varying temperature ranges.

A simulation Python module was added that sweeps all input parameter combinations, generates SPICE testbenches from a template using the same Mako syntax, and runs parallel simulations to generate the final output. The following is an example of the usage of the module.

from common.simulation import run_simulations

num_simulations = run_simulations(
    parameters={
        'temp': {'start': tempStart, 'end': tempStop, 'step': tempStep},
        'model_file': model_file,
        'model_corner': platformConfig['model_corner'],
        'nominal_voltage': platformConfig['nominal_voltage'],
        'design_name': designName
    },
    template_path=os.path.join("templates", f"tempsenseInst_{simTool}.sp"),
    sim_tool=simTool,
    netlist_path=dstNetlist
)

The simulation module was used in the Temperature Sensor, LDO, and DC-DC Converter generators.

In the LDO generator, the module significantly simplified and fixed bugs in the simulations. In the DC-DC generator, new simulation testbenches were added. Overall, this module replaces a lot of duplicated and generator-specific code and abstracts many of the details, thus easing the creation of new generators.

3. Documentation

Both the Verilog generation and Simulation modules were documented. Python type hints and docstrings were used to write documentation for developers.

Apart from this, more detailed documentation was added on ReadTheDocs.

4. Regression Tests

The common Python modules were unit-tested using pytest. A workflow in the CI runs these tests on every pull request and on push.

For the Verilog generation module, the tests use sample Verilog templates and generate different versions of it with various parameters to verify if the correct file is generated. For the simulation module, different testbenches are generated and simulated.

Work Left

1. DC-DC Generator Documentation and Schematics

While working on the simulations for the DC-DC converter generator (which only partially works), I fixed various bugs and made enhancements, such as enabling support for the sky130hs platform. I also created circuit schematics and found a way to extract a SPICE netlist from the synthesized Verilog, add power pins, and run simulations using it.

Only the simulations and bug fixes made it to the final pull request.

2. Implementing Remaining FASoC Generators

Originally, migrating the remaining generators in FASoC to OpenFASoC was proposed, but since the proposal was changed and due to time constraints, the focus shifted to improving existing generators only.

3. Other Common Python Modules

In the common API proposal, modules for running the flow, parsing parameters and environment, generating a summary, etc. were proposed but could not be implemented during GSoC. If implemented in the future, these will be tracked in this issue.

Contributions

NOTE: Some pull requests listed below were opened during the GSoC coding period but may not have been merged before it ended.

PR	Description
#212	Creating the common Verilog generation module, documentation, testing, and implementation in the temperature sensor generator
#223	Using the Verilog generation module in the Cryo generator
#224	Using the Verilog generation module in the LDO generator
#226	Creating the common simulation module, documentation, testing, and implementation in the temperature sensor generator
#229	Fixing and updating simulations of the LDO generator to use the common simulation module
#230	Updating the DC-DC converter generator to use the common Verilog generation module, fixing multiple bugs in the generator's flow and implementing simulation test benches for it using the simulation module