Syntax of AMDGPU Instruction Modifiers

Conventions

The following notation is used throughout this document:

Notation

Description

{0..N}

Any integer value in the range from 0 to N (inclusive).

<x>

Syntax and meaning of x are explained elsewhere.

Modifiers

DS Modifiers

offset0

Specifies the first 8-bit offset, in bytes. The default value is 0.

Used with DS instructions that expect two addresses.

Syntax

Description

offset0:{0..0xFF}

Specifies an unsigned 8-bit offset as a positive integer number or an absolute expression.

Examples:

offset0:0xff
offset0:2-x
offset0:-x-y

offset1

Specifies the second 8-bit offset, in bytes. The default value is 0.

Used with DS instructions that expect two addresses.

Syntax

Description

offset1:{0..0xFF}

Specifies an unsigned 8-bit offset as a positive integer number or an absolute expression.

Examples:

offset1:0xff
offset1:2-x
offset1:-x-y

offset

Specifies a 16-bit offset, in bytes. The default value is 0.

Used with DS instructions that expect a single address.

Syntax

Description

offset:{0..0xFFFF}

Specifies an unsigned 16-bit offset as a positive integer number or an absolute expression.

Examples:

offset:65535
offset:0xffff
offset:-x-y

swizzle pattern

This is a special modifier that may be used with ds_swizzle_b32 instruction only. It specifies a swizzle pattern in numeric or symbolic form. The default value is 0.

Syntax

Description

offset:{0..0xFFFF}

Specifies a 16-bit swizzle pattern.

offset:swizzle(QUAD_PERM,{0..3},{0..3},{0..3},{0..3})

Specifies a quad permute mode pattern

Each number is a lane id.

offset:swizzle(BITMASK_PERM, “<mask>”)

Specifies a bitmask permute mode pattern.

The pattern converts a 5-bit lane id to another lane id with which the lane interacts.

The mask is a 5-character sequence which specifies how to transform the bits of the lane id.

The following characters are allowed:

  • “0” - set bit to 0.

  • “1” - set bit to 1.

  • “p” - preserve bit.

  • “i” - inverse bit.

offset:swizzle(BROADCAST,{2..32},{0..N})

Specifies a broadcast mode.

Broadcasts the value of any particular lane to all lanes in its group.

The first numeric parameter is a group size and must be equal to 2, 4, 8, 16 or 32.

The second numeric parameter is an index of the lane being broadcast.

The index must not exceed group size.

offset:swizzle(SWAP,{1..16})

Specifies a swap mode.

Swaps the neighboring groups of 1, 2, 4, 8 or 16 lanes.

offset:swizzle(REVERSE,{2..32})

Specifies a reverse mode.

Reverses the lanes for groups of 2, 4, 8, 16 or 32 lanes.

Note: numeric values may be specified as either integer numbers or absolute expressions.

Examples:

offset:255
offset:0xffff
offset:swizzle(QUAD_PERM, 0, 1, 2, 3)
offset:swizzle(BITMASK_PERM, "01pi0")
offset:swizzle(BROADCAST, 2, 0)
offset:swizzle(SWAP, 8)
offset:swizzle(REVERSE, 30 + 2)

gds

Specifies whether to use GDS or LDS memory (LDS is the default).

Syntax

Description

gds

Use GDS memory.

EXP Modifiers

done

Specifies if this is the last export from the shader to the target. By default, an export instruction does not finish an export sequence.

Syntax

Description

done

Indicates the last export operation.

compr

Indicates if the data is compressed (data is not compressed by default).

Syntax

Description

compr

Data is compressed.

vm

Specifies if the exec mask is valid for this export instruction (the mask is not valid by default).

Syntax

Description

vm

Set the flag indicating a valid exec mask.

row_en

Specifies whether to export one row or multiple rows of data.

Syntax

Description

row_en

Export multiple rows using row index from M0.

FLAT Modifiers

offset12

Specifies an immediate unsigned 12-bit offset, in bytes. The default value is 0.

Syntax

Description

offset:{0..4095}

Specifies a 12-bit unsigned offset as a positive integer number or an absolute expression.

Examples:

offset:4095
offset:x-0xff

offset13s

Specifies an immediate signed 13-bit offset, in bytes. The default value is 0.

Syntax

Description

offset:{-4096..4095}

Specifies a 13-bit signed offset as an integer number or an absolute expression.

Examples:

offset:-4000
offset:0x10
offset:-x

offset12s

