UTTORI ASM · IN DEVELOPMENT

Assembly and state API

Integrate assembly and state api through supported Uttori ASM APIs.

assembleSource parses source text and runs collectDefinitions, resolveLayout, and emitProgram in order. Source line inputs are zero-based. Read binary output only after successful assembly. Failures can leave partial state. Use a fresh session after failure. getBinaryOutput delegates to the output formatter without reassembling. Copy the returned bytes for independent ownership. baseImage is copied at construction. setIncludePaths retains its supplied array.

analyzeSource uses an isolated temporary session, defaults to definition collection, and returns recoverable diagnostics. Plugin construction or cleanup failures can still throw. fileProvider supports virtual documents. Built-in file reads are synchronous. The default Node provider searches the macro source directory, current source directory, include directories, then process cwd.

Plugin state slots are created for every registered contribution in each session, even when another target is selected. state.get(key) returns the live mutable value. The plugin's clone hook must copy mutable descendants to isolate stage snapshots. resetForStage runs before onStageStart. Construction also enters collectDefinitions, so these hooks run once before the first build and again when that build's definition pass starts. Reset hooks must tolerate repeated entry. Keep state cloneable: discarded snapshots are not individually disposed. Low-level restore adopts its supplied map without copying. Session construction is not a resource transaction. Plugin-wide external resources belong in the activation disposable.

Lifecycle hooks run in registration order. The first beforeDirective result of handled skips later middleware and the handler. The last defined shouldEndifCloseInnermostWhile result wins. After emission, onStageEnd precedes beforeOutputFinalize and output-format finalization. Session disposal reverses lifecycle order, then disposes live state slots in reverse order.

Logical addresses and physical output offsets are distinct byte addresses. Address width is in bits, and write widths/instruction sizes are in bytes. A decoder-only architecture can be registered for analysis, but every architecture selected by an assembly target must provide an encoder. Expression output.read accepts a logical address and applies mapping. output.canRead checks a physical offset. Both inspect the base image when present, otherwise current output.