pack_untilize_block

template<uint32_t block_ct_dim = 8, uint32_t full_ct_dim = block_ct_dim, bool narrow_row = false, std::uint32_t row_num_datums = TILE_C_DIM, bool dense = false, bool configure_remap = true, bool is_fp32_dest_acc_en = DST_ACCUM_MODE>
void ckernel::pack_untilize_dest_init(uint32_t ocb, uint32_t call_line = __builtin_LINE())

Performs the necessary hardware and software initialization for the pack untilize operation. This initialization function should be used when the desired PACK input is already in DEST register - therefore, it doesn’t configure UNPACK and MATH threads for transferring data from circular buffers to DEST register (this is done with pack_untilize_init function). Matching pack untilize operation for this initialization function is pack_untilize_dest. In order for this untilization to be performed correctly, some other function must place the tiles in the DEST register, e.g. reduce_tile, copy_tile, etc. This initialization function should, therefore, be called right after the op-specific initialization function (reduce_init, copy_init, etc.).

Since pack untilize works on a block of tiles, the user should specify the width of a single block (block_ct_dim), and the width of the full block (full_ct_dim). It is not needed to provide the height of the block during the initialization, since pack_untilize_block will loop over the height of the block. Note that the maximum size of the block is limited by the size of the DEST and synchronization mode used. These are maximum sizes:

  • half-sync mode (16-bit mode): 8 tiles

  • half-sync mode (32-bit mode): 4 tiles

  • full-sync mode (16-bit mode): 16 tiles

  • full-sync mode (32-bit mode): 8 tiles

NOTE: Face geometry (face_r_dim, num_faces) is derived from the output circular buffer metadata configured on the host via CircularBufferConfig::set_unpack_face_geometry / CBFormatDescriptor::face_geometry. Callers that need non-default face geometry must configure it on the output CB at program creation time.

By default this init configures BH DEST remap. Pass configure_remap = false only when the caller has already configured BH DEST remap and no intervening operation requires a different DEST remap state.

Return value: None

Param Type Name

Template block_ct_dim

Template full_ct_dim

Template narrow_row

Template row_num_datums

Template dense

Template configure_remap

Template is_fp32_dest_acc_en

Function ocb

NOTE: When a row is processed in multiple blocks, every block must use the same block_ct_dim; full_ct_dim must be divisible by block_ct_dim. Remainder blocks are unsupported because the L1 column offset is computed as block_c_index * block_ct_dim.

template<uint32_t block_ct_dim = 8, uint32_t full_ct_dim = block_ct_dim, bool is_fp32_dest_acc_en = DST_ACCUM_MODE>
void ckernel::pack_untilize_init(uint32_t icb, uint32_t ocb, uint32_t call_line = __builtin_LINE())

Performs the necessary hardware and software initialization for the pack untilize operation. Initializes all three threads: UNPACK, MATH, and PACK. This function should be used when the desired PACK input is not yet in DEST register. Internally, this function calls pack_untilize_dest_init to initialize the PACK thread.

Since pack untilize works on a block of tiles, the user should specify the width of a single block (block_ct_dim), and the width of the full block (full_ct_dim). It is not needed to provide the height of the block during the initialization, since pack_untilize_block will loop over the height of the block. Note that the maximum size of the block is limited by the size of the DEST and synchronization mode used. These are maximum sizes:

  • half-sync mode (16-bit mode): 8 tiles

  • half-sync mode (32-bit mode): 4 tiles

  • full-sync mode (16-bit mode): 16 tiles

  • full-sync mode (32-bit mode): 8 tiles

NOTE: Face geometry (face_r_dim, num_faces) is derived from the output circular buffer metadata configured on the host via CircularBufferConfig::set_unpack_face_geometry / CBFormatDescriptor::face_geometry.

This default init configures BH DEST remap. Use pack_untilize_init_skip_remap only when the caller has already configured BH DEST remap and no intervening operation requires a different DEST remap state.

Return value: None

Param Type Name

Template block_ct_dim

Template full_ct_dim

Template is_fp32_dest_acc_en

Function icb

Function ocb