Specifies an immediate signed 12-bit offset, in bytes. The default value is 0.

Syntax

Description

offset:{-2048..2047}

Specifies a 12-bit signed offset as an integer number or an absolute expression.

Examples:

offset:-2000
offset:0x10
offset:-x+y

offset11

Specifies an immediate unsigned 11-bit offset, in bytes. The default value is 0.

Syntax

Description

offset:{0..2047}

Specifies an 11-bit unsigned offset as a positive integer number or an absolute expression.

Examples:

offset:2047
offset:x+0xff

dlc

See a description here.

glc

See a description here.

lds

See a description here.

slc

See a description here.

tfe

See a description here.

nv

See a description here.

sc0

See a description here.

sc1

See a description here.

nt

See a description here.

MIMG Modifiers

dmask

Specifies which channels (image components) are used by the operation. By default, no channels are used.

Syntax

Description

dmask:{0..15}

Specifies image channels as a positive integer number or an absolute expression.

Each bit corresponds to one of 4 image components (RGBA).

If the specified bit value is 0, the image component is not used, while value 1 means that the component is used.

This modifier has some limitations depending on the instruction kind:

Instruction Kind

Valid dmask Values

32-bit atomic cmpswap

0x3

32-bit atomic instructions except for cmpswap

0x1

64-bit atomic cmpswap

0xF

64-bit atomic instructions except for cmpswap

0x3

gather4

0x1, 0x2, 0x4, 0x8

GFX11+ msaa_load

0x1, 0x2, 0x4, 0x8

Other instructions

any value

Examples:

dmask:0xf
dmask:0b1111
dmask:x|y|z

unorm

Specifies whether the address is normalized or not (the address is normalized by default).

Syntax

Description

unorm

Force the address to be not normalized.

glc

See a description here.

slc

See a description here.

r128

Specifies texture resource size. The default size is 256 bits.

Syntax

Description

r128

Specifies 128 bits texture resource size.

Warning

Using this modifier shall decrease rsrc operand size from 8 to 4 dwords, but assembler does not currently support this feature.

tfe

See a description here.

lwe

Specifies LOD warning status (LOD warning is disabled by default).

Syntax

Description

lwe

Enables LOD warning.

da

Specifies if an array index must be sent to TA. By default, the array index is not sent.

Syntax

Description

da

Send an array index to TA.

d16

Specifies data size: 16 or 32 bits (32 bits by default).

Syntax

Description

d16

Enables 16-bits data mode.

On loads, convert data in memory to 16-bit format before storing it in VGPRs.

For stores, convert 16-bit data in VGPRs to 32 bits before writing the values to memory.

Note that GFX8.0 does not support data packing. Each 16-bit data element occupies 1 VGPR.

GFX8.1 and GFX9+ support data packing. Each pair of 16-bit data elements occupies 1 VGPR.

a16

Specifies the size of image address components: 16 or 32 bits (32 bits by default).

Syntax

Description

a16

Enables 16-bits image address components.

dim

Specifies surface dimension. This is a mandatory modifier. There is no default value.

Syntax

Description

dim:1D

One-dimensional image.

dim:2D

Two-dimensional image.

dim:3D

Three-dimensional image.

dim:CUBE

Cubemap array.

dim:1D_ARRAY

One-dimensional image array.

dim:2D_ARRAY

Two-dimensional image array.

dim:2D_MSAA

Two-dimensional multi-sample auto-aliasing image.

dim:2D_MSAA_ARRAY

Two-dimensional multi-sample auto-aliasing image array.

The following table defines an alternative syntax which is supported for compatibility with SP3 assembler:

Syntax

Description

dim:SQ_RSRC_IMG_1D

One-dimensional image.

dim:SQ_RSRC_IMG_2D

Two-dimensional image.

dim:SQ_RSRC_IMG_3D

Three-dimensional image.

dim:SQ_RSRC_IMG_CUBE

Cubemap array.

dim:SQ_RSRC_IMG_1D_ARRAY

One-dimensional image array.

dim:SQ_RSRC_IMG_2D_ARRAY

Two-dimensional image array.

dim:SQ_RSRC_IMG_2D_MSAA

Two-dimensional multi-sample auto-aliasing image.

dim:SQ_RSRC_IMG_2D_MSAA_ARRAY

Two-dimensional multi-sample auto-aliasing image array.

dlc

See a description here.

Miscellaneous Modifiers

dlc

Controls device level cache policy for memory operations. Used for synchronization. When specified, forces operation to bypass device level cache, making the operation device level coherent. By default, instructions use device level cache.

