commit - release 1

2026-03-18 11:47:48 -07:00
commit 6f43807900
109 changed files with 14909 additions and 0 deletions
@@ -0,0 +1,184 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import IntEnum
+from typing import Literal
+
+MAX_51 = (1 << 51) - 1
+
+
+class PhysAddrError(Exception):
+    pass
+
+
+def _chk_range(name: str, v: int, bits: int) -> None:
+    if not (0 <= v < (1 << bits)):
+        raise PhysAddrError(f"{name} out of range for {bits} bits: {v}")
+
+
+def _chk_max(name: str, v: int, maxv: int) -> None:
+    if not (0 <= v <= maxv):
+        raise PhysAddrError(f"{name} out of range (0..{maxv}): {v}")
+
+
+class UnitType(IntEnum):
+    PE = 0
+    MCPU = 1
+    SRAM = 2
+
+
+@dataclass(frozen=True)
+class PhysAddr:
+    """
+    51-bit physical address value object.
+
+    Layout:
+      [50:47] rack_id  (4)
+      [46:43] sip_id   (4)
+      [42:38] sip_seg  (5)   # cube_id
+      [37:0]  local_offset (38) => each segment is 256GB
+
+    local_offset:
+      [37] selector: 1 = HBM window (128GB reserved), 0 = PE resource window
+    """
+
+    rack_id: int
+    sip_id: int
+    sip_seg: int
+    local_offset: int
+
+    kind: Literal["hbm", "pe_resource", "raw"] = "raw"
+    cube_id: int = 0
+    unit_type: UnitType = UnitType.PE
+    pe_id: int = 0
+    ext: int = 0
+    sub_offset: int = 0
+    hbm_offset: int = 0
+
+    HBM_WINDOW_BYTES = 1 << 37  # 128GB
+
+    def encode(self) -> int:
+        _chk_range("rack_id", self.rack_id, 4)
+        _chk_range("sip_id", self.sip_id, 4)
+        _chk_range("sip_seg", self.sip_seg, 5)
+        _chk_range("local_offset", self.local_offset, 38)
+        addr = (self.rack_id << 47) | (self.sip_id << 43) | (self.sip_seg << 38) | self.local_offset
+        if not (0 <= addr <= MAX_51):
+            raise PhysAddrError("address exceeds 51-bit space")
+        return addr
+
+    @staticmethod
+    def decode(addr: int) -> PhysAddr:
+        if not (0 <= addr <= MAX_51):
+            raise PhysAddrError("addr must be a 51-bit value")
+        rack = (addr >> 47) & 0xF
+        sip_id = (addr >> 43) & 0xF
+        sip_seg = (addr >> 38) & 0x1F
+        off = addr & ((1 << 38) - 1)
+        cube_id = sip_seg
+        sel = (off >> 37) & 0x1
+        if sel == 1:
+            hbm_offset = int(off & ((1 << 37) - 1))
+            return PhysAddr(
+                rack_id=rack,
+                sip_id=sip_id,
+                sip_seg=sip_seg,
+                local_offset=off,
+                kind="hbm",
+                cube_id=cube_id,
+                hbm_offset=hbm_offset,
+            )
+        # PE resource decode
+        raw_ut = int((off >> 34) & 0x7)
+        try:
+            unit_type = UnitType(raw_ut)
+        except ValueError:
+            raise PhysAddrError(f"unknown unit_type: {raw_ut}") from None
+        pe_id = int((off >> 30) & 0xF)
+        ext = int((off >> 29) & 0x1)
+        sub_offset = int(off & ((1 << 29) - 1))
+        return PhysAddr(
+            rack_id=rack,
+            sip_id=sip_id,
+            sip_seg=sip_seg,
+            local_offset=off,
+            kind="pe_resource",
+            cube_id=cube_id,
+            unit_type=unit_type,
+            pe_id=pe_id,
+            ext=ext,
+            sub_offset=sub_offset,
+            hbm_offset=0,
+        )
+
+    @staticmethod
+    def hbm_addr(*, rack_id: int, sip_id: int, cube_id: int, hbm_offset: int) -> PhysAddr:
+        _chk_max("cube_id", cube_id, 31)
+        _chk_range("hbm_offset", hbm_offset, 37)
+        sip_seg = cube_id
+        local_offset = (1 << 37) | int(hbm_offset)
+        return PhysAddr(
+            rack_id=rack_id,
+            sip_id=sip_id,
+            sip_seg=sip_seg,
+            local_offset=local_offset,
+            kind="hbm",
+            cube_id=cube_id,
+            hbm_offset=int(hbm_offset),
+        )
+
+    @staticmethod
+    def pe_hbm_addr(
+        *,
+        rack_id: int,
+        sip_id: int,
+        cube_id: int,
+        pe_id: int,
+        pe_local_hbm_offset: int,
+        slice_size_bytes: int,
+    ) -> PhysAddr:
+        _chk_max("cube_id", cube_id, 31)
+        _chk_range("pe_id", pe_id, 4)
+        if not (0 <= pe_local_hbm_offset < slice_size_bytes):
+            raise PhysAddrError("pe_local_hbm_offset out of PE local slice range")
+        hbm_offset = int(pe_id) * int(slice_size_bytes) + int(pe_local_hbm_offset)
+        if not (0 <= hbm_offset < PhysAddr.HBM_WINDOW_BYTES):
+            raise PhysAddrError("HBM offset exceeds reserved 128GB window")
+        return PhysAddr.hbm_addr(
+            rack_id=rack_id, sip_id=sip_id, cube_id=cube_id, hbm_offset=hbm_offset
+        )
+
+    @staticmethod
+    def hbm_pe_id(hbm_offset: int, slice_size_bytes: int) -> int:
+        return hbm_offset // slice_size_bytes
+
+    @staticmethod
+    def cube_sram_addr(
+        *, rack_id: int, sip_id: int, cube_id: int, sram_offset: int,
+    ) -> PhysAddr:
+        _chk_max("cube_id", cube_id, 31)
+        _chk_range("sram_offset", sram_offset, 29)
+        sip_seg = cube_id
+        local_offset = (UnitType.SRAM << 34) | sram_offset
+        return PhysAddr(
+            rack_id=rack_id, sip_id=sip_id, sip_seg=sip_seg,
+            local_offset=local_offset,
+            kind="pe_resource", cube_id=cube_id,
+            unit_type=UnitType.SRAM, sub_offset=sram_offset,
+        )
+
+    @staticmethod
+    def pe_tcm_addr(
+        *, rack_id: int, sip_id: int, cube_id: int, pe_id: int, tcm_offset: int,
+    ) -> PhysAddr:
+        _chk_max("cube_id", cube_id, 31)
+        _chk_range("pe_id", pe_id, 4)
+        _chk_range("tcm_offset", tcm_offset, 29)
+        sip_seg = cube_id
+        local_offset = (UnitType.PE << 34) | (pe_id << 30) | tcm_offset
+        return PhysAddr(
+            rack_id=rack_id, sip_id=sip_id, sip_seg=sip_seg,
+            local_offset=local_offset,
+            kind="pe_resource", cube_id=cube_id,
+            unit_type=UnitType.PE, pe_id=pe_id, sub_offset=tcm_offset,
+        )