dau-core 0.1.0__py3-none-any.whl

dau_core/__init__.py

@@ -0,0 +1,60 @@
+from .aggregations import EmptyInputError, UnsupportedAggregationError, aggregate_values, synthetic_values
+from .capabilities import DeviceCapabilities, DmaConstraints, OperatorCapability
+from .registers import (
+    DAU_MAGIC_WORD,
+    DEFAULT_STREAM_JOB_REGISTER_CONTRACT,
+    JobControlFlag,
+    JobStatusFlag,
+    RegisterBlockSnapshot,
+    RegisterMapVersion,
+    RegisterOffset,
+    RegisterWriteError,
+    ResetScope,
+    StreamJobRegisterContract,
+    StreamProtocolVersion,
+)
+from .stream import (
+    BatchHeader,
+    ColumnDescriptor,
+    GroupRole,
+    InvalidStreamError,
+    LogicalType,
+    OperationCode,
+    OperationDescriptor,
+    PolicyFlag,
+    StreamAggregationErrorCode,
+    StreamFlag,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "BatchHeader",
+    "ColumnDescriptor",
+    "DAU_MAGIC_WORD",
+    "DEFAULT_STREAM_JOB_REGISTER_CONTRACT",
+    "DeviceCapabilities",
+    "DmaConstraints",
+    "EmptyInputError",
+    "GroupRole",
+    "InvalidStreamError",
+    "JobControlFlag",
+    "JobStatusFlag",
+    "LogicalType",
+    "OperationCode",
+    "OperationDescriptor",
+    "OperatorCapability",
+    "PolicyFlag",
+    "RegisterMapVersion",
+    "RegisterBlockSnapshot",
+    "RegisterOffset",
+    "RegisterWriteError",
+    "ResetScope",
+    "StreamAggregationErrorCode",
+    "StreamFlag",
+    "StreamJobRegisterContract",
+    "StreamProtocolVersion",
+    "UnsupportedAggregationError",
+    "aggregate_values",
+    "synthetic_values",
+]

