Merge branch 'dev' into feature_arm_thumb

src/copapy/_basic_types.py

@@ -429,8 +429,8 @@ class Op(Node):
     def __hash__(self) -> int:
         return self.node_hash
 
-# Interface for vector and tensor types
 class ArrayType(Generic[TNum]):
+    """Interface for vector and tensor types."""
     def __init__(self, shape: tuple[int, ...]) -> None:
         self.shape = shape
         self.values: tuple[TNum | value[TNum], ...] = ()

src/copapy/_compiler.py

@@ -134,7 +134,7 @@ def get_const_nets(nodes: list[Node]) -> list[Net]:
 
 
 def add_load_ops(node_list: list[Node]) -> Generator[tuple[Net | None, Node], None, None]:
-    """Add read node before each op where arguments are not already positioned
+    """Add load/read node before each op where arguments are not already positioned
     correctly in the registers
 
     Arguments:
@@ -172,7 +172,7 @@ def add_load_ops(node_list: list[Node]) -> Generator[tuple[Net | None, Node], No
 
 
 def add_store_ops(net_node_list: list[tuple[Net | None, Node]], const_nets: list[Net]) -> Generator[tuple[Net | None, Node], None, None]:
-    """Add write operation for each new defined net if a read operation is later followed
+    """Add store/write operation for each new defined net if a read operation is later followed
 
     Returns:
         Yields tuples of a net and a node. The associated net is provided for read and write nodes.

src/copapy/_stencils.py

@@ -33,11 +33,14 @@ class relocation_entry:
 @dataclass
 class patch_entry:
     """
-    A dataclass for representing a relocation entry
+    A dataclass for representing a patch entry
 
     Attributes:
-        addr (int): address of first byte to patch relative to the start of the symbol
+        mask (int): Bit-mask to apply to the patched value
-        type (RelocationType): relocation type
+        address (int): Address where to patch
+        value (int): The value to write at the patch address
+        scale (int): The scale factor for the patch value
+        patch_type (int): The type of patch
     """
     mask: int
     address: int
@@ -47,6 +50,10 @@ class patch_entry:
 
 
 def detect_process_arch() -> str:
+    """For running the code locally in the python module
+    the architecture of the current process is detected
+    by this function to load the correct stencil database.
+    """
     cp_target_arch = os.environ.get("CP_TARGET_ARCH")
     if cp_target_arch:
         return cp_target_arch

src/coparun/coparun.c

@@ -1,3 +1,15 @@
+/*
+ * file: coparun.c
+ * Description: This file alows to run copapy programs in the command line
+ * reading copapy data, code and patch instructions from a file and jump to the
+ * entry point to execute it or dump the patched code memory for debugging to a file.
+ * 
+ * It's intended for testing and debugging purposes, to run copapy programs in a
+ * debugger or emulator like qemu.
+ * 
+ * Usage: coparun <code_file> [memory_dump_file]
+ */
+
 #include <stdio.h>
 #include <stdlib.h>
 #include "runmem.h"

src/coparun/coparun_module.c

@@ -1,3 +1,10 @@
+/*
+ * file: coparun_module.c
+ * Description: This file defines a Python C extension module that provides an
+ * interface to the core functions of the coparun runner, to run copapy programs
+ * directly local in Python.
+ */ 
+
 #define PY_SSIZE_T_CLEAN
 #include <Python.h>
 #include "runmem.h"

src/coparun/mem_man.c

@@ -1,3 +1,11 @@
+/*
+ * file: mem_man.c
+ * Description: This file contains memory management functions for the coparun
+ * runner, including allocation and deallocation of executable and data memory.
+ * Depending of the target operating system or bare metal environment, it
+ * handles memory management accordingly.
+*/
+
 #include <stdio.h>
 #include <stdint.h>
 #include <stdlib.h>

src/coparun/runmem.c

@@ -1,3 +1,10 @@
+/*
+ * file: runmem.c
+ * Description: This file contain the core functions of the runner
+ * to receive data, code and patch instruction, does the patching
+ * and jumps to the entry point of the copapy program
+ */
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>

src/coparun/runmem.h

@@ -1,3 +1,10 @@
+/**
+ * @file runmem.h
+ * @brief Header file for runmem.c, which contains core functions of
+ * the runner to receive data, code and patch instructions, perform
+ * patching, and jump to the entry point of the copapy program.
+ */
+
 #ifndef RUNMEM_H
 #define RUNMEM_H