Sphinx Documentation and Deploymment

.github/workflows/docs.yml

@@ -0,0 +1,59 @@
+# Copyright 2024 ETH Zurich and University of Bologna.
+# Licensed under the Apache License, Version 2.0, see LICENSE for details.
+# SPDX-License-Identifier: Apache-2.0
+
+# Author: Philip Wiese <[email protected]>
+
+name: Sphinx Documentation
+
+on: [push, pull_request]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build and publish documentation
+    permissions:
+      contents: write
+      pages: write
+    runs-on: ubuntu-latest
+    steps:
+      - 
+        name: Checkout
+        uses: actions/[email protected]
+        with:
+          persist-credentials: false
+      - 
+        name: Install Dependencies 
+        run: |
+              sudo apt-get update && sudo apt-get install -y doxygen
+              python -m pip install --upgrade pip
+              pip install -r docs/requirements.txt
+      - 
+        name: Build HTML
+        run : |
+          cd docs
+          make html
+      -
+        name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: html-docs
+          path: docs/_build_sphinx/html
+      - 
+        name: Prepare Multipages
+        uses: rkdarst/gh-pages-multibranch@main
+        if: ${{ github.event_name == 'push' }}
+        with:
+          directory: docs/_build_sphinx/html
+      - 
+        name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.event_name == 'push' }}
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/_build_sphinx/html
+          force_orphan: true
+

.github/workflows/lint.yml

@@ -7,7 +7,7 @@
 
 name: lint
 
-on: [ push ]
+on: [ push, pull_request ]
 
 jobs:
 
@@ -51,3 +51,15 @@ jobs:
           AllowShortIfStatementsOnASingleLine: true,
           AllowShortLoopsOnASingleLine: true
           }
+
+  ling-py:
+    runs-on: ubuntu-latest
+    steps:
+    -
+      name: Checkout
+      uses: actions/checkout@v3
+    -
+      name: Check Python
+      uses: diegovalenzuelaiturra/yapf-action@master
+      with:
+        args: . --verbose --recursive --diff --parallel

.gitignore

@@ -3,3 +3,12 @@
 **/build/*
 
 .vscode/settings.json
+
+# Python
+.venv
+venv
+__pycache__
+
+# Documentation
+docs/_build
+docs/_autosummary

.yapfignore

@@ -0,0 +1,3 @@
+*third_party/
+*venv/
+*build*/

README.md

@@ -8,49 +8,16 @@ Chimera and Chimera-SDK are developed as part of the PULP project, a joint effor
 
 Unless specified otherwise in the respective file headers, all code checked into this repository is made available under a permissive license. All software sources are licensed under Apache 2.0 (see LICENSE) or compatible licenses, with the exception of `scripts/run_clang_format.py`, which is licensed under the MIT license.
 
