treewide: Add Doxygen-generated docs (#189)

* docs: Set up Doxygen documentation

* snRuntime: Document fundamental modules

* ci: Install Doxygen in container and use for doc deployment

.github/workflows/publish-docs.yml

@@ -10,32 +10,19 @@ jobs:
   deploy:
     name: Deploy documentation
     runs-on: ubuntu-22.04
+    container:
+      image: ghcr.io/pulp-platform/snitch_cluster:main
     steps:
       - uses: actions/checkout@v2
-      - uses: actions/setup-python@v4
-        with:
-          python-version: "3.11"
-      - uses: mattnotmitt/doxygen-action@v1
-        with:
-          working-directory: sw/
-      - name: bender install
-        uses: pulp-platform/pulp-actions/bender-install@v2
-        with:
-          version: 0.27.1
-      - name: Install Python requirements
-        run: pip install -r python-requirements.txt
-      - name: Generate runtime documentation
-        # yamllint disable rule:line-length
+      # For some reason, the checkout is done by a different user,
+      # than that deploying to Github (root, possibly due to Docker).
+      # So we need to set the repository as a safe directory.
+      - name: Git config safe.directory
         run: |
-          mkdir doxybook2; cd doxybook2
-          wget https://github.com/matusnovak/doxybook2/releases/download/v1.4.0/doxybook2-linux-amd64-v1.4.0.zip
-          unzip doxybook2-linux-amd64-v1.4.0.zip; cd ../
-          chmod +x doxybook2/bin/doxybook2
-          mkdir docs/runtime
-          ./doxybook2/bin/doxybook2 --input sw/doxygen/xml --output docs/runtime --config docs/doxybook2.json
-          rm -rf doxybook2
-        # yamllint enable rule:line-length
+          git config --global --add safe.directory $GITHUB_WORKSPACE
       - name: Generate documentation sources
-        run: make doc-srcs
+        run: |
+          make doc-srcs
+          make doxygen-docs
       - name: Build and deploy documentation
         run: mkdocs gh-deploy --force

.gitignore

@@ -18,6 +18,7 @@ gmon.out
 # Docs
 /site/
 /docs/generated/
+/docs/doxygen/
 
 # Installation directories
 /.venv/

Makefile

@@ -49,23 +49,36 @@ clean-nonfree:
 # Docs #
 ########
 
-GENERATED_DOCS_DIR = docs/generated
+DOCS_DIR = docs
+
+GENERATED_DOCS_DIR = $(DOCS_DIR)/generated
 GENERATED_DOC_SRCS = $(GENERATED_DOCS_DIR)/peripherals.md
 
+DOXYGEN_DOCS_DIR = $(DOCS_DIR)/doxygen
+DOXYGEN_INPUTS   = $(DOCS_DIR)/rm/snRuntime.md
+DOXYGEN_INPUTS  += $(shell find sw/snRuntime -name '*.c' -o -name '*.h')
+DOXYFILE         = $(DOCS_DIR)/Doxyfile
+
 all: docs
 clean: clean-docs
-.PHONY: doc-srcs docs clean-docs
+.PHONY: doc-srcs doxygen-docs docs clean-docs
 
 doc-srcs: $(GENERATED_DOC_SRCS)
 
-docs: doc-srcs
+doxygen-docs: $(DOXYGEN_DOCS_DIR)
+
+docs: doc-srcs doxygen-docs
 	mkdocs build
 
 clean-docs:
 	rm -rf $(GENERATED_DOCS_DIR)
+	rm -rf $(DOXYGEN_DOCS_DIR)
 
 $(GENERATED_DOCS_DIR):
 	mkdir -p $@
 
 $(GENERATED_DOCS_DIR)/peripherals.md: hw/snitch_cluster/src/snitch_cluster_peripheral/snitch_cluster_peripheral_reg.hjson | $(GENERATED_DOCS_DIR)
 	$(REGGEN) -d $< > $@
+
+$(DOXYGEN_DOCS_DIR): $(DOXYFILE) $(DOXYGEN_INPUTS)
+	doxygen $<

docs/Doxyfile

@@ -0,0 +1,11 @@
+PROJECT_NAME = "Snitch Runtime"
+INPUT = docs/rm/snRuntime.md sw/snRuntime
+RECURSIVE = YES
+FILE_PATTERNS = *.h *.c
+OUTPUT_DIRECTORY = docs/doxygen/
+USE_MDFILE_AS_MAINPAGE = docs/rm/snRuntime.md
+GENERATE_LATEX = NO
+ENABLE_PREPROCESSING = YES
+MACRO_EXPANSION = YES
+EXPAND_ONLY_PREDEF = YES
+PREDEFINED = __attribute__(x)=

docs/rm/snRuntime.md

@@ -0,0 +1 @@
+These pages host the documentation for the Snitch runtime, a set of runtime and library functions to make writing parallel and efficient C code for Snitch easier.

mkdocs.yml

@@ -77,11 +77,5 @@ nav:
           - Snitch Target Utilities:
               - run.py: rm/snitch_target_utils/run.md
               - build.py: rm/snitch_target_utils/build.md
-          - Snitch Runtime:
-              - Pages: runtime/Pages/index.md
-              - Files: runtime/Files/index.md
-              - Classes: runtime/Classes/index.md
-              - Examples: runtime/Examples/index.md
-              - Modules: runtime/Modules/index.md
-              - Namespaces: runtime/Namespaces/index.md
+          - Snitch Runtime: doxygen/html/index.html
   - Publications: publications.md

sw/snRuntime/src/alloc_v2.h

@@ -2,29 +2,61 @@
 // Licensed under the Apache License, Version 2.0, see LICENSE for details.
 // SPDX-License-Identifier: Apache-2.0
 
+/**
+ * @file
+ * @brief Defines functions to dynamically allocate the cluster's L1 memory.
+ *
+ * This file provides functions to dynamically allocate the cluster's L1
+ * memory. It includes functions for allocating memory for cluster-local
+ * variables, compute core-local variables, and for manipulating pointers to
+ * variables allocated by different cores or clusters.
+ */
+
 extern __thread snrt_allocator_t l1_allocator_v2;
 
+/**
+ * @brief Get a pointer to the L1 allocator.
+ *
+ * @return Pointer to the L1 allocator.
+ */
 inline snrt_allocator_t *snrt_l1_allocator_v2() { return &l1_allocator_v2; }
 
+/**
+ * @brief Get the next pointer of the L1 allocator.
+ *
+ * @return The next pointer of the L1 allocator.
+ */
 inline void *snrt_l1_next_v2() { return (void *)snrt_l1_allocator_v2()->next; }
 
 /**
- * @brief Override the L1 allocator next pointer
+ * @brief Override the L1 allocator next pointer.
+ *
+ * @param next The new value for the next pointer.
  */
 inline void snrt_l1_update_next_v2(void *next) {
     snrt_l1_allocator_v2()->next = (uint32_t)next;
 }
 
-// Check that allocation doesn't exceed allocator bounds, and raise an
-// exception otherwise
+/**
+ * @brief Check if the allocation exceeds the allocator bounds and raise an
+ *        exception if it does.
+ */
 inline void snrt_l1_alloc_check_bounds() {
     if (snrt_l1_allocator_v2()->next > snrt_l1_allocator_v2()->end)
         asm volatile("ecall \n");
 }
 
-// Dynamically allocate space for a variable of size `size` in the cluster's L1
-// memory. This function should be invoked by every core in a cluster. Every
-// core receives a pointer to the allocated variable.
+/**
+ * @brief Allocate space for a variable in the cluster's L1 memory.
+ *
+ * This function dynamically allocates space for a variable of size `size` in
+ * the cluster's L1 memory.
+ * The allocation is aligned to the specified `alignment`.
+ *
+ * @param size The size of the variable to allocate.
+ * @param alignment The alignment of the allocation.
+ * @return Pointer to the allocated variable.
+ */
 inline void *snrt_l1_alloc_cluster_local(size_t size, const size_t alignment) {
     snrt_l1_allocator_v2()->next =
         ALIGN_UP(snrt_l1_allocator_v2()->next, alignment);
@@ -34,11 +66,19 @@ inline void *snrt_l1_alloc_cluster_local(size_t size, const size_t alignment) {
     return retval;
 }
 
-// Dynamically allocate space for N variables of size `size` in the cluster's
-// L1 memory, N being the number of compute cores in the cluster. This function
-// should be invoked by every core in a cluster. Every compute core receives a
-// pointer to a unique variable among the N which have been allocated. The
-// return value for the DM core is undefined.
+/**
+ * @brief Allocate space for N variables in the cluster's L1 memory.
+ *
+ * This function dynamically allocates space for N variables of size `size` in
+ * the cluster's L1 memory, where N is the number of compute cores in the
+ * cluster. The variables are allocated in a contiguous block of memory.
+ * The whole block is aligned to the specified `alignment`.
+ *
+ * @param size The size of each variable to allocate.
+ * @param alignment The alignment of the allocation.
+ * @return Pointer to the allocated variable for each compute core.
+ *         The return value for the DM core is undefined.
+ */
 inline void *snrt_l1_alloc_compute_core_local(size_t size,
                                               const size_t alignment) {
     snrt_l1_allocator_v2()->next =
@@ -49,24 +89,52 @@ inline void *snrt_l1_alloc_compute_core_local(size_t size,
     return retval;
 }
 
-// Takes a pointer to a variable allocated using
-// `snrt_l1_alloc_compute_core_local` and returns a pointer to the same
-// variable allocated by another core, as specified by `core_idx`.
-// The `size` argument should be the same used during allocation.
+/**
+ * @brief Get a pointer to the same variable allocated by another core.
+ *
+ * This function takes a pointer to a variable allocated using
+ * `snrt_l1_alloc_compute_core_local` and returns a pointer to the same
+ * variable allocated by another core, as specified by `core_idx`.
+ * The `size` argument should be the same used during allocation.
+ *
+ * @param ptr Pointer to the variable allocated by the current core.
+ * @param core_idx Index of the core that allocated the variable.
+ * @param size The size of the variable.
+ * @return Pointer to the same variable allocated by the specified core.
+ */
 inline void *snrt_compute_core_local_ptr(void *ptr, uint32_t core_idx,
                                          size_t size) {
     size_t offset = (core_idx - snrt_cluster_core_idx()) * size;
     return (void *)((uintptr_t)ptr + offset);
 }
 
-// Takes a pointer to a variable in the source cluster's L1 memory and returns
-// a pointer to the same offset in the destination cluster's L1 memory.
+/**
+ * @brief Get a pointer to the same offset in another cluster's L1 memory.
+ *
+ * This function takes a pointer to a variable in the calling (source)
+ * cluster's L1 memory and returns a pointer to the same offset in the target
+ * (destination) cluster's L1 memory.
+ *
+ * @param ptr Pointer to the variable in the source cluster's L1 memory.
+ * @param src_cluster_idx Index of the source cluster.
+ * @param dst_cluster_idx Index of the destination cluster.
+ * @return Pointer to the same offset in the destination cluster's L1 memory.
+ */
 inline void *snrt_remote_l1_ptr(void *ptr, uint32_t src_cluster_idx,
                                 uint32_t dst_cluster_idx) {
     return (void *)((uintptr_t)ptr +
                     (dst_cluster_idx - src_cluster_idx) * SNRT_CLUSTER_OFFSET);
 }
 
+/**
+ * @brief Initialize the L1 allocator.
+ *
+ * This function initializes the L1 allocator by calculating the end address
+ * of the heap and setting the base, end, and next pointers of the allocator.
+ *
+ * @note This function should be called before using any of the allocation
+ *       functions.
+ */
 inline void snrt_alloc_init_v2() {
     // Calculate end address of the heap. The top of the TCDM address space is
     // reserved for the cluster-local storage (CLS) and the stack of every