TGATHER

1// PTO-INSTRUCTION: {"assembly":["TGATHER <bundle operands>"],"block":["BSTART.SFU TGATHER, ValueDataType","B.DATR Layout (optional)","B.DIM LB0=ValidCol","B.DIM LB1=ValidRow (optional)","B.DIM LB2=Col (optional)","B.IOT ValueSrc, IndexSrc, mask=PE_MASK, <last>, ->DstTile<TSize>","BSTOP"],"catalog_indices":[79],"catalog_records":[{"arguments":[{"operand":"destination0"},{"operand":"source0"},{"operand":"source1"}],"command_mnemonic":"BSTART.TEPL","contract_status":"reviewed-complete","datr_contract":{"allowed_nonzero_fields":["Layout"],"pad_union":"must-zero"},"disposition":"accepted-direct-operation","effect_contract":"TGATHER","family":"TEPL","fault_contract":"ExecuteTileInstruction","function":15,"legality_handler":"TileOperandsLegal_TGATHER","mode":3,"name":"TGATHER","operands":[{"field":"destination0","role":"new Local value destination"},{"field":"source0","role":"persistent Local value source"},{"field":"source1","role":"persistent Local S16, U16, S32, U32, S64, or U64 row-index source"}],"restart_contract":"CompleteBundleAtWithAcceptedApplicabilityRules","selector":"0x06F","semantic_handler":"TGATHER","state_effects":["operand:destination0:new-local-value-destination","operand:source0:persistent-value-source","operand:source1:persistent-row-index-source","runtime:TilePad_Null:physical-padding"]}],"classification":["irregular-and-complex","layout"],"contract":{"block_composition":["BSTART.SFU TGATHER, ValueDataType","B.DATR Layout (optional)","B.DIM LB0=ValidCol","B.DIM LB1=ValidRow (optional)","B.DIM LB2=Col (optional)","B.IOT ValueSrc, IndexSrc, mask=PE_MASK, <last>, ->DstTile<TSize>","BSTOP"],"canonical_assembly":["TGATHER <bundle operands>"],"defaults":["LB0 is required and supplies nonzero destination ValidCol; omitted LB1 selects destination ValidRow=1 and omitted LB2 selects physical Col=ValidCol.","Omitted B.DATR retains row-major destination layout; an assigned legal Layout changes only destination physical placement. PadValueOrByteId, secondary DataType, CMode, RMode, Sat, and Canonicalize remain zero.","Physical destination coordinates outside the valid rectangle are undefined Null padding."],"encoding_class":"selector-encoded-block-operation","examples":["BSTART.SFU TGATHER, U16; B.DIM LB0=2; B.DIM LB1=2; B.IOT ValueSrc, IndexSrc, mask=1111, <last>, ->Dst<2>; BSTOP"],"exceptions":["Malformed bindings, B.IOR, B.IOS, unsupported value or index DataType, zero or mismatched valid shape, insufficient source columns, negative or out-of-range index, undefined index, undefined selected source element, invalid consumed encoding, reserved Layout, or insufficient destination capacity raises the applicable Tile fault before effects.","PE_MASK=0000 is a strict no-op before Tile reads, index checks, allocation, faults, or payload effects."],"field_contracts":{},"field_zero_meanings":{"B.DATR.Layout":"Encoded zero selects row-major destination placement.","B.DIM.LB1":"Omission selects ValidRow=1; an explicitly encoded zero is not a legal nonzero dimension.","B.DIM.LB2":"Omission selects physical Col=ValidCol; an explicitly encoded zero is not a legal physical column count."},"legality":["TGATHER uses the TEPL encoding carrier Mode 3 Function 15, is canonically assembled with BSTART.SFU, and has no standalone opcode.","Exactly one terminating Local B.IOT supplies one persistent value source, one persistent row-index source, and one newly allocated destination; B.IOR and B.IOS are illegal.","Value source and destination use the same one of HiF8, E4M3, E5M2, E3M2, E2M3, E8M0, S8, U8, FP16, BF16, S16, U16, FP32, TF32, HF32, S32, U32, FP64, S64, or U64. The index source is exactly S16, U16, S32, U32, S64, or U64.","Index and destination valid shapes are equal and nonzero. The value source has at least destination ValidCol columns.","Every signed index is nonnegative and every index is less than source ValidRow. The complete index rectangle and every selected source[value,row,column] element are defined and validly encoded.","All three bindings use the same PE_MASK; any nonzero subset is legal."],"memory_effects":["none"],"operands":[{"field":"destination0","role":"new Local value destination"},{"field":"source0","role":"persistent Local value source"},{"field":"source1","role":"persistent Local S16, U16, S32, U32, S64, or U64 row-index source"}],"ordering":["Complete schema, descriptor, type, dimension, layout, capacity, index-range, and referenced-definedness preflight precedes source snapshots.","Both source payloads are snapshotted before result construction; complete destination payload, definedness, Null padding, and descriptor publish atomically."],"standalone_opcode":false,"state_effects":["For every destination coordinate [r,c], read k=index[r,c] and copy source[k,c] bit-for-bit to destination[r,c].","Indices select logical source rows and never flatten, wrap, clamp, or select another column.","Both sources persist and rejection publishes no destination state."]},"depends_on":["PTO-TILE-MODEL-LEGALITY-INDEXED-REARRANGEMENT","PTO-TILE-MODEL-EXECUTION-INDEXED-REARRANGEMENT"],"engine":"SFU","id":"PTO-TILE-TGATHER","mnemonic":"TGATHER","summary":"Gather values from source rows selected independently at each destination coordinate.","surface":"tile"}2// PTO-REVIEW: {"review_method":"formal-definition-read","outcome":"FORMAL-COMPLETE","reviewed_fields":["assembly","encoding","defaults","operation","state","memory","ordering","faults","reserved"]}3// NDF-BEGIN: PTO-TGATHER-CONTRACT-0014// ndf: kind=contract level=L1 layer=tile status=accepted5// TGATHER MUST accept every non-packed B8-NP, B16, B32, or B64 value type with6// every S16, U16, S32, U32, S64, or U64 index type. Each index element is a7// logical source-row selector at the current column. It MUST reject negative,8// out-of-range, or undefined references before effects, snapshot both sources,9// move raw value carrier bits without numeric-validity rejection, and publish10// one complete same-type destination with Null physical padding atomically.11// NDF-END: PTO-TGATHER-CONTRACT-00112// DOC-BEGIN: decode13readonly func InstructionContractOperation_TGATHER() => TileOperation14begin15    return TileOperation_TGATHER;16end;17// DOC-END: decode18// DOC-BEGIN: operation19readonly func InstructionContractOperandsLegal_TGATHER(20    destination: TileIndex,21    source: TileIndex,22    indices: TileIndex) => boolean23begin24    return TileOperandsLegal_TGATHER(destination, source, indices);25end;26
27readonly func InstructionContractHandler_TGATHER() => TileSemanticHandler28begin29    return TileHandler_TGATHER;30end;31
32func InstructionContractExecute_TGATHER(33    destination: TileIndex,34    source: TileIndex,35    indices: TileIndex)36begin37    assert InstructionContractOperandsLegal_TGATHER(38        destination,39        source,40        indices);41    TGATHER(destination, source, indices);42end;43// DOC-END: operation44