dau_core/aggregations.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import math
+from collections.abc import Iterable
+
+from .stream import LogicalType, OperationCode
+
+
+class EmptyInputError(ValueError):
+    pass
+
+
+class UnsupportedAggregationError(ValueError):
+    pass
+
+
+_INTEGER_RANGES = {
+    LogicalType.INT8: (-(1 << 7), (1 << 7) - 1),
+    LogicalType.INT16: (-(1 << 15), (1 << 15) - 1),
+    LogicalType.INT32: (-(1 << 31), (1 << 31) - 1),
+    LogicalType.INT64: (-(1 << 63), (1 << 63) - 1),
+    LogicalType.UINT8: (0, (1 << 8) - 1),
+    LogicalType.UINT16: (0, (1 << 16) - 1),
+    LogicalType.UINT32: (0, (1 << 32) - 1),
+    LogicalType.UINT64: (0, (1 << 64) - 1),
+}
+
+_FLOAT_TYPES = {LogicalType.FLOAT32, LogicalType.FLOAT64}
+
+
+def aggregate_values(opcode: OperationCode, values: Iterable[int | float | bool], logical_type: LogicalType) -> int | float:
+    materialized_values = list(values)
+
+    if opcode == OperationCode.COUNT:
+        return len(materialized_values)
+
+    if not materialized_values:
+        if opcode == OperationCode.SUM:
+            return 0.0 if logical_type in _FLOAT_TYPES else 0
+        raise EmptyInputError(f"{opcode.name.lower()} requires at least one value")
+
+    if logical_type in _FLOAT_TYPES and any(_is_nan(value) for value in materialized_values):
+        return math.nan
+
+    if opcode == OperationCode.MIN:
+        return min(materialized_values)
+    if opcode == OperationCode.MAX:
+        return max(materialized_values)
+    if opcode == OperationCode.SUM:
+        return _sum_values(materialized_values, logical_type)
+    if opcode == OperationCode.AVERAGE:
+        return float(sum(materialized_values) / len(materialized_values))
+
+    raise UnsupportedAggregationError(f"unsupported operation {opcode!r}")
+
+
+def synthetic_values(name: str, logical_type: LogicalType) -> list[int | float | bool]:
+    if name == "empty":
+        return []
+    if name == "one":
+        return [1.0] if logical_type in _FLOAT_TYPES else [1]
+    if name == "odd_ints":
+        return [-3, -1, 0, 1, 3]
+    if name == "with_nan":
+        if logical_type not in _FLOAT_TYPES:
+            raise ValueError("with_nan fixture requires a floating-point logical type")
+        return [1.0, math.nan, 3.0]
+    if name == "repeated":
+        return [2.0, 2.0, 2.0, 2.0] if logical_type in _FLOAT_TYPES else [2, 2, 2, 2]
+    if name == "sorted":
+        return [1.0, 2.0, 3.0, 4.0] if logical_type in _FLOAT_TYPES else [1, 2, 3, 4]
+    if name == "skewed":
+        return [0.0, 0.0, 0.0, 99.0] if logical_type in _FLOAT_TYPES else [0, 0, 0, 99]
+    if name == "bounds":
+        return _bounds_fixture(logical_type)
+    raise ValueError(f"unknown synthetic fixture {name!r}")
+
+
+def _sum_values(values: list[int | float | bool], logical_type: LogicalType) -> int | float:
+    total = sum(values)
+    if logical_type in _INTEGER_RANGES:
+        minimum, maximum = _INTEGER_RANGES[logical_type]
+        return min(max(int(total), minimum), maximum)
+    if logical_type in _FLOAT_TYPES:
+        return float(total)
+    raise UnsupportedAggregationError(f"sum does not support {logical_type.name.lower()}")
+
+
+def _bounds_fixture(logical_type: LogicalType) -> list[int | float | bool]:
+    if logical_type in _INTEGER_RANGES:
+        minimum, maximum = _INTEGER_RANGES[logical_type]
+        return [minimum, 0, maximum]
+    if logical_type in _FLOAT_TYPES:
+        return [-math.inf, 0.0, math.inf]
+    if logical_type == LogicalType.BOOL:
+        return [False, True]
+    raise ValueError(f"no bounds fixture for {logical_type.name.lower()}")
+
+
+def _is_nan(value: int | float | bool) -> bool:
+    return isinstance(value, float) and math.isnan(value)

dau_core/capabilities.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .registers import RegisterMapVersion, StreamProtocolVersion
+from .stream import LogicalType, OperationCode
+
+
+@dataclass(frozen=True)
+class DmaConstraints:
+    alignment_bytes: int
+    descriptor_bytes: int
+    max_transfer_bytes: int
+    read_channels: int
+    write_channels: int
+
+    def __post_init__(self) -> None:
+        if self.alignment_bytes <= 0:
+            raise ValueError("alignment_bytes must be positive")
+        if self.descriptor_bytes <= 0:
+            raise ValueError("descriptor_bytes must be positive")
+        if self.max_transfer_bytes <= 0:
+            raise ValueError("max_transfer_bytes must be positive")
+        if self.read_channels < 0 or self.write_channels < 0:
+            raise ValueError("DMA channel counts cannot be negative")
+
+    def is_aligned(self, value: int) -> bool:
+        return value % self.alignment_bytes == 0
+
+    @property
+    def max_aligned_transfer_bytes(self) -> int:
+        return self.max_transfer_bytes - (self.max_transfer_bytes % self.alignment_bytes)
+
+
+@dataclass(frozen=True)
+class OperatorCapability:
+    opcode: OperationCode
+    input_types: tuple[LogicalType, ...]
+    output_type: LogicalType
+    supports_group_by: bool
+
+    def supports(self, opcode: OperationCode, logical_type: LogicalType) -> bool:
+        return self.opcode == opcode and logical_type in self.input_types
+
+
+@dataclass(frozen=True)
+class DeviceCapabilities:
+    platform_id: str
+    pci_vendor_id: int
+    pci_device_id: int
+    register_map_version: RegisterMapVersion
+    stream_protocol_version: StreamProtocolVersion
+    dma: DmaConstraints
+    operators: tuple[OperatorCapability, ...]
+
+    def supports(self, opcode: OperationCode, logical_type: LogicalType) -> bool:
+        return any(operator.supports(opcode, logical_type) for operator in self.operators)

