{"id":51007631,"url":"https://github.com/chipfoundry/caravel_user_project","last_synced_at":"2026-06-20T22:02:20.650Z","repository":{"id":293302560,"uuid":"975111900","full_name":"chipfoundry/caravel_user_project","owner":"chipfoundry","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-23T22:45:45.000Z","size":364266,"stargazers_count":17,"open_issues_count":61,"forks_count":15,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-24T00:27:24.331Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Verilog","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chipfoundry.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-04-29T19:57:08.000Z","updated_at":"2026-04-23T22:45:49.000Z","dependencies_parsed_at":"2025-09-28T11:27:10.750Z","dependency_job_id":"e18ef4c0-6d75-40af-ac82-852d4aa44367","html_url":"https://github.com/chipfoundry/caravel_user_project","commit_stats":null,"previous_names":["chipfoundry/caravel_user_project"],"tags_count":43,"template":true,"template_full_name":null,"purl":"pkg:github/chipfoundry/caravel_user_project","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chipfoundry%2Fcaravel_user_project","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chipfoundry%2Fcaravel_user_project/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chipfoundry%2Fcaravel_user_project/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chipfoundry%2Fcaravel_user_project/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chipfoundry","download_url":"https://codeload.github.com/chipfoundry/caravel_user_project/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chipfoundry%2Fcaravel_user_project/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34586666,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-20T02:00:06.407Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-20T22:02:19.682Z","updated_at":"2026-06-20T22:02:20.643Z","avatar_url":"https://github.com/chipfoundry.png","language":"Verilog","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"https://umsousercontent.com/lib_lnlnuhLgkYnZdkSC/hj0vk05j0kemus1i.png\" alt=\"ChipFoundry Logo\" height=\"140\" /\u003e\n\n[![Typing SVG](https://readme-typing-svg.demolab.com?font=Inter\u0026size=44\u0026duration=3000\u0026pause=600\u0026color=4C6EF5\u0026center=true\u0026vCenter=true\u0026width=1100\u0026lines=Caravel+User+Project+Template;OpenLane+%2B+ChipFoundry+Flow;Verification+and+Shuttle-Ready)](https://git.io/typing-svg)\n\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![ChipFoundry Marketplace](https://img.shields.io/badge/ChipFoundry-Marketplace-6E40C9.svg)](https://platform.chipfoundry.io/marketplace)\n\n\u003c/div\u003e\n\n## Table of Contents\n- [Overview](#overview)\n- [Documentation \u0026 Resources](#documentation--resources)\n- [Prerequisites](#prerequisites)\n- [Project Structure](#project-structure)\n- [Starting Your Project](#starting-your-project)\n- [Development Flow](#development-flow)\n- [GPIO Configuration](#gpio-configuration)\n- [Local Precheck](#local-precheck)\n- [Checklist for Shuttle Submission](#checklist-for-shuttle-submission)\n\n## Overview\nThis repository contains a user project designed for integration into the **Caravel chip user space**. Use it as a template for integrating custom RTL with Caravel's system-on-chip (SoC) utilities, including:\n\n* **IO Pads:** Configurable general-purpose input/output.\n* **Logic Analyzer Probes:** 128 signals for non-intrusive hardware debugging.\n* **Wishbone Port:** A 32-bit standard bus interface for communication between the RISC-V management core and your custom hardware.\n\n---\n\n## Documentation \u0026 Resources\nFor detailed hardware specifications and register maps, refer to the following official documents:\n\n* **[Caravel Datasheet](https://github.com/chipfoundry/caravel/blob/main/docs/caravel_datasheet_2.pdf)**: Detailed electrical and physical specifications of the Caravel harness.\n* **[Caravel Technical Reference Manual (TRM)](https://github.com/chipfoundry/caravel/blob/main/docs/caravel_datasheet_2_register_TRM_r2.pdf)**: Complete register maps and programming guides for the management SoC.\n* **[ChipFoundry Marketplace](https://platform.chipfoundry.io/marketplace)**: Access additional IP blocks, EDA tools, and shuttle services.\n\n---\n\n## Prerequisites\nEnsure your environment meets the following requirements:\n\n1. **Docker** [Linux](https://docs.docker.com/desktop/setup/install/linux/ubuntu/) | [Windows](https://docs.docker.com/desktop/setup/install/windows-install/) | [Mac](https://docs.docker.com/desktop/setup/install/mac-install/)\n2. **Python 3.8+** with `pip`.\n3. **Git**: For repository management.\n\n---\n\n## Project Structure\nA successful Caravel project requires a specific directory layout for the automated tools to function:\n\n| Directory | Description |\n| :--- | :--- |\n| `openlane/` | Configuration files for hardening macros and the wrapper. |\n| `verilog/rtl/` | Source Verilog code for the project. |\n| `verilog/gl/` | Gate-level netlists (generated after hardening). |\n| `verilog/dv/` | Design Verification (cocotb and Verilog testbenches). |\n| `gds/` | Final GDSII binary files for fabrication. |\n| `lef/` | Library Exchange Format files for the macros. |\n\n---\n\n## Starting Your Project\n\n### 1. Repository Setup\nCreate a new repository based on the `caravel_user_project` template and clone it to your local machine:\n\n```bash\ngit clone \u003cyour-github-repo-URL\u003e\npip install chipfoundry-cli\ncd \u003cproject_name\u003e\n```\n\n### 2. Platform Login\n\nLog in to the ChipFoundry platform (required before `cf init`, `cf push`, `cf pull`, etc.):\n\n```bash\ncf login\n```\n\n### 3. Project Initialization\n\n\u003e [!IMPORTANT]\n\u003e Run this first! Initialize your project configuration:\n\n```bash\ncf init\n```\n\nThis creates `.cf/project.json` with project metadata. **This must be run before any other commands** (`cf setup`, `cf gpio-config`, `cf harden`, `cf precheck`, `cf verify`).\n\n### 4. Environment Setup\nInstall the ChipFoundry CLI tool and set up the local environment (PDKs, OpenLane, and Caravel lite):\n\n```bash\ncf setup\n```\n\nThe `cf setup` command installs:\n\n- Caravel Lite: The Caravel SoC template.\n- Management Core: RISC-V management area required for simulation.\n- OpenLane: The RTL-to-GDS hardening flow.\n- PDK: Skywater 130nm process design kit.\n- Timing Scripts: For Static Timing Analysis (STA).\n\n---\n\n## Development Flow\n\n### Hardening the Design\nHardening is the process of synthesizing your RTL and performing Place \u0026 Route (P\u0026R) to create a GDSII layout.\n\n#### Macro Hardening\nCreate a subdirectory for each custom macro under `openlane/` containing your `config.tcl`.\n\n```bash\ncf harden --list         # List detected configurations\ncf harden \u003cmacro_name\u003e   # Harden a specific macro\n```\n\n#### Integration\nInstantiate your module(s) in `verilog/rtl/user_project_wrapper.v`.\n\nUpdate `openlane/user_project_wrapper/config.json` environment variables (`VERILOG_FILES_BLACKBOX`, `EXTRA_LEFS`, `EXTRA_GDS_FILES`) to point to your new macros.\n\n#### Wrapper Hardening\nFinalize the top-level user project:\n\n```bash\ncf harden user_project_wrapper\n```\n\n### Verification\n\n#### 1. Simulation\nWe use cocotb for functional verification. Ensure your file lists are updated in `verilog/includes/`.\n\n**Configure GPIO settings first (required before verification):**\n\n```bash\ncf gpio-config\n```\n\nThis interactive command will:\n- Configure all GPIO pins interactively\n- Automatically update `verilog/rtl/user_defines.v`\n- Automatically run `gen_gpio_defaults.py` to generate GPIO defaults for simulation\n\nGPIO configuration is required before running any verification tests.\n\nRun RTL Simulation:\n\n```bash\ncf verify \u003ctest_name\u003e\n```\n\nRun Gate-Level (GL) Simulation:\n\n```bash\ncf verify \u003ctest_name\u003e --sim gl\n```\n\nRun all tests:\n\n```bash\ncf verify --all\n```\n\n#### 2. Static Timing Analysis (STA)\nVerify that your design meets timing constraints using OpenSTA:\n\n```bash\nmake extract-parasitics\nmake create-spef-mapping\nmake caravel-sta\n```\n\n\u003e [!NOTE]\n\u003e Run `make setup-timing-scripts` if you need to update the STA environment.\n\n---\n\n## GPIO Configuration\nConfigure the power-on default configuration for each GPIO using the interactive CLI tool.\n\n**Use the GPIO configuration command:**\n```bash\ncf gpio-config\n```\n\nThis command will:\n- Present an interactive form for configuring GPIO pins 5-37 (GPIO 0-4 are fixed system pins)\n- Show available GPIO modes with descriptions\n- Allow selection by number, partial key, or full mode name\n- Save configuration to `.cf/project.json` (as hex values)\n- Automatically update `verilog/rtl/user_defines.v` with the new configuration\n- Automatically run `gen_gpio_defaults.py` to generate GPIO defaults for simulation (if Caravel is installed)\n\n**GPIO Pin Information:**\n- GPIO[0] to GPIO[4]: Preset system pins (do not change).\n- GPIO[5] to GPIO[37]: User-configurable pins.\n\n**Available GPIO Modes:**\n- Management modes: `mgmt_input_nopull`, `mgmt_input_pulldown`, `mgmt_input_pullup`, `mgmt_output`, `mgmt_bidirectional`, `mgmt_analog`\n- User modes: `user_input_nopull`, `user_input_pulldown`, `user_input_pullup`, `user_output`, `user_bidirectional`, `user_output_monitored`, `user_analog`\n\n\u003e [!NOTE]\n\u003e GPIO configuration is required before running `cf precheck` or `cf verify`. Invalid modes cannot be saved - all GPIOs must have valid configurations.\n\n---\n\n## Local Precheck\nBefore submitting your design for fabrication, run the local precheck to ensure it complies with all shuttle requirements:\n\n\u003e [!IMPORTANT]\n\u003e GPIO configuration is required before running precheck. Make sure you've run `cf gpio-config` first.\n\n```bash\ncf precheck\n```\n\nYou can also run specific checks or disable LVS:\n\n```bash\ncf precheck --disable-lvs                    # Skip LVS check\ncf precheck --checks gpio_defines --checks xor  # Run specific checks only\n```\n---\n\n## Checklist for Shuttle Submission\n- [ ] Top-level macro is named user_project_wrapper.\n- [ ] Full Chip Simulation passes for both RTL and GL.\n- [ ] Hardened Macros are LVS and DRC clean.\n- [ ] user_project_wrapper matches the required pin order/template.\n- [ ] Design passes the local cf precheck.\n- [ ] Documentation (this README) is updated with project-specific details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchipfoundry%2Fcaravel_user_project","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchipfoundry%2Fcaravel_user_project","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchipfoundry%2Fcaravel_user_project/lists"}