diff --git a/src/simudator/core/modules/register.py b/src/simudator/core/modules/register.py index 79425c365aa5adcfdb2543f8d72e2b667e55832a..00f0dfef3f62e7ffda01b5a75a7601782e10928c 100644 --- a/src/simudator/core/modules/register.py +++ b/src/simudator/core/modules/register.py @@ -8,23 +8,34 @@ from simudator.core.signal import Signal class Register(Module): """ - A simple module that can store a value. + A simple module that can store and output a value. + + Parameters + ---------- + input : Signal + Signal from which the value is stored in the register. + output : Signal + Signal onto which the value of the register is outputted. + value : Any + Initial value of the register. + name : str + Name of the register. """ __slots__ = "_value" def __init__( self, - input_signal: Signal, - output_signal: Signal, + input: Signal, + output: Signal, value: Any = 0, name: str = "Register", ) -> None: # signals signals = { - "in_content": input_signal, - "out_content": output_signal, + "in_content": input, + "out_content": output, } # init the instance @@ -32,9 +43,10 @@ class Register(Module): self._value = value def update_register(self) -> None: - """ - Propagate the input signal to the registers internal state. - Throw away bits larger than the length of the register. + """Update the internal value of the register with the input signal. + + Any extra bits that do not fit the bit length of the register are + thrown away. """ input_value = self.signals["in_content"].get_value() if input_value is None: @@ -44,6 +56,7 @@ class Register(Module): def output_register(self) -> None: """ Propagate the value of the register to the output signal. + It is the response of the destination to know when it should read the output. """ @@ -51,6 +64,8 @@ class Register(Module): def update_logic(self): """ + Do nothing. + The register has no logic. """ pass @@ -58,7 +73,8 @@ class Register(Module): def get_state(self) -> dict[str, Any]: """ Returns a dict of the register state. - These states are changable via set_states. + + These states are changeable via set_states. """ state = super().get_state() state["value"] = self._value @@ -70,7 +86,13 @@ class Register(Module): def set_state(self, state: dict[str, Any]) -> None: """ - Sets the register state to one given in dict. + Set the state of the register. + + Parameters + ---------- + state : dict[str, Any] + The state of the register to load. Should contain the keys "name" + and "value" with values of type ``str`` and ``int`` respectively. """ self.name = state["name"] self._value = state["value"] @@ -81,9 +103,10 @@ class Register(Module): """ self._value = 0 - def save_state_to_file(self, file_path: str) -> True: + def save_state_to_file(self, file_path: str) -> bool: """ Tries to save the modules state to a given file. + Returns true on success and false if something went wrong. """ content = self.name + ":\n" + "value: " + str(self._value) + "\n\n" @@ -101,15 +124,29 @@ class Register(Module): class IntegerRegister(Register): """ - A simple module that can store an integer value with a given bit-length. + A register intended to store integers only. + + Parameters + ---------- + input : Signal + Signal from which the value is stored in the register. + output : Signal + Signal onto which the value of the register is outputted. + bit_length : int + Maximum number of bits of the input to store in the register. All extra + bits of the input value are discarded. + value : Any + Initial value of the register. + name : str + Name of the register. """ __slots__ = "_bit_length" def __init__( self, - input_signal: Signal, - output_signal: Signal, + input: Signal, + output: Signal, bit_length: int, value: int = 0, name: str | None = None, @@ -119,25 +156,17 @@ class IntegerRegister(Register): if name is None: name = f"{bit_length}-bit register" - super().__init__(input_signal, output_signal, value=value, name=name) + super().__init__(input, output, value=value, name=name) # set the bit length of the register self._bit_length = bit_length def update_register(self) -> None: - """ - Propagate the input signal to the registers internal state. - Throw away bits larger than the length of the register. - """ super().update_register() mask = 2**self._bit_length - 1 self._value = self._value & mask def get_state(self) -> dict[str, Any]: - """ - Returns a dict of the register state. - These states are changable via set_states. - """ state = super().get_state() return state @@ -150,9 +179,6 @@ class IntegerRegister(Register): return parameter def set_state(self, state: dict[str, Any]) -> None: - """ - Sets the register state to one given in dict. - """ super().set_state(state) def save_state_to_file(self, file_path: str) -> None: @@ -177,8 +203,8 @@ class Flag(IntegerRegister): def __init__( self, - input_signal: Signal, - output_signal: Signal, + input: Signal, + output: Signal, bit_length=1, value=0, name="Flag", @@ -186,8 +212,8 @@ class Flag(IntegerRegister): # set the flags name super().__init__( - input_signal=input_signal, - output_signal=output_signal, + input=input, + output=output, bit_length=bit_length, value=value, name=name,