dau_core/hdl/__init__.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from importlib.resources import files
+
+DAU_IDENTITY_REGISTERS_SV = files(__package__).joinpath("dau_identity_registers.sv")
+DAU_IDENTITY_AXIL_V = files(__package__).joinpath("dau_identity_axil.v")
+DAU_INT32_AGGREGATION_TILE_SV = files(__package__).joinpath("dau_int32_aggregation_tile.sv")
+DAU_INT32_STREAM_AGGREGATION_SV = files(__package__).joinpath("dau_int32_stream_aggregation.sv")
+DAU_INT32_ARROW_LITE_STREAM_AGGREGATION_SV = files(__package__).joinpath("dau_int32_arrow_lite_stream_aggregation.sv")
+
+__all__ = (
+    "DAU_IDENTITY_AXIL_V",
+    "DAU_IDENTITY_REGISTERS_SV",
+    "DAU_INT32_AGGREGATION_TILE_SV",
+    "DAU_INT32_ARROW_LITE_STREAM_AGGREGATION_SV",
+    "DAU_INT32_STREAM_AGGREGATION_SV",
+)

dau_core/hdl/dau_identity_axil.v

@@ -0,0 +1,129 @@
+`default_nettype none
+
+module dau_identity_axil #(
+    parameter [31:0] REGISTER_MAP_VERSION = 32'h0000_0001,
+    parameter [31:0] STREAM_PROTOCOL_VERSION = 32'h0000_0001,
+    parameter [31:0] PLATFORM_ID = 32'h4554_494e,
+    parameter [31:0] SHELL_VERSION = 32'h0000_0000,
+    parameter [63:0] BUILD_ID = 64'h0000_0000_0000_0000,
+    parameter [31:0] STATUS = 32'h0000_0000,
+    parameter [31:0] DMA_CONSTRAINTS = 32'h0000_0000,
+    parameter [31:0] OPERATOR_BITMAP = 32'h0000_0000,
+    parameter [31:0] LAST_ERROR = 32'h0000_0000,
+    parameter [63:0] H2C_BYTES = 64'h0000_0000_0000_0000,
+    parameter [63:0] C2H_BYTES = 64'h0000_0000_0000_0000,
+    parameter [63:0] ROWS = 64'h0000_0000_0000_0000,
+    parameter [31:0] BATCHES = 32'h0000_0000,
+    parameter [31:0] STALLS = 32'h0000_0000
+) (
+    (* X_INTERFACE_INFO = "xilinx.com:signal:clock:1.0 s_axi_aclk CLK" *)
+    (* X_INTERFACE_PARAMETER = "ASSOCIATED_BUSIF S_AXI, ASSOCIATED_RESET s_axi_aresetn" *)
+    input wire s_axi_aclk,
+    (* X_INTERFACE_INFO = "xilinx.com:signal:reset:1.0 s_axi_aresetn RST" *)
+    (* X_INTERFACE_PARAMETER = "POLARITY ACTIVE_LOW" *)
+    input wire s_axi_aresetn,
+
+    (* X_INTERFACE_INFO = "xilinx.com:interface:aximm:1.0 S_AXI AWADDR" *)
+    (* X_INTERFACE_PARAMETER = "XIL_INTERFACENAME S_AXI, PROTOCOL AXI4LITE, DATA_WIDTH 32, ADDR_WIDTH 16, HAS_BURST 0, HAS_LOCK 0, HAS_PROT 0, HAS_CACHE 0, HAS_QOS 0, HAS_REGION 0, HAS_WSTRB 1, HAS_BRESP 1, HAS_RRESP 1" *)
+    input wire [15:0] s_axi_awaddr,
+    (* X_INTERFACE_INFO = "xilinx.com:interface:aximm:1.0 S_AXI AWVALID" *)
+    input wire s_axi_awvalid,
+    (* X_INTERFACE_INFO = "xilinx.com:interface:aximm:1.0 S_AXI AWREADY" *)
+    output reg s_axi_awready,
+    (* X_INTERFACE_INFO = "xilinx.com:interface:aximm:1.0 S_AXI WDATA" *)
+    input wire [31:0] s_axi_wdata,
+    (* X_INTERFACE_INFO = "xilinx.com:interface:aximm:1.0 S_AXI WSTRB" *)
+    input wire [3:0] s_axi_wstrb,
+    (* X_INTERFACE_INFO = "xilinx.com:interface:aximm:1.0 S_AXI WVALID" *)
+    input wire s_axi_wvalid,
+    (* X_INTERFACE_INFO = "xilinx.com:interface:aximm:1.0 S_AXI WREADY" *)
+    output reg s_axi_wready,
+    (* X_INTERFACE_INFO = "xilinx.com:interface:aximm:1.0 S_AXI BRESP" *)
+    output wire [1:0] s_axi_bresp,
+    (* X_INTERFACE_INFO = "xilinx.com:interface:aximm:1.0 S_AXI BVALID" *)
+    output reg s_axi_bvalid,
+    (* X_INTERFACE_INFO = "xilinx.com:interface:aximm:1.0 S_AXI BREADY" *)
+    input wire s_axi_bready,
+    (* X_INTERFACE_INFO = "xilinx.com:interface:aximm:1.0 S_AXI ARADDR" *)
+    input wire [15:0] s_axi_araddr,
+    (* X_INTERFACE_INFO = "xilinx.com:interface:aximm:1.0 S_AXI ARVALID" *)
+    input wire s_axi_arvalid,
+    (* X_INTERFACE_INFO = "xilinx.com:interface:aximm:1.0 S_AXI ARREADY" *)
+    output reg s_axi_arready,
+    (* X_INTERFACE_INFO = "xilinx.com:interface:aximm:1.0 S_AXI RDATA" *)
+    output reg [31:0] s_axi_rdata,
+    (* X_INTERFACE_INFO = "xilinx.com:interface:aximm:1.0 S_AXI RRESP" *)
+    output wire [1:0] s_axi_rresp,
+    (* X_INTERFACE_INFO = "xilinx.com:interface:aximm:1.0 S_AXI RVALID" *)
+    output reg s_axi_rvalid,
+    (* X_INTERFACE_INFO = "xilinx.com:interface:aximm:1.0 S_AXI RREADY" *)
+    input wire s_axi_rready,
+
+    output wire [31:0] reset_request
+);
+    wire write_fire;
+    wire read_fire;
+    wire [15:0] selected_addr;
+    wire [15:0] identity_addr;
+    wire [31:0] identity_rdata;
+
+    assign write_fire = !s_axi_bvalid && s_axi_awvalid && s_axi_wvalid;
+    assign read_fire = !write_fire && !s_axi_rvalid && s_axi_arvalid;
+    assign selected_addr = write_fire ? s_axi_awaddr : s_axi_araddr;
+    assign identity_addr = {4'h0, selected_addr[11:0]};
+    assign s_axi_bresp = 2'b00;
+    assign s_axi_rresp = 2'b00;
+
+    dau_identity_registers #(
+        .REGISTER_MAP_VERSION(REGISTER_MAP_VERSION),
+        .STREAM_PROTOCOL_VERSION(STREAM_PROTOCOL_VERSION),
+        .PLATFORM_ID(PLATFORM_ID),
+        .SHELL_VERSION(SHELL_VERSION),
+        .BUILD_ID(BUILD_ID),
+        .STATUS(STATUS),
+        .DMA_CONSTRAINTS(DMA_CONSTRAINTS),
+        .OPERATOR_BITMAP(OPERATOR_BITMAP),
+        .LAST_ERROR(LAST_ERROR),
+        .H2C_BYTES(H2C_BYTES),
+        .C2H_BYTES(C2H_BYTES),
+        .ROWS(ROWS),
+        .BATCHES(BATCHES),
+        .STALLS(STALLS)
+    ) identity_registers (
+        .addr(identity_addr),
+        .wen(write_fire),
+        .wdata(s_axi_wdata),
+        .reset_request(reset_request),
+        .rdata(identity_rdata)
+    );
+
+    always @(posedge s_axi_aclk) begin
+        if (!s_axi_aresetn) begin
+            s_axi_awready <= 1'b0;
+            s_axi_wready <= 1'b0;
+            s_axi_bvalid <= 1'b0;
+            s_axi_arready <= 1'b0;
+            s_axi_rdata <= 32'h0000_0000;
+            s_axi_rvalid <= 1'b0;
+        end else begin
+            s_axi_awready <= write_fire;
+            s_axi_wready <= write_fire;
+            s_axi_arready <= read_fire;
+
+            if (write_fire) begin
+                s_axi_bvalid <= 1'b1;
+            end else if (s_axi_bvalid && s_axi_bready) begin
+                s_axi_bvalid <= 1'b0;
+            end
+
+            if (read_fire) begin
+                s_axi_rdata <= identity_rdata;
+                s_axi_rvalid <= 1'b1;
+            end else if (s_axi_rvalid && s_axi_rready) begin
+                s_axi_rvalid <= 1'b0;
+            end
+        end
+    end
+endmodule
+
+`default_nettype wire

