Skip to content

Commit de914ff

Browse files
jdicorpojdicorpo
authored
Merge pull request #9 from chipfoundry/makefile_deprecation
updated README
2 parents 1c28117 + 046921f commit de914ff

1 file changed

Lines changed: 137 additions & 39 deletions

File tree

‎README.md‎

Lines changed: 137 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,75 +1,173 @@
1-
# OpenFrame Overview
1+
<div align="center">
22

3-
The OpenFrame Project provides an empty harness chip that differs significantly from the Caravel and Caravan designs. Unlike Caravel and Caravan, which include integrated SoCs and additional features, OpenFrame offers only the essential padframe, providing users with a clean slate for their custom designs.
3+
<img src="https://umsousercontent.com/lib_lnlnuhLgkYnZdkSC/hj0vk05j0kemus1i.png" alt="ChipFoundry Logo" height="140" />
44

5-
<img width="256" alt="Screenshot 2024-06-24 at 12 53 39 PM" src="https://github.com/efabless/openframe_timer_example/assets/67271180/ff58b58b-b9c8-4d5e-b9bc-bf344355fa80">
5+
[![Typing SVG](https://readme-typing-svg.demolab.com?font=Inter&size=44&duration=3000&pause=600&color=4C6EF5&center=true&vCenter=true&width=1100&lines=OpenFrame+User+Project+Template;OpenLane+%2B+ChipFoundry+Flow;Verification+and+Shuttle-Ready)](https://git.io/typing-svg)
66

7-
## Key Characteristics of OpenFrame
7+
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
8+
[![ChipFoundry Marketplace](https://img.shields.io/badge/ChipFoundry-Marketplace-6E40C9.svg)](https://platform.chipfoundry.io/marketplace)
89

9-
1. **Minimalist Design:**
10-
- No integrated SoC or additional circuitry.
11-
- Only includes the padframe, a power-on-reset circuit, and a digital ROM containing the 32-bit project ID.
10+
</div>
1211

13-
2. **Padframe Compatibility:**
14-
- The padframe design and pin placements match those of the Caravel and Caravan chips, ensuring compatibility and ease of transition between designs.
15-
- Pin types are identical, with power and ground pins positioned similarly and the same power domains available.
12+
## Table of Contents
13+
- [Overview](#overview)
14+
- [Documentation & Resources](#documentation--resources)
15+
- [Prerequisites](#prerequisites)
16+
- [Project Structure](#project-structure)
17+
- [Starting Your Project](#starting-your-project)
18+
- [Development Flow](#development-flow)
19+
- [Local Precheck](#local-precheck)
20+
- [Checklist for Shuttle Submission](#checklist-for-shuttle-submission)
1621

17-
3. **Flexibility:**
18-
- Provides full access to all GPIO controls.
19-
- Maximizes the user project area, allowing for greater customization and integration of alternative SoCs or user-specific projects at the same hierarchy level.
22+
## Overview
23+
OpenFrame is a ChipFoundry project template that provides only a bare padframe (no integrated SoC), giving you a 15 mm² user area and 44 GPIOs to design your own custom chip. You are free to implement your design and directly connect it to the available GPIOs throught the pins provided on the openframe wrapper.
2024

21-
4. **Simplified I/O:**
22-
- Pins that previously connected to CPU functions (e.g., flash controller interface, SPI interface, UART) are now repurposed as general-purpose I/O, offering flexibility for various applications.
25+
---
2326

24-
The OpenFrame harness is ideal for those looking to implement custom SoCs or integrate user projects without the constraints of an existing SoC.
27+
## Documentation & Resources
28+
For detailed hardware specifications and design guidelines, refer to the following official documents:
2529

26-
## Features
30+
* **[ChipFoundry Marketplace](https://platform.chipfoundry.io/marketplace)**: Access additional IP blocks, EDA tools, and shuttle services.
2731

28-
1. 44 configurable GPIOs.
29-
2. User area of approximately 15mm².
30-
3. Supports digital, analog, or mixed-signal designs.
32+
---
3133

32-
# openframe_timer_example
34+
## Prerequisites
35+
Ensure your environment meets the following requirements:
3336

34-
This example implements a simple timer and connects it to the GPIOs.
37+
1. **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/)
38+
2. **Python 3.8+** with `pip`.
39+
3. **Git**: For repository management.
3540

36-
## Installation and Setup
41+
---
3742

38-
First, clone the repository:
43+
## Project Structure
44+
A successful OpenFrame project requires a specific directory layout for the automated tools to function:
45+
46+
| Directory | Description |
47+
| :--- | :--- |
48+
| `openlane/` | Configuration files for hardening macros and the wrapper. |
49+
| `verilog/rtl/` | Source Verilog code for the project. |
50+
| `verilog/gl/` | Gate-level netlists (generated after hardening). |
51+
| `verilog/dv/` | Design Verification (cocotb and Verilog testbenches). |
52+
| `gds/` | Final GDSII binary files for fabrication. |
53+
| `lef/` | Library Exchange Format files for the macros. |
54+
55+
---
56+
57+
## Starting Your Project
58+
59+
### 1. Repository Setup
60+
Create a new repository based on the `openframe_user_project` template and clone it to your local machine:
3961

4062
```bash
41-
git clone https://github.com/efabless/openframe_user_project.git
42-
cd openframe_user_project
63+
git clone <your-github-repo-URL>
64+
pip install chipfoundry-cli
65+
cd <project_name>
4366
```
4467

45-
Then, download all dependencies:
68+
### 2. Project Initialization
69+
70+
> [!IMPORTANT]
71+
> Run this first! Initialize your project configuration:
4672
4773
```bash
48-
make setup
74+
cf init
4975
```
5076

51-
## Hardening the Design
77+
This creates `.cf/project.json` with project metadata. **This must be run before any other commands**
5278

53-
In this example, we will harden the timer. You will need to harden your own design similarly.
79+
### 3. Environment Setup
80+
Install the ChipFoundry CLI tool and set up the local environment (PDKs, OpenLane, and OpenFrame):
5481

5582
```bash
56-
make user_proj_timer
83+
cf setup
5784
```
5885

59-
Once you have hardened your design, integrate it into the OpenFrame wrapper:
86+
The `cf setup` command installs:
87+
88+
- OpenFrame: The OpenFrame harness template.
89+
- OpenLane: The RTL-to-GDS hardening flow.
90+
- PDK: Skywater 130nm process design kit.
91+
- Timing Scripts: For Static Timing Analysis (STA).
92+
93+
---
94+
95+
## Development Flow
96+
97+
### Hardening the Design
98+
Hardening is the process of synthesizing your RTL and performing Place & Route (P&R) to create a GDSII layout.
99+
100+
#### Macro Hardening
101+
Create a subdirectory for each custom macro under `openlane/` containing your `config.json`.
60102

61103
```bash
62-
make openframe_project_wrapper
104+
cf harden --list # List detected configurations
105+
cf harden <macro_name> # Harden a specific macro
63106
```
64107

65-
## Important Notes
108+
#### Integration
109+
Instantiate your module(s) in `verilog/rtl/openframe_project_wrapper.v`.
66110

67-
1. **Connecting to Power:**
111+
Update `openlane/openframe_project_wrapper/config.json` environment variables (`VERILOG_FILES_BLACKBOX`, `EXTRA_LEFS`, `EXTRA_GDS_FILES`) to point to your new macros.
112+
113+
#### Wrapper Hardening
114+
Finalize the top-level user project:
115+
116+
```bash
117+
cf harden openframe_project_wrapper
118+
```
119+
120+
### Important Notes
121+
122+
**Connecting to Power:**
68123
- Ensure your design is connected to power using the power pins on the wrapper.
69124
- Use the `vccd1_connection` and `vssd1_connection` macros, which contain the necessary vias and nets for power connections.
70125

71-
2. **Flattening the Design:**
72-
- If you plan to flatten your design within the `openframe_project_wrapper`, do not buffer the analog pins using standard cells.
126+
### Verification
127+
128+
#### 1. Simulation
129+
We use cocotb for functional verification. Ensure your file lists are updated in `verilog/includes/`.
73130

74-
3. **Running Custom Steps:**
75-
- Execute the custom step in OpenLane that copies the power pins from the template DEF. If this step is skipped, the precheck will fail, and your design will not be powered.
131+
Run RTL Simulation:
132+
133+
```bash
134+
cf verify <test_name>
135+
```
136+
137+
Run Gate-Level (GL) Simulation:
138+
139+
```bash
140+
cf verify <test_name> --sim gl
141+
```
142+
143+
Run all tests:
144+
145+
```bash
146+
cf verify --all
147+
```
148+
149+
---
150+
151+
## Local Precheck
152+
Before submitting your design for fabrication, run the local precheck to ensure it complies with all shuttle requirements:
153+
154+
```bash
155+
cf precheck
156+
```
157+
158+
You can also run specific checks or disable LVS:
159+
160+
```bash
161+
cf precheck --disable-lvs # Skip LVS check
162+
cf precheck --checks license --checks makefile # Run specific checks only
163+
```
164+
---
165+
166+
## Checklist for Shuttle Submission
167+
- [ ] Top-level macro is named openframe_project_wrapper.
168+
- [ ] Full Chip Simulation passes for both RTL and GL.
169+
- [ ] Hardened Macros are LVS and DRC clean.
170+
- [ ] openframe_project_wrapper matches the required pin order/template.
171+
- [ ] Design is properly connected to power (vccd1/vssd1).
172+
- [ ] Design passes the local cf precheck.
173+
- [ ] Documentation (this README) is updated with project-specific details.

0 commit comments

Comments
 (0)