Mercurial > hg > CbC > CbC_llvm

comparison docs/AMDGPUOperandSyntax.rst @ 148:63bd29f05246

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
merged
author Shinji KONO <kono@ie.u-ryukyu.ac.jp>
date Wed, 14 Aug 2019 19:46:37 +0900
parents c2174574ed3a
children
comparison
equal deleted inserted replaced
146:3fc4d5c3e21e 148:63bd29f05246
1 =====================================
2 Syntax of AMDGPU Instruction Operands
3 =====================================
4
5 .. contents::
6 :local:
7
8 Conventions
9 ===========
10
11 The following notation is used throughout this document:
12
13 =================== =============================================================================
14 Notation Description
15 =================== =============================================================================
16 {0..N} Any integer value in the range from 0 to N (inclusive).
17 <x> Syntax and meaning of *x* is explained elsewhere.
18 =================== =============================================================================
19
20 .. _amdgpu_syn_operands:
21
22 Operands
23 ========
24
25 .. _amdgpu_synid_v:
26
27 v
28 -
29
30 Vector registers. There are 256 32-bit vector registers.
31
32 A sequence of *vector* registers may be used to operate with more than 32 bits of data.
33
34 Assembler currently supports sequences of 1, 2, 3, 4, 8 and 16 *vector* registers.
35
36 =================================================== ====================================================================
37 Syntax Description
38 =================================================== ====================================================================
39 **v**\<N> A single 32-bit *vector* register.
40
41 *N* must be a decimal integer number.
42 **v[**\ <N>\ **]** A single 32-bit *vector* register.
43
44 *N* may be specified as an
45 :ref:`integer number<amdgpu_synid_integer_number>`
46 or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`.
47 **v[**\ <N>:<K>\ **]** A sequence of (\ *K-N+1*\ ) *vector* registers.
48
49 *N* and *K* may be specified as
50 :ref:`integer numbers<amdgpu_synid_integer_number>`
51 or :ref:`absolute expressions<amdgpu_synid_absolute_expression>`.
52 **[v**\ <N>, \ **v**\ <N+1>, ... **v**\ <K>\ **]** A sequence of (\ *K-N+1*\ ) *vector* registers.
53
54 Register indices must be specified as decimal integer numbers.
55 =================================================== ====================================================================
56
57 Note. *N* and *K* must satisfy the following conditions:
58
59 * *N* <= *K*.
60 * 0 <= *N* <= 255.
61 * 0 <= *K* <= 255.
62 * *K-N+1* must be equal to 1, 2, 3, 4, 8 or 16.
63
64 Examples:
65
66 .. parsed-literal::
67
68 v255
69 v[0]
70 v[0:1]
71 v[1:1]
72 v[0:3]
73 v[2*2]
74 v[1-1:2-1]
75 [v252]
76 [v252,v253,v254,v255]
77
78 .. _amdgpu_synid_nsa:
79
80 *Image* instructions may use special *NSA* (Non-Sequential Address) syntax for *image addresses*:
81
82 =================================================== ====================================================================
83 Syntax Description
84 =================================================== ====================================================================
85 **[v**\ <A>, \ **v**\ <B>, ... **v**\ <X>\ **]** A sequence of *vector* registers. At least one register
86 must be specified.
87
88 In contrast with standard syntax described above, registers in
89 this sequence are not required to have consecutive indices.
90 Moreover, the same register may appear in the list more than once.
91 =================================================== ====================================================================
92
93 Note. Reqister indices must be in the range 0..255. They must be specified as decimal integer numbers.
94
95 Examples:
96
97 .. parsed-literal::
98
99 [v32,v1,v2]
100 [v4,v4,v4,v4]
101
102 .. _amdgpu_synid_s:
103
104 s
105 -
106
107 Scalar 32-bit registers. The number of available *scalar* registers depends on GPU:
108
109 ======= ============================
110 GPU Number of *scalar* registers
111 ======= ============================
112 GFX7 104
113 GFX8 102
114 GFX9 102
115 GFX10 106
116 ======= ============================
117
118 A sequence of *scalar* registers may be used to operate with more than 32 bits of data.
119 Assembler currently supports sequences of 1, 2, 4, 8 and 16 *scalar* registers.
120
121 Pairs of *scalar* registers must be even-aligned (the first register must be even).
122 Sequences of 4 and more *scalar* registers must be quad-aligned.
123
124 ======================================================== ====================================================================
125 Syntax Description
126 ======================================================== ====================================================================
127 **s**\ <N> A single 32-bit *scalar* register.
128
129 *N* must be a decimal integer number.
130 **s[**\ <N>\ **]** A single 32-bit *scalar* register.
131
132 *N* may be specified as an
133 :ref:`integer number<amdgpu_synid_integer_number>`
134 or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`.
135 **s[**\ <N>:<K>\ **]** A sequence of (\ *K-N+1*\ ) *scalar* registers.
136
137 *N* and *K* may be specified as
138 :ref:`integer numbers<amdgpu_synid_integer_number>`
139 or :ref:`absolute expressions<amdgpu_synid_absolute_expression>`.
140 **[s**\ <N>, \ **s**\ <N+1>, ... **s**\ <K>\ **]** A sequence of (\ *K-N+1*\ ) *scalar* registers.
141
142 Register indices must be specified as decimal integer numbers.
143 ======================================================== ====================================================================
144
145 Note. *N* and *K* must satisfy the following conditions:
146
147 * *N* must be properly aligned based on sequence size.
148 * *N* <= *K*.
149 * 0 <= *N* < *SMAX*\ , where *SMAX* is the number of available *scalar* registers.
150 * 0 <= *K* < *SMAX*\ , where *SMAX* is the number of available *scalar* registers.
151 * *K-N+1* must be equal to 1, 2, 4, 8 or 16.
152
153 Examples:
154
155 .. parsed-literal::
156
157 s0
158 s[0]
159 s[0:1]
160 s[1:1]
161 s[0:3]
162 s[2*2]
163 s[1-1:2-1]
164 [s4]
165 [s4,s5,s6,s7]
166
167 Examples of *scalar* registers with an invalid alignment:
168
169 .. parsed-literal::
170
171 s[1:2]
172 s[2:5]
173
174 .. _amdgpu_synid_trap:
175
176 trap
177 ----
178
179 A set of trap handler registers:
180
181 * :ref:`ttmp<amdgpu_synid_ttmp>`
182 * :ref:`tba<amdgpu_synid_tba>`
183 * :ref:`tma<amdgpu_synid_tma>`
184
185 .. _amdgpu_synid_ttmp:
186
187 ttmp
188 ----
189
190 Trap handler temporary scalar registers, 32-bits wide.
191 The number of available *ttmp* registers depends on GPU:
192
193 ======= ===========================
194 GPU Number of *ttmp* registers
195 ======= ===========================
196 GFX7 12
197 GFX8 12
198 GFX9 16
199 GFX10 16
200 ======= ===========================
201
202 A sequence of *ttmp* registers may be used to operate with more than 32 bits of data.
203 Assembler currently supports sequences of 1, 2, 4, 8 and 16 *ttmp* registers.
204
205 Pairs of *ttmp* registers must be even-aligned (the first register must be even).
206 Sequences of 4 and more *ttmp* registers must be quad-aligned.
207
208 ============================================================= ====================================================================
209 Syntax Description
210 ============================================================= ====================================================================
211 **ttmp**\ <N> A single 32-bit *ttmp* register.
212
213 *N* must be a decimal integer number.
214 **ttmp[**\ <N>\ **]** A single 32-bit *ttmp* register.
215
216 *N* may be specified as an
217 :ref:`integer number<amdgpu_synid_integer_number>`
218 or an :ref:`absolute expression<amdgpu_synid_absolute_expression>`.
219 **ttmp[**\ <N>:<K>\ **]** A sequence of (\ *K-N+1*\ ) *ttmp* registers.
220
221 *N* and *K* may be specified as
222 :ref:`integer numbers<amdgpu_synid_integer_number>`
223 or :ref:`absolute expressions<amdgpu_synid_absolute_expression>`.
224 **[ttmp**\ <N>, \ **ttmp**\ <N+1>, ... **ttmp**\ <K>\ **]** A sequence of (\ *K-N+1*\ ) *ttmp* registers.
225
226 Register indices must be specified as decimal integer numbers.
227 ============================================================= ====================================================================
228
229 Note. *N* and *K* must satisfy the following conditions:
230
231 * *N* must be properly aligned based on sequence size.
232 * *N* <= *K*.
233 * 0 <= *N* < *TMAX*, where *TMAX* is the number of available *ttmp* registers.
234 * 0 <= *K* < *TMAX*, where *TMAX* is the number of available *ttmp* registers.
235 * *K-N+1* must be equal to 1, 2, 4, 8 or 16.
236
237 Examples:
238
239 .. parsed-literal::
240
241 ttmp0
242 ttmp[0]
243 ttmp[0:1]
244 ttmp[1:1]
245 ttmp[0:3]
246 ttmp[2*2]
247 ttmp[1-1:2-1]
248 [ttmp4]
249 [ttmp4,ttmp5,ttmp6,ttmp7]
250
251 Examples of *ttmp* registers with an invalid alignment:
252
253 .. parsed-literal::
254
255 ttmp[1:2]
256 ttmp[2:5]
257
258 .. _amdgpu_synid_tba:
259
260 tba
261 ---
262
263 Trap base address, 64-bits wide. Holds the pointer to the current trap handler program.
264
265 ================== ======================================================================= =============
266 Syntax Description Availability
267 ================== ======================================================================= =============
268 tba 64-bit *trap base address* register. GFX7, GFX8
269 [tba] 64-bit *trap base address* register (an alternative syntax). GFX7, GFX8
270 [tba_lo,tba_hi] 64-bit *trap base address* register (an alternative syntax). GFX7, GFX8
271 ================== ======================================================================= =============
272
273 High and low 32 bits of *trap base address* may be accessed as separate registers:
274
275 ================== ======================================================================= =============
276 Syntax Description Availability
277 ================== ======================================================================= =============
278 tba_lo Low 32 bits of *trap base address* register. GFX7, GFX8
279 tba_hi High 32 bits of *trap base address* register. GFX7, GFX8
280 [tba_lo] Low 32 bits of *trap base address* register (an alternative syntax). GFX7, GFX8
281 [tba_hi] High 32 bits of *trap base address* register (an alternative syntax). GFX7, GFX8
282 ================== ======================================================================= =============
283
284 Note that *tba*, *tba_lo* and *tba_hi* are not accessible as assembler registers in GFX9 and GFX10,
285 but *tba* is readable/writable with the help of *s_get_reg* and *s_set_reg* instructions.
286
287 .. _amdgpu_synid_tma:
288
289 tma
290 ---
291
292 Trap memory address, 64-bits wide.
293
294 ================= ======================================================================= ==================
295 Syntax Description Availability
296 ================= ======================================================================= ==================
297 tma 64-bit *trap memory address* register. GFX7, GFX8
298 [tma] 64-bit *trap memory address* register (an alternative syntax). GFX7, GFX8
299 [tma_lo,tma_hi] 64-bit *trap memory address* register (an alternative syntax). GFX7, GFX8
300 ================= ======================================================================= ==================
301
302 High and low 32 bits of *trap memory address* may be accessed as separate registers:
303
304 ================= ======================================================================= ==================
305 Syntax Description Availability
306 ================= ======================================================================= ==================
307 tma_lo Low 32 bits of *trap memory address* register. GFX7, GFX8
308 tma_hi High 32 bits of *trap memory address* register. GFX7, GFX8
309 [tma_lo] Low 32 bits of *trap memory address* register (an alternative syntax). GFX7, GFX8
310 [tma_hi] High 32 bits of *trap memory address* register (an alternative syntax). GFX7, GFX8
311 ================= ======================================================================= ==================
312
313 Note that *tma*, *tma_lo* and *tma_hi* are not accessible as assembler registers in GFX9 and GFX10,
314 but *tma* is readable/writable with the help of *s_get_reg* and *s_set_reg* instructions.
315
316 .. _amdgpu_synid_flat_scratch:
317
318 flat_scratch
319 ------------
320
321 Flat scratch address, 64-bits wide. Holds the base address of scratch memory.
322
323 ================================== ================================================================
324 Syntax Description
325 ================================== ================================================================
326 flat_scratch 64-bit *flat scratch* address register.
327 [flat_scratch] 64-bit *flat scratch* address register (an alternative syntax).
328 [flat_scratch_lo,flat_scratch_hi] 64-bit *flat scratch* address register (an alternative syntax).
329 ================================== ================================================================
330
331 High and low 32 bits of *flat scratch* address may be accessed as separate registers:
332
333 ========================= =========================================================================
334 Syntax Description
335 ========================= =========================================================================
336 flat_scratch_lo Low 32 bits of *flat scratch* address register.
337 flat_scratch_hi High 32 bits of *flat scratch* address register.
338 [flat_scratch_lo] Low 32 bits of *flat scratch* address register (an alternative syntax).
339 [flat_scratch_hi] High 32 bits of *flat scratch* address register (an alternative syntax).
340 ========================= =========================================================================
341
342 .. _amdgpu_synid_xnack:
343
344 xnack
345 -----
346
347 Xnack mask, 64-bits wide. Holds a 64-bit mask of which threads
348 received an *XNACK* due to a vector memory operation.
349
350 .. WARNING:: GFX7 does not support *xnack* feature. For availability of this feature in other GPUs, refer :ref:`this table<amdgpu-processors>`.
351
352 \
353
354 ============================== =====================================================
355 Syntax Description
356 ============================== =====================================================
357 xnack_mask 64-bit *xnack mask* register.
358 [xnack_mask] 64-bit *xnack mask* register (an alternative syntax).
359 [xnack_mask_lo,xnack_mask_hi] 64-bit *xnack mask* register (an alternative syntax).
360 ============================== =====================================================
361
362 High and low 32 bits of *xnack mask* may be accessed as separate registers:
363
364 ===================== ==============================================================
365 Syntax Description
366 ===================== ==============================================================
367 xnack_mask_lo Low 32 bits of *xnack mask* register.
368 xnack_mask_hi High 32 bits of *xnack mask* register.
369 [xnack_mask_lo] Low 32 bits of *xnack mask* register (an alternative syntax).
370 [xnack_mask_hi] High 32 bits of *xnack mask* register (an alternative syntax).
371 ===================== ==============================================================
372
373 .. _amdgpu_synid_vcc:
374 .. _amdgpu_synid_vcc_lo:
375
376 vcc
377 ---
378
379 Vector condition code, 64-bits wide. A bit mask with one bit per thread;
380 it holds the result of a vector compare operation.
381
382 Note that GFX10 H/W does not use high 32 bits of *vcc* in *wave32* mode.
383
384 ================ =========================================================================
385 Syntax Description
386 ================ =========================================================================
387 vcc 64-bit *vector condition code* register.
388 [vcc] 64-bit *vector condition code* register (an alternative syntax).
389 [vcc_lo,vcc_hi] 64-bit *vector condition code* register (an alternative syntax).
390 ================ =========================================================================
391
392 High and low 32 bits of *vector condition code* may be accessed as separate registers:
393
394 ================ =========================================================================
395 Syntax Description
396 ================ =========================================================================
397 vcc_lo Low 32 bits of *vector condition code* register.
398 vcc_hi High 32 bits of *vector condition code* register.
399 [vcc_lo] Low 32 bits of *vector condition code* register (an alternative syntax).
400 [vcc_hi] High 32 bits of *vector condition code* register (an alternative syntax).
401 ================ =========================================================================
402
403 .. _amdgpu_synid_m0:
404
405 m0
406 --
407
408 A 32-bit memory register. It has various uses,
409 including register indexing and bounds checking.
410
411 =========== ===================================================
412 Syntax Description
413 =========== ===================================================
414 m0 A 32-bit *memory* register.
415 [m0] A 32-bit *memory* register (an alternative syntax).
416 =========== ===================================================
417
418 .. _amdgpu_synid_exec:
419
420 exec
421 ----
422
423 Execute mask, 64-bits wide. A bit mask with one bit per thread,
424 which is applied to vector instructions and controls which threads execute
425 and which ignore the instruction.
426
427 Note that GFX10 H/W does not use high 32 bits of *exec* in *wave32* mode.
428
429 ===================== =================================================================
430 Syntax Description
431 ===================== =================================================================
432 exec 64-bit *execute mask* register.
433 [exec] 64-bit *execute mask* register (an alternative syntax).
434 [exec_lo,exec_hi] 64-bit *execute mask* register (an alternative syntax).
435 ===================== =================================================================
436
437 High and low 32 bits of *execute mask* may be accessed as separate registers:
438
439 ===================== =================================================================
440 Syntax Description
441 ===================== =================================================================
442 exec_lo Low 32 bits of *execute mask* register.
443 exec_hi High 32 bits of *execute mask* register.
444 [exec_lo] Low 32 bits of *execute mask* register (an alternative syntax).
445 [exec_hi] High 32 bits of *execute mask* register (an alternative syntax).
446 ===================== =================================================================
447
448 .. _amdgpu_synid_vccz:
449
450 vccz
451 ----
452
453 A single bit flag indicating that the :ref:`vcc<amdgpu_synid_vcc>` is all zeros.
454
455 Note. When GFX10 operates in *wave32* mode, this register reflects state of :ref:`vcc_lo<amdgpu_synid_vcc_lo>`.
456
457 .. _amdgpu_synid_execz:
458
459 execz
460 -----
461
462 A single bit flag indicating that the :ref:`exec<amdgpu_synid_exec>` is all zeros.
463
464 Note. When GFX10 operates in *wave32* mode, this register reflects state of :ref:`exec_lo<amdgpu_synid_exec>`.
465
466 .. _amdgpu_synid_scc:
467
468 scc
469 ---
470
471 A single bit flag indicating the result of a scalar compare operation.
472
473 .. _amdgpu_synid_lds_direct:
474
475 lds_direct
476 ----------
477
478 A special operand which supplies a 32-bit value
479 fetched from *LDS* memory using :ref:`m0<amdgpu_synid_m0>` as an address.
480
481 .. _amdgpu_synid_null:
482
483 null
484 ----
485
486 This is a special operand which may be used as a source or a destination.
487
488 When used as a destination, the result of the operation is discarded.
489
490 When used as a source, it supplies zero value.
491
492 GFX10 only.
493
494 .. WARNING:: Due to a H/W bug, this operand cannot be used with VALU instructions in first generation of GFX10.
495
496 .. _amdgpu_synid_constant:
497
498 constant
499 --------
500
501 A set of integer and floating-point *inline* constants and values:
502
503 * :ref:`iconst<amdgpu_synid_iconst>`
504 * :ref:`fconst<amdgpu_synid_fconst>`
505 * :ref:`ival<amdgpu_synid_ival>`
506
507 In contrast with :ref:`literals<amdgpu_synid_literal>`, these operands are encoded as a part of instruction.
508
509 If a number may be encoded as either
510 a :ref:`literal<amdgpu_synid_literal>` or
511 a :ref:`constant<amdgpu_synid_constant>`,
512 assembler selects the latter encoding as more efficient.
513
514 .. _amdgpu_synid_iconst:
515
516 iconst
517 ~~~~~~
518
519 An :ref:`integer number<amdgpu_synid_integer_number>`
520 encoded as an *inline constant*.
521
522 Only a small fraction of integer numbers may be encoded as *inline constants*.
523 They are enumerated in the table below.
524 Other integer numbers have to be encoded as :ref:`literals<amdgpu_synid_literal>`.
525
526 Integer *inline constants* are converted to
527 :ref:`expected operand type<amdgpu_syn_instruction_type>`
528 as described :ref:`here<amdgpu_synid_int_const_conv>`.
529
530 ================================== ====================================
531 Value Note
532 ================================== ====================================
533 {0..64} Positive integer inline constants.
534 {-16..-1} Negative integer inline constants.
535 ================================== ====================================
536
537 .. WARNING:: GFX7 does not support inline constants for *f16* operands.
538
539 .. _amdgpu_synid_fconst:
540
541 fconst
542 ~~~~~~
543
544 A :ref:`floating-point number<amdgpu_synid_floating-point_number>`
545 encoded as an *inline constant*.
546
547 Only a small fraction of floating-point numbers may be encoded as *inline constants*.
548 They are enumerated in the table below.
549 Other floating-point numbers have to be encoded as :ref:`literals<amdgpu_synid_literal>`.
550
551 Floating-point *inline constants* are converted to
552 :ref:`expected operand type<amdgpu_syn_instruction_type>`
553 as described :ref:`here<amdgpu_synid_fp_const_conv>`.
554
555 ===================== ===================================================== ==================
556 Value Note Availability
557 ===================== ===================================================== ==================
558 0.0 The same as integer constant 0. All GPUs
559 0.5 Floating-point constant 0.5 All GPUs
560 1.0 Floating-point constant 1.0 All GPUs
561 2.0 Floating-point constant 2.0 All GPUs
562 4.0 Floating-point constant 4.0 All GPUs
563 -0.5 Floating-point constant -0.5 All GPUs
564 -1.0 Floating-point constant -1.0 All GPUs
565 -2.0 Floating-point constant -2.0 All GPUs
566 -4.0 Floating-point constant -4.0 All GPUs
567 0.1592 1.0/(2.0*pi). Use only for 16-bit operands. GFX8, GFX9, GFX10
568 0.15915494 1.0/(2.0*pi). Use only for 16- and 32-bit operands. GFX8, GFX9, GFX10
569 0.15915494309189532 1.0/(2.0*pi). GFX8, GFX9, GFX10
570 ===================== ===================================================== ==================
571
572 .. WARNING:: GFX7 does not support inline constants for *f16* operands.
573
574 .. _amdgpu_synid_ival:
575
576 ival
577 ~~~~
578
579 A symbolic operand encoded as an *inline constant*.
580 These operands provide read-only access to H/W registers.
581
582 ======================== ================================================ =============
583 Syntax Note Availability
584 ======================== ================================================ =============
585 shared_base Base address of shared memory region. GFX9, GFX10
586 shared_limit Address of the end of shared memory region. GFX9, GFX10
587 private_base Base address of private memory region. GFX9, GFX10
588 private_limit Address of the end of private memory region. GFX9, GFX10
589 pops_exiting_wave_id A dedicated counter for POPS. GFX9, GFX10
590 ======================== ================================================ =============
591
592 .. _amdgpu_synid_literal:
593
594 literal
595 -------
596
597 A literal is a 64-bit value which is encoded as a separate 32-bit dword in the instruction stream.
598
599 If a number may be encoded as either
600 a :ref:`literal<amdgpu_synid_literal>` or
601 an :ref:`inline constant<amdgpu_synid_constant>`,
602 assembler selects the latter encoding as more efficient.
603
604 Literals may be specified as :ref:`integer numbers<amdgpu_synid_integer_number>`,
605 :ref:`floating-point numbers<amdgpu_synid_floating-point_number>` or
606 :ref:`expressions<amdgpu_synid_expression>`
607 (expressions are currently supported for 32-bit operands only).
608
609 A 64-bit literal value is converted by assembler
610 to an :ref:`expected operand type<amdgpu_syn_instruction_type>`
611 as described :ref:`here<amdgpu_synid_lit_conv>`.
612
613 An instruction may use only one literal but several operands may refer the same literal.
614
615 .. _amdgpu_synid_uimm8:
616
617 uimm8
618 -----
619
620 A 8-bit positive :ref:`integer number<amdgpu_synid_integer_number>`.
621 The value is encoded as part of the opcode so it is free to use.
622
623 .. _amdgpu_synid_uimm32:
624
625 uimm32
626 ------
627
628 A 32-bit positive :ref:`integer number<amdgpu_synid_integer_number>`.
629 The value is stored as a separate 32-bit dword in the instruction stream.
630
631 .. _amdgpu_synid_uimm20:
632
633 uimm20
634 ------
635
636 A 20-bit positive :ref:`integer number<amdgpu_synid_integer_number>`.
637
638 .. _amdgpu_synid_uimm21:
639
640 uimm21
641 ------
642
643 A 21-bit positive :ref:`integer number<amdgpu_synid_integer_number>`.
644
645 .. WARNING:: Assembler currently supports 20-bit offsets only. Use :ref:`uimm20<amdgpu_synid_uimm20>` as a replacement.
646
647 .. _amdgpu_synid_simm21:
648
649 simm21
650 ------
651
652 A 21-bit :ref:`integer number<amdgpu_synid_integer_number>`.
653
654 .. WARNING:: Assembler currently supports 20-bit unsigned offsets only. Use :ref:`uimm20<amdgpu_synid_uimm20>` as a replacement.
655
656 .. _amdgpu_synid_off:
657
658 off
659 ---
660
661 A special entity which indicates that the value of this operand is not used.
662
663 ================================== ===================================================
664 Syntax Description
665 ================================== ===================================================
666 off Indicates an unused operand.
667 ================================== ===================================================
668
669
670 .. _amdgpu_synid_number:
671
672 Numbers
673 =======
674
675 .. _amdgpu_synid_integer_number:
676
677 Integer Numbers
678 ---------------
679
680 Integer numbers are 64 bits wide.
681 They may be specified in binary, octal, hexadecimal and decimal formats:
682
683 ============== ====================================
684 Format Syntax
685 ============== ====================================
686 Decimal [-]?[1-9][0-9]*
687 Binary [-]?0b[01]+
688 Octal [-]?0[0-7]+
689 Hexadecimal [-]?0x[0-9a-fA-F]+
690 \ [-]?[0x]?[0-9][0-9a-fA-F]*[hH]
691 ============== ====================================
692
693 Examples:
694
695 .. parsed-literal::
696
697 -1234
698 0b1010
699 010
700 0xff
701 0ffh
702
703 .. _amdgpu_synid_floating-point_number:
704
705 Floating-Point Numbers
706 ----------------------
707
708 All floating-point numbers are handled as double (64 bits wide).
709
710 Floating-point numbers may be specified in hexadecimal and decimal formats:
711
712 ============== ======================================================== ========================================================
713 Format Syntax Note
714 ============== ======================================================== ========================================================
715 Decimal [-]?[0-9]*[.][0-9]*([eE][+-]?[0-9]*)? Must include either a decimal separator or an exponent.
716 Hexadecimal [-]0x[0-9a-fA-F]*(.[0-9a-fA-F]*)?[pP][+-]?[0-9a-fA-F]+
717 ============== ======================================================== ========================================================
718
719 Examples:
720
721 .. parsed-literal::
722
723 -1.234
724 234e2
725 -0x1afp-10
726 0x.1afp10
727
728 .. _amdgpu_synid_expression:
729
730 Expressions
731 ===========
732
733 An expression specifies an address or a numeric value.
734 There are two kinds of expressions:
735
736 * :ref:`Absolute<amdgpu_synid_absolute_expression>`.
737 * :ref:`Relocatable<amdgpu_synid_relocatable_expression>`.
738
739 .. _amdgpu_synid_absolute_expression:
740
741 Absolute Expressions
742 --------------------
743
744 The value of an absolute expression remains the same after program relocation.
745 Absolute expressions must not include unassigned and relocatable values
746 such as labels.
747
748 Examples:
749
750 .. parsed-literal::
751
752 x = -1
753 y = x + 10
754
755 .. _amdgpu_synid_relocatable_expression:
756
757 Relocatable Expressions
758 -----------------------
759
760 The value of a relocatable expression depends on program relocation.
761
762 Note that use of relocatable expressions is limited with branch targets
763 and 32-bit :ref:`literals<amdgpu_synid_literal>`.
764
765 Addition information about relocation may be found :ref:`here<amdgpu-relocation-records>`.
766
767 Examples:
768
769 .. parsed-literal::
770
771 y = x + 10 // x is not yet defined. Undefined symbols are assumed to be PC-relative.
772 z = .
773
774 Expression Data Type
775 --------------------
776
777 Expressions and operands of expressions are interpreted as 64-bit integers.
778
779 Expressions may include 64-bit :ref:`floating-point numbers<amdgpu_synid_floating-point_number>` (double).
780 However these operands are also handled as 64-bit integers
781 using binary representation of specified floating-point numbers.
782 No conversion from floating-point to integer is performed.
783
784 Examples:
785
786 .. parsed-literal::
787
788 x = 0.1 // x is assigned an integer 4591870180066957722 which is a binary representation of 0.1.
789 y = x + x // y is a sum of two integer values; it is not equal to 0.2!
790
791 Syntax
792 ------
793
794 Expressions are composed of
795 :ref:`symbols<amdgpu_synid_symbol>`,
796 :ref:`integer numbers<amdgpu_synid_integer_number>`,
797 :ref:`floating-point numbers<amdgpu_synid_floating-point_number>`,
798 :ref:`binary operators<amdgpu_synid_expression_bin_op>`,
799 :ref:`unary operators<amdgpu_synid_expression_un_op>` and subexpressions.
800
801 Expressions may also use "." which is a reference to the current PC (program counter).
802
803 The syntax of expressions is shown below::
804
805 expr ::= expr binop expr | primaryexpr ;
806
807 primaryexpr ::= '(' expr ')' | symbol | number | '.' | unop primaryexpr ;
808
809 binop ::= '&&'
810 | '||'
811 | '|'
812 | '^'
813 | '&'
814 | '!'
815 | '=='
816 | '!='
817 | '<>'
818 | '<'
819 | '<='
820 | '>'
821 | '>='
822 | '<<'
823 | '>>'
824 | '+'
825 | '-'
826 | '*'
827 | '/'
828 | '%' ;
829
830 unop ::= '~'
831 | '+'
832 | '-'
833 | '!' ;
834
835 .. _amdgpu_synid_expression_bin_op:
836
837 Binary Operators
838 ----------------
839
840 Binary operators are described in the following table.
841 They operate on and produce 64-bit integers.
842 Operators with higher priority are performed first.
843
844 ========== ========= ===============================================
845 Operator Priority Meaning
846 ========== ========= ===============================================
847 \* 5 Integer multiplication.
848 / 5 Integer division.
849 % 5 Integer signed remainder.
850 \+ 4 Integer addition.
851 \- 4 Integer subtraction.
852 << 3 Integer shift left.
853 >> 3 Logical shift right.
854 == 2 Equality comparison.
855 != 2 Inequality comparison.
856 <> 2 Inequality comparison.
857 < 2 Signed less than comparison.
858 <= 2 Signed less than or equal comparison.
859 > 2 Signed greater than comparison.
860 >= 2 Signed greater than or equal comparison.
861 \| 1 Bitwise or.
862 ^ 1 Bitwise xor.
863 & 1 Bitwise and.
864 && 0 Logical and.
865 || 0 Logical or.
866 ========== ========= ===============================================
867
868 .. _amdgpu_synid_expression_un_op:
869
870 Unary Operators
871 ---------------
872
873 Unary operators are described in the following table.
874 They operate on and produce 64-bit integers.
875
876 ========== ===============================================
877 Operator Meaning
878 ========== ===============================================
879 ! Logical negation.
880 ~ Bitwise negation.
881 \+ Integer unary plus.
882 \- Integer unary minus.
883 ========== ===============================================
884
885 .. _amdgpu_synid_symbol:
886
887 Symbols
888 -------
889
890 A symbol is a named 64-bit value, representing a relocatable
891 address or an absolute (non-relocatable) number.
892
893 Symbol names have the following syntax:
894 ``[a-zA-Z_.][a-zA-Z0-9_$.@]*``
895
896 The table below provides several examples of syntax used for symbol definition.
897
898 ================ ==========================================================
899 Syntax Meaning
900 ================ ==========================================================
901 .globl <S> Declares a global symbol S without assigning it a value.
902 .set <S>, <E> Assigns the value of an expression E to a symbol S.
903 <S> = <E> Assigns the value of an expression E to a symbol S.
904 <S>: Declares a label S and assigns it the current PC value.
905 ================ ==========================================================
906
907 A symbol may be used before it is declared or assigned;
908 unassigned symbols are assumed to be PC-relative.
909
910 Addition information about symbols may be found :ref:`here<amdgpu-symbols>`.
911
912 .. _amdgpu_synid_conv:
913
914 Conversions
915 ===========
916
917 This section describes what happens when a 64-bit
918 :ref:`integer number<amdgpu_synid_integer_number>`, a
919 :ref:`floating-point numbers<amdgpu_synid_floating-point_number>` or a
920 :ref:`symbol<amdgpu_synid_symbol>`
921 is used for an operand which has a different type or size.
922
923 Depending on operand kind, this conversion is performed by either assembler or AMDGPU H/W:
924
925 * Values encoded as :ref:`inline constants<amdgpu_synid_constant>` are handled by H/W.
926 * Values encoded as :ref:`literals<amdgpu_synid_literal>` are converted by assembler.
927
928 .. _amdgpu_synid_const_conv:
929
930 Inline Constants
931 ----------------
932
933 .. _amdgpu_synid_int_const_conv:
934
935 Integer Inline Constants
936 ~~~~~~~~~~~~~~~~~~~~~~~~
937
938 Integer :ref:`inline constants<amdgpu_synid_constant>`
939 may be thought of as 64-bit
940 :ref:`integer numbers<amdgpu_synid_integer_number>`;
941 when used as operands they are truncated to the size of
942 :ref:`expected operand type<amdgpu_syn_instruction_type>`.
943 No data type conversions are performed.
944
945 Examples:
946
947 .. parsed-literal::
948
949 // GFX9
950
951 v_add_u16 v0, -1, 0 // v0 = 0xFFFF
952 v_add_f16 v0, -1, 0 // v0 = 0xFFFF (NaN)
953
954 v_add_u32 v0, -1, 0 // v0 = 0xFFFFFFFF
955 v_add_f32 v0, -1, 0 // v0 = 0xFFFFFFFF (NaN)
956
957 .. _amdgpu_synid_fp_const_conv:
958
959 Floating-Point Inline Constants
960 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
961
962 Floating-point :ref:`inline constants<amdgpu_synid_constant>`
963 may be thought of as 64-bit
964 :ref:`floating-point numbers<amdgpu_synid_floating-point_number>`;
965 when used as operands they are converted to a floating-point number of
966 :ref:`expected operand size<amdgpu_syn_instruction_type>`.
967
968 Examples:
969
970 .. parsed-literal::
971
972 // GFX9
973
974 v_add_f16 v0, 1.0, 0 // v0 = 0x3C00 (1.0)
975 v_add_u16 v0, 1.0, 0 // v0 = 0x3C00
976
977 v_add_f32 v0, 1.0, 0 // v0 = 0x3F800000 (1.0)
978 v_add_u32 v0, 1.0, 0 // v0 = 0x3F800000
979
980
981 .. _amdgpu_synid_lit_conv:
982
983 Literals
984 --------
985
986 .. _amdgpu_synid_int_lit_conv:
987
988 Integer Literals
989 ~~~~~~~~~~~~~~~~
990
991 Integer :ref:`literals<amdgpu_synid_literal>`
992 are specified as 64-bit :ref:`integer numbers<amdgpu_synid_integer_number>`.
993
994 When used as operands they are converted to
995 :ref:`expected operand type<amdgpu_syn_instruction_type>` as described below.
996
997 ============== ============== =============== ====================================================================
998 Expected type Condition Result Note
999 ============== ============== =============== ====================================================================
1000 i16, u16, b16 cond(num,16) num.u16 Truncate to 16 bits.
1001 i32, u32, b32 cond(num,32) num.u32 Truncate to 32 bits.
1002 i64 cond(num,32) {-1,num.i32} Truncate to 32 bits and then sign-extend the result to 64 bits.
1003 u64, b64 cond(num,32) { 0,num.u32} Truncate to 32 bits and then zero-extend the result to 64 bits.
1004 f16 cond(num,16) num.u16 Use low 16 bits as an f16 value.
1005 f32 cond(num,32) num.u32 Use low 32 bits as an f32 value.
1006 f64 cond(num,32) {num.u32,0} Use low 32 bits of the number as high 32 bits
1007 of the result; low 32 bits of the result are zeroed.
1008 ============== ============== =============== ====================================================================
1009
1010 The condition *cond(X,S)* indicates if a 64-bit number *X*
1011 can be converted to a smaller size *S* by truncation of upper bits.
1012 There are two cases when the conversion is possible:
1013
1014 * The truncated bits are all 0.
1015 * The truncated bits are all 1 and the value after truncation has its MSB bit set.
1016
1017 Examples of valid literals:
1018
1019 .. parsed-literal::
1020
1021 // GFX9
1022 // Literal value after conversion:
1023 v_add_u16 v0, 0xff00, v0 // 0xff00
1024 v_add_u16 v0, 0xffffffffffffff00, v0 // 0xff00
1025 v_add_u16 v0, -256, v0 // 0xff00
1026 // Literal value after conversion:
1027 s_bfe_i64 s[0:1], 0xffefffff, s3 // 0xffffffffffefffff
1028 s_bfe_u64 s[0:1], 0xffefffff, s3 // 0x00000000ffefffff
1029 v_ceil_f64_e32 v[0:1], 0xffefffff // 0xffefffff00000000 (-1.7976922776554302e308)
1030
1031 Examples of invalid literals:
1032
1033 .. parsed-literal::
1034
1035 // GFX9
1036
1037 v_add_u16 v0, 0x1ff00, v0 // truncated bits are not all 0 or 1
1038 v_add_u16 v0, 0xffffffffffff00ff, v0 // truncated bits do not match MSB of the result
1039
1040 .. _amdgpu_synid_fp_lit_conv:
1041
1042 Floating-Point Literals
1043 ~~~~~~~~~~~~~~~~~~~~~~~
1044
1045 Floating-point :ref:`literals<amdgpu_synid_literal>` are specified as 64-bit
1046 :ref:`floating-point numbers<amdgpu_synid_floating-point_number>`.
1047
1048 When used as operands they are converted to
1049 :ref:`expected operand type<amdgpu_syn_instruction_type>` as described below.
1050
1051 ============== ============== ================= =================================================================
1052 Expected type Condition Result Note
1053 ============== ============== ================= =================================================================
1054 i16, u16, b16 cond(num,16) f16(num) Convert to f16 and use bits of the result as an integer value.
1055 i32, u32, b32 cond(num,32) f32(num) Convert to f32 and use bits of the result as an integer value.
1056 i64, u64, b64 false \- Conversion disabled because of an unclear semantics.
1057 f16 cond(num,16) f16(num) Convert to f16.
1058 f32 cond(num,32) f32(num) Convert to f32.
1059 f64 true {num.u32.hi,0} Use high 32 bits of the number as high 32 bits of the result;
1060 zero-fill low 32 bits of the result.
1061
1062 Note that the result may differ from the original number.
1063 ============== ============== ================= =================================================================
1064
1065 The condition *cond(X,S)* indicates if an f64 number *X* can be converted
1066 to a smaller *S*-bit floating-point type without overflow or underflow.
1067 Precision lost is allowed.
1068
1069 Examples of valid literals:
1070
1071 .. parsed-literal::
1072
1073 // GFX9
1074
1075 v_add_f16 v1, 65500.0, v2
1076 v_add_f32 v1, 65600.0, v2
1077
1078 // Literal value before conversion: 1.7976931348623157e308 (0x7fefffffffffffff)
1079 // Literal value after conversion: 1.7976922776554302e308 (0x7fefffff00000000)
1080 v_ceil_f64 v[0:1], 1.7976931348623157e308
1081
1082 Examples of invalid literals:
1083
1084 .. parsed-literal::
1085
1086 // GFX9
1087
1088 v_add_f16 v1, 65600.0, v2 // overflow
1089
1090 .. _amdgpu_synid_exp_conv:
1091
1092 Expressions
1093 ~~~~~~~~~~~
1094
1095 Expressions operate with and result in 64-bit integers.
1096
1097 When used as operands they are truncated to
1098 :ref:`expected operand size<amdgpu_syn_instruction_type>`.
1099 No data type conversions are performed.
1100
1101 Examples:
1102
1103 .. parsed-literal::
1104
1105 // GFX9
1106
1107 x = 0.1
1108 v_sqrt_f32 v0, x // v0 = [low 32 bits of 0.1 (double)]
1109 v_sqrt_f32 v0, (0.1 + 0) // the same as above
1110 v_sqrt_f32 v0, 0.1 // v0 = [0.1 (double) converted to float]
1111