dau_core/hdl/dau_identity_registers.sv

@@ -0,0 +1,51 @@
+`default_nettype none
+
+module dau_identity_registers #(
+    parameter logic [31:0] REGISTER_MAP_VERSION = 32'h0000_0001,
+    parameter logic [31:0] STREAM_PROTOCOL_VERSION = 32'h0000_0001,
+    parameter logic [31:0] PLATFORM_ID = 32'h4554_494e,
+    parameter logic [31:0] SHELL_VERSION = 32'h0000_0000,
+    parameter logic [63:0] BUILD_ID = 64'h0000_0000_0000_0000,
+    parameter logic [31:0] STATUS = 32'h0000_0000,
+    parameter logic [31:0] DMA_CONSTRAINTS = 32'h0000_0000,
+    parameter logic [31:0] OPERATOR_BITMAP = 32'h0000_0000,
+    parameter logic [31:0] LAST_ERROR = 32'h0000_0000,
+    parameter logic [63:0] H2C_BYTES = 64'h0000_0000_0000_0000,
+    parameter logic [63:0] C2H_BYTES = 64'h0000_0000_0000_0000,
+    parameter logic [63:0] ROWS = 64'h0000_0000_0000_0000,
+    parameter logic [31:0] BATCHES = 32'h0000_0000,
+    parameter logic [31:0] STALLS = 32'h0000_0000
+) (
+    input  wire logic [15:0] addr,
+    input  wire logic        wen,
+    input  wire logic [31:0] wdata,
+    output logic [31:0] reset_request,
+    output logic [31:0] rdata
+);
+    assign reset_request = (wen && (addr == 16'h0020)) ? wdata : 32'h0000_0000;
+
+    assign rdata =
+        (addr == 16'h0000) ? 32'h4441_5531 :
+        (addr == 16'h0004) ? REGISTER_MAP_VERSION :
+        (addr == 16'h0008) ? STREAM_PROTOCOL_VERSION :
+        (addr == 16'h000c) ? PLATFORM_ID :
+        (addr == 16'h0010) ? SHELL_VERSION :
+        (addr == 16'h0014) ? BUILD_ID[31:0] :
+        (addr == 16'h0018) ? BUILD_ID[63:32] :
+        (addr == 16'h001c) ? STATUS :
+        (addr == 16'h0020) ? 32'h0000_0000 :
+        (addr == 16'h0024) ? DMA_CONSTRAINTS :
+        (addr == 16'h0028) ? OPERATOR_BITMAP :
+        (addr == 16'h002c) ? LAST_ERROR :
+        (addr == 16'h0030) ? H2C_BYTES[31:0] :
+        (addr == 16'h0034) ? H2C_BYTES[63:32] :
+        (addr == 16'h0038) ? C2H_BYTES[31:0] :
+        (addr == 16'h003c) ? C2H_BYTES[63:32] :
+        (addr == 16'h0040) ? ROWS[31:0] :
+        (addr == 16'h0044) ? ROWS[63:32] :
+        (addr == 16'h0048) ? BATCHES :
+        (addr == 16'h004c) ? STALLS :
+        32'hffff_ffff;
+endmodule
+
+`default_nettype wire