Syntax

Description

dlc

Bypass device level cache.

glc

For atomic opcodes, this modifier indicates that the instruction returns the value from memory before the operation. For other opcodes, it is used together with slc to specify cache policy.

The default value is off (0).

Syntax

Description

glc

Set glc bit to 1.

lds

Specifies where to store the result: VGPRs or LDS (VGPRs by default).

Syntax

Description

lds

Store the result in LDS.

nv

Specifies if the instruction is operating on non-volatile memory. By default, memory is volatile.

Syntax

Description

nv

Indicates that the instruction operates on non-volatile memory.

slc

Controls behavior of L2 cache. The default value is off (0).

Syntax

Description

slc

Set slc bit to 1.

tfe

Controls access to partially resident textures. The default value is off (0).

Syntax

Description

tfe

Set tfe bit to 1.

sc0

For atomic opcodes, this modifier indicates that the instruction returns the value from memory before the operation. For other opcodes, it is used together with sc1 to specify cache policy.

Syntax

Description

sc0

Set sc0 bit to 1.

sc1

This modifier is used together with sc0 to specify cache policy.

Syntax

Description

sc1

Set sc1 bit to 1.

nt

Indicates an operation with non-temporal data.

Syntax

Description

nt

Set nt bit to 1.

MUBUF/MTBUF Modifiers

idxen

Specifies whether address components include an index. By default, the index is not used.

May be used together with offen.

Cannot be used with addr64.

Syntax

Description

idxen

Address components include an index.

offen

Specifies whether address components include an offset. By default, the offset is not used.

May be used together with idxen.

Cannot be used with addr64.

Syntax

Description

offen

Address components include an offset.

addr64

Specifies whether a 64-bit address is used. By default, no address is used.

Cannot be used with offen and idxen modifiers.

Syntax

Description

addr64

A 64-bit address is used.

offset12

Specifies an immediate unsigned 12-bit offset, in bytes. The default value is 0.

Syntax

Description

offset:{0..0xFFF}

Specifies a 12-bit unsigned offset as a positive integer number or an absolute expression.

Examples:

offset:x+y
offset:0x10

glc

See a description here.

slc

See a description here.

lds

See a description here.

dlc

See a description here.

tfe

See a description here.

fmt

Specifies data and numeric formats used by the operation. The default numeric format is BUF_NUM_FORMAT_UNORM. The default data format is BUF_DATA_FORMAT_8.

Syntax

Description

format:{0..127}

Use a format specified as either an integer number or an absolute expression.

format:[<data format>]

Use the specified data format and default numeric format.

format:[<numeric format>]

Use the specified numeric format and default data format.

format:[<data format>,<numeric format>]

Use the specified data and numeric formats.

format:[<numeric format>,<data format>]

Use the specified data and numeric formats.

Supported data formats are defined in the following table:

Syntax

Note

BUF_DATA_FORMAT_INVALID

BUF_DATA_FORMAT_8

The default value.

BUF_DATA_FORMAT_16

BUF_DATA_FORMAT_8_8

BUF_DATA_FORMAT_32

BUF_DATA_FORMAT_16_16

BUF_DATA_FORMAT_10_11_11

BUF_DATA_FORMAT_11_11_10

BUF_DATA_FORMAT_10_10_10_2

BUF_DATA_FORMAT_2_10_10_10

BUF_DATA_FORMAT_8_8_8_8

BUF_DATA_FORMAT_32_32

BUF_DATA_FORMAT_16_16_16_16

BUF_DATA_FORMAT_32_32_32

BUF_DATA_FORMAT_32_32_32_32

BUF_DATA_FORMAT_RESERVED_15

Supported numeric formats are defined below:

Syntax

Note

BUF_NUM_FORMAT_UNORM

The default value.

BUF_NUM_FORMAT_SNORM

BUF_NUM_FORMAT_USCALED

BUF_NUM_FORMAT_SSCALED

BUF_NUM_FORMAT_UINT

BUF_NUM_FORMAT_SINT

BUF_NUM_FORMAT_SNORM_OGL

GFX7 only.

BUF_NUM_FORMAT_RESERVED_6

GFX8 and GFX9 only.

BUF_NUM_FORMAT_FLOAT

Examples:

format:0
format:127
format:[BUF_DATA_FORMAT_16]
format:[BUF_DATA_FORMAT_16,BUF_NUM_FORMAT_SSCALED]
format:[BUF_NUM_FORMAT_FLOAT]