-## Getting started
+## Documentation
+All revelevant documentation can be found in the `docs` folder and is hosted on GitHub Pages.
+Access the documentation on 
+- [Master Branch](https://pulp-platform.github.io/chimera-sdk/)
+- [Devel Branch](https://pulp-platform.github.io/chimera-sdk/branch/devel)
 
-If you are working on an IIS system, you can use the preinstalled SEPP packages to add the correct versions of the RISC-V toolchain and questasim into your path. If you use bash, you might run
-```
-riscv bash
-```
-
-If you are not on an IIS system, please ensure a RISC-V toolchain and questa installation are available in your path by checking that the output of
-```
-which riscv32-unknown-elf-gcc
-```
-is not empty.
-
-## LLVM Toolchain
-
-The applications are built using the RISC-V LLVM toolchain. On IIS systems, users can use the pre-installed LLVM version 12.0.1.
-
-Outside of IIS systems, you need to install LLVM version 12.0.1 or later to ensure compatibility. The exact command on IIS systems is:
-```
-cmake -DTARGET_PLATFORM=[YOURTARGETPLATFORM] -DTOOLCHAIN_DIR=/usr/pack/riscv-1.0-kgf/pulp-llvm-0.12.0/bin ..  && cmake --build .
-```
-
-The correct version of the toolchain can be verified by running
-```
-llvm-config --version
-```
-
-## Building the SDK
-
-To build the SDK and all tests contained in the SDK, run
-
-```
-mkdir build && cd build
-cmake -DTARGET_PLATFORM=[YOURTARGETPLATFORM]  ../
-cmake --build .
-```
-
-where you should replace `[YOURTARGETPLATFORM]` by one of the platforms defined in `targets/CMakeLists.txt` under `AVAILABLE_TARGETS`.
-
-The resulting binaries will be stored in `build/bin`, and can be used within the `chimera` repo as tests.
-
-## CXX Formatting
+The documentation for a specific branch can be accessed via `https://pulp-platform.github.io/chimera-sdk/branch/<branch>`
 
+## Contributing
+### CXX Formatting
 To format all source files, run
 ```
 python scripts/run_clang_format.py -ir hal/ targets/ tests/ drivers/
@@ -59,39 +26,11 @@ python scripts/run_clang_format.py -ir hal/ targets/ tests/ drivers/
 Our CI uses llvm-12 for clang-format, so on IIS machines you may run
 ```
 python scripts/run_clang_format.py -ir tests/ hal/ targets/ drivers/ --clang-format-executable=/usr/pack/riscv-1.0-kgf/pulp-llvm-0.12.0/bin/clang-format
-
 ```
 
-## Visual Studio Code Integration
-
-To enable automatic configuration of the C/C++ extension and support for the integrated cMake build flow on the IIS workstations, add the following content to `.vscode/settings.json`:
-```json
-{
-    "cmake.configureSettings": {
-        "TOOLCHAIN_DIR": "/usr/pack/riscv-1.0-kgf/pulp-llvm-0.12.0/bin",
-        "TARGET_PLATFORM": "chimera-convolve",
-    },
-    "cmake.environment": {
-        "PATH": "/usr/pack/riscv-1.0-kgf/default/bin:${env:PATH}",
-        "LD_LIBRARY_PATH": "/usr/pack/riscv-1.0-kgf/lib64:/usr/pack/riscv-1.0-kgf/lib64",
-    }
-}
+### Python Formatting
+To format all python files, run
+```bash
+python -m yapf -rip .
 ```
-If you are not on an IIS system, you need to adjust the paths according to your local installation.
-
-## Technical Details
-
-### Mixed ISA Compilation
-The current approach compiles all code for both the host and cluster cores into a single library. This requires precise handling to ensure compatibility between the different instruction set architectures (ISAs) and application binary interfaces (ABIs).
-This requires careful handling to avoid invalid instructions caused by mismatched ISAs between the host and cluster cores. Hence, we define four CMake variables,`ABI`, `ISA_HOST`, and `ISA_CLUSTER_SNITCH`, to specify the appropriate ISA for each core type. The ABI has to be identical to ensure correct function calls.
-Furthermore, the tests are split into `src_host` and `src_cluster` directories to clearly separate code executed on the host and cluster cores. 
-
-### cMake Build Flow
-All runtime functions executed by the host core are compiled into a dedicated `runtime_host` static library and the cluster code into `runtime_cluster_<type>` (e.g. `runtime_cluster_snitch`). Additionally, the HAL layer is compiled into the `hal_host` static libary.
-The final binary is seperated into two object libaries, one for the host and one for the cluster core. The host object library is linked with the `runtime_host` and `hal_host` libraries, while the cluster object library is linked with the `runtime_cluster_<type>` library. The final binary is then linked from the two object libraries.
-
-### Warning
-Special attention is required for functions that execute before the cluster core is fully initialized, such as the trampoline function and interrupt handlers. At this stage, critical resources like the stack, global pointer, and thread pointer are not yet configured. Consequently, the compiler must not generate code that allocates stack frames. To address this, such functions are implemented as naked functions, which prevent the compiler from adding prologues or epilogues that rely on stack operations.
-
-**It is recommended to always check the generated assembly code to ensure that the correct instructions are generated for the target core!**
 

cmake/Utils.cmake

@@ -32,7 +32,7 @@ endmacro()
 
 
 #[=======================================================================[.rst:
-.. command:: add_chimera_subdirectories(target_platform, category, mappings)
+.. cmake:command:: add_chimera_subdirectories(target_platform, category, mappings)
 
    Add subdirectories based on a mapping of target platforms to folders.
    The mappings are expected to be in the format ``target_platform:folder1,folder2,...``.
@@ -42,8 +42,8 @@ endmacro()
    :param mappings: A list of mappings from target platforms to folders. Make sure to wrap the list in quotes!
 
    .. code-block:: cmake
-      :caption Example Usage
-
+      :caption: Example Usage
+   
       set(MAPPINGS
           chimera-convolve:snitch_cluster
           chimera-open:snitch_cluster

devices/snitch_cluster/trampoline_snitchCluster.c

@@ -4,6 +4,10 @@
 //
 // Philip Wiese <[email protected]>
 
+/** \addtogroup devices_snitchCluster
+ *  @{
+ */
+
 #include <stdint.h>
 
 // Persistent trampoline function pointer for each core
@@ -56,3 +60,5 @@ void __attribute__((naked)) _trampoline() {
         "jr a1\n" // Jump and link to the function pointer in a1
     );
 }
+
+/** @}*/

docs/.gitignore

@@ -0,0 +1,4 @@
+
+# Documentation
+_build*
+_autosummary