Skip to content

Commit 1fcbae1

Browse files
mevalvermevalver
committed
Modular Design Toolkit, scripts and Subsystems
1 parent c81313a commit 1fcbae1

File tree

116 files changed

+19849
-1
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

116 files changed

+19849
-1
lines changed

‎LICENSE

+56
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
Copyright 2024-2025 Altera Corporation
2+
3+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
4+
documentation files (the “Software”), to deal in the Software without restriction, except as set forth below,
5+
including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
6+
sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to
7+
the following conditions:
8+
9+
The above copyright notice and this permission notice shall be included in all copies or substantial
10+
portions of the Software;
11+
12+
If a file contained in this Software includes separate license text or a header file with license terms,
13+
those terms will supersede this agreement for purposes of that file only, all files without a separate
14+
agreement are subject to this agreement;
15+
16+
The Software must be used solely for design and implementation on an Altera product;
17+
18+
You must not use the Software or devices you configure using this Software to violate any internationally
19+
recognized human right; and
20+
21+
The Software may be subject to export controls under applicable government laws and regulations, including
22+
those of the U.S. You must:
23+
24+
a) comply with applicable laws and regulations and obtain any necessary authorizations;
25+
b) not export, import, or transfer the materials to any prohibited or sanctioned country, person, or entity; or
26+
c) use the materials for the development, design, manufacture, or production of nuclear, missile, chemical,
27+
or biological weapons.
28+
29+
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
30+
TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
31+
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
32+
CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
33+
DEALINGS IN THE SOFTWARE.
34+
35+
Governing Law and Jurisdiction. If you are in the Americas, U.S. and Delaware law governs all disputes arising
36+
out of or relating to this agreement without regard to conflict-of-laws principles. The state and federal courts
37+
in Wilmington, Delaware will have exclusive jurisdiction over any dispute arising out of or relating to this
38+
agreement. If you are in Europe or Africa, the laws of England and Wales govern all matters arising out of or
39+
relating to this agreement without regard to conflict-of-laws principles. The courts in England will have
40+
exclusive jurisdiction over any dispute arising out of or relating to this agreement. If you are in Asia or
41+
Australia, Singapore law governs all disputes arising out of or relating to this agreement without regard to
42+
conflict-of-laws principles. The courts in Singapore will have exclusive jurisdiction over any dispute arising
43+
out of or relating to this agreement. You and Intel consent to personal jurisdiction and venue in the courts
44+
designated for your location. If you are in China, Hong Kong law governs all disputes arising out of or relating
45+
to this agreement without regard to conflict-of-laws principles. Any dispute arising out of or relating to this
46+
agreement will be subject to arbitration by the Hong Kong International Arbitration Centre, this arbitration
47+
agreement will be governed by Hong Kong law, and the seat and location of proceedings will be Hong Kong. The
48+
current rules of the HKIAC will apply, except that the arbitration will be
49+
50+
referred to a sole arbitrator and the proceedings will be conducted in English. The Arbitral Tribunal may only
51+
award monetary damages and may not award injunctive relief or any remedy that requires a party to license any
52+
intellectual property rights. Regardless of the above or your location, claims for misappropriation of trade
53+
secrets and breach of confidentiality obligations may also be brought in any court that has jurisdiction over
54+
the parties if the relief sought is limited to injunctive or other nonmonetary relief. The parties exclude the
55+
application of the United Nations Convention on Contracts for the International Sale of Goods (1980).
56+

‎Readme.md

