diff --git a/assembler_tools/hec-assembler-tools/linker/instructions/cinst/__init__.py b/assembler_tools/hec-assembler-tools/linker/instructions/cinst/__init__.py index 850a5c14..9d1ab03c 100644 --- a/assembler_tools/hec-assembler-tools/linker/instructions/cinst/__init__.py +++ b/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, + } diff --git a/assembler_tools/hec-assembler-tools/linker/instructions/cinst/bload.py b/assembler_tools/hec-assembler-tools/linker/instructions/cinst/bload.py index 2fc070bd..ee7521f4 100644 --- a/assembler_tools/hec-assembler-tools/linker/instructions/cinst/bload.py +++ b/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: , bload, , , - Returns: - int: The number of tokens, which is 5. + @return The number of tokens, which is 5. """ # 5 tokens: # , bload, , , @@ -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] diff --git a/assembler_tools/hec-assembler-tools/linker/instructions/cinst/bones.py b/assembler_tools/hec-assembler-tools/linker/instructions/cinst/bones.py index e2459f21..a0e34fa6 100644 --- a/assembler_tools/hec-assembler-tools/linker/instructions/cinst/bones.py +++ b/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: , bones, , - Returns: - int: The number of tokens, which is 4. + @return The number of tokens, which is 4. """ # 4 tokens: # , bones, , @@ -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] diff --git a/assembler_tools/hec-assembler-tools/linker/instructions/cinst/cexit.py b/assembler_tools/hec-assembler-tools/linker/instructions/cinst/cexit.py index 23137724..79cd7fca 100644 --- a/assembler_tools/hec-assembler-tools/linker/instructions/cinst/cexit.py +++ b/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: , 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) \ No newline at end of file + super().__init__(tokens, comment=comment) diff --git a/assembler_tools/hec-assembler-tools/linker/instructions/cinst/cinstruction.py b/assembler_tools/hec-assembler-tools/linker/instructions/cinst/cinstruction.py index 81df3417..a0a8ccf0 100644 --- a/assembler_tools/hec-assembler-tools/linker/instructions/cinst/cinstruction.py +++ b/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) diff --git a/assembler_tools/hec-assembler-tools/linker/instructions/cinst/cload.py b/assembler_tools/hec-assembler-tools/linker/instructions/cinst/cload.py index 41218a24..f17f0909 100644 --- a/assembler_tools/hec-assembler-tools/linker/instructions/cinst/cload.py +++ b/assembler_tools/hec-assembler-tools/linker/instructions/cinst/cload.py @@ -1,8 +1,14 @@ -from .cinstruction import CInstruction +# Copyright (C) 2025 Intel Corporation +# SPDX-License-Identifier: Apache-2.0 + +"""@brief This module implements the cload C-instruction which loads data from SPAD to registers.""" + +from .cinstruction import CInstruction + class Instruction(CInstruction): """ - Encapsulates a `cload` CInstruction. + @brief Encapsulates a `cload` CInstruction. This instruction loads a single polynomial residue from scratchpad into a register. @@ -11,15 +17,14 @@ class Instruction(CInstruction): """ @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 `cload` instruction requires 4 tokens: , cload, , - Returns: - int: The number of tokens, which is 4. + @return The number of tokens, which is 4. """ # 4 tokens: # , cload, , @@ -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 "cload". + @return The name of the instruction, which is "cload". """ return "cload" def __init__(self, tokens: list, comment: str = ""): """ - Constructs a new `cload` 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 `cload` 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] diff --git a/assembler_tools/hec-assembler-tools/linker/instructions/cinst/cnop.py b/assembler_tools/hec-assembler-tools/linker/instructions/cinst/cnop.py index 266b719b..86756b09 100644 --- a/assembler_tools/hec-assembler-tools/linker/instructions/cinst/cnop.py +++ b/assembler_tools/hec-assembler-tools/linker/instructions/cinst/cnop.py @@ -1,8 +1,14 @@ -from .cinstruction import CInstruction +# Copyright (C) 2025 Intel Corporation +# SPDX-License-Identifier: Apache-2.0 + +"""@brief This module implements the cnop C-instruction which adds idle cycles to the control flow.""" + +from .cinstruction import CInstruction + class Instruction(CInstruction): """ - Encapsulates a `cnop` CInstruction. + @brief Encapsulates a `cnop` CInstruction. This instruction adds a desired amount of idle cycles in the Cfetch flow. @@ -16,60 +22,51 @@ 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 `cnop` instruction requires 3 tokens: , cnop, - Returns: - int: The number of tokens, which is 3. + @return The number of tokens, which is 3. """ return 3 @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 "cnop". + @return The name of the instruction, which is "cnop". """ return "cnop" def __init__(self, tokens: list, comment: str = ""): """ - Constructs a new `cnop` CInstruction. + @brief Constructs a new `cnop` 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. - - 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 cycles(self) -> int: """ - Gets the number of idle cycles. + @brief Gets the number of idle cycles. - Returns: - int: The number of idle cycles. + @return The number of idle cycles. """ return int(self.tokens[2]) @cycles.setter def cycles(self, value: int): """ - Sets the number of idle cycles. - - Args: - value (int): The number of idle cycles to set. + @brief Sets the number of idle cycles. - Raises: - ValueError: If the value is negative. + @param value The number of idle cycles to set. + @throws ValueError If the value is negative. """ if value < 0: - raise ValueError(f'`value` must be non-negative, but {value} received.') - self.tokens[2] = str(value) \ No newline at end of file + raise ValueError(f"`value` must be non-negative, but {value} received.") + self.tokens[2] = str(value) diff --git a/assembler_tools/hec-assembler-tools/linker/instructions/cinst/cstore.py b/assembler_tools/hec-assembler-tools/linker/instructions/cinst/cstore.py index a95abad6..d8d34077 100644 --- a/assembler_tools/hec-assembler-tools/linker/instructions/cinst/cstore.py +++ b/assembler_tools/hec-assembler-tools/linker/instructions/cinst/cstore.py @@ -1,8 +1,14 @@ -from .cinstruction import CInstruction +# Copyright (C) 2025 Intel Corporation +# SPDX-License-Identifier: Apache-2.0 + +"""@brief This module implements the cstore C-instruction which stores data to SPAD.""" + +from .cinstruction import CInstruction + class Instruction(CInstruction): """ - Encapsulates a `cstore` CInstruction. + @brief Encapsulates a `cstore` CInstruction. This instruction fetches a single polynomial residue from the intermediate data buffer and stores it back to SPAD. @@ -11,15 +17,14 @@ class Instruction(CInstruction): """ @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 `cstore` instruction requires 3 tokens: , cstore, - Returns: - int: The number of tokens, which is 3. + @return The number of tokens, which is 3. """ # 3 tokens: # , cstore, @@ -30,34 +35,37 @@ 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 "cstore". + @return The name of the instruction, which is "cstore". """ return "cstore" def __init__(self, tokens: list, comment: str = ""): """ - Constructs a new `cstore` 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 `cstore` 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 dest(self) -> str: """ - Name of the destination. + @brief Name of the destination. This is a Variable name when loaded. Should be set to HBM address to write back. + + @return The destination variable name or address. """ return self.tokens[2] @dest.setter def dest(self, value: str): + """ + @brief Sets the destination of the instruction. + + @param value The new destination value to set. + """ self.tokens[2] = value diff --git a/assembler_tools/hec-assembler-tools/linker/instructions/cinst/csyncm.py b/assembler_tools/hec-assembler-tools/linker/instructions/cinst/csyncm.py index 204bb4e7..bbcf7dd3 100644 --- a/assembler_tools/hec-assembler-tools/linker/instructions/cinst/csyncm.py +++ b/assembler_tools/hec-assembler-tools/linker/instructions/cinst/csyncm.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 csyncm C-instruction which synchronizes memory operations.""" + +from .cinstruction import CInstruction + class Instruction(CInstruction): """ - Encapsulates a `csyncm` CInstruction. - + @brief Encapsulates a `csyncm` CInstruction. + Wait instruction similar to a barrier that stalls the execution of the CINST queue until the specified instruction from the MINST queue has completed. @@ -17,60 +23,53 @@ 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 `csyncm` instruction requires 3 tokens: , csyncm, - Returns: - int: The number of tokens, which is 3. + @return The number of tokens, which is 3. """ return 3 @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 "csyncm". + @return The name of the instruction, which is "csyncm". """ return "csyncm" def __init__(self, tokens: list, comment: str = ""): """ - Constructs a new `csyncm` 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 `csyncm` 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 target(self) -> int: """ - Gets the target MInst. + @brief Gets the target MInst. - Returns: - int: The target MInst. + @return The target MInst. """ return int(self.tokens[2]) @target.setter def target(self, value: int): """ - Sets the target MInst. - - Args: - value (int): The target MInst to set. + @brief Sets the target MInst. - Raises: - ValueError: If the value is negative. + @param value The target MInst to set. + @throws ValueError If the value is negative. """ if value < 0: - raise ValueError(f'`value`: expected non-negative target, but {value} received.') - self.tokens[2] = str(value) \ No newline at end of file + raise ValueError( + f"`value`: expected non-negative target, but {value} received." + ) + self.tokens[2] = str(value) diff --git a/assembler_tools/hec-assembler-tools/linker/instructions/cinst/ifetch.py b/assembler_tools/hec-assembler-tools/linker/instructions/cinst/ifetch.py index 96924223..18d0c485 100644 --- a/assembler_tools/hec-assembler-tools/linker/instructions/cinst/ifetch.py +++ b/assembler_tools/hec-assembler-tools/linker/instructions/cinst/ifetch.py @@ -1,8 +1,14 @@ -from .cinstruction import CInstruction +# Copyright (C) 2025 Intel Corporation +# SPDX-License-Identifier: Apache-2.0 + +"""@brief This module implements the ifetch C-instruction which fetches an instruction from memory.""" + +from .cinstruction import CInstruction + class Instruction(CInstruction): """ - Encapsulates an `ifetch` CInstruction. + @brief Encapsulates an `ifetch` CInstruction. This instruction fetches a bundle of instructions from the XINST queue and sends it to the CE for execution. @@ -16,60 +22,53 @@ 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 `ifetch` instruction requires 3 tokens: , ifetch, - Returns: - int: The number of tokens, which is 3. + @return The number of tokens, which is 3. """ return 3 @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 "ifetch". + @return The name of the instruction, which is "ifetch". """ return "ifetch" def __init__(self, tokens: list, comment: str = ""): """ - Constructs a new `ifetch` CInstruction. + @brief Constructs a new `ifetch` 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. - - 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 bundle(self) -> int: """ - Gets the target bundle index. + @brief Gets the target bundle index. - Returns: - int: The target bundle index. + @return The target bundle index. """ return int(self.tokens[2]) @bundle.setter def bundle(self, value: int): """ - Sets the target bundle index. - - Args: - value (int): The target bundle index to set. + @brief Sets the target bundle index. - Raises: - ValueError: If the value is negative. + @param value The target bundle index to set. + @throws ValueError If the value is negative. """ if value < 0: - raise ValueError(f'`value`: expected non-negative bundle index, but {value} received.') - self.tokens[2] = str(value) \ No newline at end of file + raise ValueError( + f"`value`: expected non-negative bundle index, but {value} received." + ) + self.tokens[2] = str(value) diff --git a/assembler_tools/hec-assembler-tools/linker/instructions/cinst/kgload.py b/assembler_tools/hec-assembler-tools/linker/instructions/cinst/kgload.py index 2c7126e9..87ae3717 100644 --- a/assembler_tools/hec-assembler-tools/linker/instructions/cinst/kgload.py +++ b/assembler_tools/hec-assembler-tools/linker/instructions/cinst/kgload.py @@ -1,42 +1,45 @@ -from .cinstruction import CInstruction +# Copyright (C) 2025 Intel Corporation +# SPDX-License-Identifier: Apache-2.0 + +"""@brief This module implements the kgload C-instruction which loads key generation data.""" + +from .cinstruction import CInstruction + class Instruction(CInstruction): """ - Encapsulates a `kg_load` CInstruction. + @brief Encapsulates a `kg_load` CInstruction. + + This instruction loads key generation data. """ @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 `kg_load` instruction requires 3 tokens: , kg_load, - Returns: - int: The number of tokens, which is 3. + @return The number of tokens, which is 3. """ return 3 @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 "kg_load". + @return The name of the instruction, which is "kg_load". """ return "kg_load" def __init__(self, tokens: list, comment: str = ""): """ - Constructs a new `kg_load` 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 `kg_load` 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) \ No newline at end of file + super().__init__(tokens, comment=comment) diff --git a/assembler_tools/hec-assembler-tools/linker/instructions/cinst/kgseed.py b/assembler_tools/hec-assembler-tools/linker/instructions/cinst/kgseed.py index f067f0e2..36a5e9a1 100644 --- a/assembler_tools/hec-assembler-tools/linker/instructions/cinst/kgseed.py +++ b/assembler_tools/hec-assembler-tools/linker/instructions/cinst/kgseed.py @@ -1,42 +1,45 @@ -from .cinstruction import CInstruction +# Copyright (C) 2025 Intel Corporation +# SPDX-License-Identifier: Apache-2.0 + +"""@brief This module implements the kgseed C-instruction which loads key generation seed data.""" + +from .cinstruction import CInstruction + class Instruction(CInstruction): """ - Encapsulates a `kg_seed` CInstruction. + @brief Encapsulates a `kg_seed` CInstruction. + + This instruction loads key generation seed data. """ @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 `kg_seed` instruction requires 4 tokens: , kg_seed, , - Returns: - int: The number of tokens, which is 4. + @return The number of tokens, which is 4. """ return 4 @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 "kg_seed". + @return The name of the instruction, which is "kg_seed". """ return "kg_seed" def __init__(self, tokens: list, comment: str = ""): """ - Constructs a new `kg_seed` 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 `kg_seed` 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) \ No newline at end of file + super().__init__(tokens, comment=comment) diff --git a/assembler_tools/hec-assembler-tools/linker/instructions/cinst/kgstart.py b/assembler_tools/hec-assembler-tools/linker/instructions/cinst/kgstart.py index 89e8669d..1b0ab005 100644 --- a/assembler_tools/hec-assembler-tools/linker/instructions/cinst/kgstart.py +++ b/assembler_tools/hec-assembler-tools/linker/instructions/cinst/kgstart.py @@ -1,42 +1,45 @@ -from .cinstruction import CInstruction +# Copyright (C) 2025 Intel Corporation +# SPDX-License-Identifier: Apache-2.0 + +"""@brief This module implements the kg_start C-instruction which initiates key generation process.""" + +from .cinstruction import CInstruction + class Instruction(CInstruction): """ - Encapsulates a `kg_start` CInstruction. + @brief Encapsulates a `kg_start` CInstruction. + + This instruction initiates the key generation process. """ @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 `kg_start` instruction requires 2 tokens: , kg_start - 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 "kg_start". + @return The name of the instruction, which is "kg_start". """ return "kg_start" def __init__(self, tokens: list, comment: str = ""): """ - Constructs a new `kg_start` 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 `kg_start` 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) \ No newline at end of file + super().__init__(tokens, comment=comment) diff --git a/assembler_tools/hec-assembler-tools/linker/instructions/cinst/nload.py b/assembler_tools/hec-assembler-tools/linker/instructions/cinst/nload.py index c2d13df7..d6e43f21 100644 --- a/assembler_tools/hec-assembler-tools/linker/instructions/cinst/nload.py +++ b/assembler_tools/hec-assembler-tools/linker/instructions/cinst/nload.py @@ -1,8 +1,14 @@ -from .cinstruction import CInstruction +# Copyright (C) 2025 Intel Corporation +# SPDX-License-Identifier: Apache-2.0 + +"""@brief This module implements the nload C-instruction which loads NTT tables from SPAD.""" + +from .cinstruction import CInstruction + class Instruction(CInstruction): """ - Encapsulates a `nload` CInstruction. + @brief Encapsulates an `nload` CInstruction. This instruction loads metadata (for NTT/iNTT routing mapping) from scratchpad into a special routing table register. @@ -12,15 +18,14 @@ class Instruction(CInstruction): """ @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 `nload` instruction requires 4 tokens: , nload, , - Returns: - int: The number of tokens, which is 4. + @return The number of tokens, which is 4. """ # 4 tokens: # , nload, , @@ -31,30 +36,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 "nload". + @return The name of the instruction, which is "nload". """ return "nload" def __init__(self, tokens: list, comment: str = ""): """ - Constructs a new `nload` 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 `nload` 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] diff --git a/assembler_tools/hec-assembler-tools/linker/instructions/cinst/xinstfetch.py b/assembler_tools/hec-assembler-tools/linker/instructions/cinst/xinstfetch.py index f82fbcf7..25782268 100644 --- a/assembler_tools/hec-assembler-tools/linker/instructions/cinst/xinstfetch.py +++ b/assembler_tools/hec-assembler-tools/linker/instructions/cinst/xinstfetch.py @@ -1,8 +1,14 @@ -from .cinstruction import CInstruction +# Copyright (C) 2025 Intel Corporation +# SPDX-License-Identifier: Apache-2.0 + +"""@brief This module implements the xinstfetch C-instruction which fetches X-instructions from memory.""" + +from .cinstruction import CInstruction + class Instruction(CInstruction): """ - Encapsulates a `xinstfetch` CInstruction. + @brief Encapsulates an `xinstfetch` CInstruction. This instruction fetches instructions from the HBM and sends them to the XINST queue. @@ -10,94 +16,86 @@ class Instruction(CInstruction): https://github.com/IntelLabs/hec-assembler-tools/blob/master/docsrc/inst_spec/cinst/cinst_xinstfetch.md Properties: - dstXQueue: Gets or sets the destination in the XINST queue. - srcHBM: Gets or sets the source in the HBM. + dst_x_queue: Gets or sets the destination in the XINST queue. + src_hbm: Gets or sets the source in the HBM. """ @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 `xinstfetch` instruction requires 4 tokens: , xinstfetch, , - Returns: - int: The number of tokens, which is 4. + @return The number of tokens, which is 4. """ return 4 @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 "xinstfetch". + @return The name of the instruction, which is "xinstfetch". """ return "xinstfetch" def __init__(self, tokens: list, comment: str = ""): """ - Constructs a new `xinstfetch` CInstruction. + @brief Constructs a new `xinstfetch` 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. - - Raises: - ValueError: If the number of tokens is invalid or the instruction name is incorrect. - NotImplementedError: If the `xinstfetch` CInstruction is not supported in the linker. + @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) - raise NotImplementedError('`xinstfetch` CInstruction is not currently supported in linker.') + raise NotImplementedError( + "`xinstfetch` CInstruction is not currently supported in linker." + ) @property - def dstXQueue(self) -> int: + def dst_x_queue(self) -> int: """ - Gets the destination in the XINST queue. + @brief Gets the destination in the XINST queue. - Returns: - int: The destination in the XINST queue. + @return The destination in the XINST queue. """ return int(self.tokens[2]) - @dstXQueue.setter - def dstXQueue(self, value: int): + @dst_x_queue.setter + def dst_x_queue(self, value: int): """ - Sets the destination in the XINST queue. - - Args: - value (int): The destination value to set. + @brief Sets the destination in the XINST queue. - Raises: - ValueError: If the value is negative. + @param value The destination value to set. + @throws ValueError If the value is negative. """ if value < 0: - raise ValueError(f'`value`: expected non-negative value, but {value} received.') + raise ValueError( + f"`value`: expected non-negative value, but {value} received." + ) self.tokens[2] = str(value) @property - def srcHBM(self) -> int: + def src_hbm(self) -> int: """ - Gets the source in the HBM. + @brief Gets the source in the HBM. - Returns: - int: The source in the HBM. + @return The source in the HBM. """ return int(self.tokens[3]) - @srcHBM.setter - def srcHBM(self, value: int): + @src_hbm.setter + def src_hbm(self, value: int): """ - Sets the source in the HBM. - - Args: - value (int): The source value to set. + @brief Sets the source in the HBM. - Raises: - ValueError: If the value is negative. + @param value The source value to set. + @throws ValueError If the value is negative. """ if value < 0: - raise ValueError(f'`value`: expected non-negative value, but {value} received.') - self.tokens[3] = str(value) \ No newline at end of file + raise ValueError( + f"`value`: expected non-negative value, but {value} received." + ) + self.tokens[3] = str(value) diff --git a/assembler_tools/hec-assembler-tools/linker/instructions/minst/__init__.py b/assembler_tools/hec-assembler-tools/linker/instructions/minst/__init__.py index fd037e60..d069bc35 100644 --- a/assembler_tools/hec-assembler-tools/linker/instructions/minst/__init__.py +++ b/assembler_tools/hec-assembler-tools/linker/instructions/minst/__init__.py @@ -1,4 +1,8 @@ - +# Copyright (C) 2025 Intel Corporation +# SPDX-License-Identifier: Apache-2.0 + +"""@brief This module provides all the supported M-instructions for the linker toolchain.""" + from . import mload, mstore, msyncc # MInst aliases @@ -7,13 +11,11 @@ MStore = mstore.Instruction MSyncc = msyncc.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 { MLoad, - MStore, - MSyncc } + return {MLoad, MStore, MSyncc} diff --git a/assembler_tools/hec-assembler-tools/linker/instructions/minst/minstruction.py b/assembler_tools/hec-assembler-tools/linker/instructions/minst/minstruction.py index bb00f61f..15238d72 100644 --- a/assembler_tools/hec-assembler-tools/linker/instructions/minst/minstruction.py +++ b/assembler_tools/hec-assembler-tools/linker/instructions/minst/minstruction.py @@ -1,46 +1,42 @@ # Copyright (C) 2025 Intel Corporation # SPDX-License-Identifier: Apache-2.0 -# pylint: disable=duplicate-code -"""This module implements the base class for MInstructions.""" +"""@brief This module implements the base class for all M-instructions.""" from linker.instructions.instruction import BaseInstruction class MInstruction(BaseInstruction): """ - Represents an MInstruction, inheriting from BaseInstruction. + @brief Represents an MInstruction, 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, which is 1. """ 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() @@ -49,14 +45,11 @@ def _get_num_tokens(cls) -> int: def __init__(self, tokens: list, comment: str = ""): """ - Constructs a new MInstruction. - - Parameters: - tokens (list): List of tokens for the instruction. - comment (str): Optional comment for the instruction. + @brief Constructs a new MInstruction. - 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) diff --git a/assembler_tools/hec-assembler-tools/linker/instructions/minst/mload.py b/assembler_tools/hec-assembler-tools/linker/instructions/minst/mload.py index b662101b..0900b94e 100644 --- a/assembler_tools/hec-assembler-tools/linker/instructions/minst/mload.py +++ b/assembler_tools/hec-assembler-tools/linker/instructions/minst/mload.py @@ -1,8 +1,14 @@ -from .minstruction import MInstruction +# Copyright (C) 2025 Intel Corporation +# SPDX-License-Identifier: Apache-2.0 + +"""@brief This module implements the mload M-instruction which loads data from memory to scratchpad.""" + +from .minstruction import MInstruction + class Instruction(MInstruction): """ - Encapsulates an `mload` MInstruction. + @brief Encapsulates an `mload` MInstruction. This instruction loads a single polynomial residue from local memory to scratchpad. @@ -16,57 +22,50 @@ class Instruction(MInstruction): @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 `mload` instruction requires 4 tokens: , mload, , - Returns: - int: The number of tokens, which is 4. + @return The number of tokens, which is 4. """ return 4 @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 "mload". + @return The name of the instruction, which is "mload". """ return "mload" def __init__(self, tokens: list, comment: str = ""): """ - Constructs a new `mload` MInstruction. - - 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 `mload` MInstruction. - 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: """ - Gets the name of the source. + @brief Gets the name of the source. This is a Variable name when loaded. Should be set to HBM address to write back. - Returns: - str: The name of the source. + @return The name of the source. """ return self.tokens[3] @source.setter def source(self, value: str): """ - Sets the name of the source. + @brief Sets the name of the source. - Args: - value (str): The name of the source to set. + @param value The name of the source to set. """ - self.tokens[3] = value \ No newline at end of file + self.tokens[3] = value diff --git a/assembler_tools/hec-assembler-tools/linker/instructions/minst/mstore.py b/assembler_tools/hec-assembler-tools/linker/instructions/minst/mstore.py index 6046ea0f..921dcff7 100644 --- a/assembler_tools/hec-assembler-tools/linker/instructions/minst/mstore.py +++ b/assembler_tools/hec-assembler-tools/linker/instructions/minst/mstore.py @@ -1,8 +1,14 @@ -from .minstruction import MInstruction +# Copyright (C) 2025 Intel Corporation +# SPDX-License-Identifier: Apache-2.0 + +"""@brief This module implements the mstore M-instruction which stores data from scratchpad to memory.""" + +from .minstruction import MInstruction + class Instruction(MInstruction): """ - Encapsulates an `mstore` MInstruction. + @brief Encapsulates an `mstore` MInstruction. This instruction stores a single polynomial residue from scratchpad to local memory. @@ -16,57 +22,50 @@ class Instruction(MInstruction): @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 `mstore` instruction requires 4 tokens: , mstore, , - Returns: - int: The number of tokens, which is 4. + @return The number of tokens, which is 4. """ return 4 @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 "mstore". + @return The name of the instruction, which is "mstore". """ return "mstore" def __init__(self, tokens: list, comment: str = ""): """ - Constructs a new `mstore` MInstruction. - - 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 `mstore` MInstruction. - 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 dest(self) -> str: """ - Gets the name of the destination. + @brief Gets the name of the destination. This is a Variable name when loaded. Should be set to HBM address to write back. - Returns: - str: The name of the destination. + @return The name of the destination. """ return self.tokens[2] @dest.setter def dest(self, value: str): """ - Sets the name of the destination. + @brief Sets the name of the destination. - Args: - value (str): The name of the destination to set. + @param value The name of the destination to set. """ - self.tokens[2] = value \ No newline at end of file + self.tokens[2] = value diff --git a/assembler_tools/hec-assembler-tools/linker/instructions/minst/msyncc.py b/assembler_tools/hec-assembler-tools/linker/instructions/minst/msyncc.py index 4291d239..5d374293 100644 --- a/assembler_tools/hec-assembler-tools/linker/instructions/minst/msyncc.py +++ b/assembler_tools/hec-assembler-tools/linker/instructions/minst/msyncc.py @@ -1,8 +1,14 @@ -from .minstruction import MInstruction +# Copyright (C) 2025 Intel Corporation +# SPDX-License-Identifier: Apache-2.0 + +"""@brief This module implements the msyncc M-instruction which synchronizes with the control flow.""" + +from .minstruction import MInstruction + class Instruction(MInstruction): """ - Encapsulates an `msyncc` MInstruction. + @brief Encapsulates an `msyncc` MInstruction. Wait instruction similar to a barrier that stalls the execution of the MINST queue until the specified instruction from the CINST queue has completed. @@ -17,60 +23,53 @@ class Instruction(MInstruction): @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 `msyncc` instruction requires 3 tokens: , msyncc, - Returns: - int: The number of tokens, which is 3. + @return The number of tokens, which is 3. """ return 3 @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 "msyncc". + @return The name of the instruction, which is "msyncc". """ return "msyncc" def __init__(self, tokens: list, comment: str = ""): """ - Constructs a new `msyncc` MInstruction. + @brief Constructs a new `msyncc` MInstruction. - Args: - tokens (list): A list of tokens representing the instruction. - comment (str, optional): An optional comment for the instruction. Defaults to an empty string. - - 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 target(self) -> int: """ - Gets the target CInst. + @brief Gets the target CInst. - Returns: - int: The target CInst. + @return The target CInst. """ return int(self.tokens[2]) @target.setter def target(self, value: int): """ - Sets the target CInst. - - Args: - value (int): The target CInst to set. + @brief Sets the target CInst. - Raises: - ValueError: If the value is negative. + @param value The target CInst to set. + @throws ValueError If the value is negative. """ if value < 0: - raise ValueError(f'`value`: expected non-negative target, but {value} received.') - self.tokens[2] = str(value) \ No newline at end of file + raise ValueError( + f"`value`: expected non-negative target, but {value} received." + ) + self.tokens[2] = str(value) diff --git a/assembler_tools/hec-assembler-tools/linker/instructions/xinst/__init__.py b/assembler_tools/hec-assembler-tools/linker/instructions/xinst/__init__.py index 3a63845c..6f92646d 100644 --- a/assembler_tools/hec-assembler-tools/linker/instructions/xinst/__init__.py +++ b/assembler_tools/hec-assembler-tools/linker/instructions/xinst/__init__.py @@ -1,6 +1,27 @@ -from . import add, sub, mul, muli, mac, maci, ntt, intt, twntt, twintt, rshuffle, move, xstore, nop +# Copyright (C) 2025 Intel Corporation +# SPDX-License-Identifier: Apache-2.0 + +"""@brief This module provides all the supported X-instructions for the linker toolchain.""" + +from . import ( + add, + sub, + mul, + muli, + mac, + maci, + ntt, + intt, + twntt, + twintt, + rshuffle, + move, + xstore, + nop, +) from . import exit as exit_mod -#from . import copy as copy_mod + +# from . import copy as copy_mod # XInst aliases @@ -12,35 +33,37 @@ Mac = mac.Instruction Maci = maci.Instruction NTT = ntt.Instruction -iNTT = intt.Instruction -twNTT = twntt.Instruction -twiNTT = twintt.Instruction -rShuffle = rshuffle.Instruction +INTT = intt.Instruction +TwNTT = twntt.Instruction +TwiNTT = twintt.Instruction +RShuffle = rshuffle.Instruction # All other XInsts Move = move.Instruction XStore = xstore.Instruction Exit = exit_mod.Instruction Nop = nop.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 { Add, - Sub, - Mul, - Muli, - Mac, - Maci, - NTT, - iNTT, - twNTT, - twiNTT, - rShuffle, - Move, - XStore, - Exit, - Nop } + return { + Add, + Sub, + Mul, + Muli, + Mac, + Maci, + NTT, + INTT, + TwNTT, + TwiNTT, + RShuffle, + Move, + XStore, + Exit, + Nop, + } diff --git a/assembler_tools/hec-assembler-tools/linker/instructions/xinst/add.py b/assembler_tools/hec-assembler-tools/linker/instructions/xinst/add.py index ac7194e8..54c66ec2 100644 --- a/assembler_tools/hec-assembler-tools/linker/instructions/xinst/add.py +++ b/assembler_tools/hec-assembler-tools/linker/instructions/xinst/add.py @@ -1,8 +1,14 @@ -from .xinstruction import XInstruction +# Copyright (C) 2025 Intel Corporation +# SPDX-License-Identifier: Apache-2.0 + +"""@brief This module implements the add X-instruction which performs element-wise polynomial addition.""" + +from .xinstruction import XInstruction + class Instruction(XInstruction): """ - Encapsulates an `add` XInstruction. + @brief Encapsulates an `add` XInstruction. This instruction adds two polynomials stored in the register file and stores the result in a register. @@ -14,35 +20,30 @@ class Instruction(XInstruction): @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 `add` instruction requires 7 tokens: F, , add, , , , - Returns: - int: The number of tokens, which is 7. + @return The number of tokens, which is 7. """ return 7 @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 "add". + @return The name of the instruction, which is "add". """ return "add" def __init__(self, tokens: list, comment: str = ""): """ - Constructs a new `add` XInstruction. - - 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 `add` XInstruction. - 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) \ No newline at end of file + super().__init__(tokens, comment=comment) diff --git a/assembler_tools/hec-assembler-tools/linker/instructions/xinst/exit.py b/assembler_tools/hec-assembler-tools/linker/instructions/xinst/exit.py index 98d36ada..30dd6158 100644 --- a/assembler_tools/hec-assembler-tools/linker/instructions/xinst/exit.py +++ b/assembler_tools/hec-assembler-tools/linker/instructions/xinst/exit.py @@ -1,8 +1,14 @@ -from .xinstruction import XInstruction +# Copyright (C) 2025 Intel Corporation +# SPDX-License-Identifier: Apache-2.0 + +"""@brief This module implements the bexit X-instruction which terminates execution of an instruction bundle.""" + +from .xinstruction import XInstruction + class Instruction(XInstruction): """ - Encapsulates an `bexit` XInstruction. + @brief Encapsulates an `bexit` XInstruction. This instruction terminates execution of an instruction bundle. @@ -13,35 +19,30 @@ class Instruction(XInstruction): @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 `bexit` instruction requires 3 tokens: F, , bexit - Returns: - int: The number of tokens, which is 3. + @return The number of tokens, which is 3. """ return 3 @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 "bexit". + @return The name of the instruction, which is "bexit". """ return "bexit" def __init__(self, tokens: list, comment: str = ""): """ - Constructs a new `bexit` XInstruction. - - 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 `bexit` XInstruction. - 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) \ No newline at end of file + super().__init__(tokens, comment=comment) diff --git a/assembler_tools/hec-assembler-tools/linker/instructions/xinst/intt.py b/assembler_tools/hec-assembler-tools/linker/instructions/xinst/intt.py index c9240440..8236e925 100644 --- a/assembler_tools/hec-assembler-tools/linker/instructions/xinst/intt.py +++ b/assembler_tools/hec-assembler-tools/linker/instructions/xinst/intt.py @@ -1,8 +1,14 @@ -from .xinstruction import XInstruction +# Copyright (C) 2025 Intel Corporation +# SPDX-License-Identifier: Apache-2.0 + +"""@brief This module implements the intt X-instruction which converts NTT form to positional form.""" + +from .xinstruction import XInstruction + class Instruction(XInstruction): """ - Encapsulates an `intt` XInstruction. + @brief Encapsulates an `intt` XInstruction. The Inverse Number Theoretic Transform (iNTT) converts NTT form to positional form. @@ -13,35 +19,30 @@ class Instruction(XInstruction): @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 `intt` instruction requires 10 tokens: F, , intt, , , , , , , - Returns: - int: The number of tokens, which is 10. + @return The number of tokens, which is 10. """ return 10 @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 "intt". + @return The name of the instruction, which is "intt". """ return "intt" def __init__(self, tokens: list, comment: str = ""): """ - Constructs a new `intt` XInstruction. - - 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 `intt` XInstruction. - 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) \ No newline at end of file + super().__init__(tokens, comment=comment) diff --git a/assembler_tools/hec-assembler-tools/linker/instructions/xinst/mac.py b/assembler_tools/hec-assembler-tools/linker/instructions/xinst/mac.py index d7e9800d..b108733e 100644 --- a/assembler_tools/hec-assembler-tools/linker/instructions/xinst/mac.py +++ b/assembler_tools/hec-assembler-tools/linker/instructions/xinst/mac.py @@ -1,8 +1,14 @@ -from .xinstruction import XInstruction +# Copyright (C) 2025 Intel Corporation +# SPDX-License-Identifier: Apache-2.0 + +"""@brief This module implements the mac X-instruction which performs element-wise polynomial multiplication and accumulation.""" + +from .xinstruction import XInstruction + class Instruction(XInstruction): """ - Encapsulates a `mac` XInstruction. + @brief Encapsulates a `mac` XInstruction. Element-wise polynomial multiplication and accumulation. @@ -13,35 +19,30 @@ class Instruction(XInstruction): @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 `mac` instruction requires 8 tokens: F, , mac, , , , , - Returns: - int: The number of tokens, which is 8. + @return The number of tokens, which is 8. """ return 8 @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 "mac". + @return The name of the instruction, which is "mac". """ return "mac" def __init__(self, tokens: list, comment: str = ""): """ - Constructs a new `mac` XInstruction. - - 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 `mac` XInstruction. - 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) \ No newline at end of file + super().__init__(tokens, comment=comment) diff --git a/assembler_tools/hec-assembler-tools/linker/instructions/xinst/maci.py b/assembler_tools/hec-assembler-tools/linker/instructions/xinst/maci.py index a1703be8..d8c3e846 100644 --- a/assembler_tools/hec-assembler-tools/linker/instructions/xinst/maci.py +++ b/assembler_tools/hec-assembler-tools/linker/instructions/xinst/maci.py @@ -1,8 +1,14 @@ -from .xinstruction import XInstruction +# Copyright (C) 2025 Intel Corporation +# SPDX-License-Identifier: Apache-2.0 + +"""@brief This module implements the maci X-instruction which performs element-wise polynomial scaling by an immediate value and accumulation.""" + +from .xinstruction import XInstruction + class Instruction(XInstruction): """ - Encapsulates a `maci` XInstruction. + @brief Encapsulates a `maci` XInstruction. Element-wise polynomial scaling by an immediate value and accumulation. @@ -13,35 +19,30 @@ class Instruction(XInstruction): @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 `maci` instruction requires 8 tokens: F, , maci, , , , , - Returns: - int: The number of tokens, which is 8. + @return The number of tokens, which is 8. """ return 8 @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 "maci". + @return The name of the instruction, which is "maci". """ return "maci" def __init__(self, tokens: list, comment: str = ""): """ - Constructs a new `maci` XInstruction. - - 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 `maci` XInstruction. - 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) \ No newline at end of file + super().__init__(tokens, comment=comment) diff --git a/assembler_tools/hec-assembler-tools/linker/instructions/xinst/move.py b/assembler_tools/hec-assembler-tools/linker/instructions/xinst/move.py index 8ae2233a..ec4b2836 100644 --- a/assembler_tools/hec-assembler-tools/linker/instructions/xinst/move.py +++ b/assembler_tools/hec-assembler-tools/linker/instructions/xinst/move.py @@ -1,8 +1,14 @@ -from .xinstruction import XInstruction +# Copyright (C) 2025 Intel Corporation +# SPDX-License-Identifier: Apache-2.0 + +"""@brief This module implements the move X-instruction which copies data from one register to another.""" + +from .xinstruction import XInstruction + class Instruction(XInstruction): """ - Encapsulates a `move` XInstruction. + @brief Encapsulates a `move` XInstruction. This instruction copies data from one register to a different one. @@ -13,35 +19,30 @@ class Instruction(XInstruction): @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 `move` instruction requires 5 tokens: F, , move, , - Returns: - int: The number of tokens, which is 5. + @return The number of tokens, which is 5. """ return 5 @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 "move". + @return The name of the instruction, which is "move". """ return "move" def __init__(self, tokens: list, comment: str = ""): """ - Constructs a new `move` XInstruction. - - 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 `move` XInstruction. - 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) \ No newline at end of file + super().__init__(tokens, comment=comment) diff --git a/assembler_tools/hec-assembler-tools/linker/instructions/xinst/mul.py b/assembler_tools/hec-assembler-tools/linker/instructions/xinst/mul.py index 40bbb0c6..c6a7c01c 100644 --- a/assembler_tools/hec-assembler-tools/linker/instructions/xinst/mul.py +++ b/assembler_tools/hec-assembler-tools/linker/instructions/xinst/mul.py @@ -1,9 +1,15 @@ -from .xinstruction import XInstruction +# Copyright (C) 2025 Intel Corporation +# SPDX-License-Identifier: Apache-2.0 + +"""@brief This module implements the mul X-instruction which performs element-wise polynomial multiplication.""" + +from .xinstruction import XInstruction + class Instruction(XInstruction): """ - Encapsulates a `mul` XInstruction. - + @brief Encapsulates a `mul` XInstruction. + This instruction performs element-wise polynomial multiplication. For more information, check the specification: @@ -13,35 +19,30 @@ class Instruction(XInstruction): @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 `mul` instruction requires 7 tokens: F, , mul, , , , - Returns: - int: The number of tokens, which is 7. + @return The number of tokens, which is 7. """ return 7 @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 "mul". + @return The name of the instruction, which is "mul". """ return "mul" def __init__(self, tokens: list, comment: str = ""): """ - Constructs a new `mul` XInstruction. - - 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 `mul` XInstruction. - 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) \ No newline at end of file + super().__init__(tokens, comment=comment) diff --git a/assembler_tools/hec-assembler-tools/linker/instructions/xinst/muli.py b/assembler_tools/hec-assembler-tools/linker/instructions/xinst/muli.py index 3590a6c6..3ff40e55 100644 --- a/assembler_tools/hec-assembler-tools/linker/instructions/xinst/muli.py +++ b/assembler_tools/hec-assembler-tools/linker/instructions/xinst/muli.py @@ -1,8 +1,14 @@ -from .xinstruction import XInstruction +# Copyright (C) 2025 Intel Corporation +# SPDX-License-Identifier: Apache-2.0 + +"""@brief This module implements the muli X-instruction which performs element-wise polynomial scaling by an immediate value.""" + +from .xinstruction import XInstruction + class Instruction(XInstruction): """ - Encapsulates a `muli` XInstruction. + @brief Encapsulates a `muli` XInstruction. This instruction performs element-wise polynomial scaling by an immediate value. @@ -13,35 +19,30 @@ class Instruction(XInstruction): @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 `muli` instruction requires 7 tokens: F, , muli, , , , - Returns: - int: The number of tokens, which is 7. + @return The number of tokens, which is 7. """ return 7 @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 "muli". + @return The name of the instruction, which is "muli". """ return "muli" def __init__(self, tokens: list, comment: str = ""): """ - Constructs a new `muli` XInstruction. - - 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 `muli` XInstruction. - 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) \ No newline at end of file + super().__init__(tokens, comment=comment) diff --git a/assembler_tools/hec-assembler-tools/linker/instructions/xinst/nop.py b/assembler_tools/hec-assembler-tools/linker/instructions/xinst/nop.py index f6b3f513..2f40fc0e 100644 --- a/assembler_tools/hec-assembler-tools/linker/instructions/xinst/nop.py +++ b/assembler_tools/hec-assembler-tools/linker/instructions/xinst/nop.py @@ -1,8 +1,14 @@ -from .xinstruction import XInstruction +# Copyright (C) 2025 Intel Corporation +# SPDX-License-Identifier: Apache-2.0 + +"""@brief This module implements the nop X-instruction which adds idle cycles to the compute flow.""" + +from .xinstruction import XInstruction + class Instruction(XInstruction): """ - Encapsulates a `nop` XInstruction. + @brief Encapsulates a `nop` XInstruction. This instruction adds a desired amount of idle cycles to the compute flow. @@ -13,35 +19,30 @@ class Instruction(XInstruction): @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 `nop` instruction requires 4 tokens: F, , nop, - Returns: - int: The number of tokens, which is 4. + @return The number of tokens, which is 4. """ return 4 @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 "nop". + @return The name of the instruction, which is "nop". """ return "nop" def __init__(self, tokens: list, comment: str = ""): """ - Constructs a new `nop` XInstruction. - - 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 `nop` XInstruction. - 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) \ No newline at end of file + super().__init__(tokens, comment=comment) diff --git a/assembler_tools/hec-assembler-tools/linker/instructions/xinst/ntt.py b/assembler_tools/hec-assembler-tools/linker/instructions/xinst/ntt.py index ead438ea..18b3875c 100644 --- a/assembler_tools/hec-assembler-tools/linker/instructions/xinst/ntt.py +++ b/assembler_tools/hec-assembler-tools/linker/instructions/xinst/ntt.py @@ -1,8 +1,15 @@ -from .xinstruction import XInstruction +# Copyright (C) 2025 Intel Corporation +# SPDX-License-Identifier: Apache-2.0 + +"""@brief This module implements the ntt X-instruction which converts positional form to NTT form.""" + +from .xinstruction import XInstruction + class Instruction(XInstruction): """ - Encapsulates an `ntt` XInstruction (Number Theoretic Transform). + @brief Encapsulates an `ntt` XInstruction (Number Theoretic Transform). + Converts positional form to NTT form. For more information, check the specification: @@ -12,35 +19,30 @@ class Instruction(XInstruction): @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 `ntt` instruction requires 10 tokens: F, , ntt, , , , , , , - Returns: - int: The number of tokens, which is 10. + @return The number of tokens, which is 10. """ return 10 @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 "ntt". + @return The name of the instruction, which is "ntt". """ return "ntt" def __init__(self, tokens: list, comment: str = ""): """ - Constructs a new `ntt` XInstruction. - - 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 `ntt` XInstruction. - 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) \ No newline at end of file + super().__init__(tokens, comment=comment) diff --git a/assembler_tools/hec-assembler-tools/linker/instructions/xinst/rshuffle.py b/assembler_tools/hec-assembler-tools/linker/instructions/xinst/rshuffle.py index daf0d754..93620b9b 100644 --- a/assembler_tools/hec-assembler-tools/linker/instructions/xinst/rshuffle.py +++ b/assembler_tools/hec-assembler-tools/linker/instructions/xinst/rshuffle.py @@ -1,42 +1,45 @@ -from .xinstruction import XInstruction +# Copyright (C) 2025 Intel Corporation +# SPDX-License-Identifier: Apache-2.0 + +"""@brief This module implements the rshuffle X-instruction which performs data shuffling operations.""" + +from .xinstruction import XInstruction + class Instruction(XInstruction): """ - Encapsulates an `rshuffle` XInstruction. + @brief Encapsulates an `rshuffle` XInstruction. + + This instruction performs data shuffling operations between registers. """ @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 `rshuffle` instruction requires 9 tokens: F, , rshuffle, , , , , , - Returns: - int: The number of tokens, which is 9. + @return The number of tokens, which is 9. """ return 9 @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 "rshuffle". + @return The name of the instruction, which is "rshuffle". """ return "rshuffle" def __init__(self, tokens: list, comment: str = ""): """ - Constructs a new `rshuffle` XInstruction. - - 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 `rshuffle` XInstruction. - 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) \ No newline at end of file + super().__init__(tokens, comment=comment) diff --git a/assembler_tools/hec-assembler-tools/linker/instructions/xinst/sub.py b/assembler_tools/hec-assembler-tools/linker/instructions/xinst/sub.py index f4cecb19..d71ab723 100644 --- a/assembler_tools/hec-assembler-tools/linker/instructions/xinst/sub.py +++ b/assembler_tools/hec-assembler-tools/linker/instructions/xinst/sub.py @@ -1,8 +1,14 @@ -from .xinstruction import XInstruction +# Copyright (C) 2025 Intel Corporation +# SPDX-License-Identifier: Apache-2.0 + +"""@brief This module implements the sub X-instruction which performs element-wise polynomial subtraction.""" + +from .xinstruction import XInstruction + class Instruction(XInstruction): """ - Encapsulates a `sub` XInstruction. + @brief Encapsulates a `sub` XInstruction. This instruction performs element-wise polynomial subtraction. @@ -13,35 +19,30 @@ class Instruction(XInstruction): @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 `sub` instruction requires 7 tokens: F, , sub, , , , - Returns: - int: The number of tokens, which is 7. + @return The number of tokens, which is 7. """ return 7 @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 "sub". + @return The name of the instruction, which is "sub". """ return "sub" def __init__(self, tokens: list, comment: str = ""): """ - Constructs a new `sub` XInstruction. - - 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 `sub` XInstruction. - 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) \ No newline at end of file + super().__init__(tokens, comment=comment) diff --git a/assembler_tools/hec-assembler-tools/linker/instructions/xinst/twintt.py b/assembler_tools/hec-assembler-tools/linker/instructions/xinst/twintt.py index 5ea3b62c..e6e4a245 100644 --- a/assembler_tools/hec-assembler-tools/linker/instructions/xinst/twintt.py +++ b/assembler_tools/hec-assembler-tools/linker/instructions/xinst/twintt.py @@ -1,8 +1,14 @@ -from .xinstruction import XInstruction +# Copyright (C) 2025 Intel Corporation +# SPDX-License-Identifier: Apache-2.0 + +"""@brief This module implements the twintt X-instruction which generates twiddle factors for the next stage of iNTT.""" + +from .xinstruction import XInstruction + class Instruction(XInstruction): """ - Encapsulates a `twintt` XInstruction. + @brief Encapsulates a `twintt` XInstruction. This instruction performs on-die generation of twiddle factors for the next stage of iNTT. @@ -13,35 +19,30 @@ class Instruction(XInstruction): @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 `twintt` instruction requires 10 tokens: F, , twintt, , , , , , , - Returns: - int: The number of tokens, which is 10. + @return The number of tokens, which is 10. """ return 10 @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 "twintt". + @return The name of the instruction, which is "twintt". """ return "twintt" def __init__(self, tokens: list, comment: str = ""): """ - Constructs a new `twintt` XInstruction. - - 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 `twintt` XInstruction. - 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) \ No newline at end of file + super().__init__(tokens, comment=comment) diff --git a/assembler_tools/hec-assembler-tools/linker/instructions/xinst/twntt.py b/assembler_tools/hec-assembler-tools/linker/instructions/xinst/twntt.py index 1e1ae65b..f01fa5ed 100644 --- a/assembler_tools/hec-assembler-tools/linker/instructions/xinst/twntt.py +++ b/assembler_tools/hec-assembler-tools/linker/instructions/xinst/twntt.py @@ -1,9 +1,15 @@ -from .xinstruction import XInstruction +# Copyright (C) 2025 Intel Corporation +# SPDX-License-Identifier: Apache-2.0 + +"""@brief This module implements the twntt X-instruction which generates twiddle factors for the next stage of NTT.""" + +from .xinstruction import XInstruction + class Instruction(XInstruction): """ - Encapsulates a `twntt` XInstruction. - + @brief Encapsulates a `twntt` XInstruction. + This instruction performs on-die generation of twiddle factors for the next stage of NTT. For more information, check the specification: @@ -13,35 +19,30 @@ class Instruction(XInstruction): @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 `twntt` instruction requires 10 tokens: F, , twntt, , , , , , , - Returns: - int: The number of tokens, which is 10. + @return The number of tokens, which is 10. """ return 10 @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 "twntt". + @return The name of the instruction, which is "twntt". """ return "twntt" def __init__(self, tokens: list, comment: str = ""): """ - Constructs a new `twntt` XInstruction. - - 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 `twntt` XInstruction. - 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) \ No newline at end of file + super().__init__(tokens, comment=comment) diff --git a/assembler_tools/hec-assembler-tools/linker/instructions/xinst/xinstruction.py b/assembler_tools/hec-assembler-tools/linker/instructions/xinst/xinstruction.py index 43b2b9b4..465f4127 100644 --- a/assembler_tools/hec-assembler-tools/linker/instructions/xinst/xinstruction.py +++ b/assembler_tools/hec-assembler-tools/linker/instructions/xinst/xinstruction.py @@ -1,34 +1,32 @@ # Copyright (C) 2025 Intel Corporation # SPDX-License-Identifier: Apache-2.0 -"""This module implements the XInstruction""" +"""@brief This module implements the base class for all X-instructions.""" from linker.instructions.instruction import BaseInstruction class XInstruction(BaseInstruction): """ - Represents an XInstruction, inheriting from BaseInstruction. + @brief Represents an XInstruction, 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 2. + @return The index of the name token, which is 2. """ # Name at index 2. return 2 @@ -36,11 +34,10 @@ def _get_name_token_index(cls) -> int: @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() @@ -49,27 +46,21 @@ def _get_num_tokens(cls) -> int: def __init__(self, tokens: list, comment: str = ""): """ - Constructs a new XInstruction. + @brief Constructs a new XInstruction. - Parameters: - tokens (list): List of tokens for the instruction. - comment (str): Optional comment for the instruction. - - 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) @property def bundle(self) -> int: """ - Gets the bundle index. - - Returns: - int: The bundle index. + @brief Gets the bundle index. - Raises: - RuntimeError: If the bundle format is invalid. + @return The bundle index. + @throws RuntimeError If the bundle format is invalid. """ if len(self.tokens[0]) < 2 or self.tokens[0][0] != "F": raise RuntimeError(f'Invalid bundle format detected: "{self.tokens[0]}".') @@ -78,13 +69,10 @@ def bundle(self) -> int: @bundle.setter def bundle(self, value: int): """ - Sets the bundle index. - - Parameters: - value (int): The new bundle index. + @brief Sets the bundle index. - Raises: - ValueError: If the value is negative. + @param value The new bundle index. + @throws ValueError If the value is negative. """ if value < 0: raise ValueError( diff --git a/assembler_tools/hec-assembler-tools/linker/instructions/xinst/xstore.py b/assembler_tools/hec-assembler-tools/linker/instructions/xinst/xstore.py index 8ed88dbb..e2563be6 100644 --- a/assembler_tools/hec-assembler-tools/linker/instructions/xinst/xstore.py +++ b/assembler_tools/hec-assembler-tools/linker/instructions/xinst/xstore.py @@ -1,11 +1,17 @@ -from .xinstruction import XInstruction +# Copyright (C) 2025 Intel Corporation +# SPDX-License-Identifier: Apache-2.0 + +"""@brief This module implements the xstore X-instruction which transfers data from a register to the intermediate data buffer.""" + +from .xinstruction import XInstruction + class Instruction(XInstruction): """ - Encapsulates an `xstore` XInstruction. + @brief Encapsulates an `xstore` XInstruction. This instruction transfers data from a register into the intermediate data buffer for subsequent transfer into SPAD. - + For more information, check the specification: https://github.com/IntelLabs/hec-assembler-tools/blob/master/docsrc/inst_spec/xinst/xinst_xstore.md """ @@ -13,35 +19,30 @@ class Instruction(XInstruction): @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 `xstore` instruction requires 4 tokens: F, , xstore, - Returns: - int: The number of tokens, which is 4. + @return The number of tokens, which is 4. """ return 4 @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 "xstore". + @return The name of the instruction, which is "xstore". """ return "xstore" def __init__(self, tokens: list, comment: str = ""): """ - Constructs a new `xstore` XInstruction. - - 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 `xstore` XInstruction. - 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) \ No newline at end of file + super().__init__(tokens, comment=comment) diff --git a/assembler_tools/hec-assembler-tools/linker/steps/__init__.py b/assembler_tools/hec-assembler-tools/linker/steps/__init__.py index e02abfc9..4057dc01 100644 --- a/assembler_tools/hec-assembler-tools/linker/steps/__init__.py +++ b/assembler_tools/hec-assembler-tools/linker/steps/__init__.py @@ -1 +1,2 @@ - +# Copyright (C) 2025 Intel Corporation +# SPDX-License-Identifier: Apache-2.0