From 6a9bbe36bf608681993eb5d6ace0f895322ac5fd Mon Sep 17 00:00:00 2001
From: Cyril Koenig <47349427+CyrilKoe@users.noreply.github.com>
Date: Mon, 3 Feb 2025 13:23:07 +0100
Subject: [PATCH] Ck/carfield docs (#3)
* docs: Add requirements.txt
* docs: Add more in Getting Started
* sw.mk: Update variable name
* doc: Prepare PR
---
.github/workflows/publish-docs.yml | 2 +-
docs/gs.md | 94 ++++++++++++++++++++++++++++--
docs/img/arch.svg | 4 --
docs/img/clk_rst.svg | 4 --
docs/img/isolation.svg | 4 --
docs/platforms/carfield.md | 6 +-
docs/platforms/milkv.md | 2 -
docs/platforms/occamy.md | 2 +-
docs/software/index.md | 6 +-
mkdocs.yml | 7 +--
requirements.txt | 3 +
sw/sw.mk | 4 +-
12 files changed, 106 insertions(+), 32 deletions(-)
delete mode 100644 docs/img/arch.svg
delete mode 100644 docs/img/clk_rst.svg
delete mode 100644 docs/img/isolation.svg
create mode 100644 requirements.txt
diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml
index 0d0ecf2..40ef51a 100644
--- a/.github/workflows/publish-docs.yml
+++ b/.github/workflows/publish-docs.yml
@@ -20,7 +20,7 @@ jobs:
name: Checkout
uses: actions/checkout@v3
with:
- submodules: recursive
+ submodules: false
-
name: Install Python
uses: actions/setup-python@v2
diff --git a/docs/gs.md b/docs/gs.md
index 5d8f4d2..079385b 100644
--- a/docs/gs.md
+++ b/docs/gs.md
@@ -87,15 +87,97 @@ This will create multiple files in `cva6-sdk/install64` including:
- vmlinux: An intermediate result of the uImage, this can be used to obtain debug symbols
-## Building the runtimes for Linux
-The command below will compile the libhero (bridging between the hardware drivers and the OpenMP runtime), the libllvm (required for the OpenMP target runtime), and the the OpenMP target host runtime itself.
-All these libraries are compiled for the host (RV64) using the GCC compiler previously built.
+## Buiding the host software
+
+From now, you will need to select a platform to continue with, the platform is decided by the following variables:
+- HERO_HOST can be
+ - cva6
+ - sg2042
+- HERO_DEVICE can be
+ - occamy_snitch_cluster
+ - carfield_snitch_cluster
+ - carfield_spatz_cluster
+ - carfield_safety_island
+
+### Building the Linux kernel module
+
+The kernel modules are located in `sw/hero-driver`. The modules are shared for a platform. For instance, Carfield has a unique module that maps every island. If any island is not actually on-chip (on-FPGA) it will detect it and won't map it.
+
+To build a kernel module do:
+
+```bash
+# Make sure that you have BR_LINUX_DIR set, otherwise re-source setenv.sh
+source scripts/setenv.sh
+echo $BR_LINUX_DIR
+
+# Go the the module's source and compile it
+cd sw/hero-driver/carfield
+make
+
+# Now you can copy your module into your Linux image rootfs
+cp *.ko $HERO_ROOT/cva6-sdk/rootfs/root/
+
+```
+
+__Note:__ Everytime your change the rootfs, you must update the Linux image like so:
+
+```bash
+cd $HERO_ROOT/cva6-sdk
+make clean images
+# Your new image is in install64/uImage
+```
+
+
+### Building the runtimes for the host
+
+Now that you have the kernel module, you will need to build the host libraries that allow offloading.
+- libhero: It bridges between the hardware drivers and the OpenMP runtime. You can find its code in `sw/libhero`,
+- libomp: The OpenMP runtime. It is built in `sw/libomp` but its sources are in `toolchain/llvm-project/openmp`
+- libllvm: Auxiliaries libraries needed by the OpenMP runtime. It is built in `sw/libllvm`. You can find its code in `toolchain/llvm-project/llvm`
+
+All these libraries are compiled for the host (RV64) using the GCC compiler you previously built.
+
+You can compile all at once:
+
+```bash
+make HERO_HOST=[host] HERO_DEVICE=[device] hero-sw-all
+```
+
+Similarly, you can deploy the libraries to the `rootfs`:
+
+```bash
+make HERO_HOST=[host] HERO_DEVICE=[device] hero-sw-all hero-sw-deploy
+# Now you need to rebuild your Linux image
+```
+
+## Buiding the device software
+
+The device software does not reside in this repository but directly with the hardware.
+To build the device library, this repo will the hardware repos based on `platforms/platforms.mk`.
+
+For instance, you can build the device software for Carfield Snitch using
```bash
-make HERO_HOST=cva6 HERO_DEVICE=[platform] hero-sw-all
+make hero-carfield-snitch-sw-all
```
-## Start your platform on an FPGA
+Go to [Targets](platforms/index.md) for more informations.
+
+## Building the application
+
+Since now, you have built:
-Go to [Targets](platforms/index.md) and pick the architecture you want to use.
+- The GCC compiler for CVA6
+- The Linux image for CVA6
+- The kernel module to map the system's address map
+- The host libraries (libllvm, libomp, libhero)
+- The device library
+
+You can go and build an example application in `apps`.
+
+```bash
+cd apps/omp/basic/offload_benchmark
+# Attention to add the "all"
+make HERO_HOST=cva6 HERO_DEVICE=carfield_snitch_cluster all
+```
diff --git a/docs/img/arch.svg b/docs/img/arch.svg
deleted file mode 100644
index a1a7ee4..0000000
--- a/docs/img/arch.svg
+++ /dev/null
@@ -1,4 +0,0 @@
-
-
-
-
\ No newline at end of file
diff --git a/docs/img/clk_rst.svg b/docs/img/clk_rst.svg
deleted file mode 100644
index 4d2f4fb..0000000
--- a/docs/img/clk_rst.svg
+++ /dev/null
@@ -1,4 +0,0 @@
-
-
-
-
\ No newline at end of file
diff --git a/docs/img/isolation.svg b/docs/img/isolation.svg
deleted file mode 100644
index 50989f6..0000000
--- a/docs/img/isolation.svg
+++ /dev/null
@@ -1,4 +0,0 @@
-
-
-
-
\ No newline at end of file
diff --git a/docs/platforms/carfield.md b/docs/platforms/carfield.md
index b4ab96f..da23b6c 100644
--- a/docs/platforms/carfield.md
+++ b/docs/platforms/carfield.md
@@ -2,8 +2,8 @@
## Platform
-...
+Carfield is a mixed-criticality platform built around Cheshire, with a number of safety/security and predictability features. You can find more informations on the [Github Repository](https://github.com/pulp-platform/carfield).
-## Get started
+## Tood
-...
+For now please follow Getting Started to build an application for Carfield.
\ No newline at end of file
diff --git a/docs/platforms/milkv.md b/docs/platforms/milkv.md
index 0f7af2c..a7d7d5e 100644
--- a/docs/platforms/milkv.md
+++ b/docs/platforms/milkv.md
@@ -2,8 +2,6 @@
## Platform
-...
-
The SG2042 can be used as an host to your PCIe accelerator. In this configuration CVA6 stays dormant, and SG2042 interracts with the accelerator directly.
## Get started
diff --git a/docs/platforms/occamy.md b/docs/platforms/occamy.md
index 429b106..253ea34 100644
--- a/docs/platforms/occamy.md
+++ b/docs/platforms/occamy.md
@@ -2,7 +2,7 @@
## Platform
-...
+Occamy is a high-efficiency system-on-chip for floating-point compute workloads. You can find more informations on the [Github Repository](https://github.com/pulp-platform/occamy).
## Get started
diff --git a/docs/software/index.md b/docs/software/index.md
index a4e6f76..26917e5 100644
--- a/docs/software/index.md
+++ b/docs/software/index.md
@@ -1,3 +1,7 @@
# HeroSDK software
-Todo
+## The Hero driver (sw/hero-driver)
+
+## The Hero library (sw/libhero)
+
+## The OpenMP library (sw/libllvm and sw/libomp)
diff --git a/mkdocs.yml b/mkdocs.yml
index 2697ca4..f8a2a21 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -5,10 +5,9 @@
# Cyril Koenig
site_name: Hero-Tools
-site_dir: public
theme:
- name: readthedocs
+ name: material
icon:
repo: fontawesome/brands/github
features:
@@ -18,8 +17,8 @@ theme:
- navigation.indexes
- navigation.footer
-repo_url: https://iis-git.ee.ethz.ch/hero/hero-tools/
-repo_name: hero-tools
+repo_url: https://github.com/pulp-platform/hero-tools
+repo_name: pulp-platform/hero-tools
nav:
- Home:
diff --git a/requirements.txt b/requirements.txt
new file mode 100644
index 0000000..973b2f8
--- /dev/null
+++ b/requirements.txt
@@ -0,0 +1,3 @@
+mkdocs
+mkdocs-material
+mkdocs-glightbox
diff --git a/sw/sw.mk b/sw/sw.mk
index 95f575c..c6c9a5f 100644
--- a/sw/sw.mk
+++ b/sw/sw.mk
@@ -21,11 +21,11 @@ $(HERO_SW_DIR)/libllvm/lib/libLLVMSupport.a:
# Compile libhero-[device] layer
$(HERO_SW_DIR)/libhero/lib/libhero_%.so:
- make HOST=$(HERO_HOST) PLATFORM=$* -C $(HERO_SW_DIR)/libhero
+ make HERO_HOST=$(HERO_HOST) HERO_DEVICE=$* -C $(HERO_SW_DIR)/libhero all
# Compile libomp/libomptarget for rv64 and a specific libomptarget-hero-[device] runtime
$(HERO_SW_DIR)/libomp/lib/libomptarget.rtl.herodev_%.so: $(HERO_SW_DIR)/libllvm/lib/libLLVMSupport.a $(HERO_SW_DIR)/libhero/lib/libhero_%.so
- make HOST=$(HERO_HOST) PLATFORM=$* -C $(HERO_SW_DIR)/libomp
+ make HERO_HOST=$(HERO_HOST) HERO_DEVICE=$* -C $(HERO_SW_DIR)/libomp
#############
# Device SW #