+212-1
Original file line numberDiff line numberDiff line change
@@ -1 +1,212 @@
1-
New file
1+
# Modular Design Toolkit (MDT) for Altera® Design Examples
2+
3+
## Overview
4+
5+
The Altera® Modular Design Toolkit simplifies the creation of designs for the Platform Designer
6+
(PD) tool included with the Altera® Quartus® Prime software. The toolkit provides a framework
7+
to assemble complete FPGA designs from a library of subsystems. “Subsystem” is a PD term
8+
describing a subgroup of IPs connected to each other within a larger system of subsystems and
9+
individual IPs. A Modular Design is a collection of subsystems targeting a specific hardware
10+
configuration. This modular design framework allows you to quickly target a particular board
11+
as they include the subsystems necessary for the board IO. The goal of the Modular Design
12+
Toolkit approach is to create modular designs from existing subsystems & IP in a consistent
13+
manner and reduce the time to create new designs.
14+
15+
The Modular Design Toolkit provides support for the following:
16+
17+
- Library of subsystems: A set of pre-defined subsystems using Altera® IP components.
18+
- Creation of custom subsystems: Define and reuse custom parameterizable subsystems in a
19+
Subsystem Definition File that describes IP components, connectivity, and interfaces.
20+
- Project creation and build: Automated creation and build of a full Quartus® project and
21+
folder hierarchy.
22+
23+
### Software Requirements
24+
25+
This release of the Modular Design Toolkit requires the following software and versions (in Linux):
26+
27+
- Altera® Quartus® Prime Pro version (24.3 or above), including open-source tools to
28+
compile software targeting NiosV soft-processors.
29+
- Altera® VIP Suite version 24.3 - (optional – only needed for designs with video
30+
processing IP from Altera® VIP suite)
31+
32+
### Hardware Requirements
33+
34+
To operate modular systems on hardware, ensure you have the suitable board or development kit that is
35+
compatible with your chosen `board_subsystem`. Additionally, you may need relevant accessories such as
36+
daughter cards and other components.
37+
<br><br>
38+
39+
## Getting Started
40+
41+
### Create your own design with an XML description file
42+
43+
The Modular Design Toolkit allows you to create and build designs through the use of a TCL
44+
script and an XML file.
45+
46+
- To get started with a simple design clone the repository:
47+
48+
```bash
49+
cd <workspace>
50+
git clone -b <TAG> https://github.com/altera-fpga/modular-design-toolkit.git modular_design_toolkit
51+
mkdir my_design
52+
cd my_design
53+
vi my_design.xml
54+
```
55+
56+
A typical XML design description file can look like this.
57+
58+
```xml
59+
<PROJECT name="top">
60+
<DEVKIT>AGX_5E_Modular_Devkit</DEVKIT>
61+
<FAMILY>Agilex 5</FAMILY>
62+
<DEVICE>A5ED065BB32AE6SR0</DEVICE>
63+
<VERSION>24.1</VERSION>
64+
<SUBSYSTEM type="clock" name="clock_subsystem">
65+
<NUM_GEN_CLOCKS>0</NUM_GEN_CLOCKS>
66+
</SUBSYSTEM>
67+
<SUBSYSTEM type="debug"></SUBSYSTEM>
68+
<SUBSYSTEM type="board" name="board_subsystem">
69+
</SUBSYSTEM>
70+
<SUBSYSTEM type="hps" name="hps_subsystem">
71+
<AVMM_HOST>
72+
<NAME>hps_subsystem</NAME>
73+
</AVMM_HOST>
74+
<H2F_EXPORT>FULL</H2F_EXPORT>
75+
</SUBSYSTEM>
76+
</PROJECT>
77+
```
78+
79+
The XML file describes a project that is assembled from subsystems available in the
80+
“subsystems” directory. These are predefined subsystems that you can use to create a
81+
variety of projects. You can add and create your subsystems if required. In this
82+
example, the project contains the following characteristics:
83+
84+
- **PROJECT name**: by default **"top"** (recommended)
85+
- **DEVKIT**: Development Kit name. Available boards can be found at "platform_designer_subsystems/board_subsystem/boards" in this case
86+
**"AGX_5E_Modular_Devkit"** or [Agilex™ 5 FPGA E-Series 065B Modular Development Kit](https://www.intel.com/content/www/us/en/products/details/fpga/development-kits/agilex/a5e065b-modular.html)
87+
- **DEVICE**: must be a valid device within the Development Kit.
88+
- **clock_subsystem**: does not generate any additional clock other than the available default board oscillator
89+
- **board_subsystem**: baseboard pin assignments and configurations.
90+
- **hps_subsystem**: an instance of the Agilex5 Hard Processor Subsystem with supporting
91+
HW (such a DDR4 EMIF for Modular Devkit onboard RAM). The property H2F_EXPORT specifies
92+
that the project should export a Platform Designer top-level interface for the full
93+
HPS-to-FPGA (H2F) bridge (the Lightweight bridge can also be exported by setting
94+
this property to "BOTH").
95+
96+
- To create the Quartus® Project for your design, execute:
97+
98+
```bash
99+
cd ..
100+
quartus_sh -t ./modular_design_toolkit/scripts/create/create_shell.tcl -xml_path ./my_design/my_design.xml -proj_path <project> -o
101+
```
102+
103+
Option **"-help"** list out all possible options provided by the create script.
104+
105+
```bash
106+
quartus_sh -t ./modular_design_toolkit/scripts/create/create_shell.tcl -help
107+
```
108+
109+
The Altera® Quartus® project file is located at ./\<project>/quartus/top.qpf and the
110+
Altera® Platform Designer file is located at ./\<project>/rtl/top.qsys. A typical
111+
top-level PD system looks like this with individual subsystems instantiated in it.
112+
113+
![pd-mdt](./assets/pd-mdt.png)
114+
115+
The created folder structure under the project directory (\<project>) is the following:
116+
117+
![dir-mdt](./assets/dir-mdt.png)
118+
119+
### Build your design
120+
121+
The following steps show you how to compile the design created in the step above.
122+
Two flows are described. Automated/scripted compilation and compilation using
123+
the Platform Designer and Quartus® GUIs.
124+
125+
#### **a. Automated Compilation**
126+
127+
- In a terminal, navigate to \<project>/scripts and type the following command:
128+
129+
```bash
130+
cd <project>/scripts
131+
quartus_sh -t build_shell.tcl <build-options>
132+
```
133+
134+
- Option **"-help"** list out all possible options provided by the build script.
135+
136+
```bash
137+
cd <project>/scripts
138+
quartus_sh -t build_shell.tcl -help
139+
```
140+
141+
- The exact build command needed to generate the relevant FPGA programming files
142+
is given below.
143+
144+
```bash
145+
cd <project>/scripts
146+
quartus_sh -t build_shell.tcl -hw_compile
147+
```
148+
149+
![comp-mdt](./assets/comp-mdt.png)
150+
151+
#### **b. Quartus® GUI Compilation**
152+
153+
- In a windows explorer, navigate to \<project>/quartus and double click on
154+
the file top.qpf (if you named your project "top").
155+
156+
![top-qpf-mdt](./assets/top-qpf-mdt.png)
157+
158+
- Once Quartus® Prime opens, in the "Compilation Dashboard" press "Compile Design"
159+
(or instead navigate to Processing -> Start Compilation in the top menu).
160+
161+
![comp-dash-mdt](./assets/comp-dash-mdt.png)
162+
163+
From either method, once the compilation is finished a new FPGA programming file will be generated under \<project>/quartus/output_files.
164+
165+
<span style="color:red">**Note:**</span> **this example contains an instance of the Agilex5 HPS, to boot you need to create an RBF/JIC file pair and an SD card image. Please refer to the Linux Build Examples in this [link](https://altera-fpga.github.io/rel-24.3/embedded-designs/agilex-5/e-series/modular/boot-examples/ug-linux-boot-agx5e-modular/) or the GSRD User Guide in this [link](https://altera-fpga.github.io/rel-24.3/embedded-designs/agilex-5/e-series/modular/gsrd/ug-gsrd-agx5e-modular/).**
166+
<br><br>
167+
168+
## Repository Structure
169+
170+
The diagram below summarizes the contents of the Modular Design Toolkit (MDT)
171+
172+
modular-design-toolkit
173+
|--------- scripts
174+
| |------------build
175+
| | |-----packages
176+
| |------------create
177+
| |-----packages
178+
|
179+
|---------subsystems
180+
|----------platform_designer_subsystems
181+
| |----board_subsystem
182+
| |---- (…)
183+
| |----top_subsystem
184+
|
185+
|----------custom_user_subsystems
186+
| |----drive_subsystems
187+
| |---- (…)
188+
| |----agx5_motor_model_subsystem
189+
|
190+
|------------------common/non_qpds_ip
191+
|----*fpga*ip
192+
193+
The next table describes the contents of the repo.
194+
195+
| Directory Name | Sub-Directory | Description |
196+
| --- | --- | --- |
197+
| scripts | | Contains the TCL scripts required for the Modular Design Toolkit to function. The function of these scripts is described in later sections of this document.|
198+
| | create | A collection of TCL scripts and packages to create modular designs based on available subsystems in this repo.|
199+
| | build | A collection of TCL scripts and packages to build and compile modular designs in this repository. This directory is copied into the "project" directory generated in the "creation" phase.|
200+
| Subsystems | | Available subsystems to use as "building blocks" for any designs. Divided into "Platform Designer Subsystems" and "Custom User Subsystems". |
201+
| Subsystems | platform_designer_subsystems | Subsystems with Platform Designer Components. |
202+
| | platform_designer_subsystems/board_subsystems | TCL Subsystem description and collateral to target Development Kits Basic pin assignment, components and configuration files.<br> -Available boards: <br> [Agilex™ 5 FPGA E-Series 065B Modular Development Kit](https://www.intel.com/content/www/us/en/products/details/fpga/development-kits/agilex/a5e065b-modular.html) |
203+
| | platform_designer_subsystems/clock _subsystems | Subsystem to enable/add clocking to the project. |
204+
| | platform_designer_subsystems/cpu_subsystem | Subsystem to enable/add embedded CPU and supporting HW to the project. <br> Available variants: <br> - NiosV/g Subsystem for Drive-On-Chip. |
205+
| | platform_designer_subsystems/debug_subsystem | Probe interfacing for debugging. |
206+
| | platform_designer_subsystems/hps_subsystem | Subsystem to enable/add Hard Processor System and supporting HW to the project. <br> Available variants: <br> - Agilex 5E HPS. |
207+
| | platform_designer_subsystems/top_subsystem | Subsystem to enable/add top-level Verilog files to the project. |
208+
| | custom_user_subsystems | Available Subsystems based on custom RTL to use as "BUILDING BLOCKS" for any designs. |
209+
| | custom_user_subsystems/agx5_motor_model_subsystem | Motor Model Subsystem based on the characteristics of Tamagawa TS4747N3200E600 motor. RTL and HW files are products of the DSP Builder Advanced compilation targeting Agilex5 of the model "setup_motor_kit_sim_20MHz.m" |
210+
| | custom_user_subsystems/drive_subsystems | A collection of subsystems IP and Software for motor control designs. |
211+
| | custom_user_subsystems/safety_subsystems | A collection of subsystems and custom IP for Drive-On-Chip with Safety Function design examples based on speed monitoring and Agilex devices |
212+
| | common/non_qpds_ip | General-use custom IPs. |

‎assets/comp-dash-mdt.png

17.6 KB
Loading

‎assets/comp-mdt.png

33.6 KB
Loading

‎assets/dir-mdt.png

123 KB
Loading

‎assets/pd-mdt.png

85.3 KB
Loading

‎assets/top-qpf-mdt.png

5.18 KB
Loading

0 commit comments

Comments
 (0)