altera-fpga · kbrunham-intel · Aug 8, 2025 · Aug 8, 2025
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,2 @@
+/venv/
+/install/
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,67 @@
+Copyright 2024-2025 Altera Corporation 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of 
+this software and associated documentation files (the “Software”), to deal in 
+the Software without restriction, except as set forth below, including without 
+limitation the rights to use, copy, modify, merge, publish, distribute, 
+sublicense, and/or sell copies of the Software, and to permit persons to whom 
+the Software is furnished to do so, subject to the following conditions: 
+
+The above copyright notice and this permission notice shall be included in all 
+copies or substantial portions of the Software; 
+
+If a file contained in this Software includes separate license text or a header 
+file with license terms, those terms will supersede this agreement for purposes 
+of that file only, all files without a separate agreement are subject to this 
+agreement; 
+
+The Software must be used solely for design and implementation on an Altera 
+product; 
+
+You must not use the Software or devices you configure using this Software to 
+violate any internationally recognized human right; and 
+
+The Software may be subject to export controls under applicable government laws 
+and regulations, including those of the U.S. You must: a) comply with 
+applicable laws and regulations and obtain any necessary authorizations; b) not 
+export, import, or transfer the materials to any prohibited or sanctioned 
+country, person, or entity; or c) use the materials for the development, 
+design, manufacture, or production of nuclear, missile, chemical, or biological 
+weapons. 
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 
+SOFTWARE. 
+
+Governing Law and Jurisdiction. If you are in the Americas, U.S. and Delaware 
+law governs all disputes arising out of or relating to this agreement without 
+regard to conflict-of-laws principles. The state and federal courts in 
+Wilmington, Delaware will have exclusive jurisdiction over any dispute arising 
+out of or relating to this agreement. If you are in Europe or Africa, the laws 
+of England and Wales govern all matters arising out of or relating to this 
+agreement without regard to conflict-of-laws principles. The courts in England 
+will have exclusive jurisdiction over any dispute arising out of or relating to 
+this agreement. If you are in Asia or Australia, Singapore law governs all 
+disputes arising out of or relating to this agreement without regard to 
+conflict-of-laws principles. The courts in Singapore will have exclusive 
+jurisdiction over any dispute arising out of or relating to this agreement. You 
+and Intel consent to personal jurisdiction and venue in the courts designated 
+for your location. If you are in China, Hong Kong law governs all disputes 
+arising out of or relating to this agreement without regard to conflict-of-laws 
+principles. Any dispute arising out of or relating to this agreement will be 
+subject to arbitration by the Hong Kong International Arbitration Centre, this 
+arbitration agreement will be governed by Hong Kong law, and the seat and 
+location of proceedings will be Hong Kong. The current rules of the HKIAC will 
+apply, except that the arbitration will be referred to a sole arbitrator and 
+the proceedings will be conducted in English. The Arbitral Tribunal may only 
+award monetary damages and may not award injunctive relief or any remedy that 
+requires a party to license any intellectual property rights. Regardless of the 
+above or your location, claims for misappropriation of trade secrets and breach 
+of confidentiality obligations may also be brought in any court that has 
+jurisdiction over the parties if the relief sought is limited to injunctive or 
+other nonmonetary relief. The parties exclude the application of the United 
+Nations Convention on Contracts for the International Sale of Goods (1980). 
diff --git a/Makefile b/Makefile
@@ -0,0 +1,226 @@
+THIS_MK_ABSPATH := $(abspath $(lastword $(MAKEFILE_LIST)))
+THIS_MK_DIR := $(dir $(THIS_MK_ABSPATH))
+
+# Enable pipefail for all commands
+SHELL=/bin/bash -o pipefail
+
+# Enable second expansion
+.SECONDEXPANSION:
+
+# Clear all built in suffixes
+.SUFFIXES:
+
+NOOP :=
+SPACE := $(NOOP) $(NOOP)
+COMMA := ,
+HOSTNAME := $(shell hostname)
+
+##############################################################################
+# Environment check
+##############################################################################
+
+
+##############################################################################
+# Configuration
+##############################################################################
+WORK_ROOT := $(abspath $(THIS_MK_DIR)/work)
+INSTALL_RELATIVE_ROOT ?= install
+INSTALL_ROOT ?= $(abspath $(THIS_MK_DIR)/$(INSTALL_RELATIVE_ROOT))
+
+PYTHON3 ?= python3
+VENV_DIR := venv
+VENV_PY := $(VENV_DIR)/bin/python
+VENV_PIP := $(VENV_DIR)/bin/pip
+ifneq ($(https_proxy),)
+PIP_PROXY := --proxy $(https_proxy)
+else
+PIP_PROXY :=
+endif
+VENV_PIP_INSTALL := $(VENV_PIP) install $(PIP_PROXY) --timeout 90 --trusted-host pypi.org --trusted-host files.pythonhosted.org
+
+##############################################################################
+# Set default goal before any targets. The default goal here is "test"
+##############################################################################
+DEFAULT_TARGET := all
+
+.DEFAULT_GOAL := default
+.PHONY: default
+default: $(DEFAULT_TARGET)
+
+
+##############################################################################
+# Makefile starts here
+##############################################################################
+
+
+###############################################################################
+#                          Design Targets
+###############################################################################
+
+# Initialize variables
+ALL_TARGET_STEM_NAMES =
+ALL_PRE_PREP_TARGETS =
+ALL_PREP_TARGETS =
+ALL_IP_UPGRADE_TARGETS =
+ALL_GENERATE_DESIGN_TARGETS =
+ALL_PACKAGE_DESIGN_TARGETS =
+ALL_BUILD_TARGETS =
+ALL_SW_BUILD_TARGETS =
+ALL_TEST_TARGETS =
+ALL_INSTALL_SOF_TARGETS =
+ALL_TARGET_ALL_NAMES =
+
+# Define function to create targets
+define create_targets_on_subdir
+ALL_TARGET_STEM_NAMES += $(addprefix $(strip $(1))-,$(strip $(2)))
+ALL_PRE_PREP_TARGETS += $(addsuffix -pre-prep,$(addprefix $(strip $(1))-,$(strip $(2))))
+ALL_PREP_TARGETS += $(addsuffix -prep,$(addprefix $(strip $(1))-,$(strip $(2))))
+ALL_IP_UPGRADE_TARGETS += $(addsuffix -ip-upgrade,$(addprefix $(strip $(1))-,$(strip $(2))))
+ALL_GENERATE_DESIGN_TARGETS += $(addsuffix -generate-design,$(addprefix $(strip $(1))-,$(strip $(2))))
+ALL_PACKAGE_DESIGN_TARGETS += $(addsuffix -package-design,$(addprefix $(strip $(1))-,$(strip $(2))))
+ALL_BUILD_TARGETS += $(addsuffix -build,$(addprefix $(strip $(1))-,$(strip $(2))))
+ALL_SW_BUILD_TARGETS += $(addsuffix -sw-build,$(addprefix $(strip $(1))-,$(strip $(2))))
+ALL_TEST_TARGETS += $(addsuffix -test,$(addprefix $(strip $(1))-,$(strip $(2))))
+ALL_INSTALL_SOF_TARGETS += $(addsuffix -install-sof,$(addprefix $(strip $(1))-,$(strip $(2))))
+ALL_TARGET_ALL_NAMES += $(addsuffix -all,$(addprefix $(strip $(1))-,$(strip $(2))))
+
+
+$(strip $(1))-%-pre-prep : venv
+	$(MAKE) --no-print-directory -C $(strip $(1)) $$*-pre-prep
+
+$(strip $(1))-%-prep : venv
+	$(MAKE) --no-print-directory -C $(strip $(1)) $$*-prep
+
+$(strip $(1))-%-ip-upgrade : venv
+	$(MAKE) --no-print-directory -C $(strip $(1)) $$*-ip-upgrade
+
+$(strip $(1))-%-generate-design : venv
+	$(MAKE) --no-print-directory -C $(strip $(1)) $$*-generate-design
+
+$(strip $(1))-%-package-design :
+	$(MAKE) --no-print-directory -C $(strip $(1)) $$*-package-design INSTALL_ROOT=$(INSTALL_ROOT)/$(strip $(3))
+
+$(strip $(1))-%-build :
+	$(MAKE) --no-print-directory -C $(strip $(1)) $$*-build
+
+$(strip $(1))-%-sw-build :
+	$(MAKE) --no-print-directory -C $(strip $(1)) $$*-sw-build
+
+$(strip $(1))-%-test :
+	$(MAKE) --no-print-directory -C $(strip $(1)) $$*-test
+
+$(strip $(1))-%-install-sof :
+	$(MAKE) --no-print-directory -C $(strip $(1)) $$*-install-sof INSTALL_ROOT=$(INSTALL_ROOT)/$(strip $(3))
+
+.PHONY: $(addsuffix -all,$(addprefix $(strip $(1))-,$(strip $(2))))
+$(addsuffix -all,$(addprefix $(strip $(1))-,$(strip $(2)))): venv
+	$(MAKE) $(addsuffix -pre-prep,$(addprefix $(strip $(1))-,$(strip $(2))))
+	$(MAKE) $(addsuffix -generate-design,$(addprefix $(strip $(1))-,$(strip $(2))))
+	$(MAKE) $(addsuffix -package-design,$(addprefix $(strip $(1))-,$(strip $(2))))
+	$(MAKE) $(addsuffix -prep,$(addprefix $(strip $(1))-,$(strip $(2))))
+	$(MAKE) $(addsuffix -build,$(addprefix $(strip $(1))-,$(strip $(2))))
+	$(MAKE) $(addsuffix -sw-build,$(addprefix $(strip $(1))-,$(strip $(2))))
+	$(MAKE) $(addsuffix -test,$(addprefix $(strip $(1))-,$(strip $(2))))
+	$(MAKE) $(addsuffix -install-sof,$(addprefix $(strip $(1))-,$(strip $(2))))
+
+endef
+
+# Create rules for subdirs
+TARGET_SUBDIR := \
+	a3cw135-devkit-oobe
+
+# Create the subdir recipes by recurinsively calling the create_targets_on_subdir on each TARGET_SUBDIR
+define create_subdir_targets
+$(foreach target, $(shell make  --no-print-directory -q -C $(1) print-targets), $(eval $(call create_targets_on_subdir, $(1), $(target), designs)))
+endef
+$(foreach subdir,$(TARGET_SUBDIR),$(eval $(call create_subdir_targets,$(subdir))))
+
+###############################################################################
+#                          UTILITY TARGETS
+###############################################################################
+# Deep clean using git
+.PHONY: dev-clean
+dev-clean :
+	rm -rf $(INSTALL_ROOT) $(WORK_ROOT)
+	git clean -dfx --exclude=/.vscode --exclude=.lfsconfig
+
+# Using git
+.PHONY: dev-update
+dev-update :
+	git pull
+	git submodule update --init --recursive
+
+.PHONY: clean
+clean:
+	rm -rf $(INSTALL_ROOT) $(WORK_ROOT)
+	git clean -dfx --exclude=/.vscode --exclude=.lfsconfig --exclude=$(VENV_DIR)
+
+# Prep workspace
+venv:
+	$(PYTHON3) -m venv $(VENV_DIR)
+	$(VENV_PIP_INSTALL) --upgrade pip
+	$(VENV_PIP_INSTALL) -r requirements.txt
+
+
+.PHONY: venv-freeze
+venv-freeze:
+	$(VENV_PIP) freeze > requirements.txt
+	sed -i -e 's/==/~=/g' requirements.txt
+
+.PHONY: prepare-tools
+prepare-tools : venv
+
+# Include not_shipped Makefile if present
+-include not_shipped/Makefile.mk
+
+###############################################################################
+#                          Toplevel Targets
+###############################################################################
+.PHONY: pre-prep
+pre-prep: $(ALL_PRE_PREP_TARGETS)
+
+.PHONY: prep
+prep: $(ALL_PREP_TARGETS)
+
+.PHONY: ip-upgrade
+ip-upgrade: $(ALL_IP_UPGRADE_TARGETS)
+
+.PHONY: generate-designs
+generate-designs: $(ALL_GENERATE_DESIGN_TARGETS)
+
+.PHONY: package-designs
+package-designs: $(ALL_PACKAGE_DESIGN_TARGETS)
+
+# Build options
+.PHONY: build
+build: $(ALL_BUILD_TARGETS)
+
+# SW-Build options
+.PHONY: sw-build
+sw-build: $(ALL_SW_BUILD_TARGETS)
+
+# Run all tests
+.PHONY: test
+test : build
+
+.PHONY: install-sof
+install-sof: $(ALL_INSTALL_SOF_TARGETS)
+
+.PHONY: all
+all: $(ALL_TARGET_ALL_NAMES)
+
+###############################################################################
+#                                HELP
+###############################################################################
+.PHONY: help
+help:
+	$(info GHRD Build)
+	$(info ----------------)
+	$(info    All Targets             : $(ALL_TARGET_ALL_NAMES))
+	$(info    Stem names              : $(ALL_TARGET_STEM_NAMES))
+	$(info    Pre-Prep Targets        : $(ALL_PRE_PREP_TARGETS))
+	$(info    Prep Targets            : $(ALL_PREP_TARGETS))
+	$(info    Build Targets           : $(ALL_BUILD_TARGETS))
+	$(info    Test Targets            : $(ALL_TEST_TARGETS))
+	$(info    Package Targets 	      : $(ALL_PACKAGE_DESIGN_TARGETS))
+
diff --git a/README.md b/README.md
@@ -1,2 +1,91 @@
-# agilex3c-ed-gsrd
-Altera Agilex 3 C-series GSRD
+# Agilex 3 C-Series Golden Hardware Reference Design (GHRD)
+
+This repository contains Golden Hardware Reference Design (GHRD) for Agilex 3 C-Series System On Chip (SoC) FPGA.
+The GHRD is part of the Golden System Reference Design (GSRD), which provides a complete solution, including exercising soft IP in the fabric, booting to U-Boot, then Linux, and running sample Linux applications.
+Refer to the [Altera FPGA Developer Site](https://altera-fpga.github.io/latest/ed-demo-list/ed-list/) for information about GSRD.
+
+The [designs](#designs) are stored in individual folders. Each design can be opened, modified and compiled by using Quartus Prime software.
+GHRD releases are created for each version of Quartus Prime Software. It is recommended to use the release for your version of Quartus Prime.
+These reference designs demonstrate the system integration between Hard Processor System (HPS) and FPGA IPs.
+
+## Baseline feature
+This is applicable to all designs.
+- Hard Processor System (HPS) enablement and configuration
+  - Enable dual core Arm Cortex-A55 processor
+  - HPS Peripheral and I/O (SD/MMC, EMAC, MDIO, USB, I3C, JTAG, UART, and GPIO)
+  - HPS Clock and Reset
+  - HPS FPGA Bridge and Interrupt
+- HPS EMIF configuration (Inline ECC for LPDDR4 is enabled by default)
+- System integration with FPGA IPs
+  - Peripheral subsystem that consists of System ID, Programmable I/O (PIO) IP for controlling PushButton and LEDs.
+  - Debug subsystem that consists of JTAG-to-Avalon Master IP to allow System-Console debug activity and FPGA content access through JTAG
+  - 256KB of FPGA On-Chip Memory
+
+## The GHRD use cases:
+1. use the precompiled bitstream(sof) in release assets to programm the board.
+2. open and compile the [designs](#designs) with Quartus Prime.
+3. modify and compile the [designs](#designs) with Quartus Prime.
+
+## Dependency
+* Altera Quartus Prime 25.1.1
+* Supported Board
+  - Agilex 3 FPGA and SoC C-Series Development Kit: [Devkit User Guide](https://www.intel.com/content/www/us/en/docs/programmable/851698/current)
+  ![Agilex 3 FPGA and SoC C-Series Development Kit](images/agilex3_soc_devkit.png)
+
+## Tested Platform for the GHRD Build Flow
+* SUSE Linux Enterprise Server 15 SP4
+
+## Setup
+
+Several tools are required to be in the path.
+
+* Altera Quartus Prime 25.1.1
+* Python 3.11.5 (only required when using command line to build)
+
+### Example Setup for Altera Quartus Prime tools
+This is recommended, when using command line to build.
+```bash
+export QUARTUS_ROOTDIR=~/intelFPGA_pro/25.1.1/quartus
+```
+Note: Adapt the path above to where Quartus Prime is installed.
+
+```bash
+export PATH="$QUARTUS_ROOTDIR/bin:$QUARTUS_ROOTDIR/../qsys/bin:$QUARTUS_ROOTDIR/../niosv/bin:$QUARTUS_ROOTDIR/sopc_builder/bin:$QUARTUS_ROOTDIR/../questa_fe/bin:$QUARTUS_ROOTDIR/../syscon/bin:$QUARTUS_ROOTDIR/../riscfree/RiscFree:$PATH"'
+```
+
+## Quick start
+### Notes
+- Command line and Quartus GUI should not be used intertwined.
+- Mixing both might not generate some fileset correctly and fail the build.
+
+### using command line
+Copy and run the desired make command from [designs](#designs) in the root directory.
+After build, the design files (zip, sof and rbf) can be found in install/designs folder.
+
+### using Quartus GUI
+- Launch Quartus.
+- Open the project. Example: a3cw135-devkit-oobe/legacy-baseline/top.qpf
+- Click the play button to compile the design.
+- The compiled sof can be found in output_folders of the project path.
+
+## Designs
+
+### Agilex 3 FPGA and SoC C-Series Development Kit
+Refer to the individual readme for details of the design.
+
+* [a3cw135-devkit-oobe/legacy-baseline](a3cw135-devkit-oobe/legacy-baseline/README.md) :
+  Legacy baseline GHRD for the Agilex 3 FPGA and SoC C-Series Development Kit.
+```bash
+make a3cw135-devkit-oobe-legacy-baseline-legacy_baseline-all
+```
+
+## Install location:
+After build, the design files (zip, sof and rbf) can be found in install/designs folder.
+These files are also uploaded as github release assets.
+- \<design_name>**.zip**
+  - This is the archeived project files of the individual GHRD.
+- \<design_name>**.sof**
+  - Compiled bitstream. Can be programm on board.
+- \<design_name>**hps_debug.sof**
+  - This bitstream is injected with hps wipe program. This creates a wait loop to boot with arm debugger.
+  Refer [readme](a3cw135-devkit-oobe/legacy-baseline/software/hps_debug/README.md)
diff --git a/SECURITY.md b/SECURITY.md
@@ -0,0 +1,5 @@
+# Security Policy
+Altera is committed to the security of its products.
+
+## Reporting a Vulnerability
+Security vulnerabilities in this project can be reported to Altera’s security incident response team utilizing the guidelines here: https://www.altera.com/security/psirt.html.