NOTE: When a row is processed in multiple blocks, every block must use the same block_ct_dim; full_ct_dim must be divisible by block_ct_dim. Remainder blocks are unsupported because the L1 column offset is computed as block_c_index * block_ct_dim.

template<uint32_t block_ct_dim = 8, uint32_t full_ct_dim = block_ct_dim, bool is_fp32_dest_acc_en = DST_ACCUM_MODE>
void ckernel::pack_untilize_block(uint32_t icb, uint32_t block_rt_dim, uint32_t ocb, uint32_t block_c_index = 0)

Performs the untilize operation on a block of tiles. Loops over the provided block size. The block is characterized by its width in tiles (block_ct_dim) and height in tiles (block_rt_dim). The width of the block has to be the same as the one provided during the initialization of the pack untilize operation (pack_untilize_init). It is not needed to provide the height of the block during the initialization, since pack_untilize_block will loop over the height of the block. Note that the maximum size of the block is limited by the size of the DEST and synchronization mode used. These are maximum sizes:

  • half-sync mode (16-bit mode): 8 tiles

  • half-sync mode (32-bit mode): 4 tiles

  • full-sync mode (16-bit mode): 16 tiles

  • full-sync mode (32-bit mode): 8 tiles

Return value: None

Param Type Name

Template block_ct_dim

Template full_ct_dim

Function icb

Function block_rt_dim

Function ocb

Function block_c_index

NOTE: When a row is processed in multiple blocks, every block must use the same block_ct_dim; full_ct_dim must be divisible by block_ct_dim. Remainder blocks are unsupported because the L1 column offset is computed as block_c_index * block_ct_dim.

template<uint32_t block_ct_dim = 8, uint32_t full_ct_dim = block_ct_dim, bool diagonal = false, bool narrow_row = false, std::uint32_t row_num_datums = TILE_C_DIM, uint32_t tile_dst_ct_offset = 0, bool dense = false>
void ckernel::pack_untilize_dest(uint32_t ocb, uint32_t block_rt_dim = 1, uint32_t block_c_index = 0, uint32_t tile_dst_rt_offset = 0)

Performs the pack untilize operation when PACK input is already in DEST register. In order to properly initialize the operation, a call to pack_untilize_dest_init must be made before this function. The width of the block has to be the same as the one provided during the initialization of the pack untilize operation (pack_untilize_dest_init). In order for this untilization to be performed correctly, some other function must place the tiles in the DEST register, e.g. reduce_tile, copy_tile, etc. Similarly as pack_untilize_block, this function operates on a whole block that needs to be untilized. Note that the maximum size of the block is limited by the size of the DEST and synchronization mode used. These are maximum sizes:

  • half-sync mode (16-bit mode): 8 tiles

  • half-sync mode (32-bit mode): 4 tiles

  • full-sync mode (16-bit mode): 16 tiles

  • full-sync mode (32-bit mode): 8 tiles

Return value: None

Param Type Name

Template block_ct_dim

Template full_ct_dim

Template diagonal

Template narrow_row

Template row_num_datums

Template tile_dst_ct_offset

Template dense

Function ocb

Function block_rt_dim

Function block_c_index

Function tile_dst_offset

NOTE: When a row is processed in multiple blocks, every block must use the same block_ct_dim; full_ct_dim must be divisible by block_ct_dim. Remainder blocks are unsupported because the L1 column offset is computed as block_c_index * block_ct_dim.

NOTE: Face geometry (face_r_dim, num_faces) is derived from the output circular buffer metadata configured on the host via CircularBufferConfig::set_unpack_face_geometry / CBFormatDescriptor::face_geometry.

template<bool is_fp32_dest_acc_en = DST_ACCUM_MODE>
void ckernel::pack_untilize_uninit(uint32_t ocb)

Uninitializes the pack untilize operation, allowing another operations to be initialized. Needs to be called after the last call to pack_untilize_dest or pack_untilize_block, before initializing another operation.

NOTE: This function is not in line with our programming model, and will be removed by the end of 2025 as a part of tt-metal#22904.

Return value: None

Param Type Name

Function ocb