Crate virtio_accel_tosa

Expand description

Safe, bounded TOSA graph ingestion for virtio-accel providers.

This crate validates a TOSA FlatBuffer before exposing zero-copy borrowed views. The public API contains no generated FlatBuffers types and no unchecked accessors. Validation is deliberately split into two layers:

parse enforces the serialization envelope, resource limits, stable TOSA 1.0 schema boundary, names, references, and operator/attribute correspondence;
Model::validate_for exhaustively enforces the stable operator arities, operand kinds, ranks, profiles, extensions, level limits, attributes, compile-time constants, static shapes, control-flow signatures, and numerical parameter rules for a declared Target; and
provider-specific capability and Op::CUSTOM policy can be layered through ModelValidator.

Semantic validation proves model legality; it does not execute tensor data or replace a backend’s runtime checks for data-dependent TOSA REQUIRE conditions.

The checked-in schema is from TOSA Tools v2026.05.0. The tools release implements TOSA specification 1.0.1 and appends draft TOSA 1.1 entries; parse accepts stable graph version 1.0.0 and rejects those appended entries.

Structs§

AnalysisOptions: Limits for optional analysis work. They do not relax semantic or parser limits.
AnalysisSpan: Compact half-open span into one of TosaAnalysis’s indexed slices.
AnalyzedBlock: One basic block and its precomputed execution order.
AnalyzedOperator: One operator indexed independently of serialized names.
AnalyzedRegion: One region and its contiguous block span.
AnalyzedValue: One globally indexed value in a model. Names and serialized payloads remain borrowed.
Arity: Accepted serialized operand counts for an operator.
AttributeKind: Discriminant of an operator’s serialized attribute table.
BasicBlock: Borrowed basic-block view.
BasicBlocks
BlockId
CacheInsertError: An insertion that could not reserve its one bounded cache entry.
CapabilityDescriptor: Conservative semantic admission descriptor for one exact TOSA target.
DType: A TOSA tensor data-type discriminant.
DTypeCapability: One dtype admitted in explicitly listed graph roles.
DTypeConstraints
ExtensionSet: TOSA 1.0 profile-extension bits.
GraphCapabilities: Whole-graph structural boundary that is not reducible to an operator bit.
I32List: Borrowed FlatBuffers vector of little-endian i32 attribute values.
I32Values: Exact-size iterator returned by I32List::iter.
LevelLimits: Argument ceilings assigned by a TOSA 1.0 implementation level.
Limits: Resource ceilings applied before and during graph traversal.
Model: A verified, zero-copy TOSA graph.
NanPropagationMode
Op: A TOSA operator discriminant.
Operator: Borrowed operator view.
OperatorCapability: One implemented operator and the conservative restrictions a scheduler must preserve.
OperatorConstraints
OperatorId
Operators
OptimizationHints: Numerically safe and provider-conditional lowering opportunities.
ProfileSet: Set of TOSA base profiles implemented by a target.
Region: Borrowed region view.
RegionId
Regions
ResizeMode
RoundingMode
RuntimeError: Located runtime-specialization failure.
RuntimeValidation: Result of checking every dynamic CTC value needed by one specialization.
RuntimeValue: One host-readable dynamic CTC value supplied for specialization.
SemanticValidator: Complete stable-TOSA semantic pass for a declared device-neutral target.
Shape: Borrowed shape-value view.
ShapeValues: Exact-size iterator over little-endian i64 shape values.
Shapes
SpecializationCache: Small exact-key LRU for compiled shape specializations.
SpecializationKey: Exact, collision-safe key for one set of dynamic shapes and CTC bytes.
SpecializationKeyBuilder: Bounded builder for provider cache keys.
Stats: Counts collected during the bounded validation pass.
StringList: Iterator over borrowed TOSA symbol names.
Target: Device-neutral target requirements carried in virtio-accel’s opaque target words.
Tensor: Borrowed tensor view.
Tensors
TosaAnalysis: Compact provider-neutral overlay used by lowering and specialization code.
ValueId
ValueRoles
Version: Stable TOSA graph version.

Enums§

AnalysisError: Failure while producing a compact lowering plan.
AnalyzedValueKind: Zero-copy source value retained by an analyzed plan.
ArtifactError
ConstantState: How an analyzed value becomes constant for lowering.
Error: Failure returned for malformed, unsupported, or over-budget input.
IntegerError: A TOSA integer arithmetic precondition was not satisfied.
Level: TOSA implementation level.
NameKind
OpAttributes: Safe, exhaustive view of the attribute payload used by a stable TOSA 1.0 operator.
OperandRole: Operand side used in semantic diagnostics.
Resource
RuntimeCondition: Conditions that a provider may need to lower or inspect at execution time.
RuntimeConditionSupport: Provider treatment of semantic runtime conditions derived during TOSA analysis.
RuntimeErrorKind: Failure while resolving or checking dynamic CTC data.
SemanticError: Located semantic validation failure.
SemanticErrorKind: Operator-level failure after the serialization envelope has already been validated.
SpecializationError: Failure while constructing a canonical specialization key.
TargetError

Constants§

ARTIFACT_FORMAT: Raw TOSA FlatBuffer payload ("TOSA" as a big-endian four-character code).
SCHEMA: TOSA schema source pinned into this crate.
SCHEMA_RELEASE: Upstream TOSA Tools release from which SCHEMA was copied.
SCHEMA_SHA256: SHA-256 of SCHEMA as shipped by TOSA Tools v2026.05.0.

Traits§

ModelValidator: Extension point for semantic, profile, extension, or backend-capability validators.
TosaCapabilityProvider: Optional host-side interface implemented by concrete TOSA providers.

Functions§

apply_scale_16: Apply TOSA’s 16-bit fixed-point scaling helper exactly.
apply_scale_32: Apply TOSA’s 32-bit fixed-point scaling helper exactly.
dot_i8_i32: Compute an exact signed INT8 dot product with INT32 accumulation.
fp8e4m3_to_bf16_bits: Convert one TOSA/OCP FP8 E4M3 bit pattern to BF16 storage bits.
fp8e4m3_to_f32: Convert one TOSA/OCP FP8 E4M3 bit pattern to an exactly representable f32 value.
fp8e5m2_to_bf16_bits: Convert one TOSA/OCP FP8 E5M2 bit pattern to BF16 storage bits.
fp8e5m2_to_f32: Convert one TOSA/OCP FP8 E5M2 bit pattern to an exactly representable f32 value.
low_precision_storage_bytes: Return the packed byte count for an INT4, INT8, FP8E4M3, or FP8E5M2 tensor.
pack_int4: Pack two TOSA INT4 values, with low in the low nibble and high in the high nibble.
parse: Parse with finite production defaults.
parse_with_limits: Verify and parse a stable TOSA 1.0 graph under caller-selected resource ceilings.
rescale_i32_to_i8: Rescale one INT32 accumulator into a signed INT8 tensor value.
unpack_int4: Decode one signed two’s-complement INT4 value packed low nibble first.
validate_runtime_values: Validate dynamic CTC encodings and every associated mandatory ERROR_IF condition.
validate_semantics: Validate stable TOSA operator, profile, extension, level, shape, and numerical constraints.