More field docs

coreblocks/fu/fu_decoder.py

@@ -21,7 +21,7 @@ class Decoder(Elaboratable):
     def __init__(self, gen_params: GenParams, decode_fn: Type[IntFlag], ops: Sequence[tuple], check_optype: bool):
         layouts = gen_params.get(CommonLayoutFields)
 
-        self.exec_fn = Record(layouts.exec_fn[1])
+        self.exec_fn = Record(layouts.exec_fn_layout)
         self.decode_fn = Signal(decode_fn)
         self.ops = ops
         self.check_optype = check_optype

coreblocks/params/layouts.py

@@ -1,7 +1,7 @@
 from coreblocks.params import GenParams, OpType, Funct7, Funct3
 from coreblocks.params.isa import ExceptionCause
 from coreblocks.utils.utils import layout_subset
-from coreblocks.utils import LayoutList
+from coreblocks.utils import LayoutList, LayoutListField
 
 __all__ = [
     "CommonLayoutFields",
@@ -25,86 +25,92 @@ class CommonLayoutFields:
     """Commonly used layout fields."""
 
     def __init__(self, gen_params: GenParams):
-        self.op_type = ("op_type", OpType)
+        self.op_type: LayoutListField = ("op_type", OpType)
         """Decoded operation type."""
 
-        self.funct3 = ("funct3", Funct3)
+        self.funct3: LayoutListField = ("funct3", Funct3)
         """RISC V funct3 value."""
 
-        self.funct7 = ("funct7", Funct7)
+        self.funct7: LayoutListField = ("funct7", Funct7)
         """RISC V funct7 value."""
 
-        self.rl_s1 = ("rl_s1", gen_params.isa.reg_cnt_log)
+        self.rl_s1: LayoutListField = ("rl_s1", gen_params.isa.reg_cnt_log)
         """Logical register number of first source operand."""
 
-        self.rl_s2 = ("rl_s2", gen_params.isa.reg_cnt_log)
+        self.rl_s2: LayoutListField = ("rl_s2", gen_params.isa.reg_cnt_log)
         """Logical register number of second source operand."""
 
-        self.rl_dst = ("rl_dst", gen_params.isa.reg_cnt_log)
+        self.rl_dst: LayoutListField = ("rl_dst", gen_params.isa.reg_cnt_log)
         """Logical register number of destination operand."""
 
-        self.rp_s1 = ("rp_s1", gen_params.phys_regs_bits)
+        self.rp_s1: LayoutListField = ("rp_s1", gen_params.phys_regs_bits)
         """Physical register number of first source operand."""
 
-        self.rp_s2 = ("rp_s2", gen_params.phys_regs_bits)
+        self.rp_s2: LayoutListField = ("rp_s2", gen_params.phys_regs_bits)
         """Physical register number of second source operand."""
 
-        self.rp_dst = ("rp_dst", gen_params.phys_regs_bits)
+        self.rp_dst: LayoutListField = ("rp_dst", gen_params.phys_regs_bits)
         """Physical register number of destination operand."""
 
-        self.imm = ("imm", gen_params.isa.xlen)
+        self.imm: LayoutListField = ("imm", gen_params.isa.xlen)
         """Immediate value."""
 
-        self.csr = ("csr", gen_params.isa.csr_alen)
+        self.csr: LayoutListField = ("csr", gen_params.isa.csr_alen)
         """CSR number."""
 
-        self.pc = ("pc", gen_params.isa.xlen)
+        self.pc: LayoutListField = ("pc", gen_params.isa.xlen)
         """Program counter value."""
 
-        self.rob_id = ("rob_id", gen_params.rob_entries_bits)
+        self.rob_id: LayoutListField = ("rob_id", gen_params.rob_entries_bits)
         """Reorder buffer entry identifier."""
 
-        self.s1_val = ("s1_val", gen_params.isa.xlen)
+        self.s1_val: LayoutListField = ("s1_val", gen_params.isa.xlen)
         """Value of first source operand."""
 
-        self.s2_val = ("s2_val", gen_params.isa.xlen)
+        self.s2_val: LayoutListField = ("s2_val", gen_params.isa.xlen)
         """Value of second source operand."""
 
-        self.addr = ("addr", gen_params.isa.xlen)
+        self.addr: LayoutListField = ("addr", gen_params.isa.xlen)
         """Memory address."""
 
-        self.data = ("data", gen_params.isa.xlen)
+        self.data: LayoutListField = ("data", gen_params.isa.xlen)
         """Piece of data."""
 
-        self.instr = ("instr", gen_params.isa.ilen)
+        self.instr: LayoutListField = ("instr", gen_params.isa.ilen)
         """RISC V instruction."""
 
-        self.exec_fn = ("exec_fn", [self.op_type, self.funct3, self.funct7])
+        self.exec_fn_layout: LayoutList = [self.op_type, self.funct3, self.funct7]
+        """Decoded instruction, in layout form."""
+
+        self.exec_fn: LayoutListField = ("exec_fn", self.exec_fn_layout)
         """Decoded instruction."""
 
-        self.regs_l = ("regs_l", [self.rl_s1, self.rl_s2, self.rl_dst])
+        self.regs_l: LayoutListField = ("regs_l", [self.rl_s1, self.rl_s2, self.rl_dst])
         """Logical register numbers - as described in the RISC V manual. They index the RATs."""
 
-        self.regs_p = ("regs_p", [self.rp_s1, self.rp_s2, self.rp_dst])
+        self.regs_p: LayoutListField = ("regs_p", [self.rp_s1, self.rp_s2, self.rp_dst])
         """Physical register numbers. They index the register file."""
 
-        self.reg_id = ("reg_id", gen_params.phys_regs_bits)
+        self.reg_id: LayoutListField = ("reg_id", gen_params.phys_regs_bits)
         """Physical register ID."""
 
+        self.exception: LayoutListField = ("exception", 1)
+        """Exception is raised for this instruction."""
+
 
 class SchedulerLayouts:
     """Layouts used in the scheduler."""
 
     def __init__(self, gen_params: GenParams):
         fields = gen_params.get(CommonLayoutFields)
 
-        self.rs_selected = ("rs_selected", gen_params.rs_number_bits)
+        self.rs_selected: LayoutListField = ("rs_selected", gen_params.rs_number_bits)
         """Reservation Station number for the instruction."""
 
-        self.rs_entry_id = ("rs_entry_id", gen_params.max_rs_entries_bits)
+        self.rs_entry_id: LayoutListField = ("rs_entry_id", gen_params.max_rs_entries_bits)
         """Reservation station entry ID for the instruction."""
 
-        self.regs_p_alloc_out = ("regs_p", [fields.rp_dst])
+        self.regs_p_alloc_out: LayoutListField = ("regs_p", [fields.rp_dst])
         """Physical register number for the destination operand, after allocation."""
 
         self.regs_l_rob_in = (
@@ -171,8 +177,8 @@ class RFLayouts:
     def __init__(self, gen_params: GenParams):
         fields = gen_params.get(CommonLayoutFields)
 
-        self.valid = ("valid", 1)
-        """Bit flag, says that the physical register was assigned a value."""
+        self.valid: LayoutListField = ("valid", 1)
+        """Physical register was assigned a value."""
 
         self.rf_read_in = self.rf_free = [fields.reg_id]
         self.rf_read_out = [("reg_val", gen_params.isa.xlen), self.valid]
@@ -185,7 +191,7 @@ class RATLayouts:
     def __init__(self, gen_params: GenParams):
         fields = gen_params.get(CommonLayoutFields)
 
-        self.old_rp_dst = ("old_rp_dst", gen_params.phys_regs_bits)
+        self.old_rp_dst: LayoutListField = ("old_rp_dst", gen_params.phys_regs_bits)
         """Physical register previously associated with the given logical register in RRAT."""
 
         self.rat_rename_in = [
@@ -208,42 +214,56 @@ class ROBLayouts:
     def __init__(self, gen_params: GenParams):
         fields = gen_params.get(CommonLayoutFields)
 
-        self.data_layout = [
+        self.data_layout: LayoutList = [
             fields.rl_dst,
             fields.rp_dst,
         ]
 
-        self.id_layout = [fields.rob_id]
+        self.rob_data: LayoutListField = ("rob_data", self.data_layout)
+        """Data stored in a reorder buffer entry."""
+
+        self.done: LayoutListField = ("done", 1)
+        """Instruction has executed, but is not committed yet."""
+
+        self.start: LayoutListField = ("start", gen_params.rob_entries_bits)
+        """Index of the first (the earliest) entry in the reorder buffer."""
 
-        self.internal_layout = [
-            ("rob_data", self.data_layout),
-            ("done", 1),
-            ("exception", 1),
+        self.end: LayoutListField = ("end", gen_params.rob_entries_bits)
+        """Index of the entry following the last (the latest) entry in the reorder buffer."""
+
+        self.id_layout: LayoutList = [fields.rob_id]
+
+        self.internal_layout: LayoutList = [
+            self.rob_data,
+            self.done,
+            fields.exception,
         ]
 
-        self.mark_done_layout = [
+        self.mark_done_layout: LayoutList = [
             fields.rob_id,
-            ("exception", 1),
+            fields.exception,
         ]
 
-        self.peek_layout = self.retire_layout = [
-            ("rob_data", self.data_layout),
+        self.peek_layout: LayoutList = [
+            self.rob_data,
             fields.rob_id,
-            ("exception", 1),
+            fields.exception,
         ]
 
-        self.get_indices = [("start", gen_params.rob_entries_bits), ("end", gen_params.rob_entries_bits)]
+        self.retire_layout: LayoutList = self.peek_layout
+
+        self.get_indices: LayoutList = [self.start, self.end]
 
 
 class RSLayoutFields:
     """Layout fields used in the reservation station."""
 
     def __init__(self, gen_params: GenParams, *, rs_entries_bits: int, data_layout: LayoutList):
-        self.rs_data = ("rs_data", data_layout)
-        """Data about an instuction stored in a Reservation Station."""
+        self.rs_data: LayoutListField = ("rs_data", data_layout)
+        """Data about an instuction stored in a reservation station (RS)."""
 
-        self.rs_entry_id = ("rs_entry_id", rs_entries_bits)
-        """Index in a Reservation Station."""
+        self.rs_entry_id: LayoutListField = ("rs_entry_id", rs_entries_bits)
+        """Index in a reservation station (RS)."""
 
 
 class RSFullDataLayout:
@@ -366,10 +386,10 @@ class FetchLayouts:
     def __init__(self, gen_params: GenParams):
         fields = gen_params.get(CommonLayoutFields)
 
-        self.access_fault = ("access_fault", 1)
+        self.access_fault: LayoutListField = ("access_fault", 1)
         """Bit flag, says that instruction fetch failed."""
 
-        self.rvc = ("rvc", 1)
+        self.rvc: LayoutListField = ("rvc", 1)
         """Bit flag, says that an instruction is a compressed (two-byte) one."""
 
         self.raw_instr = [
@@ -406,12 +426,9 @@ class FuncUnitLayouts:
     def __init__(self, gen_params: GenParams):
         fields = gen_params.get(CommonLayoutFields)
 
-        self.result = ("result", gen_params.isa.xlen)
+        self.result: LayoutListField = ("result", gen_params.isa.xlen)
         """The result value produced in a functional unit."""
 
-        self.exception = ("exception", 1)
-        """Bit flag, signals that the operation generated an exception."""
-
         self.issue = [
             fields.s1_val,
             fields.s2_val,
@@ -426,7 +443,7 @@ def __init__(self, gen_params: GenParams):
             fields.rob_id,
             self.result,
             fields.rp_dst,
-            self.exception,
+            fields.exception,
         ]
 
 

coreblocks/utils/_typing.py

@@ -30,7 +30,8 @@
 
 # Internal Coreblocks types
 SignalBundle: TypeAlias = Signal | Record | View | Iterable["SignalBundle"] | Mapping[str, "SignalBundle"]
-LayoutList: TypeAlias = list[tuple[str, "ShapeLike | LayoutList"]]
+LayoutListField: TypeAlias = tuple[str, "ShapeLike | LayoutList"]
+LayoutList: TypeAlias = list[LayoutListField]
 
 RecordIntDict: TypeAlias = Mapping[str, Union[int, "RecordIntDict"]]
 RecordIntDictRet: TypeAlias = Mapping[str, Any]  # full typing hard to work with