***************************************
See README1ST.pdf for important details
***************************************
Copyright (C) 2015-2019, MAXVY B.V.
All rights reserved.

Redistribution and use in source and binary forms, with or without 
modification, are permitted provided that the following conditions 
are met:

1. Redistributions of source code must retain the above copyright 
   notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright 
   notice, this list of conditions and the following disclaimer in
   the documentation and/or other materials provided with the 
   distribution.

3. Neither the name of the copyright holder nor the names of its 
   contributors may be used to endorse or promote products derived 
   from this HDL software without specific prior written permission.

THIS (HDL) SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, 
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR 
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

NOTE: No license under any third-party patent is granted or implied. 
      It is the responsibility of the licensee to obtain any required 
      third-party patent licenses.

Note on terms used above:
1. Software and HDL software are used interchangeably.
2. Binary includes FPGA, simulation, and physical forms such 
   as Silicon chips.
3. Clause 2 allows for such notice on a Web page or other 
   electronic form not part of a distribution.

Caravel User Mini

This repository contains the user project for each subproject in the Caravel Mini chip. It provides a template for integrating your design into the Caravel Mini project, allowing for closed-source submissions. This ensures that other users on the same chip cannot access your project.

Using the Caravel User Mini project is an excellent way to prototype your design, especially for small designs that do not require the entire user_project_wrapper_mini4_wrapper. This approach can be cost-effective while still offering significant benefits.

For more information about the Caravel Mini project, visit the Caravel Mini GitHub repository.

Installation

To install all dependencies and start working on your project, follow these steps:

1. Press the "Use this template" button to create your own repository.

2. Clone the repository:

   git clone https://github.com/<yourusername>/<your_new_repo_name>.git
   cd <your_new_repo_name>
   

3. Set up the environment:

   make setup
   

This will download all necessary dependencies.

Updating Verilog

You can update the RTL Verilog file located at verilog/rtl/user_project_wrapper_mini4.v. This file contains an example counter design that you can replace with your own design. You can also include macros within the user project.

You have the flexibility to include macros as either soft macros, which will be hardened together with the user project, or as hard macros, which can be integrated directly into the user project. Regardless, the user project should be the top-level module that you harden and submit to the platform.

Running RTL Verification

You can use the Cocotb infrastructure to run RTL verification. It is already set up; you just need to add a new test bench. Example test benches can be found under verilog/dv/cocotb.

To run the simulation, use the following command:

make cocotb-verify-<name_of_testbench>-rtl

Hardening Your Design

To harden your design using OpenLane, ensure that you adjust the configuration file located at openlane/user_project_wrapper_mini4/config.json as needed.

To start the hardening process, run:

make <macro_name>

Remember, the user project should be the top-level module in your design hierarchy for the final hardening and submission. You can include both soft and hard macros within this top-level module.

To harden the top level user_project_wrapper_mini4 macro run

make user_project_wrapper_mini4