pto.tcvt¶

Constraints

• src and dst MUST have compatible shapes (declared shape and valid region).
• The source/destination type pair MUST be supported by the selected target profile.
• The rounding mode MUST be supported for the given type pair.
• When a conversion path requires explicit scratch storage, callers MUST use one of the tmp-tile overloads.

• Disabling saturation may change overflow behavior for some backend/type paths, especially low-precision integer conversions.

• Temporary tile:

  • The C++ API provides overloads with an explicit tmp tile. On A2/A3 this tmp tile is consumed by PyTorch-compatible non-saturating narrowing paths when SaturationMode::OFF is used for float -> int16, half -> int16, or half -> int8. Other conversions do not require tmp space.
  • The implementation casts tmp to int32_t *; size the tile by bytes, independent of the declared TmpTileData::DType.
  • The formulas below give the minimum allocation size rounded to the 32-byte vector block granularity used by the implementation. If C = 0, no tmp-backed conversion is issued and the required tmp size is 0.
  • Common parameters:
    • R = dst.GetValidRow().
    • C = dst.GetValidCol().
    • SS = TileDataS::RowStride, in source elements.
    • REPEAT_MAX = 255, REPEAT_BYTE = 256, BLOCK_BYTE_SIZE = 32.
  • float -> int16, non-saturating (SaturationMode::OFF):
    • The temporary result is an int32_t tile produced by the first float -> int32 conversion step.
    • float source rows are 32-byte aligned by the tile constraints, so SS / 8 is the source repeat stride in 32-byte blocks.
    • For the aligned main region, one call processes one row and up to REPEAT_MAX repeats, with 64 elements per repeat: $$ \text{tmpHeadBytes} = 4 \times 64 \times \min\left(\left\lfloor\frac{C}{64}\right\rfloor, 255\right) $$
    • For the tail region, one call processes up to REPEAT_MAX rows using the source row stride. The extent is computed in 32-byte blocks because the vector repeat stride is block-based: $$ \text{tmpTailBytes} = \begin{cases} 32 \times \left((\min(R, 255) - 1) \times \frac{SS}{8} + \left\lceil\frac{C \bmod 64}{8}\right\rceil\right), & C \bmod 64 > 0 \ 0, & C \bmod 64 = 0 \end{cases} $$
    • Minimum required tmp size for this path: $$ \text{tmpFloatToInt16Bytes} = \max(\text{tmpHeadBytes}, \text{tmpTailBytes}) $$
    • A compact full-repeat upper bound for the main region is REPEAT_MAX * REPEAT_BYTE = 65280 bytes, but tail sizing can be larger when SS is large because tail rows are written with source-row stride.
  • half -> int16, non-saturating (SaturationMode::OFF):
    • The implementation processes each row in sub-chunks of at most 64 elements and reuses the same temp buffer for every sub-chunk. For C > 0, let: $$ H = \min(C, 64) $$
    • Minimum required tmp size for this path: $$ \text{tmpHalfToInt16Bytes} = 32 \times \left\lceil\frac{H}{8}\right\rceil $$
    • A shape-independent upper bound for any non-empty tile is 256 bytes.
  • half -> int8, non-saturating (SaturationMode::OFF):
    • The implementation also processes sub-chunks of at most 64 elements and reuses the same 256-byte temp region. The first step can write up to 64 int32_t values into bytes [0, 255]; after the int32 -> int16 narrow, bytes [0, 127] hold the int16_t values and bytes [128, 255] are reused as scratch.
    • tempMaskBuf = tempAndBuf + 64 advances by 64 * sizeof(int16_t) = 128 bytes, so it points at the upper half of the same 256-byte temp region. It does not require an additional 256-byte allocation.
    • Minimum required tmp size for this path: $$ \text{tmpHalfToInt8Bytes} = \max\left(32 \times \left\lceil\frac{H}{8}\right\rceil,\ 128 + 32 \times \left\lceil\frac{H}{16}\right\rceil\right) $$
    • A shape-independent upper bound for any non-empty tile is 256 bytes.
  • Overall minimum for all tmp-backed TCVT conversions:
    • Since tmpHalfToInt8Bytes >= tmpHalfToInt16Bytes, the minimum tmp size that fits all tmp-backed TCVT conversion paths for the same shape is: $$ \text{tmpSizeAllBytes} = \max(\text{tmpFloatToInt16Bytes},\ \text{tmpHalfToInt8Bytes}) $$
    • Equivalently, if the tile is non-empty and a compact shape-independent bound for the half paths is acceptable: $$ \text{tmpSizeAllBytes} = \max(\text{tmpFloatToInt16Bytes},\ 256) $$
  • The no-tmp overload remains valid for conversions that do not need the PyTorch-compatible tmp-backed path, or when native saturation behavior is sufficient.