[hec-assembler]: Complete format fixes on the Linker (#105)

Fix pylint/mypy on linker instructions
Add Copyright/License header
Change docstring style to Doxygen

Author: joserochh

assembler_tools/hec-assembler-tools/linker/instructions/cinst/__init__.py

@@ -1,8 +1,26 @@
-
-from . import bload, bones, cexit, cload, cnop, cstore, csyncm, ifetch, kgload, kgseed, kgstart, nload, xinstfetch
+# Copyright (C) 2025 Intel Corporation
+# SPDX-License-Identifier: Apache-2.0
 
-# MInst aliases
+"""@brief This module provides all the supported C-instructions for the linker toolchain."""
 
+from . import (
+    # Import all instruction modules
+    bload,
+    bones,
+    cexit,
+    cload,
+    cnop,
+    cstore,
+    csyncm,
+    ifetch,
+    kgload,
+    kgseed,
+    kgstart,
+    nload,
+    xinstfetch,
+)
+
+# CInst aliases
 BLoad = bload.Instruction
 BOnes = bones.Instruction
 CExit = cexit.Instruction
@@ -17,24 +35,25 @@
 NLoad = nload.Instruction
 XInstFetch = xinstfetch.Instruction
 
+
 def factory() -> set:
     """
-    Creates a set of all instruction classes.
+    @brief Creates a set of all instruction classes.
 
-    Returns:
-        set: A set containing all instruction classes.
+    @return A set containing all instruction classes.
     """
-
-    return { BLoad,
-             BOnes,
-             CExit,
-             CLoad,
-             CNop,
-             CStore,
-             CSyncm,
-             IFetch,
-             KGLoad,
-             KGSeed,
-             KGStart,
-             NLoad,
-             XInstFetch }
+    return {
+        BLoad,
+        BOnes,
+        CExit,
+        CLoad,
+        CNop,
+        CStore,
+        CSyncm,
+        IFetch,
+        KGLoad,
+        KGSeed,
+        KGStart,
+        NLoad,
+        XInstFetch,
+    }

assembler_tools/hec-assembler-tools/linker/instructions/cinst/bload.py

@@ -1,25 +1,30 @@
-from .cinstruction import CInstruction
+# Copyright (C) 2025 Intel Corporation
+# SPDX-License-Identifier: Apache-2.0
+
+"""@brief This module implements the bload C-instruction which loads from the SPAD to the register files."""
+
+from .cinstruction import CInstruction
+
 
 class Instruction(CInstruction):
     """
-    Encapsulates the `bload` CInstruction.
+    @brief Encapsulates a `bload` CInstruction.
 
     The `bload` instruction loads metadata from the scratchpad to special registers in the register file.
-    
+
     For more information, check the `bload` Specification:
         https://github.com/IntelLabs/hec-assembler-tools/blob/master/docsrc/inst_spec/cinst/cinst_bload.md
     """
 
     @classmethod
-    def _get_num_tokens(cls)->int:
+    def _get_num_tokens(cls) -> int:
         """
-        Gets the number of tokens required for the instruction.
+        @brief Gets the number of tokens required for the instruction.
 
         The `bload` instruction requires 5 tokens:
         <line: uint>, bload, <meta_target_idx: uint>, <spad_src: uint>, <src_col_num: uint>
 
-        Returns:
-            int: The number of tokens, which is 5.
+        @return The number of tokens, which is 5.
         """
         # 5 tokens:
         # <line: uint>, bload, <meta_target_idx: uint>, <spad_src: uint>, <src_col_num: uint>
@@ -30,31 +35,26 @@ def _get_num_tokens(cls)->int:
     @classmethod
     def _get_name(cls) -> str:
         """
-        Gets the name of the instruction.
+        @brief Gets the name of the instruction.
 
-        Returns:
-            str: The name of the instruction, which is "bload".
+        @return The name of the instruction, which is "bload".
         """
         return "bload"
 
     def __init__(self, tokens: list, comment: str = ""):
         """
-        Constructs a new `bload` CInstruction.
-
-        Args:
-            tokens (list): A list of tokens representing the instruction.
-            comment (str, optional): An optional comment for the instruction. Defaults to an empty string.
+        @brief Constructs a new `bload` CInstruction.
 
-        Raises:
-            ValueError: If the number of tokens is invalid or the instruction name is incorrect.
+        @param tokens A list of tokens representing the instruction.
+        @param comment An optional comment for the instruction.
+        @throws ValueError If the number of tokens is invalid or the instruction name is incorrect.
         """
         super().__init__(tokens, comment=comment)
 
-
     @property
     def source(self) -> str:
         """
-        Name of the source.
+        @brief Name of the source.
         This is a Variable name when loaded. Should be set to HBM address to write back.
         """
         return self.tokens[3]

assembler_tools/hec-assembler-tools/linker/instructions/cinst/bones.py

@@ -1,25 +1,30 @@
-from .cinstruction import CInstruction
+# Copyright (C) 2025 Intel Corporation
+# SPDX-License-Identifier: Apache-2.0
+
+"""@brief This module implements the bones C-instruction which loads a ones buffer from SPAD to registers."""
+
+from .cinstruction import CInstruction
+
 
 class Instruction(CInstruction):
     """
-    Encapsulates a `bones` CInstruction.
-    
+    @brief Encapsulates a `bones` CInstruction.
+
     The `bones` instruction loads metadata of identity (one) from the scratchpad to the register file.
-    
+
     For more information, check the `bones` Specification:
         https://github.com/IntelLabs/hec-assembler-tools/blob/master/docsrc/inst_spec/cinst/cinst_bones.md
     """
 
     @classmethod
-    def _get_num_tokens(cls)->int:
+    def _get_num_tokens(cls) -> int:
         """
-        Gets the number of tokens required for the instruction.
+        @brief Gets the number of tokens required for the instruction.
 
         The `bones` instruction requires 4 tokens:
         <line: uint>, bones, <spad_src: uint>, <col_num: uint>
 
-        Returns:
-            int: The number of tokens, which is 4.
+        @return The number of tokens, which is 4.
         """
         # 4 tokens:
         # <line: uint>, bones, <spad_src: uint>, <col_num: uint>
@@ -30,30 +35,26 @@ def _get_num_tokens(cls)->int:
     @classmethod
     def _get_name(cls) -> str:
         """
-        Gets the name of the instruction.
+        @brief Gets the name of the instruction.
 
-        Returns:
-            str: The name of the instruction, which is "bones".
+        @return The name of the instruction, which is "bones".
         """
         return "bones"
 
     def __init__(self, tokens: list, comment: str = ""):
         """
-        Constructs a new `bones` CInstruction.
-
-        Args:
-            tokens (list): A list of tokens representing the instruction.
-            comment (str, optional): An optional comment for the instruction. Defaults to an empty string.
+        @brief Constructs a new `bones` CInstruction.
 
-        Raises:
-            ValueError: If the number of tokens is invalid or the instruction name is incorrect.
+        @param tokens A list of tokens representing the instruction.
+        @param comment An optional comment for the instruction.
+        @throws ValueError If the number of tokens is invalid or the instruction name is incorrect.
         """
         super().__init__(tokens, comment=comment)
 
     @property
     def source(self) -> str:
         """
-        Name of the source.
+        @brief Name of the source.
         This is a Variable name when loaded. Should be set to HBM address to write back.
         """
         return self.tokens[2]

assembler_tools/hec-assembler-tools/linker/instructions/cinst/cexit.py

@@ -1,9 +1,15 @@
-from .cinstruction import CInstruction
+# Copyright (C) 2025 Intel Corporation
+# SPDX-License-Identifier: Apache-2.0
+
+"""@brief This module implements the cexit C-instruction which terminates the control flow execution."""
+
+from .cinstruction import CInstruction
+
 
 class Instruction(CInstruction):
     """
-    Encapsulates a `cexit` CInstruction.
-    
+    @brief Encapsulates a `cexit` CInstruction.
+
     This instruction terminates execution of a HERACLES program.
 
     For more information, check the `cexit` Specification:
@@ -13,35 +19,30 @@ class Instruction(CInstruction):
     @classmethod
     def _get_num_tokens(cls) -> int:
         """
-        Gets the number of tokens required for the instruction.
+        @brief Gets the number of tokens required for the instruction.
 
         The `cexit` instruction requires 2 tokens:
         <line: uint>, cexit
 
-        Returns:
-            int: The number of tokens, which is 2.
+        @return The number of tokens, which is 2.
         """
         return 2
 
     @classmethod
     def _get_name(cls) -> str:
         """
-        Gets the name of the instruction.
+        @brief Gets the name of the instruction.
 
-        Returns:
-            str: The name of the instruction, which is "cexit".
+        @return The name of the instruction, which is "cexit".
         """
         return "cexit"
 
     def __init__(self, tokens: list, comment: str = ""):
         """
-        Constructs a new `cexit` CInstruction.
-
-        Args:
-            tokens (list): A list of tokens representing the instruction.
-            comment (str, optional): An optional comment for the instruction. Defaults to an empty string.
+        @brief Constructs a new `cexit` CInstruction.
 
-        Raises:
-            ValueError: If the number of tokens is invalid or the instruction name is incorrect.
+        @param tokens A list of tokens representing the instruction.
+        @param comment An optional comment for the instruction.
+        @throws ValueError If the number of tokens is invalid or the instruction name is incorrect.
         """
-        super().__init__(tokens, comment=comment)
+        super().__init__(tokens, comment=comment)

assembler_tools/hec-assembler-tools/linker/instructions/cinst/cinstruction.py

@@ -1,45 +1,42 @@
 # Copyright (C) 2025 Intel Corporation
 # SPDX-License-Identifier: Apache-2.0
 
-"""This module implements the base class for CInstructions."""
+"""@brief This module implements the base class for all C-instructions."""
 
 from linker.instructions.instruction import BaseInstruction
 
 
 class CInstruction(BaseInstruction):
     """
-    Represents a CInstruction, inheriting from BaseInstruction.
+    @brief Represents a CInstruction, inheriting from BaseInstruction.
     """
 
     @classmethod
     def _get_name(cls) -> str:
         """
-        Derived classes should implement this method and return correct
-        name for the instruction.
+        @brief Returns the name of the instruction.
 
-        Raises:
-            NotImplementedError: Abstract method. This base method should not be called.
+        @return The instruction name.
+        @throws NotImplementedError Abstract method. This base method should not be called.
         """
         raise NotImplementedError()
 
     @classmethod
     def _get_name_token_index(cls) -> int:
         """
-        Gets the index of the token containing the name of the instruction.
+        @brief Gets the index of the token containing the name of the instruction.
 
-        Returns:
-            int: The index of the name token, which is 1.
+        @return The index of the name token.
         """
         return 1
 
     @classmethod
     def _get_num_tokens(cls) -> int:
         """
-        Derived classes should implement this method and return correct
-        required number of tokens for the instruction.
+        @brief Returns the required number of tokens for the instruction.
 
-        Raises:
-            NotImplementedError: Abstract method. This base method should not be called.
+        @return The number of required tokens.
+        @throws NotImplementedError Abstract method. This base method should not be called.
         """
         raise NotImplementedError()
 
@@ -48,14 +45,11 @@ def _get_num_tokens(cls) -> int:
 
     def __init__(self, tokens: list, comment: str = ""):
         """
-        Constructs a new CInstruction.
-
-        Parameters:
-            tokens (list): List of tokens for the instruction.
-            comment (str): Optional comment for the instruction.
+        @brief Constructs a new CInstruction.
 
-        Raises:
-            ValueError: If the number of tokens is invalid or the instruction name is incorrect.
+        @param tokens List of tokens for the instruction.
+        @param comment Optional comment for the instruction.
+        @throws ValueError If the number of tokens is invalid or the instruction name is incorrect.
         """
         super().__init__(tokens, comment=comment)