ufmt

Specifies a unified format used by the operation. The default format is BUF_FMT_8_UNORM.

Syntax

Description

format:{0..127}

Use a unified format specified as either an integer number or an absolute expression. Note that unified format numbers are incompatible with format numbers used for pre-GFX10 ISA.

format:[<unified format>]

Use the specified unified format.

Unified format is a replacement for data and numeric formats. For compatibility with older ISA, the syntax with data and numeric formats is still accepted provided that the combination of formats can be mapped to a unified format.

Supported unified formats and equivalent combinations of data and numeric formats are defined below:

BUF_NUM_FORMAT_SSCALED

 flat_scratch, , Packing Suffix

    • index struction-mnemo">

    flat_scratch, index struction-mnemo">

    Unified Format Syntax

    Equivalent Data Format

    Equivalent Numeric Format

    Note

    BUF_FMT_INVALID

    BUF_DATA_FORMAT_INVALID

    BUF_NUM_FORMAT_UNORM

    BUF_FMT_8_UNORM

    BUF_DATA_FORMAT_8

    BUF_NUM_FORMAT_UNORM

    BUF_FMT_8_SNORM

    BUF_DATA_FORMAT_8

    BUF_NUM_FORMAT_SNORM

    BUF_FMT_8_USCALED

    BUF_DATA_FORMAT_8

    BUF_NUM_FORMAT_USCALED

    BUF_FMT_8_SSCALED

    BUF_DATA_FORMAT_8

    BUF_NUM_FORMAT_SSCALED

    BUF_FMT_8_UINT

    BUF_DATA_FORMAT_8

    BUF_NUM_FORMAT_UINT

    BUF_FMT_8_SINT

    BUF_DATA_FORMAT_8

    BUF_NUM_FORMAT_SINT

    BUF_FMT_16_UNORM

    BUF_DATA_FORMAT_16

    BUF_NUM_FORMAT_UNORM

    BUF_FMT_16_SNORM

    BUF_DATA_FORMAT_16

    BUF_NUM_FORMAT_SNORM

    BUF_FMT_16_USCALED

    BUF_DATA_FORMAT_16

    BUF_NUM_FORMAT_USCALED

    BUF_FMT_16_SSCALED

    BUF_DATA_FORMAT_16

    BUF_NUM_FORMAT_SSCALED

    BUF_FMT_16_UINT

    BUF_DATA_FORMAT_16

    BUF_NUM_FORMAT_UINT

    BUF_FMT_16_SINT

    BUF_DATA_FORMAT_16

    BUF_NUM_FORMAT_SINT

    BUF_FMT_16_FLOAT

    BUF_DATA_FORMAT_16

    BUF_NUM_FORMAT_FLOAT

    BUF_FMT_8_8_UNORM

    BUF_DATA_FORMAT_8_8

    BUF_NUM_FORMAT_UNORM

    BUF_FMT_8_8_SNORM

    BUF_DATA_FORMAT_8_8

    BUF_NUM_FORMAT_SNORM

    BUF_FMT_8_8_USCALED

    BUF_DATA_FORMAT_8_8

    BUF_NUM_FORMAT_USCALED

    BUF_FMT_8_8_SSCALED

    BUF_DATA_FORMAT_8_8

    BUF_NUM_FORMAT_SSCALED

    BUF_FMT_8_8_UINTional image.

    dim:SQ_RSNUM_FOss="row-odd">

    Unified Format Syntax

    BUF_NUM_FORMAT_SSCALED

    BUF_DATA_FORMAT_8_8

    BUF_NUM_FOmber or an

    Unified Format Syntax

    Unified Format Syntax

    lid51">offset12s

    dim:SQ_RSNUM_FOss="row-odd">

    		Unified Format Syntax

    lid51">offset12soffset12s

    lio51">offsem1354EDnumeric

    		td> td>

    BUF_FMT_16_SSCALED

    BUF_DATA_FO

    BUF_FMT_8_8_SSCALED

    BUF_DATA_MAT_UINT

    BUF_FMT_8_8_SNORM

    w-odd">

    BUF_FMT_8_=4c/d>

    BUF_NUM_FORMAT_UINT

    BUF_DATA_FORMAT_16

    BUF_NUM_FORMAT_USCALED

    BUF_FMT_16_SSCALED

    BUF_DATA_FORMAT_16

    BUF_NUM_FORMAT_SSCALED

    BUF_FMT_16_SSCALED

    		 ecific uORMAT_UNORM