dau_driver.capability_decode

Shared register-block decode semantics for every DAU transport backend.

linux-xdma, macos-xdma, and the device layer all decode the same identity window; one definition here so a semantics change cannot silently diverge the backends (they were verbatim copies before, and had already drifted).

Attributes

REGISTER_BITMAP_INPUT_TYPES
REGISTER_WINDOW_OFFSETS
NOT_ADVERTISED_REGISTER_MAP_VERSION

Functions

decode_platform_id(value) → str	The platform id as ASCII, or "" when the word is not one. A board
decode_register_map_version(value) → dau_core.registers.RegisterMapVersion	Decode the register-map version word.
_typed_operators_from_bitmap(bitmap, input_types) → tuple[dau_core.capabilities.OperatorCapability, ...]
operators_from_snapshot(snapshot) → tuple[tuple[dau_core.capabilities.OperatorCapability, ...], tuple[dau_core.capabilities.OperatorCapability, ...]]	(hardware operators, host-computed operators) from the identity
contract_from_manifest_metadata(metadata) → dau_core.capability_contract.CapabilityContract | None	The machine-readable capability contract a shell-build manifest
operators_from_contract(contract) → tuple[tuple[dau_core.capabilities.OperatorCapability, ...], tuple[dau_core.capabilities.OperatorCapability, ...]]	(hardware operators, host-computed operators) from the concrete
_capability_word(read_register, offset) → int
_build_id(read_register) → int	The shell's 64-bit build identity, as TWO 32-bit reads.
_capability_words(read_register, register_map_version) → dict[str, int]	The composed-capability words, read only from a shell that
read_register_block_snapshot(read_register) → dau_core.registers.RegisterBlockSnapshot	Discovery-time identity snapshot; read_register abstracts the

Module Contents

dau_driver.capability_decode.REGISTER_BITMAP_INPUT_TYPES

dau_driver.capability_decode.REGISTER_WINDOW_OFFSETS

dau_driver.capability_decode.decode_platform_id(value: int) → str

The platform id as ASCII, or "" when the word is not one. A board that advertises no platform is unknown, not dpv1: substituting a default here once reported a dead aperture (all-ones on every word) as a working Artix, and the platform id selects the part, the pricing and the constraints downstream.

dau_driver.capability_decode.NOT_ADVERTISED_REGISTER_MAP_VERSION

dau_driver.capability_decode.decode_register_map_version(value: int) → dau_core.registers.RegisterMapVersion

Decode the register-map version word.

An all-ones read means NOT ADVERTISED — the same normalization the capability words use — not a version. Two readers used to disagree on exactly this word: one mapped it to (0, 1), a plausible-looking old shell, while the other ran it through from_u32 and got (65535, 65535), which compares GREATER than the capability-word version and so read words the shell never decoded. A sentinel below every real version makes both readers agree and keeps those offsets unread.

dau_driver.capability_decode._typed_operators_from_bitmap(bitmap: int, input_types: tuple[dau_core.stream.LogicalType, ...]) → tuple[dau_core.capabilities.OperatorCapability, ...]

dau_driver.capability_decode.operators_from_snapshot(snapshot: dau_core.registers.RegisterBlockSnapshot) → tuple[tuple[dau_core.capabilities.OperatorCapability, ...], tuple[dau_core.capabilities.OperatorCapability, ...]]

(hardware operators, host-computed operators) from the identity registers, decoded by register map version.

OPERATOR_BITMAP carries only HDL-executed opcodes (typed INT32 at register level) and HOST_OPCODE_BITMAP carries protocol-level opcodes the host derives from hardware results (AVERAGE = SUM/COUNT divide) — those must never be submitted to the device. A shell that advertises neither word reports nothing here, and its manifest capability contract is the authority.

dau_driver.capability_decode.contract_from_manifest_metadata(metadata: collections.abc.Mapping[str, str]) → dau_core.capability_contract.CapabilityContract | None

The machine-readable capability contract a shell-build manifest carries (capability_contract key, JSON), when present.

dau_driver.capability_decode.operators_from_contract(contract: dau_core.capability_contract.CapabilityContract) → tuple[tuple[dau_core.capabilities.OperatorCapability, ...], tuple[dau_core.capabilities.OperatorCapability, ...]]

(hardware operators, host-computed operators) from the concrete composition capability contract — per-tile opcodes and input types, no bitmap-times-types expansion.

dau_driver.capability_decode._capability_word(read_register: collections.abc.Callable[[dau_core.registers.RegisterOffset], int], offset: dau_core.registers.RegisterOffset) → int

dau_driver.capability_decode._build_id(read_register: collections.abc.Callable[[dau_core.registers.RegisterOffset], int]) → int

The shell’s 64-bit build identity, as TWO 32-bit reads.

Deliberately not one 8-byte access: the XDMA user BAR can short-read those. Low half at BUILD_ID_LOW, high at BUILD_ID_HIGH, matching the identity block’s split.

All-ones normalizes to 0 like every other capability word — a word nobody decoded advertises nothing, and 0 is the reserved “not stamped” value a consumer already has to handle for shells built before stamping existed.

dau_driver.capability_decode._capability_words(read_register: collections.abc.Callable[[dau_core.registers.RegisterOffset], int], register_map_version: dau_core.registers.RegisterMapVersion) → dict[str, int]

The composed-capability words, read only from a shell that advertises them. Shared by every snapshot reader so the gate and the all-ones normalization cannot diverge between them.

dau_driver.capability_decode.read_register_block_snapshot(read_register: collections.abc.Callable[[dau_core.registers.RegisterOffset], int]) → dau_core.registers.RegisterBlockSnapshot

Discovery-time identity snapshot; read_register abstracts the backend-specific window access (dev-node pread vs DriverKit BAR read). The composed-capability words are only read on register map >= 0.2 — older shells do not decode those offsets.