PTO-BLOCK-MODEL-OPERANDS-SUBVIEW-DESCRIPTOR

1// PTO-UNIT: {"id":"PTO-BLOCK-MODEL-OPERANDS-SUBVIEW-DESCRIPTOR","surface":"block","classification":["model","operands","subview-descriptor"],"depends_on":["PTO-BLOCK-MODEL-DISPATCH-DESCRIPTOR-LEGALITY","PTO-BLOCK-MODEL-OPERANDS-RANGE-MODIFIERS","PTO-BLOCK-MODEL-OPERANDS-PORTABLE-CARRIERS","PTO-BLOCK-MODEL-OPERANDS-SHARED-GENERATION","PTO-TILE-MODEL-SHAPE-CUBE-CELL"]}2
3// NDF-BEGIN: PTO-B-SUBVIEW-DESCRIPTOR-0014// ndf: kind=contract level=L1 layer=block status=accepted5// A legal Local CUBE B.SUBVIEW MUST derive a bounded descriptor from the6// parent descriptor, XLEN offset, and encoded view capacity in CELL order.7// Parent lifetime and payload remain unchanged; non-CUBE, zero-valid, and8// out-of-range geometry is rejected with Fault_TileLegality before effects.9// NDF-END: PTO-B-SUBVIEW-DESCRIPTOR-00110
11// NDF-BEGIN: PTO-BLOCK-TILE-OPERATION-APPLICABILITY-00112// ndf: kind=contract level=L1 layer=block status=accepted13// B.SUBVIEW applicability is total over accepted Tile operations; the14// selected operation handler retains ownership of dtype, layout, shape, and15// definedness legality.16// NDF-END: PTO-BLOCK-TILE-OPERATION-APPLICABILITY-00117
18pure func EmptyBundleSubviewDescriptor(parent: TileIndex)19    => BundleSubviewDescriptor20begin21    return BundleSubviewDescriptor {22        valid = FALSE,23        parent = parent,24        offset_cells = 0,25        origin_row = 0,26        origin_column = 0,27        rows = 0,28        columns = 0,29        valid_rows = 0,30        valid_columns = 0,31        cell_count = 0,32        capacity_bytes = 033    };34end;35
36readonly func BundleCubeSubviewDescriptorOf(37    parent_index: TileIndex,38    offset: Word,39    size_code: integer {1..12}) => BundleSubviewDescriptor40begin41    let empty = EmptyBundleSubviewDescriptor(parent_index);42    let parent = _Tiles[[parent_index]];43    if !parent.allocated || parent.location != TileLocation_Matrix ||44       !TileLayoutIsCube(parent.layout) || parent.valid_rows == 0 ||45       parent.valid_columns == 0 || parent.cube_cell_count == 0 then46        return empty;47    end;48    let raw_offset = UInt(offset);49    if raw_offset > 65535 || raw_offset >= parent.cube_cell_count then50        return empty;51    end;52    let offset_cells = raw_offset as integer {0..65535};53    let requested_cells = (TileSizeCodeBytes(size_code) DIVRM PTO_TILE_CELL_BYTES)54        as integer {1..2048};55    let remaining = (parent.cube_cell_count - offset_cells)56        as integer {1..16384};57    let cell_count = if requested_cells < remaining then requested_cells58        else remaining;59    let cell_rows = TileCubeCellRows(parent.layout, parent.data_type);60    let cell_columns = TileCubeCellColumns(parent.layout, parent.data_type);61    if cell_rows == 0 || cell_columns == 0 then return empty; end;62    var origin_row: integer {0..65535} = 0;63    var origin_column: integer {0..65535} = 0;64    var view_cell_count: integer {1..16384} = cell_count;65    if parent.layout == TileLayout_CUBE_N8 then66        let k_repeat = parent.cube_k_repeat;67        if k_repeat == 0 || k_repeat > 16384 then return empty; end;68        let bounded_k_repeat = k_repeat as integer {1..16384};69        let cell_k = (offset_cells MOD bounded_k_repeat)70            as integer {0..16383};71        let cell_n = (offset_cells DIVRM bounded_k_repeat)72            as integer {0..8191};73        let cells_until_n_boundary = (bounded_k_repeat - cell_k)74            as integer {1..16384};75        if view_cell_count > cells_until_n_boundary then76            view_cell_count = cells_until_n_boundary;77        end;78        origin_row = (cell_k * cell_rows) as integer {0..65535};79        origin_column = (cell_n * cell_columns) as integer {0..65535};80    else81        origin_column = (offset_cells * cell_columns)82            as integer {0..65535};83    end;84    if origin_row >= parent.valid_rows || origin_column >= parent.valid_columns then85        return empty;86    end;87    var valid_rows: integer {0..65535} = parent.valid_rows;88    if origin_row < parent.valid_rows then89        valid_rows = (parent.valid_rows - origin_row) as integer {0..65535};90    end;91    if parent.layout == TileLayout_CUBE_N8 then92        let requested_rows = (view_cell_count * cell_rows)93            as integer {1..65535};94        if valid_rows > requested_rows then valid_rows = requested_rows; end;95    end;96    let requested_columns: integer {1..65535} =97        if parent.layout == TileLayout_CUBE_N8 then cell_columns as integer {1..65535}98        else (view_cell_count * cell_columns) as integer {1..65535};99    var valid_columns: integer {0..65535} = requested_columns;100    if origin_column < parent.valid_columns &&101       parent.valid_columns - origin_column < requested_columns then102        valid_columns = (parent.valid_columns - origin_column) as integer {0..65535};103    end;104    if valid_rows == 0 || valid_columns == 0 then return empty; end;105    let rows = TileCubeStorageRows(parent.layout, valid_rows, parent.data_type);106    let columns = TileCubeStorageColumns(parent.layout, valid_columns, parent.data_type);107    let derived_cells = TileCubeCellCount(parent.layout, valid_rows, valid_columns, parent.data_type);108    let derived_capacity = TileCubeRequiredBytes(parent.layout, valid_rows, valid_columns, parent.data_type);109    if rows == 0 || columns == 0 || derived_cells == 0 || derived_capacity == 0 ||110       derived_cells > view_cell_count then return empty; end;111    return BundleSubviewDescriptor {112        valid = TRUE,113        parent = parent_index,114        offset_cells = offset_cells,115        origin_row = origin_row,116        origin_column = origin_column,117        rows = rows,118        columns = columns,119        valid_rows = valid_rows,120        valid_columns = valid_columns,121        cell_count = derived_cells,122        capacity_bytes = derived_capacity123    };124end;125
126pure func BundleSubviewElementInBounds(127    descriptor: BundleSubviewDescriptor,128    row: integer {0..65535}, column: integer {0..65535}) => boolean129begin130    return descriptor.valid && row < descriptor.valid_rows && column < descriptor.valid_columns;131end;132
133readonly func BundleSubviewOperationApplicabilityIsTotal(134    operation: integer {0..PTO_TILE_OPERATION_COUNT-1}) => boolean135begin136    // Every accepted Tile operation is a legal dispatch candidate. The137    // selected operation's existing dtype/layout/shape/definedness checks138    // remain authoritative; this helper has no private family allowlist.139    return operation < PTO_TILE_OPERATION_COUNT;140end;141
142func PrepareSelectedBundleStage2() => boolean143begin144    if !_BundleOperation.valid then return TRUE; end;145    let family = BundleTileDecodeFamily(_BundleOperation.operation_class);146    let code = BundleOperationDecodeCode(_BundleOperation);147    let decoded = DecodeTileOperation(family, code);148    if decoded == PTO_TILE_OPERATION_COUNT then149        SetFault(Fault_IllegalInstruction, ReadTPC());150        return FALSE;151    end;152    let operation = decoded as integer {0..PTO_TILE_OPERATION_COUNT-1};153    if !PrepareBundleSubviewDescriptors(operation) then return FALSE; end;154    if !ValidateBundleLocalGeneration() then return FALSE; end;155    if !ValidateBundleSharedGeneration() then156        SetFault(Fault_TileLegality, ReadTPC());157        return FALSE;158    end;159    return TRUE;160end;161
162func PrepareBundleSubviewDescriptors(163    operation: integer {0..PTO_TILE_OPERATION_COUNT-1}) => boolean164begin165    if !BundleSubviewOperationApplicabilityIsTotal(operation) then166        SetFault(Fault_TileLegality, ReadTPC());167        return FALSE;168    end;169    // Bind readiness before materialization. A waiting consumer is a170    // non-faulting no-effect outcome and must never copy unready source cells171    // into a temporary view.172    if !PrepareBundleConsumerDependencies() then return FALSE; end;173    for binding = 0 to PTO_BUNDLE_TILE_BINDING_COUNT - 1 do174        if _BundleTileBindings[[binding]].valid then175            if _BundleTileBindings[[binding]].source0_subview.valid &&176               !_BundleTileBindings[[binding]].source0_subview.derived.valid then177                let encoded_size = _BundleTileBindings[[binding]]178                    .source0_subview.size_code;179                if encoded_size == 0 then180                    SetFault(Fault_TileLegality, ReadTPC());181                    return FALSE;182                end;183                let descriptor = BundleCubeSubviewDescriptorOf(184                    _BundleTileBindings[[binding]].source0,185                    _BundleTileBindings[[binding]].source0_subview.offset,186                    encoded_size as integer {1..12});187                if !descriptor.valid then188                    SetFault(Fault_TileLegality, ReadTPC());189                    return FALSE;190                end;191                _BundleTileBindings[[binding]].source0_subview.derived =192                    descriptor;193                if !MaterializeBundleSubview(194                        binding as BundleTileBindingIndex, FALSE,195                        descriptor, operation) then return FALSE; end;196            end;197            if _BundleTileBindings[[binding]].source1_subview.valid &&198               !_BundleTileBindings[[binding]].source1_subview.derived.valid then199                let encoded_size = _BundleTileBindings[[binding]]200                    .source1_subview.size_code;201                if encoded_size == 0 then202                    SetFault(Fault_TileLegality, ReadTPC());203                    return FALSE;204                end;205                let descriptor = BundleCubeSubviewDescriptorOf(206                    _BundleTileBindings[[binding]].source1,207                    _BundleTileBindings[[binding]].source1_subview.offset,208                    encoded_size as integer {1..12});209                if !descriptor.valid then210                    SetFault(Fault_TileLegality, ReadTPC());211                    return FALSE;212                end;213                _BundleTileBindings[[binding]].source1_subview.derived =214                    descriptor;215                if !MaterializeBundleSubview(216                        binding as BundleTileBindingIndex, TRUE,217                        descriptor, operation) then return FALSE; end;218            end;219        end;220    end;221    return TRUE;222end;223
224readonly func BundleReadSubviewElement(225    binding: BundleTileBindingIndex,226    source_select: boolean,227    row: integer {0..65535},228    column: integer {0..65535}) => Word229begin230    let descriptor = if source_select then231        _BundleTileBindings[[binding]].source1_subview.derived232        else _BundleTileBindings[[binding]].source0_subview.derived;233    assert BundleSubviewElementInBounds(descriptor, row, column);234    return ReadTileElement(descriptor.parent,235        (descriptor.origin_row + row) as integer {0..65535},236        (descriptor.origin_column + column) as integer {0..65535});237end;238
239readonly func BundleTileSourceIndex(240    binding: BundleTileBindingIndex, source_select: boolean) => TileIndex241begin242    let modifier = if source_select then243        _BundleTileBindings[[binding]].source1_subview244        else _BundleTileBindings[[binding]].source0_subview;245    if modifier.materialized then return modifier.materialized_index; end;246    return if source_select then _BundleTileBindings[[binding]].source1247        else _BundleTileBindings[[binding]].source0;248end;249
250readonly func BundleTileArchitecturalSourceIndex(251    binding: BundleTileBindingIndex, source_select: boolean) => TileIndex252begin253    let modifier = if source_select then254        _BundleTileBindings[[binding]].source1_subview255        else _BundleTileBindings[[binding]].source0_subview;256    if modifier.valid && modifier.derived.valid then257        return modifier.derived.parent;258    end;259    return if source_select then _BundleTileBindings[[binding]].source1260        else _BundleTileBindings[[binding]].source0;261end;262
263func MaterializeBundleSubview(264    binding: BundleTileBindingIndex, source_select: boolean,265    descriptor: BundleSubviewDescriptor,266    operation: integer {0..PTO_TILE_OPERATION_COUNT-1}) => boolean267begin268    let parent = descriptor.parent;269    let mask = _TileAllocationMasks[[parent]];270    if mask == Zeros{4} then271        SetFault(Fault_TileLegality, ReadTPC());272        return FALSE;273    end;274    let parent_hand = (parent DIVRM 16) as integer {0..3};275    var materialized_index: TileIndex = 0;276    var found = FALSE;277    for offset = 0 to 15 do278        let candidate = (parent_hand * 16 + offset) as integer {0..63};279        if !found && !_Tiles[[candidate]].allocated then280            materialized_index = candidate as TileIndex;281            found = TRUE;282        end;283    end;284    if !found then285        SetFault(Fault_TileAllocation, ReadTPC());286        return FALSE;287    end;288    // The CUBE parent is the architectural source of the CELL-order view.289    // A non-CUBE Tile handler consumes the bounded view in its ordinary290    // row-major operand representation; CUBE handlers retain the CUBE view291    // so their matrix legality and CELL geometry remain authoritative.292    let operation_is_cube = _BundleOperation.valid &&293        BundleTileDecodeFamily(_BundleOperation.operation_class) ==294            TileDecode_CUBE;295    // Matrix bias operands retain the existing handler contract: the296    // primary matrix sources remain CUBE views, while the bias source is a297    // bounded RowMajor view.  The parent is still always the accepted CUBE298    // fixture; only the materialized representation follows the authoritative299    // bias legality rule.300    var source_ordinal: integer {0..7} = 0;301    for prior = 0 to PTO_BUNDLE_TILE_BINDING_COUNT - 1 looplimit 64 do302        if _BundleTileBindings[[prior]].valid then303            if prior < binding then304                if _BundleTileBindings[[prior]].source0_valid then305                    source_ordinal = (source_ordinal + 1) as integer {0..7};306                end;307                if _BundleTileBindings[[prior]].source1_valid then308                    source_ordinal = (source_ordinal + 1) as integer {0..7};309                end;310            elsif prior == binding && source_select &&311                  _BundleTileBindings[[prior]].source0_valid then312                source_ordinal = (source_ordinal + 1) as integer {0..7};313            end;314        end;315    end;316    let operation_kind = if _BundleOperation.valid then317        TileOperationOfIndex(318            DecodeTileOperation(319                BundleTileDecodeFamily(_BundleOperation.operation_class),320                BundleOperationDecodeCode(_BundleOperation))321                as integer {0..PTO_TILE_OPERATION_COUNT-1})322        else TileOperation_TADD;323    let bias_source =324        (operation_kind == TileOperation_TMATMUL_BIAS && source_ordinal == 2) ||325        (operation_kind == TileOperation_TGEMV_BIAS && source_ordinal == 2) ||326        (operation_kind == TileOperation_TMATMUL_MX_BIAS && source_ordinal == 4) ||327        (operation_kind == TileOperation_TGEMV_MX_BIAS && source_ordinal == 4);328    let row_major_auxiliary = bias_source;329    if operation_is_cube && !row_major_auxiliary then330        if !ConfigureCubeTileForMask(materialized_index,331                descriptor.capacity_bytes, descriptor.valid_rows,332                descriptor.valid_columns, _Tiles[[parent]].data_type,333                _Tiles[[parent]].layout, TileLocation_Matrix, mask) then334            SetFault(Fault_TileAllocation, ReadTPC());335            return FALSE;336        end;337    else338        let row_broadcast =339            (operation_kind == TileOperation_TROWEXPAND &&340             source_ordinal == 0) ||341            ((operation_kind == TileOperation_TROWEXPANDADD ||342              operation_kind == TileOperation_TROWEXPANDSUB ||343              operation_kind == TileOperation_TROWEXPANDMUL ||344              operation_kind == TileOperation_TROWEXPANDDIV ||345              operation_kind == TileOperation_TROWEXPANDMAX ||346              operation_kind == TileOperation_TROWEXPANDMIN ||347              operation_kind == TileOperation_TROWEXPANDEXPDIF) &&348             source_ordinal == 1);349        assert descriptor.valid_columns >= 1;350        var row_major_columns: integer {1..65535} =351            if row_broadcast then 1352            else descriptor.valid_columns as integer {1..65535};353        let physical_columns_raw = UInt(_BundleDimensions[[2]]);354        if !row_broadcast && _BundleDimensionPresent[[2]] &&355           physical_columns_raw >= descriptor.valid_columns &&356           physical_columns_raw <= 65535 then357            row_major_columns =358                physical_columns_raw as integer {1..65535};359        elsif !row_broadcast then360            var candidate: integer = 1;361            for exponent = 0 to 15 do362                if candidate < descriptor.valid_columns then363                    candidate = candidate * 2;364                end;365            end;366            if candidate > 65535 then367                SetFault(Fault_TileLegality, ReadTPC());368                return FALSE;369            end;370            row_major_columns = candidate as integer {1..65535};371        end;372        let row_major_rows = DerivedTileRows(descriptor.capacity_bytes,373            row_major_columns, _Tiles[[parent]].data_type);374        if row_major_rows == 0 ||375           !TileDescriptorShapeLegal(descriptor.capacity_bytes,376               row_major_columns, descriptor.valid_rows,377               descriptor.valid_columns, _Tiles[[parent]].data_type) then378            SetFault(Fault_TileLegality, ReadTPC());379            return FALSE;380        end;381        let image_to_column = operation_kind == TileOperation_TIMG2COL;382        ConfigureTileForMask(materialized_index, descriptor.capacity_bytes,383            row_major_rows, row_major_columns, descriptor.valid_rows,384            descriptor.valid_columns, _Tiles[[parent]].data_type,385            TileLayout_RowMajor,386            (if operation_is_cube || image_to_column then TileLocation_Matrix387             else TileLocation_Any), mask);388        if image_to_column && descriptor.offset_cells == 0 &&389           TileFeatureMapDescriptorStructurallyValid(parent) then390            let feature = ReadTileFeatureMapDescriptor(parent);391            ConfigureTileFeatureMapDescriptor(materialized_index,392                feature.layout, feature.batches, feature.depth,393                feature.channel_groups, feature.height, feature.width,394                feature.channels_per_group, feature.filter_height,395                feature.filter_width, feature.stride_height,396                feature.stride_width, feature.dilation_height,397                feature.dilation_width, feature.pad_left, feature.pad_right,398                feature.pad_top, feature.pad_bottom,399                feature.logical_channels, feature.padding,400                feature.transposed);401        end;402    end;403    for row = 0 to descriptor.valid_rows - 1 looplimit 65536 do404        for column = 0 to descriptor.valid_columns - 1 looplimit 65536 do405            let source_row = (descriptor.origin_row + row)406                as integer {0..65535};407            let source_column = (descriptor.origin_column + column)408                as integer {0..65535};409            if TileElementDefined(parent, source_row, source_column) then410                WriteTileElement(materialized_index as TileIndex,411                    row as integer {0..65535}, column as integer {0..65535},412                    ReadTileElement(parent, source_row, source_column));413            end;414        end;415    end;416    // A materialized view is a derived temporary source, so its readiness417    // follows the parent validity proven by the descriptor preflight.  Keep418    // undefined parent regions undefined; a fully defined parent publishes419    // the copied valid view as a normal readable Tile source.420    if TileSourceContentsDefined(parent) then421        MarkTileValidRegionDefined(materialized_index as TileIndex);422    end;423    if source_select then424        _BundleTileBindings[[binding]].source1_subview.materialized = TRUE;425        _BundleTileBindings[[binding]].source1_subview.materialized_index =426            materialized_index as TileIndex;427        _BundleTileBindings[[binding]].source1 =428            materialized_index as TileIndex;429    else430        _BundleTileBindings[[binding]].source0_subview.materialized = TRUE;431        _BundleTileBindings[[binding]].source0_subview.materialized_index =432            materialized_index as TileIndex;433        _BundleTileBindings[[binding]].source0 =434            materialized_index as TileIndex;435    end;436    return TRUE;437end;438
439func DiscardBundleSubviewMaterializations()440begin441    for binding = 0 to PTO_BUNDLE_TILE_BINDING_COUNT - 1 do442        if _BundleTileBindings[[binding]].valid then443            if _BundleTileBindings[[binding]].source0_subview.materialized then444                _BundleTileBindings[[binding]].source0 =445                    _BundleTileBindings[[binding]].source0_subview446                        .derived.parent;447                ReleaseTile(_BundleTileBindings[[binding]].source0_subview448                    .materialized_index);449                _BundleTileBindings[[binding]].source0_subview.materialized =450                    FALSE;451            end;452            if _BundleTileBindings[[binding]].source1_subview.materialized then453                _BundleTileBindings[[binding]].source1 =454                    _BundleTileBindings[[binding]].source1_subview455                        .derived.parent;456                ReleaseTile(_BundleTileBindings[[binding]].source1_subview457                    .materialized_index);458                _BundleTileBindings[[binding]].source1_subview.materialized =459                    FALSE;460            end;461        end;462    end;463end;464