dau_core/hdl/dau_int32_aggregation_tile.sv

@@ -0,0 +1,90 @@
+`default_nettype none
+
+module dau_int32_aggregation_tile (
+    input  wire logic              clk,
+    input  wire logic              rst,
+    input  wire logic              input_valid,
+    output logic                   input_ready,
+    input  wire logic              input_last,
+    input  wire logic signed [31:0] input_value,
+    input  wire logic [2:0]        input_opcode,
+    output logic                   result_valid,
+    input  wire logic              result_ready,
+    output logic signed [63:0]     result_value,
+    output logic                   error
+);
+    localparam logic [2:0] OP_MIN   = 3'd1;
+    localparam logic [2:0] OP_MAX   = 3'd2;
+    localparam logic [2:0] OP_SUM   = 3'd3;
+    localparam logic [2:0] OP_COUNT = 3'd4;
+
+    logic signed [63:0] accumulator;
+    logic signed [63:0] sample_value;
+    logic signed [63:0] next_accumulator;
+    logic [63:0]        sample_count;
+    logic [63:0]        next_sample_count;
+
+    assign input_ready = !result_valid;
+    assign sample_value = {{32{input_value[31]}}, input_value};
+    assign next_sample_count = sample_count + 64'd1;
+
+    always_comb begin
+        unique case (input_opcode)
+            OP_MIN: begin
+                next_accumulator = (sample_count == 64'd0) ? sample_value : ((sample_value < accumulator) ? sample_value : accumulator);
+            end
+            OP_MAX: begin
+                next_accumulator = (sample_count == 64'd0) ? sample_value : ((sample_value > accumulator) ? sample_value : accumulator);
+            end
+            OP_SUM: begin
+                next_accumulator = (sample_count == 64'd0) ? sample_value : (accumulator + sample_value);
+            end
+            OP_COUNT: begin
+                next_accumulator = $signed(next_sample_count);
+            end
+            default: begin
+                next_accumulator = 64'sd0;
+            end
+        endcase
+    end
+
+    always_ff @(posedge clk) begin
+        if (rst) begin
+            accumulator <= 64'sd0;
+            sample_count <= 64'd0;
+            result_valid <= 1'b0;
+            result_value <= 64'sd0;
+            error <= 1'b0;
+        end else if (result_valid) begin
+            if (result_ready) begin
+                result_valid <= 1'b0;
+                error <= 1'b0;
+            end
+        end else if (input_valid && input_ready) begin
+            unique case (input_opcode)
+                OP_MIN, OP_MAX, OP_SUM, OP_COUNT: begin
+                    error <= 1'b0;
+                    if (input_last) begin
+                        accumulator <= 64'sd0;
+                        sample_count <= 64'd0;
+                        result_value <= next_accumulator;
+                        result_valid <= 1'b1;
+                    end else begin
+                        accumulator <= next_accumulator;
+                        sample_count <= next_sample_count;
+                        result_valid <= 1'b0;
+                    end
+                end
+                default: begin
+                    accumulator <= 64'sd0;
+                    sample_count <= 64'd0;
+                    result_value <= 64'sd0;
+                    result_valid <= 1'b1;
+                    error <= 1'b1;
+                end
+            endcase
+        end
+    end
+endmodule
+
+`default_nettype wire