1 =============================
2 User Guide for AMDGPU Backend
3 =============================
11 The AMDGPU backend provides ISA code generation for AMD GPUs, starting with the
12 R600 family up until the current GCN families. It lives in the
13 ``lib/Target/AMDGPU`` directory.
18 .. _amdgpu-target-triples:
23 Use the ``clang -target <Architecture>-<Vendor>-<OS>-<Environment>`` option to
24 specify the target triple:
26 .. table:: AMDGPU Architectures
27 :name: amdgpu-architecture-table
29 ============ ==============================================================
30 Architecture Description
31 ============ ==============================================================
32 ``r600`` AMD GPUs HD2XXX-HD6XXX for graphics and compute shaders.
33 ``amdgcn`` AMD GPUs GCN GFX6 onwards for graphics and compute shaders.
34 ============ ==============================================================
36 .. table:: AMDGPU Vendors
37 :name: amdgpu-vendor-table
39 ============ ==============================================================
41 ============ ==============================================================
42 ``amd`` Can be used for all AMD GPU usage.
43 ``mesa3d`` Can be used if the OS is ``mesa3d``.
44 ============ ==============================================================
46 .. table:: AMDGPU Operating Systems
47 :name: amdgpu-os-table
49 ============== ============================================================
51 ============== ============================================================
52 *<empty>* Defaults to the *unknown* OS.
53 ``amdhsa`` Compute kernels executed on HSA [HSA]_ compatible runtimes
54 such as AMD's ROCm [AMD-ROCm]_.
55 ``amdpal`` Graphic shaders and compute kernels executed on AMD PAL
57 ``mesa3d`` Graphic shaders and compute kernels executed on Mesa 3D
59 ============== ============================================================
61 .. table:: AMDGPU Environments
62 :name: amdgpu-environment-table
64 ============ ==============================================================
65 Environment Description
66 ============ ==============================================================
68 ============ ==============================================================
70 .. _amdgpu-processors:
75 Use the ``clang -mcpu <Processor>`` option to specify the AMD GPU processor. The
76 names from both the *Processor* and *Alternative Processor* can be used.
78 .. table:: AMDGPU Processors
79 :name: amdgpu-processor-table
81 =========== =============== ============ ===== ================= ======= ======================
82 Processor Alternative Target dGPU/ Target ROCm Example
83 Processor Triple APU Features Support Products
84 Architecture Supported
86 =========== =============== ============ ===== ================= ======= ======================
87 **Radeon HD 2000/3000 Series (R600)** [AMD-RADEON-HD-2000-3000]_
88 -----------------------------------------------------------------------------------------------
89 ``r600`` ``r600`` dGPU
90 ``r630`` ``r600`` dGPU
91 ``rs880`` ``r600`` dGPU
92 ``rv670`` ``r600`` dGPU
93 **Radeon HD 4000 Series (R700)** [AMD-RADEON-HD-4000]_
94 -----------------------------------------------------------------------------------------------
95 ``rv710`` ``r600`` dGPU
96 ``rv730`` ``r600`` dGPU
97 ``rv770`` ``r600`` dGPU
98 **Radeon HD 5000 Series (Evergreen)** [AMD-RADEON-HD-5000]_
99 -----------------------------------------------------------------------------------------------
100 ``cedar`` ``r600`` dGPU
101 ``cypress`` ``r600`` dGPU
102 ``juniper`` ``r600`` dGPU
103 ``redwood`` ``r600`` dGPU
104 ``sumo`` ``r600`` dGPU
105 **Radeon HD 6000 Series (Northern Islands)** [AMD-RADEON-HD-6000]_
106 -----------------------------------------------------------------------------------------------
107 ``barts`` ``r600`` dGPU
108 ``caicos`` ``r600`` dGPU
109 ``cayman`` ``r600`` dGPU
110 ``turks`` ``r600`` dGPU
111 **GCN GFX6 (Southern Islands (SI))** [AMD-GCN-GFX6]_
112 -----------------------------------------------------------------------------------------------
113 ``gfx600`` - ``tahiti`` ``amdgcn`` dGPU
114 ``gfx601`` - ``hainan`` ``amdgcn`` dGPU
118 **GCN GFX7 (Sea Islands (CI))** [AMD-GCN-GFX7]_
119 -----------------------------------------------------------------------------------------------
120 ``gfx700`` - ``kaveri`` ``amdgcn`` APU - A6-7000
130 ``gfx701`` - ``hawaii`` ``amdgcn`` dGPU ROCm - FirePro W8100
134 ``gfx702`` ``amdgcn`` dGPU ROCm - Radeon R9 290
138 ``gfx703`` - ``kabini`` ``amdgcn`` APU - E1-2100
139 - ``mullins`` - E1-2200
147 ``gfx704`` - ``bonaire`` ``amdgcn`` dGPU - Radeon HD 7790
151 **GCN GFX8 (Volcanic Islands (VI))** [AMD-GCN-GFX8]_
152 -----------------------------------------------------------------------------------------------
153 ``gfx801`` - ``carrizo`` ``amdgcn`` APU - xnack - A6-8500P
159 \ ``amdgcn`` APU - xnack ROCm - A10-8700P
162 \ ``amdgcn`` APU - xnack - A10-9600P
168 \ ``amdgcn`` APU - xnack - E2-9010
171 ``gfx802`` - ``iceland`` ``amdgcn`` dGPU - xnack ROCm - FirePro S7150
172 - ``tonga`` [off] - FirePro S7100
179 ``gfx803`` - ``fiji`` ``amdgcn`` dGPU - xnack ROCm - Radeon R9 Nano
180 [off] - Radeon R9 Fury
184 - Radeon Instinct MI8
185 \ - ``polaris10`` ``amdgcn`` dGPU - xnack ROCm - Radeon RX 470
186 [off] - Radeon RX 480
187 - Radeon Instinct MI6
188 \ - ``polaris11`` ``amdgcn`` dGPU - xnack ROCm - Radeon RX 460
190 ``gfx810`` - ``stoney`` ``amdgcn`` APU - xnack
192 **GCN GFX9** [AMD-GCN-GFX9]_
193 -----------------------------------------------------------------------------------------------
194 ``gfx900`` ``amdgcn`` dGPU - xnack ROCm - Radeon Vega
195 [off] Frontier Edition
200 - Radeon Instinct MI25
201 ``gfx902`` ``amdgcn`` APU - xnack - Ryzen 3 2200G
203 ``gfx904`` ``amdgcn`` dGPU - xnack *TBA*
208 ``gfx906`` ``amdgcn`` dGPU - xnack - Radeon Instinct MI50
209 [off] - Radeon Instinct MI60
210 ``gfx909`` ``amdgcn`` APU - xnack *TBA* (Raven Ridge 2)
215 **GCN GFX10** [AMD-GCN-GFX10]_
216 -----------------------------------------------------------------------------------------------
217 ``gfx1010`` ``amdgcn`` dGPU - xnack *TBA*
226 ``gfx1011`` ``amdgcn`` dGPU - xnack *TBA*
235 ``gfx1012`` ``amdgcn`` dGPU - xnack *TBA*
244 =========== =============== ============ ===== ================= ======= ======================
246 .. _amdgpu-target-features:
251 Target features control how code is generated to support certain
252 processor specific features. Not all target features are supported by
253 all processors. The runtime must ensure that the features supported by
254 the device used to execute the code match the features enabled when
255 generating the code. A mismatch of features may result in incorrect
256 execution, or a reduction in performance.
258 The target features supported by each processor, and the default value
259 used if not specified explicitly, is listed in
260 :ref:`amdgpu-processor-table`.
262 Use the ``clang -m[no-]<TargetFeature>`` option to specify the AMD GPU
268 Enable the ``xnack`` feature.
270 Disable the ``xnack`` feature.
272 .. table:: AMDGPU Target Features
273 :name: amdgpu-target-feature-table
275 ====================== ==================================================
276 Target Feature Description
277 ====================== ==================================================
278 -m[no-]xnack Enable/disable generating code that has
279 memory clauses that are compatible with
280 having XNACK replay enabled.
282 This is used for demand paging and page
283 migration. If XNACK replay is enabled in
284 the device, then if a page fault occurs
285 the code may execute incorrectly if the
286 ``xnack`` feature is not enabled. Executing
287 code that has the feature enabled on a
288 device that does not have XNACK replay
289 enabled will execute correctly, but may
290 be less performant than code with the
293 -m[no-]sram-ecc Enable/disable generating code that assumes SRAM
294 ECC is enabled/disabled.
296 -m[no-]wavefrontsize64 Control the default wavefront size used when
297 generating code for kernels. When disabled
298 native wavefront size 32 is used, when enabled
299 wavefront size 64 is used.
301 -m[no-]cumode Control the default wavefront execution mode used
302 when generating code for kernels. When disabled
303 native WGP wavefront execution mode is used,
304 when enabled CU wavefront execution mode is used
305 (see :ref:`amdgpu-amdhsa-memory-model`).
306 ====================== ==================================================
308 .. _amdgpu-address-spaces:
313 The AMDGPU backend uses the following address space mappings.
315 The memory space names used in the table, aside from the region memory space, is
316 from the OpenCL standard.
318 LLVM Address Space number is used throughout LLVM (for example, in LLVM IR).
320 .. table:: Address Space Mapping
321 :name: amdgpu-address-space-mapping-table
323 ================== =================================
324 LLVM Address Space Memory Space
325 ================== =================================
333 7 Buffer Fat Pointer (experimental)
334 ================== =================================
336 The buffer fat pointer is an experimental address space that is currently
337 unsupported in the backend. It exposes a non-integral pointer that is in future
338 intended to support the modelling of 128-bit buffer descriptors + a 32-bit
339 offset into the buffer descriptor (in total encapsulating a 160-bit 'pointer'),
340 allowing us to use normal LLVM load/store/atomic operations to model the buffer
341 descriptors used heavily in graphics workloads targeting the backend.
343 .. _amdgpu-memory-scopes:
348 This section provides LLVM memory synchronization scopes supported by the AMDGPU
349 backend memory model when the target triple OS is ``amdhsa`` (see
350 :ref:`amdgpu-amdhsa-memory-model` and :ref:`amdgpu-target-triples`).
352 The memory model supported is based on the HSA memory model [HSA]_ which is
353 based in turn on HRF-indirect with scope inclusion [HRF]_. The happens-before
354 relation is transitive over the synchonizes-with relation independent of scope,
355 and synchonizes-with allows the memory scope instances to be inclusive (see
356 table :ref:`amdgpu-amdhsa-llvm-sync-scopes-table`).
358 This is different to the OpenCL [OpenCL]_ memory model which does not have scope
359 inclusion and requires the memory scopes to exactly match. However, this
360 is conservatively correct for OpenCL.
362 .. table:: AMDHSA LLVM Sync Scopes
363 :name: amdgpu-amdhsa-llvm-sync-scopes-table
365 ======================= ===================================================
366 LLVM Sync Scope Description
367 ======================= ===================================================
368 *none* The default: ``system``.
370 Synchronizes with, and participates in modification
371 and seq_cst total orderings with, other operations
372 (except image operations) for all address spaces
373 (except private, or generic that accesses private)
374 provided the other operation's sync scope is:
377 - ``agent`` and executed by a thread on the same
379 - ``workgroup`` and executed by a thread in the
381 - ``wavefront`` and executed by a thread in the
384 ``agent`` Synchronizes with, and participates in modification
385 and seq_cst total orderings with, other operations
386 (except image operations) for all address spaces
387 (except private, or generic that accesses private)
388 provided the other operation's sync scope is:
390 - ``system`` or ``agent`` and executed by a thread
392 - ``workgroup`` and executed by a thread in the
394 - ``wavefront`` and executed by a thread in the
397 ``workgroup`` Synchronizes with, and participates in modification
398 and seq_cst total orderings with, other operations
399 (except image operations) for all address spaces
400 (except private, or generic that accesses private)
401 provided the other operation's sync scope is:
403 - ``system``, ``agent`` or ``workgroup`` and
404 executed by a thread in the same workgroup.
405 - ``wavefront`` and executed by a thread in the
408 ``wavefront`` Synchronizes with, and participates in modification
409 and seq_cst total orderings with, other operations
410 (except image operations) for all address spaces
411 (except private, or generic that accesses private)
412 provided the other operation's sync scope is:
414 - ``system``, ``agent``, ``workgroup`` or
415 ``wavefront`` and executed by a thread in the
418 ``singlethread`` Only synchronizes with, and participates in
419 modification and seq_cst total orderings with,
420 other operations (except image operations) running
421 in the same thread for all address spaces (for
422 example, in signal handlers).
424 ``one-as`` Same as ``system`` but only synchronizes with other
425 operations within the same address space.
427 ``agent-one-as`` Same as ``agent`` but only synchronizes with other
428 operations within the same address space.
430 ``workgroup-one-as`` Same as ``workgroup`` but only synchronizes with
431 other operations within the same address space.
433 ``wavefront-one-as`` Same as ``wavefront`` but only synchronizes with
434 other operations within the same address space.
436 ``singlethread-one-as`` Same as ``singlethread`` but only synchronizes with
437 other operations within the same address space.
438 ======================= ===================================================
443 The AMDGPU backend implements the following LLVM IR intrinsics.
445 *This section is WIP.*
448 List AMDGPU intrinsics
453 The AMDGPU backend supports the following LLVM IR attributes.
455 .. table:: AMDGPU LLVM IR Attributes
456 :name: amdgpu-llvm-ir-attributes-table
458 ======================================= ==========================================================
459 LLVM Attribute Description
460 ======================================= ==========================================================
461 "amdgpu-flat-work-group-size"="min,max" Specify the minimum and maximum flat work group sizes that
462 will be specified when the kernel is dispatched. Generated
463 by the ``amdgpu_flat_work_group_size`` CLANG attribute [CLANG-ATTR]_.
464 "amdgpu-implicitarg-num-bytes"="n" Number of kernel argument bytes to add to the kernel
465 argument block size for the implicit arguments. This
466 varies by OS and language (for OpenCL see
467 :ref:`opencl-kernel-implicit-arguments-appended-for-amdhsa-os-table`).
468 "amdgpu-num-sgpr"="n" Specifies the number of SGPRs to use. Generated by
469 the ``amdgpu_num_sgpr`` CLANG attribute [CLANG-ATTR]_.
470 "amdgpu-num-vgpr"="n" Specifies the number of VGPRs to use. Generated by the
471 ``amdgpu_num_vgpr`` CLANG attribute [CLANG-ATTR]_.
472 "amdgpu-waves-per-eu"="m,n" Specify the minimum and maximum number of waves per
473 execution unit. Generated by the ``amdgpu_waves_per_eu``
474 CLANG attribute [CLANG-ATTR]_.
475 "amdgpu-ieee" true/false. Specify whether the function expects the IEEE field of the
476 mode register to be set on entry. Overrides the default for
477 the calling convention.
478 "amdgpu-dx10-clamp" true/false. Specify whether the function expects the DX10_CLAMP field of
479 the mode register to be set on entry. Overrides the default
480 for the calling convention.
481 ======================================= ==========================================================
486 The AMDGPU backend generates a standard ELF [ELF]_ relocatable code object that
487 can be linked by ``lld`` to produce a standard ELF shared code object which can
488 be loaded and executed on an AMDGPU target.
493 The AMDGPU backend uses the following ELF header:
495 .. table:: AMDGPU ELF Header
496 :name: amdgpu-elf-header-table
498 ========================== ===============================
500 ========================== ===============================
501 ``e_ident[EI_CLASS]`` ``ELFCLASS64``
502 ``e_ident[EI_DATA]`` ``ELFDATA2LSB``
503 ``e_ident[EI_OSABI]`` - ``ELFOSABI_NONE``
504 - ``ELFOSABI_AMDGPU_HSA``
505 - ``ELFOSABI_AMDGPU_PAL``
506 - ``ELFOSABI_AMDGPU_MESA3D``
507 ``e_ident[EI_ABIVERSION]`` - ``ELFABIVERSION_AMDGPU_HSA``
508 - ``ELFABIVERSION_AMDGPU_PAL``
509 - ``ELFABIVERSION_AMDGPU_MESA3D``
510 ``e_type`` - ``ET_REL``
512 ``e_machine`` ``EM_AMDGPU``
514 ``e_flags`` See :ref:`amdgpu-elf-header-e_flags-table`
515 ========================== ===============================
519 .. table:: AMDGPU ELF Header Enumeration Values
520 :name: amdgpu-elf-header-enumeration-values-table
522 =============================== =====
524 =============================== =====
527 ``ELFOSABI_AMDGPU_HSA`` 64
528 ``ELFOSABI_AMDGPU_PAL`` 65
529 ``ELFOSABI_AMDGPU_MESA3D`` 66
530 ``ELFABIVERSION_AMDGPU_HSA`` 1
531 ``ELFABIVERSION_AMDGPU_PAL`` 0
532 ``ELFABIVERSION_AMDGPU_MESA3D`` 0
533 =============================== =====
535 ``e_ident[EI_CLASS]``
538 * ``ELFCLASS32`` for ``r600`` architecture.
540 * ``ELFCLASS64`` for ``amdgcn`` architecture which only supports 64
544 All AMDGPU targets use ``ELFDATA2LSB`` for little-endian byte ordering.
546 ``e_ident[EI_OSABI]``
547 One of the following AMD GPU architecture specific OS ABIs
548 (see :ref:`amdgpu-os-table`):
550 * ``ELFOSABI_NONE`` for *unknown* OS.
552 * ``ELFOSABI_AMDGPU_HSA`` for ``amdhsa`` OS.
554 * ``ELFOSABI_AMDGPU_PAL`` for ``amdpal`` OS.
556 * ``ELFOSABI_AMDGPU_MESA3D`` for ``mesa3D`` OS.
558 ``e_ident[EI_ABIVERSION]``
559 The ABI version of the AMD GPU architecture specific OS ABI to which the code
562 * ``ELFABIVERSION_AMDGPU_HSA`` is used to specify the version of AMD HSA
565 * ``ELFABIVERSION_AMDGPU_PAL`` is used to specify the version of AMD PAL
568 * ``ELFABIVERSION_AMDGPU_MESA3D`` is used to specify the version of AMD MESA
572 Can be one of the following values:
576 The type produced by the AMD GPU backend compiler as it is relocatable code
580 The type produced by the linker as it is a shared code object.
582 The AMD HSA runtime loader requires a ``ET_DYN`` code object.
585 The value ``EM_AMDGPU`` is used for the machine for all processors supported
586 by the ``r600`` and ``amdgcn`` architectures (see
587 :ref:`amdgpu-processor-table`). The specific processor is specified in the
588 ``EF_AMDGPU_MACH`` bit field of the ``e_flags`` (see
589 :ref:`amdgpu-elf-header-e_flags-table`).
592 The entry point is 0 as the entry points for individual kernels must be
593 selected in order to invoke them through AQL packets.
596 The AMDGPU backend uses the following ELF header flags:
598 .. table:: AMDGPU ELF Header ``e_flags``
599 :name: amdgpu-elf-header-e_flags-table
601 ================================= ========== =============================
602 Name Value Description
603 ================================= ========== =============================
604 **AMDGPU Processor Flag** See :ref:`amdgpu-processor-table`.
605 -------------------------------------------- -----------------------------
606 ``EF_AMDGPU_MACH`` 0x000000ff AMDGPU processor selection
608 ``EF_AMDGPU_MACH_xxx`` values
610 :ref:`amdgpu-ef-amdgpu-mach-table`.
611 ``EF_AMDGPU_XNACK`` 0x00000100 Indicates if the ``xnack``
614 contained in the code object.
621 :ref:`amdgpu-target-features`.
622 ``EF_AMDGPU_SRAM_ECC`` 0x00000200 Indicates if the ``sram-ecc``
625 contained in the code object.
632 :ref:`amdgpu-target-features`.
633 ================================= ========== =============================
635 .. table:: AMDGPU ``EF_AMDGPU_MACH`` Values
636 :name: amdgpu-ef-amdgpu-mach-table
638 ================================= ========== =============================
639 Name Value Description (see
640 :ref:`amdgpu-processor-table`)
641 ================================= ========== =============================
642 ``EF_AMDGPU_MACH_NONE`` 0x000 *not specified*
643 ``EF_AMDGPU_MACH_R600_R600`` 0x001 ``r600``
644 ``EF_AMDGPU_MACH_R600_R630`` 0x002 ``r630``
645 ``EF_AMDGPU_MACH_R600_RS880`` 0x003 ``rs880``
646 ``EF_AMDGPU_MACH_R600_RV670`` 0x004 ``rv670``
647 ``EF_AMDGPU_MACH_R600_RV710`` 0x005 ``rv710``
648 ``EF_AMDGPU_MACH_R600_RV730`` 0x006 ``rv730``
649 ``EF_AMDGPU_MACH_R600_RV770`` 0x007 ``rv770``
650 ``EF_AMDGPU_MACH_R600_CEDAR`` 0x008 ``cedar``
651 ``EF_AMDGPU_MACH_R600_CYPRESS`` 0x009 ``cypress``
652 ``EF_AMDGPU_MACH_R600_JUNIPER`` 0x00a ``juniper``
653 ``EF_AMDGPU_MACH_R600_REDWOOD`` 0x00b ``redwood``
654 ``EF_AMDGPU_MACH_R600_SUMO`` 0x00c ``sumo``
655 ``EF_AMDGPU_MACH_R600_BARTS`` 0x00d ``barts``
656 ``EF_AMDGPU_MACH_R600_CAICOS`` 0x00e ``caicos``
657 ``EF_AMDGPU_MACH_R600_CAYMAN`` 0x00f ``cayman``
658 ``EF_AMDGPU_MACH_R600_TURKS`` 0x010 ``turks``
659 *reserved* 0x011 - Reserved for ``r600``
660 0x01f architecture processors.
661 ``EF_AMDGPU_MACH_AMDGCN_GFX600`` 0x020 ``gfx600``
662 ``EF_AMDGPU_MACH_AMDGCN_GFX601`` 0x021 ``gfx601``
663 ``EF_AMDGPU_MACH_AMDGCN_GFX700`` 0x022 ``gfx700``
664 ``EF_AMDGPU_MACH_AMDGCN_GFX701`` 0x023 ``gfx701``
665 ``EF_AMDGPU_MACH_AMDGCN_GFX702`` 0x024 ``gfx702``
666 ``EF_AMDGPU_MACH_AMDGCN_GFX703`` 0x025 ``gfx703``
667 ``EF_AMDGPU_MACH_AMDGCN_GFX704`` 0x026 ``gfx704``
668 *reserved* 0x027 Reserved.
669 ``EF_AMDGPU_MACH_AMDGCN_GFX801`` 0x028 ``gfx801``
670 ``EF_AMDGPU_MACH_AMDGCN_GFX802`` 0x029 ``gfx802``
671 ``EF_AMDGPU_MACH_AMDGCN_GFX803`` 0x02a ``gfx803``
672 ``EF_AMDGPU_MACH_AMDGCN_GFX810`` 0x02b ``gfx810``
673 ``EF_AMDGPU_MACH_AMDGCN_GFX900`` 0x02c ``gfx900``
674 ``EF_AMDGPU_MACH_AMDGCN_GFX902`` 0x02d ``gfx902``
675 ``EF_AMDGPU_MACH_AMDGCN_GFX904`` 0x02e ``gfx904``
676 ``EF_AMDGPU_MACH_AMDGCN_GFX906`` 0x02f ``gfx906``
677 *reserved* 0x030 Reserved.
678 ``EF_AMDGPU_MACH_AMDGCN_GFX909`` 0x031 ``gfx909``
679 *reserved* 0x032 Reserved.
680 ``EF_AMDGPU_MACH_AMDGCN_GFX1010`` 0x033 ``gfx1010``
681 ``EF_AMDGPU_MACH_AMDGCN_GFX1011`` 0x034 ``gfx1011``
682 ``EF_AMDGPU_MACH_AMDGCN_GFX1012`` 0x035 ``gfx1012``
683 ================================= ========== =============================
688 An AMDGPU target ELF code object has the standard ELF sections which include:
690 .. table:: AMDGPU ELF Sections
691 :name: amdgpu-elf-sections-table
693 ================== ================ =================================
695 ================== ================ =================================
696 ``.bss`` ``SHT_NOBITS`` ``SHF_ALLOC`` + ``SHF_WRITE``
697 ``.data`` ``SHT_PROGBITS`` ``SHF_ALLOC`` + ``SHF_WRITE``
698 ``.debug_``\ *\** ``SHT_PROGBITS`` *none*
699 ``.dynamic`` ``SHT_DYNAMIC`` ``SHF_ALLOC``
700 ``.dynstr`` ``SHT_PROGBITS`` ``SHF_ALLOC``
701 ``.dynsym`` ``SHT_PROGBITS`` ``SHF_ALLOC``
702 ``.got`` ``SHT_PROGBITS`` ``SHF_ALLOC`` + ``SHF_WRITE``
703 ``.hash`` ``SHT_HASH`` ``SHF_ALLOC``
704 ``.note`` ``SHT_NOTE`` *none*
705 ``.rela``\ *name* ``SHT_RELA`` *none*
706 ``.rela.dyn`` ``SHT_RELA`` *none*
707 ``.rodata`` ``SHT_PROGBITS`` ``SHF_ALLOC``
708 ``.shstrtab`` ``SHT_STRTAB`` *none*
709 ``.strtab`` ``SHT_STRTAB`` *none*
710 ``.symtab`` ``SHT_SYMTAB`` *none*
711 ``.text`` ``SHT_PROGBITS`` ``SHF_ALLOC`` + ``SHF_EXECINSTR``
712 ================== ================ =================================
714 These sections have their standard meanings (see [ELF]_) and are only generated
718 The standard DWARF sections. See :ref:`amdgpu-dwarf` for information on the
719 DWARF produced by the AMDGPU backend.
721 ``.dynamic``, ``.dynstr``, ``.dynsym``, ``.hash``
722 The standard sections used by a dynamic loader.
725 See :ref:`amdgpu-note-records` for the note records supported by the AMDGPU
728 ``.rela``\ *name*, ``.rela.dyn``
729 For relocatable code objects, *name* is the name of the section that the
730 relocation records apply. For example, ``.rela.text`` is the section name for
731 relocation records associated with the ``.text`` section.
733 For linked shared code objects, ``.rela.dyn`` contains all the relocation
734 records from each of the relocatable code object's ``.rela``\ *name* sections.
736 See :ref:`amdgpu-relocation-records` for the relocation records supported by
740 The executable machine code for the kernels and functions they call. Generated
741 as position independent code. See :ref:`amdgpu-code-conventions` for
742 information on conventions used in the isa generation.
744 .. _amdgpu-note-records:
749 The AMDGPU backend code object contains ELF note records in the ``.note``
750 section. The set of generated notes and their semantics depend on the code
751 object version; see :ref:`amdgpu-note-records-v2` and
752 :ref:`amdgpu-note-records-v3`.
754 As required by ``ELFCLASS32`` and ``ELFCLASS64``, minimal zero byte padding
755 must be generated after the ``name`` field to ensure the ``desc`` field is 4
756 byte aligned. In addition, minimal zero byte padding must be generated to
757 ensure the ``desc`` field size is a multiple of 4 bytes. The ``sh_addralign``
758 field of the ``.note`` section must be at least 4 to indicate at least 8 byte
761 .. _amdgpu-note-records-v2:
763 Code Object V2 Note Records (-mattr=-code-object-v3)
764 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
766 .. warning:: Code Object V2 is not the default code object version emitted by
767 this version of LLVM. For a description of the notes generated with the
768 default configuration (Code Object V3) see :ref:`amdgpu-note-records-v3`.
770 The AMDGPU backend code object uses the following ELF note record in the
771 ``.note`` section when compiling for Code Object V2 (-mattr=-code-object-v3).
773 Additional note records may be present, but any which are not documented here
774 are deprecated and should not be used.
776 .. table:: AMDGPU Code Object V2 ELF Note Records
777 :name: amdgpu-elf-note-records-table-v2
779 ===== ============================== ======================================
780 Name Type Description
781 ===== ============================== ======================================
782 "AMD" ``NT_AMD_AMDGPU_HSA_METADATA`` <metadata null terminated string>
783 ===== ============================== ======================================
787 .. table:: AMDGPU Code Object V2 ELF Note Record Enumeration Values
788 :name: amdgpu-elf-note-record-enumeration-values-table-v2
790 ============================== =====
792 ============================== =====
794 ``NT_AMD_AMDGPU_HSA_METADATA`` 10
796 ============================== =====
798 ``NT_AMD_AMDGPU_HSA_METADATA``
799 Specifies extensible metadata associated with the code objects executed on HSA
800 [HSA]_ compatible runtimes such as AMD's ROCm [AMD-ROCm]_. It is required when
801 the target triple OS is ``amdhsa`` (see :ref:`amdgpu-target-triples`). See
802 :ref:`amdgpu-amdhsa-code-object-metadata-v2` for the syntax of the code
803 object metadata string.
805 .. _amdgpu-note-records-v3:
807 Code Object V3 Note Records (-mattr=+code-object-v3)
808 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
810 The AMDGPU backend code object uses the following ELF note record in the
811 ``.note`` section when compiling for Code Object V3 (-mattr=+code-object-v3).
813 Additional note records may be present, but any which are not documented here
814 are deprecated and should not be used.
816 .. table:: AMDGPU Code Object V3 ELF Note Records
817 :name: amdgpu-elf-note-records-table-v3
819 ======== ============================== ======================================
820 Name Type Description
821 ======== ============================== ======================================
822 "AMDGPU" ``NT_AMDGPU_METADATA`` Metadata in Message Pack [MsgPack]_
824 ======== ============================== ======================================
828 .. table:: AMDGPU Code Object V3 ELF Note Record Enumeration Values
829 :name: amdgpu-elf-note-record-enumeration-values-table-v3
831 ============================== =====
833 ============================== =====
835 ``NT_AMDGPU_METADATA`` 32
836 ============================== =====
838 ``NT_AMDGPU_METADATA``
839 Specifies extensible metadata associated with an AMDGPU code
840 object. It is encoded as a map in the Message Pack [MsgPack]_ binary
841 data format. See :ref:`amdgpu-amdhsa-code-object-metadata-v3` for the
842 map keys defined for the ``amdhsa`` OS.
849 Symbols include the following:
851 .. table:: AMDGPU ELF Symbols
852 :name: amdgpu-elf-symbols-table
854 ===================== ================== ================ ==================
855 Name Type Section Description
856 ===================== ================== ================ ==================
857 *link-name* ``STT_OBJECT`` - ``.data`` Global variable
860 *link-name*\ ``.kd`` ``STT_OBJECT`` - ``.rodata`` Kernel descriptor
861 *link-name* ``STT_FUNC`` - ``.text`` Kernel entry point
862 *link-name* ``STT_OBJECT`` - SHN_AMDGPU_LDS Global variable in LDS
863 ===================== ================== ================ ==================
866 Global variables both used and defined by the compilation unit.
868 If the symbol is defined in the compilation unit then it is allocated in the
869 appropriate section according to if it has initialized data or is readonly.
871 If the symbol is external then its section is ``STN_UNDEF`` and the loader
872 will resolve relocations using the definition provided by another code object
873 or explicitly defined by the runtime.
875 If the symbol resides in local/group memory (LDS) then its section is the
876 special processor-specific section name ``SHN_AMDGPU_LDS``, and the
877 ``st_value`` field describes alignment requirements as it does for common
881 Add description of linked shared object symbols. Seems undefined symbols
882 are marked as STT_NOTYPE.
885 Every HSA kernel has an associated kernel descriptor. It is the address of the
886 kernel descriptor that is used in the AQL dispatch packet used to invoke the
887 kernel, not the kernel entry point. The layout of the HSA kernel descriptor is
888 defined in :ref:`amdgpu-amdhsa-kernel-descriptor`.
891 Every HSA kernel also has a symbol for its machine code entry point.
893 .. _amdgpu-relocation-records:
898 AMDGPU backend generates ``Elf64_Rela`` relocation records. Supported
899 relocatable fields are:
902 This specifies a 32-bit field occupying 4 bytes with arbitrary byte
903 alignment. These values use the same byte order as other word values in the
904 AMD GPU architecture.
907 This specifies a 64-bit field occupying 8 bytes with arbitrary byte
908 alignment. These values use the same byte order as other word values in the
909 AMD GPU architecture.
911 Following notations are used for specifying relocation calculations:
914 Represents the addend used to compute the value of the relocatable field.
917 Represents the offset into the global offset table at which the relocation
918 entry's symbol will reside during execution.
921 Represents the address of the global offset table.
924 Represents the place (section offset for ``et_rel`` or address for ``et_dyn``)
925 of the storage unit being relocated (computed using ``r_offset``).
928 Represents the value of the symbol whose index resides in the relocation
929 entry. Relocations not using this must specify a symbol index of ``STN_UNDEF``.
932 Represents the base address of a loaded executable or shared object which is
933 the difference between the ELF address and the actual load address. Relocations
934 using this are only valid in executable or shared objects.
936 The following relocation types are supported:
938 .. table:: AMDGPU ELF Relocation Records
939 :name: amdgpu-elf-relocation-records-table
941 ========================== ======= ===== ========== ==============================
942 Relocation Type Kind Value Field Calculation
943 ========================== ======= ===== ========== ==============================
944 ``R_AMDGPU_NONE`` 0 *none* *none*
945 ``R_AMDGPU_ABS32_LO`` Static, 1 ``word32`` (S + A) & 0xFFFFFFFF
947 ``R_AMDGPU_ABS32_HI`` Static, 2 ``word32`` (S + A) >> 32
949 ``R_AMDGPU_ABS64`` Static, 3 ``word64`` S + A
951 ``R_AMDGPU_REL32`` Static 4 ``word32`` S + A - P
952 ``R_AMDGPU_REL64`` Static 5 ``word64`` S + A - P
953 ``R_AMDGPU_ABS32`` Static, 6 ``word32`` S + A
955 ``R_AMDGPU_GOTPCREL`` Static 7 ``word32`` G + GOT + A - P
956 ``R_AMDGPU_GOTPCREL32_LO`` Static 8 ``word32`` (G + GOT + A - P) & 0xFFFFFFFF
957 ``R_AMDGPU_GOTPCREL32_HI`` Static 9 ``word32`` (G + GOT + A - P) >> 32
958 ``R_AMDGPU_REL32_LO`` Static 10 ``word32`` (S + A - P) & 0xFFFFFFFF
959 ``R_AMDGPU_REL32_HI`` Static 11 ``word32`` (S + A - P) >> 32
961 ``R_AMDGPU_RELATIVE64`` Dynamic 13 ``word64`` B + A
962 ========================== ======= ===== ========== ==============================
964 ``R_AMDGPU_ABS32_LO`` and ``R_AMDGPU_ABS32_HI`` are only supported by
965 the ``mesa3d`` OS, which does not support ``R_AMDGPU_ABS64``.
967 There is no current OS loader support for 32 bit programs and so
968 ``R_AMDGPU_ABS32`` is not used.
975 Standard DWARF [DWARF]_ Version 5 sections can be generated. These contain
976 information that maps the code object executable code and data to the source
977 language constructs. It can be used by tools such as debuggers and profilers.
979 Address Space Mapping
980 ~~~~~~~~~~~~~~~~~~~~~
982 The following address space mapping is used:
984 .. table:: AMDGPU DWARF Address Space Mapping
985 :name: amdgpu-dwarf-address-space-mapping-table
987 =================== =================
988 DWARF Address Space Memory Space
989 =================== =================
994 *omitted* Generic (Flat)
995 *not supported* Region (GDS)
996 =================== =================
998 See :ref:`amdgpu-address-spaces` for information on the memory space terminology
1001 An ``address_class`` attribute is generated on pointer type DIEs to specify the
1002 DWARF address space of the value of the pointer when it is in the *private* or
1003 *local* address space. Otherwise the attribute is omitted.
1005 An ``XDEREF`` operation is generated in location list expressions for variables
1006 that are allocated in the *private* and *local* address space. Otherwise no
1007 ``XDREF`` is omitted.
1012 *This section is WIP.*
1015 Define DWARF register enumeration.
1017 If want to present a wavefront state then should expose vector registers as
1018 64 wide (rather than per work-item view that LLVM uses). Either as separate
1019 registers, or a 64x4 byte single register. In either case use a new LANE op
1020 (akin to XDREF) to select the current lane usage in a location
1021 expression. This would also allow scalar register spilling to vector register
1022 lanes to be expressed (currently no debug information is being generated for
1023 spilling). If choose a wide single register approach then use LANE in
1024 conjunction with PIECE operation to select the dword part of the register for
1025 the current lane. If the separate register approach then use LANE to select
1031 Source text for online-compiled programs (e.g. those compiled by the OpenCL
1032 runtime) may be embedded into the DWARF v5 line table using the ``clang
1033 -gembed-source`` option, described in table :ref:`amdgpu-debug-options`.
1038 Enable the embedded source DWARF v5 extension.
1039 ``-gno-embed-source``
1040 Disable the embedded source DWARF v5 extension.
1042 .. table:: AMDGPU Debug Options
1043 :name: amdgpu-debug-options
1045 ==================== ==================================================
1046 Debug Flag Description
1047 ==================== ==================================================
1048 -g[no-]embed-source Enable/disable embedding source text in DWARF
1049 debug sections. Useful for environments where
1050 source cannot be written to disk, such as
1051 when performing online compilation.
1052 ==================== ==================================================
1054 This option enables one extended content types in the DWARF v5 Line Number
1055 Program Header, which is used to encode embedded source.
1057 .. table:: AMDGPU DWARF Line Number Program Header Extended Content Types
1058 :name: amdgpu-dwarf-extended-content-types
1060 ============================ ======================
1062 ============================ ======================
1063 ``DW_LNCT_LLVM_source`` ``DW_FORM_line_strp``
1064 ============================ ======================
1066 The source field will contain the UTF-8 encoded, null-terminated source text
1067 with ``'\n'`` line endings. When the source field is present, consumers can use
1068 the embedded source instead of attempting to discover the source on disk. When
1069 the source field is absent, consumers can access the file to get the source
1072 The above content type appears in the ``file_name_entry_format`` field of the
1073 line table prologue, and its corresponding value appear in the ``file_names``
1074 field. The current encoding of the content type is documented in table
1075 :ref:`amdgpu-dwarf-extended-content-types-encoding`
1077 .. table:: AMDGPU DWARF Line Number Program Header Extended Content Types Encoding
1078 :name: amdgpu-dwarf-extended-content-types-encoding
1080 ============================ ====================
1082 ============================ ====================
1083 ``DW_LNCT_LLVM_source`` 0x2001
1084 ============================ ====================
1086 .. _amdgpu-code-conventions:
1091 This section provides code conventions used for each supported target triple OS
1092 (see :ref:`amdgpu-target-triples`).
1097 This section provides code conventions used when the target triple OS is
1098 ``amdhsa`` (see :ref:`amdgpu-target-triples`).
1100 .. _amdgpu-amdhsa-code-object-target-identification:
1102 Code Object Target Identification
1103 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1105 The AMDHSA OS uses the following syntax to specify the code object
1106 target as a single string:
1108 ``<Architecture>-<Vendor>-<OS>-<Environment>-<Processor><Target Features>``
1112 - ``<Architecture>``, ``<Vendor>``, ``<OS>`` and ``<Environment>``
1113 are the same as the *Target Triple* (see
1114 :ref:`amdgpu-target-triples`).
1116 - ``<Processor>`` is the same as the *Processor* (see
1117 :ref:`amdgpu-processors`).
1119 - ``<Target Features>`` is a list of the enabled *Target Features*
1120 (see :ref:`amdgpu-target-features`), each prefixed by a plus, that
1121 apply to *Processor*. The list must be in the same order as listed
1122 in the table :ref:`amdgpu-target-feature-table`. Note that *Target
1123 Features* must be included in the list if they are enabled even if
1124 that is the default for *Processor*.
1128 ``"amdgcn-amd-amdhsa--gfx902+xnack"``
1130 .. _amdgpu-amdhsa-code-object-metadata:
1132 Code Object Metadata
1133 ~~~~~~~~~~~~~~~~~~~~
1135 The code object metadata specifies extensible metadata associated with the code
1136 objects executed on HSA [HSA]_ compatible runtimes such as AMD's ROCm
1137 [AMD-ROCm]_. The encoding and semantics of this metadata depends on the code
1138 object version; see :ref:`amdgpu-amdhsa-code-object-metadata-v2` and
1139 :ref:`amdgpu-amdhsa-code-object-metadata-v3`.
1141 Code object metadata is specified in a note record (see
1142 :ref:`amdgpu-note-records`) and is required when the target triple OS is
1143 ``amdhsa`` (see :ref:`amdgpu-target-triples`). It must contain the minimum
1144 information necessary to support the ROCM kernel queries. For example, the
1145 segment sizes needed in a dispatch packet. In addition, a high level language
1146 runtime may require other information to be included. For example, the AMD
1147 OpenCL runtime records kernel argument information.
1149 .. _amdgpu-amdhsa-code-object-metadata-v2:
1151 Code Object V2 Metadata (-mattr=-code-object-v3)
1152 ++++++++++++++++++++++++++++++++++++++++++++++++
1154 .. warning:: Code Object V2 is not the default code object version emitted by
1155 this version of LLVM. For a description of the metadata generated with the
1156 default configuration (Code Object V3) see
1157 :ref:`amdgpu-amdhsa-code-object-metadata-v3`.
1159 Code object V2 metadata is specified by the ``NT_AMD_AMDGPU_METADATA`` note
1160 record (see :ref:`amdgpu-note-records-v2`).
1162 The metadata is specified as a YAML formatted string (see [YAML]_ and
1166 Is the string null terminated? It probably should not if YAML allows it to
1167 contain null characters, otherwise it should be.
1169 The metadata is represented as a single YAML document comprised of the mapping
1170 defined in table :ref:`amdgpu-amdhsa-code-object-metadata-map-table-v2` and
1173 For boolean values, the string values of ``false`` and ``true`` are used for
1174 false and true respectively.
1176 Additional information can be added to the mappings. To avoid conflicts, any
1177 non-AMD key names should be prefixed by "*vendor-name*.".
1179 .. table:: AMDHSA Code Object V2 Metadata Map
1180 :name: amdgpu-amdhsa-code-object-metadata-map-table-v2
1182 ========== ============== ========= =======================================
1183 String Key Value Type Required? Description
1184 ========== ============== ========= =======================================
1185 "Version" sequence of Required - The first integer is the major
1186 2 integers version. Currently 1.
1187 - The second integer is the minor
1188 version. Currently 0.
1189 "Printf" sequence of Each string is encoded information
1190 strings about a printf function call. The
1191 encoded information is organized as
1192 fields separated by colon (':'):
1194 ``ID:N:S[0]:S[1]:...:S[N-1]:FormatString``
1199 A 32 bit integer as a unique id for
1200 each printf function call
1203 A 32 bit integer equal to the number
1204 of arguments of printf function call
1207 ``S[i]`` (where i = 0, 1, ... , N-1)
1208 32 bit integers for the size in bytes
1209 of the i-th FormatString argument of
1210 the printf function call
1213 The format string passed to the
1214 printf function call.
1215 "Kernels" sequence of Required Sequence of the mappings for each
1216 mapping kernel in the code object. See
1217 :ref:`amdgpu-amdhsa-code-object-kernel-metadata-map-table-v2`
1218 for the definition of the mapping.
1219 ========== ============== ========= =======================================
1223 .. table:: AMDHSA Code Object V2 Kernel Metadata Map
1224 :name: amdgpu-amdhsa-code-object-kernel-metadata-map-table-v2
1226 ================= ============== ========= ================================
1227 String Key Value Type Required? Description
1228 ================= ============== ========= ================================
1229 "Name" string Required Source name of the kernel.
1230 "SymbolName" string Required Name of the kernel
1231 descriptor ELF symbol.
1232 "Language" string Source language of the kernel.
1240 "LanguageVersion" sequence of - The first integer is the major
1242 - The second integer is the
1244 "Attrs" mapping Mapping of kernel attributes.
1246 :ref:`amdgpu-amdhsa-code-object-kernel-attribute-metadata-map-table-v2`
1247 for the mapping definition.
1248 "Args" sequence of Sequence of mappings of the
1249 mapping kernel arguments. See
1250 :ref:`amdgpu-amdhsa-code-object-kernel-argument-metadata-map-table-v2`
1251 for the definition of the mapping.
1252 "CodeProps" mapping Mapping of properties related to
1253 the kernel code. See
1254 :ref:`amdgpu-amdhsa-code-object-kernel-code-properties-metadata-map-table-v2`
1255 for the mapping definition.
1256 ================= ============== ========= ================================
1260 .. table:: AMDHSA Code Object V2 Kernel Attribute Metadata Map
1261 :name: amdgpu-amdhsa-code-object-kernel-attribute-metadata-map-table-v2
1263 =================== ============== ========= ==============================
1264 String Key Value Type Required? Description
1265 =================== ============== ========= ==============================
1266 "ReqdWorkGroupSize" sequence of If not 0, 0, 0 then all values
1267 3 integers must be >=1 and the dispatch
1268 work-group size X, Y, Z must
1269 correspond to the specified
1270 values. Defaults to 0, 0, 0.
1272 Corresponds to the OpenCL
1273 ``reqd_work_group_size``
1275 "WorkGroupSizeHint" sequence of The dispatch work-group size
1276 3 integers X, Y, Z is likely to be the
1279 Corresponds to the OpenCL
1280 ``work_group_size_hint``
1282 "VecTypeHint" string The name of a scalar or vector
1285 Corresponds to the OpenCL
1286 ``vec_type_hint`` attribute.
1288 "RuntimeHandle" string The external symbol name
1289 associated with a kernel.
1290 OpenCL runtime allocates a
1291 global buffer for the symbol
1292 and saves the kernel's address
1293 to it, which is used for
1294 device side enqueueing. Only
1295 available for device side
1297 =================== ============== ========= ==============================
1301 .. table:: AMDHSA Code Object V2 Kernel Argument Metadata Map
1302 :name: amdgpu-amdhsa-code-object-kernel-argument-metadata-map-table-v2
1304 ================= ============== ========= ================================
1305 String Key Value Type Required? Description
1306 ================= ============== ========= ================================
1307 "Name" string Kernel argument name.
1308 "TypeName" string Kernel argument type name.
1309 "Size" integer Required Kernel argument size in bytes.
1310 "Align" integer Required Kernel argument alignment in
1311 bytes. Must be a power of two.
1312 "ValueKind" string Required Kernel argument kind that
1313 specifies how to set up the
1314 corresponding argument.
1318 The argument is copied
1319 directly into the kernarg.
1322 A global address space pointer
1323 to the buffer data is passed
1326 "DynamicSharedPointer"
1327 A group address space pointer
1328 to dynamically allocated LDS
1329 is passed in the kernarg.
1332 A global address space
1333 pointer to a S# is passed in
1337 A global address space
1338 pointer to a T# is passed in
1342 A global address space pointer
1343 to an OpenCL pipe is passed in
1347 A global address space pointer
1348 to an OpenCL device enqueue
1349 queue is passed in the
1352 "HiddenGlobalOffsetX"
1353 The OpenCL grid dispatch
1354 global offset for the X
1355 dimension is passed in the
1358 "HiddenGlobalOffsetY"
1359 The OpenCL grid dispatch
1360 global offset for the Y
1361 dimension is passed in the
1364 "HiddenGlobalOffsetZ"
1365 The OpenCL grid dispatch
1366 global offset for the Z
1367 dimension is passed in the
1371 An argument that is not used
1372 by the kernel. Space needs to
1373 be left for it, but it does
1374 not need to be set up.
1376 "HiddenPrintfBuffer"
1377 A global address space pointer
1378 to the runtime printf buffer
1379 is passed in kernarg.
1381 "HiddenDefaultQueue"
1382 A global address space pointer
1383 to the OpenCL device enqueue
1384 queue that should be used by
1385 the kernel by default is
1386 passed in the kernarg.
1388 "HiddenCompletionAction"
1389 A global address space pointer
1390 to help link enqueued kernels into
1391 the ancestor tree for determining
1392 when the parent kernel has finished.
1394 "HiddenMultiGridSyncArg"
1395 A global address space pointer for
1396 multi-grid synchronization is
1397 passed in the kernarg.
1399 "ValueType" string Required Kernel argument value type. Only
1400 present if "ValueKind" is
1401 "ByValue". For vector data
1402 types, the value is for the
1403 element type. Values include:
1419 How can it be determined if a
1420 vector type, and what size
1422 "PointeeAlign" integer Alignment in bytes of pointee
1423 type for pointer type kernel
1424 argument. Must be a power
1425 of 2. Only present if
1427 "DynamicSharedPointer".
1428 "AddrSpaceQual" string Kernel argument address space
1429 qualifier. Only present if
1430 "ValueKind" is "GlobalBuffer" or
1431 "DynamicSharedPointer". Values
1442 Is GlobalBuffer only Global
1444 DynamicSharedPointer always
1445 Local? Can HCC allow Generic?
1446 How can Private or Region
1448 "AccQual" string Kernel argument access
1449 qualifier. Only present if
1450 "ValueKind" is "Image" or
1461 "ActualAccQual" string The actual memory accesses
1462 performed by the kernel on the
1463 kernel argument. Only present if
1464 "ValueKind" is "GlobalBuffer",
1465 "Image", or "Pipe". This may be
1466 more restrictive than indicated
1467 by "AccQual" to reflect what the
1468 kernel actual does. If not
1469 present then the runtime must
1470 assume what is implied by
1471 "AccQual" and "IsConst". Values
1478 "IsConst" boolean Indicates if the kernel argument
1479 is const qualified. Only present
1483 "IsRestrict" boolean Indicates if the kernel argument
1484 is restrict qualified. Only
1485 present if "ValueKind" is
1488 "IsVolatile" boolean Indicates if the kernel argument
1489 is volatile qualified. Only
1490 present if "ValueKind" is
1493 "IsPipe" boolean Indicates if the kernel argument
1494 is pipe qualified. Only present
1495 if "ValueKind" is "Pipe".
1498 Can GlobalBuffer be pipe
1500 ================= ============== ========= ================================
1504 .. table:: AMDHSA Code Object V2 Kernel Code Properties Metadata Map
1505 :name: amdgpu-amdhsa-code-object-kernel-code-properties-metadata-map-table-v2
1507 ============================ ============== ========= =====================
1508 String Key Value Type Required? Description
1509 ============================ ============== ========= =====================
1510 "KernargSegmentSize" integer Required The size in bytes of
1512 that holds the values
1515 "GroupSegmentFixedSize" integer Required The amount of group
1519 bytes. This does not
1521 dynamically allocated
1522 group segment memory
1526 "PrivateSegmentFixedSize" integer Required The amount of fixed
1527 private address space
1528 memory required for a
1530 bytes. If the kernel
1532 stack then additional
1534 to this value for the
1536 "KernargSegmentAlign" integer Required The maximum byte
1539 kernarg segment. Must
1541 "WavefrontSize" integer Required Wavefront size. Must
1543 "NumSGPRs" integer Required Number of scalar
1547 includes the special
1549 Scratch (GFX7-GFX10)
1551 GFX8-GFX10). It does
1553 SGPR added if a trap
1559 "NumVGPRs" integer Required Number of vector
1563 "MaxFlatWorkGroupSize" integer Required Maximum flat
1566 kernel in work-items.
1569 ReqdWorkGroupSize if
1571 "NumSpilledSGPRs" integer Number of stores from
1572 a scalar register to
1573 a register allocator
1576 "NumSpilledVGPRs" integer Number of stores from
1577 a vector register to
1578 a register allocator
1581 ============================ ============== ========= =====================
1583 .. _amdgpu-amdhsa-code-object-metadata-v3:
1585 Code Object V3 Metadata (-mattr=+code-object-v3)
1586 ++++++++++++++++++++++++++++++++++++++++++++++++
1588 Code object V3 metadata is specified by the ``NT_AMDGPU_METADATA`` note record
1589 (see :ref:`amdgpu-note-records-v3`).
1591 The metadata is represented as Message Pack formatted binary data (see
1592 [MsgPack]_). The top level is a Message Pack map that includes the
1593 keys defined in table
1594 :ref:`amdgpu-amdhsa-code-object-metadata-map-table-v3` and referenced
1597 Additional information can be added to the maps. To avoid conflicts,
1598 any key names should be prefixed by "*vendor-name*." where
1599 ``vendor-name`` can be the the name of the vendor and specific vendor
1600 tool that generates the information. The prefix is abbreviated to
1601 simply "." when it appears within a map that has been added by the
1604 .. table:: AMDHSA Code Object V3 Metadata Map
1605 :name: amdgpu-amdhsa-code-object-metadata-map-table-v3
1607 ================= ============== ========= =======================================
1608 String Key Value Type Required? Description
1609 ================= ============== ========= =======================================
1610 "amdhsa.version" sequence of Required - The first integer is the major
1611 2 integers version. Currently 1.
1612 - The second integer is the minor
1613 version. Currently 0.
1614 "amdhsa.printf" sequence of Each string is encoded information
1615 strings about a printf function call. The
1616 encoded information is organized as
1617 fields separated by colon (':'):
1619 ``ID:N:S[0]:S[1]:...:S[N-1]:FormatString``
1624 A 32 bit integer as a unique id for
1625 each printf function call
1628 A 32 bit integer equal to the number
1629 of arguments of printf function call
1632 ``S[i]`` (where i = 0, 1, ... , N-1)
1633 32 bit integers for the size in bytes
1634 of the i-th FormatString argument of
1635 the printf function call
1638 The format string passed to the
1639 printf function call.
1640 "amdhsa.kernels" sequence of Required Sequence of the maps for each
1641 map kernel in the code object. See
1642 :ref:`amdgpu-amdhsa-code-object-kernel-metadata-map-table-v3`
1643 for the definition of the keys included
1645 ================= ============== ========= =======================================
1649 .. table:: AMDHSA Code Object V3 Kernel Metadata Map
1650 :name: amdgpu-amdhsa-code-object-kernel-metadata-map-table-v3
1652 =================================== ============== ========= ================================
1653 String Key Value Type Required? Description
1654 =================================== ============== ========= ================================
1655 ".name" string Required Source name of the kernel.
1656 ".symbol" string Required Name of the kernel
1657 descriptor ELF symbol.
1658 ".language" string Source language of the kernel.
1668 ".language_version" sequence of - The first integer is the major
1670 - The second integer is the
1672 ".args" sequence of Sequence of maps of the
1673 map kernel arguments. See
1674 :ref:`amdgpu-amdhsa-code-object-kernel-argument-metadata-map-table-v3`
1675 for the definition of the keys
1676 included in that map.
1677 ".reqd_workgroup_size" sequence of If not 0, 0, 0 then all values
1678 3 integers must be >=1 and the dispatch
1679 work-group size X, Y, Z must
1680 correspond to the specified
1681 values. Defaults to 0, 0, 0.
1683 Corresponds to the OpenCL
1684 ``reqd_work_group_size``
1686 ".workgroup_size_hint" sequence of The dispatch work-group size
1687 3 integers X, Y, Z is likely to be the
1690 Corresponds to the OpenCL
1691 ``work_group_size_hint``
1693 ".vec_type_hint" string The name of a scalar or vector
1696 Corresponds to the OpenCL
1697 ``vec_type_hint`` attribute.
1699 ".device_enqueue_symbol" string The external symbol name
1700 associated with a kernel.
1701 OpenCL runtime allocates a
1702 global buffer for the symbol
1703 and saves the kernel's address
1704 to it, which is used for
1705 device side enqueueing. Only
1706 available for device side
1708 ".kernarg_segment_size" integer Required The size in bytes of
1710 that holds the values
1713 ".group_segment_fixed_size" integer Required The amount of group
1717 bytes. This does not
1719 dynamically allocated
1720 group segment memory
1724 ".private_segment_fixed_size" integer Required The amount of fixed
1725 private address space
1726 memory required for a
1728 bytes. If the kernel
1730 stack then additional
1732 to this value for the
1734 ".kernarg_segment_align" integer Required The maximum byte
1737 kernarg segment. Must
1739 ".wavefront_size" integer Required Wavefront size. Must
1741 ".sgpr_count" integer Required Number of scalar
1742 registers required by a
1744 GFX6-GFX9. A register
1745 is required if it is
1747 if a higher numbered
1750 includes the special
1756 SGPR added if a trap
1762 ".vgpr_count" integer Required Number of vector
1763 registers required by
1765 GFX6-GFX9. A register
1766 is required if it is
1768 if a higher numbered
1771 ".max_flat_workgroup_size" integer Required Maximum flat
1774 kernel in work-items.
1777 ReqdWorkGroupSize if
1779 ".sgpr_spill_count" integer Number of stores from
1780 a scalar register to
1781 a register allocator
1784 ".vgpr_spill_count" integer Number of stores from
1785 a vector register to
1786 a register allocator
1789 =================================== ============== ========= ================================
1793 .. table:: AMDHSA Code Object V3 Kernel Argument Metadata Map
1794 :name: amdgpu-amdhsa-code-object-kernel-argument-metadata-map-table-v3
1796 ====================== ============== ========= ================================
1797 String Key Value Type Required? Description
1798 ====================== ============== ========= ================================
1799 ".name" string Kernel argument name.
1800 ".type_name" string Kernel argument type name.
1801 ".size" integer Required Kernel argument size in bytes.
1802 ".offset" integer Required Kernel argument offset in
1803 bytes. The offset must be a
1804 multiple of the alignment
1805 required by the argument.
1806 ".value_kind" string Required Kernel argument kind that
1807 specifies how to set up the
1808 corresponding argument.
1812 The argument is copied
1813 directly into the kernarg.
1816 A global address space pointer
1817 to the buffer data is passed
1820 "dynamic_shared_pointer"
1821 A group address space pointer
1822 to dynamically allocated LDS
1823 is passed in the kernarg.
1826 A global address space
1827 pointer to a S# is passed in
1831 A global address space
1832 pointer to a T# is passed in
1836 A global address space pointer
1837 to an OpenCL pipe is passed in
1841 A global address space pointer
1842 to an OpenCL device enqueue
1843 queue is passed in the
1846 "hidden_global_offset_x"
1847 The OpenCL grid dispatch
1848 global offset for the X
1849 dimension is passed in the
1852 "hidden_global_offset_y"
1853 The OpenCL grid dispatch
1854 global offset for the Y
1855 dimension is passed in the
1858 "hidden_global_offset_z"
1859 The OpenCL grid dispatch
1860 global offset for the Z
1861 dimension is passed in the
1865 An argument that is not used
1866 by the kernel. Space needs to
1867 be left for it, but it does
1868 not need to be set up.
1870 "hidden_printf_buffer"
1871 A global address space pointer
1872 to the runtime printf buffer
1873 is passed in kernarg.
1875 "hidden_default_queue"
1876 A global address space pointer
1877 to the OpenCL device enqueue
1878 queue that should be used by
1879 the kernel by default is
1880 passed in the kernarg.
1882 "hidden_completion_action"
1883 A global address space pointer
1884 to help link enqueued kernels into
1885 the ancestor tree for determining
1886 when the parent kernel has finished.
1888 "hidden_multigrid_sync_arg"
1889 A global address space pointer for
1890 multi-grid synchronization is
1891 passed in the kernarg.
1893 ".value_type" string Required Kernel argument value type. Only
1894 present if ".value_kind" is
1895 "by_value". For vector data
1896 types, the value is for the
1897 element type. Values include:
1913 How can it be determined if a
1914 vector type, and what size
1916 ".pointee_align" integer Alignment in bytes of pointee
1917 type for pointer type kernel
1918 argument. Must be a power
1919 of 2. Only present if
1921 "dynamic_shared_pointer".
1922 ".address_space" string Kernel argument address space
1923 qualifier. Only present if
1924 ".value_kind" is "global_buffer" or
1925 "dynamic_shared_pointer". Values
1936 Is "global_buffer" only "global"
1938 "dynamic_shared_pointer" always
1939 "local"? Can HCC allow "generic"?
1940 How can "private" or "region"
1942 ".access" string Kernel argument access
1943 qualifier. Only present if
1944 ".value_kind" is "image" or
1955 ".actual_access" string The actual memory accesses
1956 performed by the kernel on the
1957 kernel argument. Only present if
1958 ".value_kind" is "global_buffer",
1959 "image", or "pipe". This may be
1960 more restrictive than indicated
1961 by ".access" to reflect what the
1962 kernel actual does. If not
1963 present then the runtime must
1964 assume what is implied by
1965 ".access" and ".is_const" . Values
1972 ".is_const" boolean Indicates if the kernel argument
1973 is const qualified. Only present
1977 ".is_restrict" boolean Indicates if the kernel argument
1978 is restrict qualified. Only
1979 present if ".value_kind" is
1982 ".is_volatile" boolean Indicates if the kernel argument
1983 is volatile qualified. Only
1984 present if ".value_kind" is
1987 ".is_pipe" boolean Indicates if the kernel argument
1988 is pipe qualified. Only present
1989 if ".value_kind" is "pipe".
1992 Can "global_buffer" be pipe
1994 ====================== ============== ========= ================================
2001 The HSA architected queuing language (AQL) defines a user space memory interface
2002 that can be used to control the dispatch of kernels, in an agent independent
2003 way. An agent can have zero or more AQL queues created for it using the ROCm
2004 runtime, in which AQL packets (all of which are 64 bytes) can be placed. See the
2005 *HSA Platform System Architecture Specification* [HSA]_ for the AQL queue
2006 mechanics and packet layouts.
2008 The packet processor of a kernel agent is responsible for detecting and
2009 dispatching HSA kernels from the AQL queues associated with it. For AMD GPUs the
2010 packet processor is implemented by the hardware command processor (CP),
2011 asynchronous dispatch controller (ADC) and shader processor input controller
2014 The ROCm runtime can be used to allocate an AQL queue object. It uses the kernel
2015 mode driver to initialize and register the AQL queue with CP.
2017 To dispatch a kernel the following actions are performed. This can occur in the
2018 CPU host program, or from an HSA kernel executing on a GPU.
2020 1. A pointer to an AQL queue for the kernel agent on which the kernel is to be
2021 executed is obtained.
2022 2. A pointer to the kernel descriptor (see
2023 :ref:`amdgpu-amdhsa-kernel-descriptor`) of the kernel to execute is
2024 obtained. It must be for a kernel that is contained in a code object that that
2025 was loaded by the ROCm runtime on the kernel agent with which the AQL queue is
2027 3. Space is allocated for the kernel arguments using the ROCm runtime allocator
2028 for a memory region with the kernarg property for the kernel agent that will
2029 execute the kernel. It must be at least 16 byte aligned.
2030 4. Kernel argument values are assigned to the kernel argument memory
2031 allocation. The layout is defined in the *HSA Programmer's Language Reference*
2032 [HSA]_. For AMDGPU the kernel execution directly accesses the kernel argument
2033 memory in the same way constant memory is accessed. (Note that the HSA
2034 specification allows an implementation to copy the kernel argument contents to
2035 another location that is accessed by the kernel.)
2036 5. An AQL kernel dispatch packet is created on the AQL queue. The ROCm runtime
2037 api uses 64 bit atomic operations to reserve space in the AQL queue for the
2038 packet. The packet must be set up, and the final write must use an atomic
2039 store release to set the packet kind to ensure the packet contents are
2040 visible to the kernel agent. AQL defines a doorbell signal mechanism to
2041 notify the kernel agent that the AQL queue has been updated. These rules, and
2042 the layout of the AQL queue and kernel dispatch packet is defined in the *HSA
2043 System Architecture Specification* [HSA]_.
2044 6. A kernel dispatch packet includes information about the actual dispatch,
2045 such as grid and work-group size, together with information from the code
2046 object about the kernel, such as segment sizes. The ROCm runtime queries on
2047 the kernel symbol can be used to obtain the code object values which are
2048 recorded in the :ref:`amdgpu-amdhsa-code-object-metadata`.
2049 7. CP executes micro-code and is responsible for detecting and setting up the
2050 GPU to execute the wavefronts of a kernel dispatch.
2051 8. CP ensures that when the a wavefront starts executing the kernel machine
2052 code, the scalar general purpose registers (SGPR) and vector general purpose
2053 registers (VGPR) are set up as required by the machine code. The required
2054 setup is defined in the :ref:`amdgpu-amdhsa-kernel-descriptor`. The initial
2055 register state is defined in
2056 :ref:`amdgpu-amdhsa-initial-kernel-execution-state`.
2057 9. The prolog of the kernel machine code (see
2058 :ref:`amdgpu-amdhsa-kernel-prolog`) sets up the machine state as necessary
2059 before continuing executing the machine code that corresponds to the kernel.
2060 10. When the kernel dispatch has completed execution, CP signals the completion
2061 signal specified in the kernel dispatch packet if not 0.
2063 .. _amdgpu-amdhsa-memory-spaces:
2068 The memory space properties are:
2070 .. table:: AMDHSA Memory Spaces
2071 :name: amdgpu-amdhsa-memory-spaces-table
2073 ================= =========== ======== ======= ==================
2074 Memory Space Name HSA Segment Hardware Address NULL Value
2076 ================= =========== ======== ======= ==================
2077 Private private scratch 32 0x00000000
2078 Local group LDS 32 0xFFFFFFFF
2079 Global global global 64 0x0000000000000000
2080 Constant constant *same as 64 0x0000000000000000
2082 Generic flat flat 64 0x0000000000000000
2083 Region N/A GDS 32 *not implemented
2085 ================= =========== ======== ======= ==================
2087 The global and constant memory spaces both use global virtual addresses, which
2088 are the same virtual address space used by the CPU. However, some virtual
2089 addresses may only be accessible to the CPU, some only accessible by the GPU,
2092 Using the constant memory space indicates that the data will not change during
2093 the execution of the kernel. This allows scalar read instructions to be
2094 used. The vector and scalar L1 caches are invalidated of volatile data before
2095 each kernel dispatch execution to allow constant memory to change values between
2098 The local memory space uses the hardware Local Data Store (LDS) which is
2099 automatically allocated when the hardware creates work-groups of wavefronts, and
2100 freed when all the wavefronts of a work-group have terminated. The data store
2101 (DS) instructions can be used to access it.
2103 The private memory space uses the hardware scratch memory support. If the kernel
2104 uses scratch, then the hardware allocates memory that is accessed using
2105 wavefront lane dword (4 byte) interleaving. The mapping used from private
2106 address to physical address is:
2108 ``wavefront-scratch-base +
2109 (private-address * wavefront-size * 4) +
2110 (wavefront-lane-id * 4)``
2112 There are different ways that the wavefront scratch base address is determined
2113 by a wavefront (see :ref:`amdgpu-amdhsa-initial-kernel-execution-state`). This
2114 memory can be accessed in an interleaved manner using buffer instruction with
2115 the scratch buffer descriptor and per wavefront scratch offset, by the scratch
2116 instructions, or by flat instructions. If each lane of a wavefront accesses the
2117 same private address, the interleaving results in adjacent dwords being accessed
2118 and hence requires fewer cache lines to be fetched. Multi-dword access is not
2119 supported except by flat and scratch instructions in GFX9-GFX10.
2121 The generic address space uses the hardware flat address support available in
2122 GFX7-GFX10. This uses two fixed ranges of virtual addresses (the private and
2123 local appertures), that are outside the range of addressible global memory, to
2124 map from a flat address to a private or local address.
2126 FLAT instructions can take a flat address and access global, private (scratch)
2127 and group (LDS) memory depending in if the address is within one of the
2128 apperture ranges. Flat access to scratch requires hardware aperture setup and
2129 setup in the kernel prologue (see :ref:`amdgpu-amdhsa-flat-scratch`). Flat
2130 access to LDS requires hardware aperture setup and M0 (GFX7-GFX8) register setup
2131 (see :ref:`amdgpu-amdhsa-m0`).
2133 To convert between a segment address and a flat address the base address of the
2134 appertures address can be used. For GFX7-GFX8 these are available in the
2135 :ref:`amdgpu-amdhsa-hsa-aql-queue` the address of which can be obtained with
2136 Queue Ptr SGPR (see :ref:`amdgpu-amdhsa-initial-kernel-execution-state`). For
2137 GFX9-GFX10 the appature base addresses are directly available as inline constant
2138 registers ``SRC_SHARED_BASE/LIMIT`` and ``SRC_PRIVATE_BASE/LIMIT``. In 64 bit
2139 address mode the apperture sizes are 2^32 bytes and the base is aligned to 2^32
2140 which makes it easier to convert from flat to segment or segment to flat.
2145 Image and sample handles created by the ROCm runtime are 64 bit addresses of a
2146 hardware 32 byte V# and 48 byte S# object respectively. In order to support the
2147 HSA ``query_sampler`` operations two extra dwords are used to store the HSA BRIG
2148 enumeration values for the queries that are not trivially deducible from the S#
2154 HSA signal handles created by the ROCm runtime are 64 bit addresses of a
2155 structure allocated in memory accessible from both the CPU and GPU. The
2156 structure is defined by the ROCm runtime and subject to change between releases
2157 (see [AMD-ROCm-github]_).
2159 .. _amdgpu-amdhsa-hsa-aql-queue:
2164 The HSA AQL queue structure is defined by the ROCm runtime and subject to change
2165 between releases (see [AMD-ROCm-github]_). For some processors it contains
2166 fields needed to implement certain language features such as the flat address
2167 aperture bases. It also contains fields used by CP such as managing the
2168 allocation of scratch memory.
2170 .. _amdgpu-amdhsa-kernel-descriptor:
2175 A kernel descriptor consists of the information needed by CP to initiate the
2176 execution of a kernel, including the entry point address of the machine code
2177 that implements the kernel.
2179 Kernel Descriptor for GFX6-GFX10
2180 ++++++++++++++++++++++++++++++++
2182 CP microcode requires the Kernel descriptor to be allocated on 64 byte
2185 .. table:: Kernel Descriptor for GFX6-GFX10
2186 :name: amdgpu-amdhsa-kernel-descriptor-gfx6-gfx10-table
2188 ======= ======= =============================== ============================
2189 Bits Size Field Name Description
2190 ======= ======= =============================== ============================
2191 31:0 4 bytes GROUP_SEGMENT_FIXED_SIZE The amount of fixed local
2192 address space memory
2193 required for a work-group
2194 in bytes. This does not
2195 include any dynamically
2196 allocated local address
2197 space memory that may be
2198 added when the kernel is
2200 63:32 4 bytes PRIVATE_SEGMENT_FIXED_SIZE The amount of fixed
2201 private address space
2202 memory required for a
2203 work-item in bytes. If
2204 is_dynamic_callstack is 1
2205 then additional space must
2206 be added to this value for
2208 127:64 8 bytes Reserved, must be 0.
2209 191:128 8 bytes KERNEL_CODE_ENTRY_BYTE_OFFSET Byte offset (possibly
2212 descriptor to kernel's
2213 entry point instruction
2214 which must be 256 byte
2216 351:272 20 Reserved, must be 0.
2218 383:352 4 bytes COMPUTE_PGM_RSRC3 GFX6-9
2219 Reserved, must be 0.
2222 program settings used by
2224 ``COMPUTE_PGM_RSRC3``
2227 :ref:`amdgpu-amdhsa-compute_pgm_rsrc3-gfx10-table`.
2228 415:384 4 bytes COMPUTE_PGM_RSRC1 Compute Shader (CS)
2229 program settings used by
2231 ``COMPUTE_PGM_RSRC1``
2234 :ref:`amdgpu-amdhsa-compute_pgm_rsrc1-gfx6-gfx10-table`.
2235 447:416 4 bytes COMPUTE_PGM_RSRC2 Compute Shader (CS)
2236 program settings used by
2238 ``COMPUTE_PGM_RSRC2``
2241 :ref:`amdgpu-amdhsa-compute_pgm_rsrc2-gfx6-gfx10-table`.
2242 448 1 bit ENABLE_SGPR_PRIVATE_SEGMENT Enable the setup of the
2243 _BUFFER SGPR user data registers
2245 :ref:`amdgpu-amdhsa-initial-kernel-execution-state`).
2247 The total number of SGPR
2249 requested must not exceed
2250 16 and match value in
2251 ``compute_pgm_rsrc2.user_sgpr.user_sgpr_count``.
2252 Any requests beyond 16
2254 449 1 bit ENABLE_SGPR_DISPATCH_PTR *see above*
2255 450 1 bit ENABLE_SGPR_QUEUE_PTR *see above*
2256 451 1 bit ENABLE_SGPR_KERNARG_SEGMENT_PTR *see above*
2257 452 1 bit ENABLE_SGPR_DISPATCH_ID *see above*
2258 453 1 bit ENABLE_SGPR_FLAT_SCRATCH_INIT *see above*
2259 454 1 bit ENABLE_SGPR_PRIVATE_SEGMENT *see above*
2261 457:455 3 bits Reserved, must be 0.
2262 458 1 bit ENABLE_WAVEFRONT_SIZE32 GFX6-9
2263 Reserved, must be 0.
2266 wavefront size 64 mode.
2268 native wavefront size
2270 463:459 5 bits Reserved, must be 0.
2271 511:464 6 bytes Reserved, must be 0.
2272 512 **Total size 64 bytes.**
2273 ======= ====================================================================
2277 .. table:: compute_pgm_rsrc1 for GFX6-GFX10
2278 :name: amdgpu-amdhsa-compute_pgm_rsrc1-gfx6-gfx10-table
2280 ======= ======= =============================== ===========================================================================
2281 Bits Size Field Name Description
2282 ======= ======= =============================== ===========================================================================
2283 5:0 6 bits GRANULATED_WORKITEM_VGPR_COUNT Number of vector register
2284 blocks used by each work-item;
2285 granularity is device
2290 - max(0, ceil(vgprs_used / 4) - 1)
2291 GFX10 (wavefront size 64)
2293 - max(0, ceil(vgprs_used / 4) - 1)
2294 GFX10 (wavefront size 32)
2296 - max(0, ceil(vgprs_used / 8) - 1)
2298 Where vgprs_used is defined
2299 as the highest VGPR number
2300 explicitly referenced plus
2303 Used by CP to set up
2304 ``COMPUTE_PGM_RSRC1.VGPRS``.
2307 :ref:`amdgpu-assembler`
2309 automatically for the
2310 selected processor from
2311 values provided to the
2312 `.amdhsa_kernel` directive
2314 `.amdhsa_next_free_vgpr`
2315 nested directive (see
2316 :ref:`amdhsa-kernel-directives-table`).
2317 9:6 4 bits GRANULATED_WAVEFRONT_SGPR_COUNT Number of scalar register
2318 blocks used by a wavefront;
2319 granularity is device
2324 - max(0, ceil(sgprs_used / 8) - 1)
2327 - 2 * max(0, ceil(sgprs_used / 16) - 1)
2329 Reserved, must be 0.
2334 defined as the highest
2335 SGPR number explicitly
2336 referenced plus one, plus
2337 a target-specific number
2338 of additional special
2340 FLAT_SCRATCH (GFX7+) and
2341 XNACK_MASK (GFX8+), and
2344 limitations. It does not
2345 include the 16 SGPRs added
2346 if a trap handler is
2350 limitations and special
2351 SGPR layout are defined in
2353 documentation, which can
2355 :ref:`amdgpu-processors`
2358 Used by CP to set up
2359 ``COMPUTE_PGM_RSRC1.SGPRS``.
2362 :ref:`amdgpu-assembler`
2364 automatically for the
2365 selected processor from
2366 values provided to the
2367 `.amdhsa_kernel` directive
2369 `.amdhsa_next_free_sgpr`
2370 and `.amdhsa_reserve_*`
2371 nested directives (see
2372 :ref:`amdhsa-kernel-directives-table`).
2373 11:10 2 bits PRIORITY Must be 0.
2375 Start executing wavefront
2376 at the specified priority.
2378 CP is responsible for
2380 ``COMPUTE_PGM_RSRC1.PRIORITY``.
2381 13:12 2 bits FLOAT_ROUND_MODE_32 Wavefront starts execution
2382 with specified rounding
2385 precision floating point
2388 Floating point rounding
2389 mode values are defined in
2390 :ref:`amdgpu-amdhsa-floating-point-rounding-mode-enumeration-values-table`.
2392 Used by CP to set up
2393 ``COMPUTE_PGM_RSRC1.FLOAT_MODE``.
2394 15:14 2 bits FLOAT_ROUND_MODE_16_64 Wavefront starts execution
2395 with specified rounding
2396 denorm mode for half/double (16
2397 and 64 bit) floating point
2398 precision floating point
2401 Floating point rounding
2402 mode values are defined in
2403 :ref:`amdgpu-amdhsa-floating-point-rounding-mode-enumeration-values-table`.
2405 Used by CP to set up
2406 ``COMPUTE_PGM_RSRC1.FLOAT_MODE``.
2407 17:16 2 bits FLOAT_DENORM_MODE_32 Wavefront starts execution
2408 with specified denorm mode
2411 precision floating point
2414 Floating point denorm mode
2415 values are defined in
2416 :ref:`amdgpu-amdhsa-floating-point-denorm-mode-enumeration-values-table`.
2418 Used by CP to set up
2419 ``COMPUTE_PGM_RSRC1.FLOAT_MODE``.
2420 19:18 2 bits FLOAT_DENORM_MODE_16_64 Wavefront starts execution
2421 with specified denorm mode
2423 and 64 bit) floating point
2424 precision floating point
2427 Floating point denorm mode
2428 values are defined in
2429 :ref:`amdgpu-amdhsa-floating-point-denorm-mode-enumeration-values-table`.
2431 Used by CP to set up
2432 ``COMPUTE_PGM_RSRC1.FLOAT_MODE``.
2433 20 1 bit PRIV Must be 0.
2435 Start executing wavefront
2436 in privilege trap handler
2439 CP is responsible for
2441 ``COMPUTE_PGM_RSRC1.PRIV``.
2442 21 1 bit ENABLE_DX10_CLAMP Wavefront starts execution
2443 with DX10 clamp mode
2444 enabled. Used by the vector
2445 ALU to force DX10 style
2446 treatment of NaN's (when
2447 set, clamp NaN to zero,
2451 Used by CP to set up
2452 ``COMPUTE_PGM_RSRC1.DX10_CLAMP``.
2453 22 1 bit DEBUG_MODE Must be 0.
2455 Start executing wavefront
2456 in single step mode.
2458 CP is responsible for
2460 ``COMPUTE_PGM_RSRC1.DEBUG_MODE``.
2461 23 1 bit ENABLE_IEEE_MODE Wavefront starts execution
2463 enabled. Floating point
2464 opcodes that support
2465 exception flag gathering
2466 will quiet and propagate
2467 signaling-NaN inputs per
2468 IEEE 754-2008. Min_dx10 and
2469 max_dx10 become IEEE
2470 754-2008 compliant due to
2471 signaling-NaN propagation
2474 Used by CP to set up
2475 ``COMPUTE_PGM_RSRC1.IEEE_MODE``.
2476 24 1 bit BULKY Must be 0.
2478 Only one work-group allowed
2479 to execute on a compute
2482 CP is responsible for
2484 ``COMPUTE_PGM_RSRC1.BULKY``.
2485 25 1 bit CDBG_USER Must be 0.
2487 Flag that can be used to
2488 control debugging code.
2490 CP is responsible for
2492 ``COMPUTE_PGM_RSRC1.CDBG_USER``.
2493 26 1 bit FP16_OVFL GFX6-GFX8
2494 Reserved, must be 0.
2496 Wavefront starts execution
2497 with specified fp16 overflow
2500 - If 0, fp16 overflow generates
2502 - If 1, fp16 overflow that is the
2503 result of an +/-INF input value
2504 or divide by 0 produces a +/-INF,
2505 otherwise clamps computed
2506 overflow to +/-MAX_FP16 as
2509 Used by CP to set up
2510 ``COMPUTE_PGM_RSRC1.FP16_OVFL``.
2511 28:27 2 bits Reserved, must be 0.
2512 29 1 bit WGP_MODE GFX6-GFX9
2513 Reserved, must be 0.
2515 - If 0 execute work-groups in
2516 CU wavefront execution mode.
2517 - If 1 execute work-groups on
2518 in WGP wavefront execution mode.
2520 See :ref:`amdgpu-amdhsa-memory-model`.
2522 Used by CP to set up
2523 ``COMPUTE_PGM_RSRC1.WGP_MODE``.
2524 30 1 bit MEM_ORDERED GFX6-9
2525 Reserved, must be 0.
2527 Controls the behavior of the
2528 waitcnt's vmcnt and vscnt
2531 - If 0 vmcnt reports completion
2532 of load and atomic with return
2533 out of order with sample
2534 instructions, and the vscnt
2535 reports the completion of
2536 store and atomic without
2538 - If 1 vmcnt reports completion
2539 of load, atomic with return
2540 and sample instructions in
2541 order, and the vscnt reports
2542 the completion of store and
2543 atomic without return in order.
2545 Used by CP to set up
2546 ``COMPUTE_PGM_RSRC1.MEM_ORDERED``.
2547 31 1 bit FWD_PROGRESS GFX6-9
2548 Reserved, must be 0.
2550 - If 0 execute SIMD wavefronts
2551 using oldest first policy.
2552 - If 1 execute SIMD wavefronts to
2553 ensure wavefronts will make some
2556 Used by CP to set up
2557 ``COMPUTE_PGM_RSRC1.FWD_PROGRESS``.
2558 32 **Total size 4 bytes**
2559 ======= ===================================================================================================================
2563 .. table:: compute_pgm_rsrc2 for GFX6-GFX10
2564 :name: amdgpu-amdhsa-compute_pgm_rsrc2-gfx6-gfx10-table
2566 ======= ======= =============================== ===========================================================================
2567 Bits Size Field Name Description
2568 ======= ======= =============================== ===========================================================================
2569 0 1 bit ENABLE_SGPR_PRIVATE_SEGMENT Enable the setup of the
2570 _WAVEFRONT_OFFSET SGPR wavefront scratch offset
2571 system register (see
2572 :ref:`amdgpu-amdhsa-initial-kernel-execution-state`).
2574 Used by CP to set up
2575 ``COMPUTE_PGM_RSRC2.SCRATCH_EN``.
2576 5:1 5 bits USER_SGPR_COUNT The total number of SGPR
2578 requested. This number must
2579 match the number of user
2580 data registers enabled.
2582 Used by CP to set up
2583 ``COMPUTE_PGM_RSRC2.USER_SGPR``.
2584 6 1 bit ENABLE_TRAP_HANDLER Must be 0.
2587 ``COMPUTE_PGM_RSRC2.TRAP_PRESENT``,
2588 which is set by the CP if
2589 the runtime has installed a
2591 7 1 bit ENABLE_SGPR_WORKGROUP_ID_X Enable the setup of the
2592 system SGPR register for
2593 the work-group id in the X
2595 :ref:`amdgpu-amdhsa-initial-kernel-execution-state`).
2597 Used by CP to set up
2598 ``COMPUTE_PGM_RSRC2.TGID_X_EN``.
2599 8 1 bit ENABLE_SGPR_WORKGROUP_ID_Y Enable the setup of the
2600 system SGPR register for
2601 the work-group id in the Y
2603 :ref:`amdgpu-amdhsa-initial-kernel-execution-state`).
2605 Used by CP to set up
2606 ``COMPUTE_PGM_RSRC2.TGID_Y_EN``.
2607 9 1 bit ENABLE_SGPR_WORKGROUP_ID_Z Enable the setup of the
2608 system SGPR register for
2609 the work-group id in the Z
2611 :ref:`amdgpu-amdhsa-initial-kernel-execution-state`).
2613 Used by CP to set up
2614 ``COMPUTE_PGM_RSRC2.TGID_Z_EN``.
2615 10 1 bit ENABLE_SGPR_WORKGROUP_INFO Enable the setup of the
2616 system SGPR register for
2617 work-group information (see
2618 :ref:`amdgpu-amdhsa-initial-kernel-execution-state`).
2620 Used by CP to set up
2621 ``COMPUTE_PGM_RSRC2.TGID_SIZE_EN``.
2622 12:11 2 bits ENABLE_VGPR_WORKITEM_ID Enable the setup of the
2623 VGPR system registers used
2624 for the work-item ID.
2625 :ref:`amdgpu-amdhsa-system-vgpr-work-item-id-enumeration-values-table`
2628 Used by CP to set up
2629 ``COMPUTE_PGM_RSRC2.TIDIG_CMP_CNT``.
2630 13 1 bit ENABLE_EXCEPTION_ADDRESS_WATCH Must be 0.
2632 Wavefront starts execution
2634 exceptions enabled which
2635 are generated when L1 has
2636 witnessed a thread access
2640 CP is responsible for
2641 filling in the address
2643 ``COMPUTE_PGM_RSRC2.EXCP_EN_MSB``
2644 according to what the
2646 14 1 bit ENABLE_EXCEPTION_MEMORY Must be 0.
2648 Wavefront starts execution
2649 with memory violation
2650 exceptions exceptions
2651 enabled which are generated
2652 when a memory violation has
2653 occurred for this wavefront from
2655 (write-to-read-only-memory,
2656 mis-aligned atomic, LDS
2657 address out of range,
2658 illegal address, etc.).
2662 ``COMPUTE_PGM_RSRC2.EXCP_EN_MSB``
2663 according to what the
2665 23:15 9 bits GRANULATED_LDS_SIZE Must be 0.
2667 CP uses the rounded value
2668 from the dispatch packet,
2669 not this value, as the
2670 dispatch may contain
2671 dynamically allocated group
2672 segment memory. CP writes
2674 ``COMPUTE_PGM_RSRC2.LDS_SIZE``.
2676 Amount of group segment
2677 (LDS) to allocate for each
2678 work-group. Granularity is
2682 roundup(lds-size / (64 * 4))
2684 roundup(lds-size / (128 * 4))
2686 24 1 bit ENABLE_EXCEPTION_IEEE_754_FP Wavefront starts execution
2687 _INVALID_OPERATION with specified exceptions
2690 Used by CP to set up
2691 ``COMPUTE_PGM_RSRC2.EXCP_EN``
2692 (set from bits 0..6).
2696 25 1 bit ENABLE_EXCEPTION_FP_DENORMAL FP Denormal one or more
2697 _SOURCE input operands is a
2699 26 1 bit ENABLE_EXCEPTION_IEEE_754_FP IEEE 754 FP Division by
2700 _DIVISION_BY_ZERO Zero
2701 27 1 bit ENABLE_EXCEPTION_IEEE_754_FP IEEE 754 FP FP Overflow
2703 28 1 bit ENABLE_EXCEPTION_IEEE_754_FP IEEE 754 FP Underflow
2705 29 1 bit ENABLE_EXCEPTION_IEEE_754_FP IEEE 754 FP Inexact
2707 30 1 bit ENABLE_EXCEPTION_INT_DIVIDE_BY Integer Division by Zero
2708 _ZERO (rcp_iflag_f32 instruction
2710 31 1 bit Reserved, must be 0.
2711 32 **Total size 4 bytes.**
2712 ======= ===================================================================================================================
2716 .. table:: compute_pgm_rsrc3 for GFX10
2717 :name: amdgpu-amdhsa-compute_pgm_rsrc3-gfx10-table
2719 ======= ======= =============================== ===========================================================================
2720 Bits Size Field Name Description
2721 ======= ======= =============================== ===========================================================================
2722 3:0 4 bits SHARED_VGPR_COUNT Number of shared VGPRs for wavefront size 64. Granularity 8. Value 0-120.
2723 compute_pgm_rsrc1.vgprs + shared_vgpr_cnt cannot exceed 64.
2724 31:4 28 Reserved, must be 0.
2726 32 **Total size 4 bytes.**
2727 ======= ===================================================================================================================
2731 .. table:: Floating Point Rounding Mode Enumeration Values
2732 :name: amdgpu-amdhsa-floating-point-rounding-mode-enumeration-values-table
2734 ====================================== ===== ==============================
2735 Enumeration Name Value Description
2736 ====================================== ===== ==============================
2737 FLOAT_ROUND_MODE_NEAR_EVEN 0 Round Ties To Even
2738 FLOAT_ROUND_MODE_PLUS_INFINITY 1 Round Toward +infinity
2739 FLOAT_ROUND_MODE_MINUS_INFINITY 2 Round Toward -infinity
2740 FLOAT_ROUND_MODE_ZERO 3 Round Toward 0
2741 ====================================== ===== ==============================
2745 .. table:: Floating Point Denorm Mode Enumeration Values
2746 :name: amdgpu-amdhsa-floating-point-denorm-mode-enumeration-values-table
2748 ====================================== ===== ==============================
2749 Enumeration Name Value Description
2750 ====================================== ===== ==============================
2751 FLOAT_DENORM_MODE_FLUSH_SRC_DST 0 Flush Source and Destination
2753 FLOAT_DENORM_MODE_FLUSH_DST 1 Flush Output Denorms
2754 FLOAT_DENORM_MODE_FLUSH_SRC 2 Flush Source Denorms
2755 FLOAT_DENORM_MODE_FLUSH_NONE 3 No Flush
2756 ====================================== ===== ==============================
2760 .. table:: System VGPR Work-Item ID Enumeration Values
2761 :name: amdgpu-amdhsa-system-vgpr-work-item-id-enumeration-values-table
2763 ======================================== ===== ============================
2764 Enumeration Name Value Description
2765 ======================================== ===== ============================
2766 SYSTEM_VGPR_WORKITEM_ID_X 0 Set work-item X dimension
2768 SYSTEM_VGPR_WORKITEM_ID_X_Y 1 Set work-item X and Y
2770 SYSTEM_VGPR_WORKITEM_ID_X_Y_Z 2 Set work-item X, Y and Z
2772 SYSTEM_VGPR_WORKITEM_ID_UNDEFINED 3 Undefined.
2773 ======================================== ===== ============================
2775 .. _amdgpu-amdhsa-initial-kernel-execution-state:
2777 Initial Kernel Execution State
2778 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2780 This section defines the register state that will be set up by the packet
2781 processor prior to the start of execution of every wavefront. This is limited by
2782 the constraints of the hardware controllers of CP/ADC/SPI.
2784 The order of the SGPR registers is defined, but the compiler can specify which
2785 ones are actually setup in the kernel descriptor using the ``enable_sgpr_*`` bit
2786 fields (see :ref:`amdgpu-amdhsa-kernel-descriptor`). The register numbers used
2787 for enabled registers are dense starting at SGPR0: the first enabled register is
2788 SGPR0, the next enabled register is SGPR1 etc.; disabled registers do not have
2791 The initial SGPRs comprise up to 16 User SRGPs that are set by CP and apply to
2792 all wavefronts of the grid. It is possible to specify more than 16 User SGPRs using
2793 the ``enable_sgpr_*`` bit fields, in which case only the first 16 are actually
2794 initialized. These are then immediately followed by the System SGPRs that are
2795 set up by ADC/SPI and can have different values for each wavefront of the grid
2798 SGPR register initial state is defined in
2799 :ref:`amdgpu-amdhsa-sgpr-register-set-up-order-table`.
2801 .. table:: SGPR Register Set Up Order
2802 :name: amdgpu-amdhsa-sgpr-register-set-up-order-table
2804 ========== ========================== ====== ==============================
2805 SGPR Order Name Number Description
2806 (kernel descriptor enable of
2808 ========== ========================== ====== ==============================
2809 First Private Segment Buffer 4 V# that can be used, together
2810 (enable_sgpr_private with Scratch Wavefront Offset
2811 _segment_buffer) as an offset, to access the
2812 private memory space using a
2815 CP uses the value provided by
2817 then Dispatch Ptr 2 64 bit address of AQL dispatch
2818 (enable_sgpr_dispatch_ptr) packet for kernel dispatch
2820 then Queue Ptr 2 64 bit address of amd_queue_t
2821 (enable_sgpr_queue_ptr) object for AQL queue on which
2822 the dispatch packet was
2824 then Kernarg Segment Ptr 2 64 bit address of Kernarg
2825 (enable_sgpr_kernarg segment. This is directly
2826 _segment_ptr) copied from the
2827 kernarg_address in the kernel
2830 Having CP load it once avoids
2831 loading it at the beginning of
2833 then Dispatch Id 2 64 bit Dispatch ID of the
2834 (enable_sgpr_dispatch_id) dispatch packet being
2836 then Flat Scratch Init 2 This is 2 SGPRs:
2837 (enable_sgpr_flat_scratch
2841 The first SGPR is a 32 bit
2843 ``SH_HIDDEN_PRIVATE_BASE_VIMID``
2844 to per SPI base of memory
2845 for scratch for the queue
2846 executing the kernel
2847 dispatch. CP obtains this
2848 from the runtime. (The
2849 Scratch Segment Buffer base
2851 ``SH_HIDDEN_PRIVATE_BASE_VIMID``
2852 plus this offset.) The value
2853 of Scratch Wavefront Offset must
2854 be added to this offset by
2855 the kernel machine code,
2856 right shifted by 8, and
2857 moved to the FLAT_SCRATCH_HI
2859 FLAT_SCRATCH_HI corresponds
2860 to SGPRn-4 on GFX7, and
2861 SGPRn-6 on GFX8 (where SGPRn
2862 is the highest numbered SGPR
2863 allocated to the wavefront).
2865 multiplied by 256 (as it is
2866 in units of 256 bytes) and
2868 ``SH_HIDDEN_PRIVATE_BASE_VIMID``
2869 to calculate the per wavefront
2870 FLAT SCRATCH BASE in flat
2871 memory instructions that
2875 The second SGPR is 32 bit
2876 byte size of a single
2877 work-item's scratch memory
2878 usage. CP obtains this from
2879 the runtime, and it is
2880 always a multiple of DWORD.
2881 CP checks that the value in
2882 the kernel dispatch packet
2883 Private Segment Byte Size is
2884 not larger, and requests the
2885 runtime to increase the
2886 queue's scratch size if
2887 necessary. The kernel code
2889 FLAT_SCRATCH_LO which is
2890 SGPRn-3 on GFX7 and SGPRn-5
2891 on GFX8. FLAT_SCRATCH_LO is
2892 used as the FLAT SCRATCH
2894 instructions. Having CP load
2895 it once avoids loading it at
2896 the beginning of every
2900 64 bit base address of the
2901 per SPI scratch backing
2902 memory managed by SPI for
2903 the queue executing the
2904 kernel dispatch. CP obtains
2905 this from the runtime (and
2906 divides it if there are
2907 multiple Shader Arrays each
2908 with its own SPI). The value
2909 of Scratch Wavefront Offset must
2910 be added by the kernel
2911 machine code and the result
2912 moved to the FLAT_SCRATCH
2913 SGPR which is SGPRn-6 and
2914 SGPRn-5. It is used as the
2915 FLAT SCRATCH BASE in flat
2916 memory instructions.
2917 then Private Segment Size 1 The 32 bit byte size of a
2918 (enable_sgpr_private single
2920 scratch_segment_size) memory
2921 allocation. This is the
2922 value from the kernel
2923 dispatch packet Private
2924 Segment Byte Size rounded up
2925 by CP to a multiple of
2928 Having CP load it once avoids
2929 loading it at the beginning of
2932 This is not used for
2933 GFX7-GFX8 since it is the same
2934 value as the second SGPR of
2935 Flat Scratch Init. However, it
2936 may be needed for GFX9-GFX10 which
2937 changes the meaning of the
2938 Flat Scratch Init value.
2939 then Grid Work-Group Count X 1 32 bit count of the number of
2940 (enable_sgpr_grid work-groups in the X dimension
2941 _workgroup_count_X) for the grid being
2942 executed. Computed from the
2943 fields in the kernel dispatch
2944 packet as ((grid_size.x +
2945 workgroup_size.x - 1) /
2947 then Grid Work-Group Count Y 1 32 bit count of the number of
2948 (enable_sgpr_grid work-groups in the Y dimension
2949 _workgroup_count_Y && for the grid being
2950 less than 16 previous executed. Computed from the
2951 SGPRs) fields in the kernel dispatch
2952 packet as ((grid_size.y +
2953 workgroup_size.y - 1) /
2956 Only initialized if <16
2957 previous SGPRs initialized.
2958 then Grid Work-Group Count Z 1 32 bit count of the number of
2959 (enable_sgpr_grid work-groups in the Z dimension
2960 _workgroup_count_Z && for the grid being
2961 less than 16 previous executed. Computed from the
2962 SGPRs) fields in the kernel dispatch
2963 packet as ((grid_size.z +
2964 workgroup_size.z - 1) /
2967 Only initialized if <16
2968 previous SGPRs initialized.
2969 then Work-Group Id X 1 32 bit work-group id in X
2970 (enable_sgpr_workgroup_id dimension of grid for
2972 then Work-Group Id Y 1 32 bit work-group id in Y
2973 (enable_sgpr_workgroup_id dimension of grid for
2975 then Work-Group Id Z 1 32 bit work-group id in Z
2976 (enable_sgpr_workgroup_id dimension of grid for
2978 then Work-Group Info 1 {first_wavefront, 14'b0000,
2979 (enable_sgpr_workgroup ordered_append_term[10:0],
2980 _info) threadgroup_size_in_wavefronts[5:0]}
2981 then Scratch Wavefront Offset 1 32 bit byte offset from base
2982 (enable_sgpr_private of scratch base of queue
2983 _segment_wavefront_offset) executing the kernel
2984 dispatch. Must be used as an
2986 segment address when using
2987 Scratch Segment Buffer. It
2988 must be used to set up FLAT
2989 SCRATCH for flat addressing
2991 :ref:`amdgpu-amdhsa-flat-scratch`).
2992 ========== ========================== ====== ==============================
2994 The order of the VGPR registers is defined, but the compiler can specify which
2995 ones are actually setup in the kernel descriptor using the ``enable_vgpr*`` bit
2996 fields (see :ref:`amdgpu-amdhsa-kernel-descriptor`). The register numbers used
2997 for enabled registers are dense starting at VGPR0: the first enabled register is
2998 VGPR0, the next enabled register is VGPR1 etc.; disabled registers do not have a
3001 VGPR register initial state is defined in
3002 :ref:`amdgpu-amdhsa-vgpr-register-set-up-order-table`.
3004 .. table:: VGPR Register Set Up Order
3005 :name: amdgpu-amdhsa-vgpr-register-set-up-order-table
3007 ========== ========================== ====== ==============================
3008 VGPR Order Name Number Description
3009 (kernel descriptor enable of
3011 ========== ========================== ====== ==============================
3012 First Work-Item Id X 1 32 bit work item id in X
3013 (Always initialized) dimension of work-group for
3015 then Work-Item Id Y 1 32 bit work item id in Y
3016 (enable_vgpr_workitem_id dimension of work-group for
3017 > 0) wavefront lane.
3018 then Work-Item Id Z 1 32 bit work item id in Z
3019 (enable_vgpr_workitem_id dimension of work-group for
3020 > 1) wavefront lane.
3021 ========== ========================== ====== ==============================
3023 The setting of registers is done by GPU CP/ADC/SPI hardware as follows:
3025 1. SGPRs before the Work-Group Ids are set by CP using the 16 User Data
3027 2. Work-group Id registers X, Y, Z are set by ADC which supports any
3028 combination including none.
3029 3. Scratch Wavefront Offset is set by SPI in a per wavefront basis which is why
3030 its value cannot included with the flat scratch init value which is per queue.
3031 4. The VGPRs are set by SPI which only supports specifying either (X), (X, Y)
3034 Flat Scratch register pair are adjacent SGRRs so they can be moved as a 64 bit
3035 value to the hardware required SGPRn-3 and SGPRn-4 respectively.
3037 The global segment can be accessed either using buffer instructions (GFX6 which
3038 has V# 64 bit address support), flat instructions (GFX7-GFX10), or global
3039 instructions (GFX9-GFX10).
3041 If buffer operations are used then the compiler can generate a V# with the
3042 following properties:
3046 * ATC: 1 if IOMMU present (such as APU)
3048 * MTYPE set to support memory coherence that matches the runtime (such as CC for
3049 APU and NC for dGPU).
3051 .. _amdgpu-amdhsa-kernel-prolog:
3056 .. _amdgpu-amdhsa-m0:
3062 The M0 register must be initialized with a value at least the total LDS size
3063 if the kernel may access LDS via DS or flat operations. Total LDS size is
3064 available in dispatch packet. For M0, it is also possible to use maximum
3065 possible value of LDS for given target (0x7FFF for GFX6 and 0xFFFF for
3068 The M0 register is not used for range checking LDS accesses and so does not
3069 need to be initialized in the prolog.
3071 .. _amdgpu-amdhsa-flat-scratch:
3076 If the kernel may use flat operations to access scratch memory, the prolog code
3077 must set up FLAT_SCRATCH register pair (FLAT_SCRATCH_LO/FLAT_SCRATCH_HI which
3078 are in SGPRn-4/SGPRn-3). Initialization uses Flat Scratch Init and Scratch Wavefront
3079 Offset SGPR registers (see :ref:`amdgpu-amdhsa-initial-kernel-execution-state`):
3082 Flat scratch is not supported.
3085 1. The low word of Flat Scratch Init is 32 bit byte offset from
3086 ``SH_HIDDEN_PRIVATE_BASE_VIMID`` to the base of scratch backing memory
3087 being managed by SPI for the queue executing the kernel dispatch. This is
3088 the same value used in the Scratch Segment Buffer V# base address. The
3089 prolog must add the value of Scratch Wavefront Offset to get the wavefront's byte
3090 scratch backing memory offset from ``SH_HIDDEN_PRIVATE_BASE_VIMID``. Since
3091 FLAT_SCRATCH_LO is in units of 256 bytes, the offset must be right shifted
3092 by 8 before moving into FLAT_SCRATCH_LO.
3093 2. The second word of Flat Scratch Init is 32 bit byte size of a single
3094 work-items scratch memory usage. This is directly loaded from the kernel
3095 dispatch packet Private Segment Byte Size and rounded up to a multiple of
3096 DWORD. Having CP load it once avoids loading it at the beginning of every
3097 wavefront. The prolog must move it to FLAT_SCRATCH_LO for use as FLAT SCRATCH
3101 The Flat Scratch Init is the 64 bit address of the base of scratch backing
3102 memory being managed by SPI for the queue executing the kernel dispatch. The
3103 prolog must add the value of Scratch Wavefront Offset and moved to the FLAT_SCRATCH
3104 pair for use as the flat scratch base in flat memory instructions.
3106 .. _amdgpu-amdhsa-memory-model:
3111 This section describes the mapping of LLVM memory model onto AMDGPU machine code
3112 (see :ref:`memmodel`). *The implementation is WIP.*
3115 Update when implementation complete.
3117 The AMDGPU backend supports the memory synchronization scopes specified in
3118 :ref:`amdgpu-memory-scopes`.
3120 The code sequences used to implement the memory model are defined in table
3121 :ref:`amdgpu-amdhsa-memory-model-code-sequences-gfx6-gfx10-table`.
3123 The sequences specify the order of instructions that a single thread must
3124 execute. The ``s_waitcnt`` and ``buffer_wbinvl1_vol`` are defined with respect
3125 to other memory instructions executed by the same thread. This allows them to be
3126 moved earlier or later which can allow them to be combined with other instances
3127 of the same instruction, or hoisted/sunk out of loops to improve
3128 performance. Only the instructions related to the memory model are given;
3129 additional ``s_waitcnt`` instructions are required to ensure registers are
3130 defined before being used. These may be able to be combined with the memory
3131 model ``s_waitcnt`` instructions as described above.
3133 The AMDGPU backend supports the following memory models:
3135 HSA Memory Model [HSA]_
3136 The HSA memory model uses a single happens-before relation for all address
3137 spaces (see :ref:`amdgpu-address-spaces`).
3138 OpenCL Memory Model [OpenCL]_
3139 The OpenCL memory model which has separate happens-before relations for the
3140 global and local address spaces. Only a fence specifying both global and
3141 local address space, and seq_cst instructions join the relationships. Since
3142 the LLVM ``memfence`` instruction does not allow an address space to be
3143 specified the OpenCL fence has to convervatively assume both local and
3144 global address space was specified. However, optimizations can often be
3145 done to eliminate the additional ``s_waitcnt`` instructions when there are
3146 no intervening memory instructions which access the corresponding address
3147 space. The code sequences in the table indicate what can be omitted for the
3148 OpenCL memory. The target triple environment is used to determine if the
3149 source language is OpenCL (see :ref:`amdgpu-opencl`).
3151 ``ds/flat_load/store/atomic`` instructions to local memory are termed LDS
3154 ``buffer/global/flat_load/store/atomic`` instructions to global memory are
3155 termed vector memory operations.
3159 * Each agent has multiple shader arrays (SA).
3160 * Each SA has multiple compute units (CU).
3161 * Each CU has multiple SIMDs that execute wavefronts.
3162 * The wavefronts for a single work-group are executed in the same CU but may be
3163 executed by different SIMDs.
3164 * Each CU has a single LDS memory shared by the wavefronts of the work-groups
3166 * All LDS operations of a CU are performed as wavefront wide operations in a
3167 global order and involve no caching. Completion is reported to a wavefront in
3169 * The LDS memory has multiple request queues shared by the SIMDs of a
3170 CU. Therefore, the LDS operations performed by different wavefronts of a work-group
3171 can be reordered relative to each other, which can result in reordering the
3172 visibility of vector memory operations with respect to LDS operations of other
3173 wavefronts in the same work-group. A ``s_waitcnt lgkmcnt(0)`` is required to
3174 ensure synchronization between LDS operations and vector memory operations
3175 between wavefronts of a work-group, but not between operations performed by the
3177 * The vector memory operations are performed as wavefront wide operations and
3178 completion is reported to a wavefront in execution order. The exception is
3179 that for GFX7-GFX9 ``flat_load/store/atomic`` instructions can report out of
3180 vector memory order if they access LDS memory, and out of LDS operation order
3181 if they access global memory.
3182 * The vector memory operations access a single vector L1 cache shared by all
3183 SIMDs a CU. Therefore, no special action is required for coherence between the
3184 lanes of a single wavefront, or for coherence between wavefronts in the same
3185 work-group. A ``buffer_wbinvl1_vol`` is required for coherence between wavefronts
3186 executing in different work-groups as they may be executing on different CUs.
3187 * The scalar memory operations access a scalar L1 cache shared by all wavefronts
3188 on a group of CUs. The scalar and vector L1 caches are not coherent. However,
3189 scalar operations are used in a restricted way so do not impact the memory
3190 model. See :ref:`amdgpu-amdhsa-memory-spaces`.
3191 * The vector and scalar memory operations use an L2 cache shared by all CUs on
3193 * The L2 cache has independent channels to service disjoint ranges of virtual
3195 * Each CU has a separate request queue per channel. Therefore, the vector and
3196 scalar memory operations performed by wavefronts executing in different work-groups
3197 (which may be executing on different CUs) of an agent can be reordered
3198 relative to each other. A ``s_waitcnt vmcnt(0)`` is required to ensure
3199 synchronization between vector memory operations of different CUs. It ensures a
3200 previous vector memory operation has completed before executing a subsequent
3201 vector memory or LDS operation and so can be used to meet the requirements of
3202 acquire and release.
3203 * The L2 cache can be kept coherent with other agents on some targets, or ranges
3204 of virtual addresses can be set up to bypass it to ensure system coherence.
3208 * Each agent has multiple shader arrays (SA).
3209 * Each SA has multiple work-group processors (WGP).
3210 * Each WGP has multiple compute units (CU).
3211 * Each CU has multiple SIMDs that execute wavefronts.
3212 * The wavefronts for a single work-group are executed in the same
3213 WGP. In CU wavefront execution mode the wavefronts may be executed by
3214 different SIMDs in the same CU. In WGP wavefront execution mode the
3215 wavefronts may be executed by different SIMDs in different CUs in the same
3217 * Each WGP has a single LDS memory shared by the wavefronts of the work-groups
3219 * All LDS operations of a WGP are performed as wavefront wide operations in a
3220 global order and involve no caching. Completion is reported to a wavefront in
3222 * The LDS memory has multiple request queues shared by the SIMDs of a
3223 WGP. Therefore, the LDS operations performed by different wavefronts of a work-group
3224 can be reordered relative to each other, which can result in reordering the
3225 visibility of vector memory operations with respect to LDS operations of other
3226 wavefronts in the same work-group. A ``s_waitcnt lgkmcnt(0)`` is required to
3227 ensure synchronization between LDS operations and vector memory operations
3228 between wavefronts of a work-group, but not between operations performed by the
3230 * The vector memory operations are performed as wavefront wide operations.
3231 Completion of load/store/sample operations are reported to a wavefront in
3232 execution order of other load/store/sample operations performed by that
3234 * The vector memory operations access a vector L0 cache. There is a single L0
3235 cache per CU. Each SIMD of a CU accesses the same L0 cache.
3236 Therefore, no special action is required for coherence between the lanes of a
3237 single wavefront. However, a ``BUFFER_GL0_INV`` is required for coherence
3238 between wavefronts executing in the same work-group as they may be executing on
3239 SIMDs of different CUs that access different L0s. A ``BUFFER_GL0_INV`` is also
3240 required for coherence between wavefronts executing in different work-groups as
3241 they may be executing on different WGPs.
3242 * The scalar memory operations access a scalar L0 cache shared by all wavefronts
3243 on a WGP. The scalar and vector L0 caches are not coherent. However, scalar
3244 operations are used in a restricted way so do not impact the memory model. See
3245 :ref:`amdgpu-amdhsa-memory-spaces`.
3246 * The vector and scalar memory L0 caches use an L1 cache shared by all WGPs on
3247 the same SA. Therefore, no special action is required for coherence between
3248 the wavefronts of a single work-group. However, a ``BUFFER_GL1_INV`` is
3249 required for coherence between wavefronts executing in different work-groups as
3250 they may be executing on different SAs that access different L1s.
3251 * The L1 caches have independent quadrants to service disjoint ranges of virtual
3253 * Each L0 cache has a separate request queue per L1 quadrant. Therefore, the
3254 vector and scalar memory operations performed by different wavefronts, whether
3255 executing in the same or different work-groups (which may be executing on
3256 different CUs accessing different L0s), can be reordered relative to each
3257 other. A ``s_waitcnt vmcnt(0) & vscnt(0)`` is required to ensure synchronization
3258 between vector memory operations of different wavefronts. It ensures a previous
3259 vector memory operation has completed before executing a subsequent vector
3260 memory or LDS operation and so can be used to meet the requirements of acquire,
3261 release and sequential consistency.
3262 * The L1 caches use an L2 cache shared by all SAs on the same agent.
3263 * The L2 cache has independent channels to service disjoint ranges of virtual
3265 * Each L1 quadrant of a single SA accesses a different L2 channel. Each L1
3266 quadrant has a separate request queue per L2 channel. Therefore, the vector
3267 and scalar memory operations performed by wavefronts executing in different
3268 work-groups (which may be executing on different SAs) of an agent can be
3269 reordered relative to each other. A ``s_waitcnt vmcnt(0) & vscnt(0)`` is
3270 required to ensure synchronization between vector memory operations of
3271 different SAs. It ensures a previous vector memory operation has completed
3272 before executing a subsequent vector memory and so can be used to meet the
3273 requirements of acquire, release and sequential consistency.
3274 * The L2 cache can be kept coherent with other agents on some targets, or ranges
3275 of virtual addresses can be set up to bypass it to ensure system coherence.
3277 Private address space uses ``buffer_load/store`` using the scratch V# (GFX6-GFX8),
3278 or ``scratch_load/store`` (GFX9-GFX10). Since only a single thread is accessing the
3279 memory, atomic memory orderings are not meaningful and all accesses are treated
3282 Constant address space uses ``buffer/global_load`` instructions (or equivalent
3283 scalar memory instructions). Since the constant address space contents do not
3284 change during the execution of a kernel dispatch it is not legal to perform
3285 stores, and atomic memory orderings are not meaningful and all access are
3286 treated as non-atomic.
3288 A memory synchronization scope wider than work-group is not meaningful for the
3289 group (LDS) address space and is treated as work-group.
3291 The memory model does not support the region address space which is treated as
3294 Acquire memory ordering is not meaningful on store atomic instructions and is
3295 treated as non-atomic.
3297 Release memory ordering is not meaningful on load atomic instructions and is
3298 treated a non-atomic.
3300 Acquire-release memory ordering is not meaningful on load or store atomic
3301 instructions and is treated as acquire and release respectively.
3303 AMDGPU backend only uses scalar memory operations to access memory that is
3304 proven to not change during the execution of the kernel dispatch. This includes
3305 constant address space and global address space for program scope const
3306 variables. Therefore the kernel machine code does not have to maintain the
3307 scalar L1 cache to ensure it is coherent with the vector L1 cache. The scalar
3308 and vector L1 caches are invalidated between kernel dispatches by CP since
3309 constant address space data may change between kernel dispatch executions. See
3310 :ref:`amdgpu-amdhsa-memory-spaces`.
3312 The one execption is if scalar writes are used to spill SGPR registers. In this
3313 case the AMDGPU backend ensures the memory location used to spill is never
3314 accessed by vector memory operations at the same time. If scalar writes are used
3315 then a ``s_dcache_wb`` is inserted before the ``s_endpgm`` and before a function
3316 return since the locations may be used for vector memory instructions by a
3317 future wavefront that uses the same scratch area, or a function call that creates a
3318 frame at the same address, respectively. There is no need for a ``s_dcache_inv``
3319 as all scalar writes are write-before-read in the same thread.
3321 For GFX6-GFX9, scratch backing memory (which is used for the private address space)
3322 is accessed with MTYPE NC_NV (non-coherenent non-volatile). Since the private
3323 address space is only accessed by a single thread, and is always
3324 write-before-read, there is never a need to invalidate these entries from the L1
3325 cache. Hence all cache invalidates are done as ``*_vol`` to only invalidate the
3326 volatile cache lines.
3328 For GFX10, scratch backing memory (which is used for the private address space)
3329 is accessed with MTYPE NC (non-coherenent). Since the private address space is
3330 only accessed by a single thread, and is always write-before-read, there is
3331 never a need to invalidate these entries from the L0 or L1 caches.
3333 For GFX10, wavefronts are executed in native mode with in-order reporting of loads
3334 and sample instructions. In this mode vmcnt reports completion of load, atomic
3335 with return and sample instructions in order, and the vscnt reports the
3336 completion of store and atomic without return in order. See ``MEM_ORDERED`` field
3337 in :ref:`amdgpu-amdhsa-compute_pgm_rsrc1-gfx6-gfx10-table`.
3339 In GFX10, wavefronts can be executed in WGP or CU wavefront execution mode:
3341 * In WGP wavefront execution mode the wavefronts of a work-group are executed
3342 on the SIMDs of both CUs of the WGP. Therefore, explicit management of the per
3343 CU L0 caches is required for work-group synchronization. Also accesses to L1 at
3344 work-group scope need to be expicitly ordered as the accesses from different
3345 CUs are not ordered.
3346 * In CU wavefront execution mode the wavefronts of a work-group are executed on
3347 the SIMDs of a single CU of the WGP. Therefore, all global memory access by
3348 the work-group access the same L0 which in turn ensures L1 accesses are
3349 ordered and so do not require explicit management of the caches for
3350 work-group synchronization.
3352 See ``WGP_MODE`` field in :ref:`amdgpu-amdhsa-compute_pgm_rsrc1-gfx6-gfx10-table`
3353 and :ref:`amdgpu-target-features`.
3355 On dGPU the kernarg backing memory is accessed as UC (uncached) to avoid needing
3356 to invalidate the L2 cache. For GFX6-GFX9, this also causes it to be treated as
3357 non-volatile and so is not invalidated by ``*_vol``. On APU it is accessed as CC
3358 (cache coherent) and so the L2 cache will be coherent with the CPU and other
3361 .. table:: AMDHSA Memory Model Code Sequences GFX6-GFX10
3362 :name: amdgpu-amdhsa-memory-model-code-sequences-gfx6-gfx10-table
3364 ============ ============ ============== ========== =============================== ==================================
3365 LLVM Instr LLVM Memory LLVM Memory AMDGPU AMDGPU Machine Code AMDGPU Machine Code
3366 Ordering Sync Scope Address GFX6-9 GFX10
3368 ============ ============ ============== ========== =============================== ==================================
3370 ----------------------------------------------------------------------------------------------------------------------
3371 load *none* *none* - global - !volatile & !nontemporal - !volatile & !nontemporal
3373 - private 1. buffer/global/flat_load 1. buffer/global/flat_load
3375 - volatile & !nontemporal - volatile & !nontemporal
3377 1. buffer/global/flat_load 1. buffer/global/flat_load
3380 - nontemporal - nontemporal
3382 1. buffer/global/flat_load 1. buffer/global/flat_load
3385 load *none* *none* - local 1. ds_load 1. ds_load
3386 store *none* *none* - global - !nontemporal - !nontemporal
3388 - private 1. buffer/global/flat_store 1. buffer/global/flat_store
3390 - nontemporal - nontemporal
3392 1. buffer/global/flat_stote 1. buffer/global/flat_store
3395 store *none* *none* - local 1. ds_store 1. ds_store
3396 **Unordered Atomic**
3397 ----------------------------------------------------------------------------------------------------------------------
3398 load atomic unordered *any* *any* *Same as non-atomic*. *Same as non-atomic*.
3399 store atomic unordered *any* *any* *Same as non-atomic*. *Same as non-atomic*.
3400 atomicrmw unordered *any* *any* *Same as monotonic *Same as monotonic
3402 **Monotonic Atomic**
3403 ----------------------------------------------------------------------------------------------------------------------
3404 load atomic monotonic - singlethread - global 1. buffer/global/flat_load 1. buffer/global/flat_load
3405 - wavefront - generic
3406 load atomic monotonic - workgroup - global 1. buffer/global/flat_load 1. buffer/global/flat_load
3409 - If CU wavefront execution mode, omit glc=1.
3411 load atomic monotonic - singlethread - local 1. ds_load 1. ds_load
3414 load atomic monotonic - agent - global 1. buffer/global/flat_load 1. buffer/global/flat_load
3415 - system - generic glc=1 glc=1 dlc=1
3416 store atomic monotonic - singlethread - global 1. buffer/global/flat_store 1. buffer/global/flat_store
3417 - wavefront - generic
3421 store atomic monotonic - singlethread - local 1. ds_store 1. ds_store
3424 atomicrmw monotonic - singlethread - global 1. buffer/global/flat_atomic 1. buffer/global/flat_atomic
3425 - wavefront - generic
3429 atomicrmw monotonic - singlethread - local 1. ds_atomic 1. ds_atomic
3433 ----------------------------------------------------------------------------------------------------------------------
3434 load atomic acquire - singlethread - global 1. buffer/global/ds/flat_load 1. buffer/global/ds/flat_load
3437 load atomic acquire - workgroup - global 1. buffer/global/flat_load 1. buffer/global_load glc=1
3439 - If CU wavefront execution mode, omit glc=1.
3441 2. s_waitcnt vmcnt(0)
3443 - If CU wavefront execution mode, omit.
3444 - Must happen before
3445 the following buffer_gl0_inv
3446 and before any following
3454 - If CU wavefront execution mode, omit.
3460 load atomic acquire - workgroup - local 1. ds_load 1. ds_load
3461 2. s_waitcnt lgkmcnt(0) 2. s_waitcnt lgkmcnt(0)
3463 - If OpenCL, omit. - If OpenCL, omit.
3464 - Must happen before - Must happen before
3465 any following the following buffer_gl0_inv
3466 global/generic and before any following
3467 load/load global/generic load/load
3468 atomic/store/store atomic/store/store
3469 atomic/atomicrmw. atomic/atomicrmw.
3470 - Ensures any - Ensures any
3471 following global following global
3472 data read is no data read is no
3473 older than the load older than the load
3474 atomic value being atomic value being
3479 - If CU wavefront execution mode, omit.
3486 load atomic acquire - workgroup - generic 1. flat_load 1. flat_load glc=1
3488 - If CU wavefront execution mode, omit glc=1.
3490 2. s_waitcnt lgkmcnt(0) 2. s_waitcnt lgkmcnt(0) &
3493 - If CU wavefront execution mode, omit vmcnt.
3494 - If OpenCL, omit. - If OpenCL, omit
3496 - Must happen before - Must happen before
3497 any following the following
3498 global/generic buffer_gl0_inv and any
3499 load/load following global/generic
3500 atomic/store/store load/load
3501 atomic/atomicrmw. atomic/store/store
3503 - Ensures any - Ensures any
3504 following global following global
3505 data read is no data read is no
3506 older than the load older than the load
3507 atomic value being atomic value being
3512 - If CU wavefront execution mode, omit.
3518 load atomic acquire - agent - global 1. buffer/global/flat_load 1. buffer/global_load
3519 - system glc=1 glc=1 dlc=1
3520 2. s_waitcnt vmcnt(0) 2. s_waitcnt vmcnt(0)
3522 - Must happen before - Must happen before
3524 buffer_wbinvl1_vol. buffer_gl*_inv.
3525 - Ensures the load - Ensures the load
3526 has completed has completed
3527 before invalidating before invalidating
3528 the cache. the caches.
3530 3. buffer_wbinvl1_vol 3. buffer_gl0_inv;
3533 - Must happen before - Must happen before
3534 any following any following
3535 global/generic global/generic
3537 atomic/atomicrmw. atomic/atomicrmw.
3538 - Ensures that - Ensures that
3540 loads will not see loads will not see
3541 stale global data. stale global data.
3543 load atomic acquire - agent - generic 1. flat_load glc=1 1. flat_load glc=1 dlc=1
3544 - system 2. s_waitcnt vmcnt(0) & 2. s_waitcnt vmcnt(0) &
3545 lgkmcnt(0) lgkmcnt(0)
3547 - If OpenCL omit - If OpenCL omit
3548 lgkmcnt(0). lgkmcnt(0).
3549 - Must happen before - Must happen before
3551 buffer_wbinvl1_vol. buffer_gl*_invl.
3552 - Ensures the flat_load - Ensures the flat_load
3553 has completed has completed
3554 before invalidating before invalidating
3555 the cache. the caches.
3557 3. buffer_wbinvl1_vol 3. buffer_gl0_inv;
3560 - Must happen before - Must happen before
3561 any following any following
3562 global/generic global/generic
3564 atomic/atomicrmw. atomic/atomicrmw.
3565 - Ensures that - Ensures that
3566 following loads following loads
3567 will not see stale will not see stale
3568 global data. global data.
3570 atomicrmw acquire - singlethread - global 1. buffer/global/ds/flat_atomic 1. buffer/global/ds/flat_atomic
3573 atomicrmw acquire - workgroup - global 1. buffer/global/flat_atomic 1. buffer/global_atomic
3574 2. s_waitcnt vm/vscnt(0)
3576 - If CU wavefront execution mode, omit.
3577 - Use vmcnt if atomic with
3578 return and vscnt if atomic
3580 - Must happen before
3581 the following buffer_gl0_inv
3582 and before any following
3590 - If CU wavefront execution mode, omit.
3596 atomicrmw acquire - workgroup - local 1. ds_atomic 1. ds_atomic
3597 2. waitcnt lgkmcnt(0) 2. waitcnt lgkmcnt(0)
3599 - If OpenCL, omit. - If OpenCL, omit.
3600 - Must happen before - Must happen before
3601 any following the following
3602 global/generic buffer_gl0_inv.
3606 - Ensures any - Ensures any
3607 following global following global
3608 data read is no data read is no
3609 older than the older than the
3610 atomicrmw value atomicrmw value
3611 being acquired. being acquired.
3621 atomicrmw acquire - workgroup - generic 1. flat_atomic 1. flat_atomic
3622 2. waitcnt lgkmcnt(0) 2. waitcnt lgkmcnt(0) &
3625 - If CU wavefront execution mode, omit vm/vscnt.
3626 - If OpenCL, omit. - If OpenCL, omit
3627 waitcnt lgkmcnt(0)..
3628 - Use vmcnt if atomic with
3629 return and vscnt if atomic
3632 - Must happen before - Must happen before
3633 any following the following
3634 global/generic buffer_gl0_inv.
3638 - Ensures any - Ensures any
3639 following global following global
3640 data read is no data read is no
3641 older than the older than the
3642 atomicrmw value atomicrmw value
3643 being acquired. being acquired.
3647 - If CU wavefront execution mode, omit.
3653 atomicrmw acquire - agent - global 1. buffer/global/flat_atomic 1. buffer/global_atomic
3654 - system 2. s_waitcnt vmcnt(0) 2. s_waitcnt vm/vscnt(0)
3656 - Use vmcnt if atomic with
3657 return and vscnt if atomic
3660 - Must happen before - Must happen before
3662 buffer_wbinvl1_vol. buffer_gl*_inv.
3663 - Ensures the - Ensures the
3664 atomicrmw has atomicrmw has
3665 completed before completed before
3666 invalidating the invalidating the
3669 3. buffer_wbinvl1_vol 3. buffer_gl0_inv;
3672 - Must happen before - Must happen before
3673 any following any following
3674 global/generic global/generic
3676 atomic/atomicrmw. atomic/atomicrmw.
3677 - Ensures that - Ensures that
3678 following loads following loads
3679 will not see stale will not see stale
3680 global data. global data.
3682 atomicrmw acquire - agent - generic 1. flat_atomic 1. flat_atomic
3683 - system 2. s_waitcnt vmcnt(0) & 2. s_waitcnt vm/vscnt(0) &
3684 lgkmcnt(0) lgkmcnt(0)
3686 - If OpenCL, omit - If OpenCL, omit
3687 lgkmcnt(0). lgkmcnt(0).
3688 - Use vmcnt if atomic with
3689 return and vscnt if atomic
3691 - Must happen before - Must happen before
3693 buffer_wbinvl1_vol. buffer_gl*_inv.
3694 - Ensures the - Ensures the
3695 atomicrmw has atomicrmw has
3696 completed before completed before
3697 invalidating the invalidating the
3700 3. buffer_wbinvl1_vol 3. buffer_gl0_inv;
3703 - Must happen before - Must happen before
3704 any following any following
3705 global/generic global/generic
3707 atomic/atomicrmw. atomic/atomicrmw.
3708 - Ensures that - Ensures that
3709 following loads following loads
3710 will not see stale will not see stale
3711 global data. global data.
3713 fence acquire - singlethread *none* *none* *none*
3715 fence acquire - workgroup *none* 1. s_waitcnt lgkmcnt(0) 1. s_waitcnt lgkmcnt(0) &
3718 - If CU wavefront execution mode, omit vmcnt and
3720 - If OpenCL and - If OpenCL and
3721 address space is address space is
3722 not generic, omit. not generic, omit
3727 vmcnt(0) and vscnt(0).
3728 - However, since LLVM - However, since LLVM
3729 currently has no currently has no
3730 address space on address space on
3731 the fence need to the fence need to
3732 conservatively conservatively
3733 always generate. If always generate. If
3734 fence had an fence had an
3735 address space then address space then
3736 set to address set to address
3737 space of OpenCL space of OpenCL
3738 fence flag, or to fence flag, or to
3739 generic if both generic if both
3740 local and global local and global
3742 specified. specified.
3753 fence-paired-atomic).
3754 - Must happen before
3765 fence-paired-atomic.
3766 - Could be split into
3769 vscnt(0) and s_waitcnt
3775 - s_waitcnt vmcnt(0)
3780 atomicrmw-with-return-value
3787 fence-paired-atomic).
3788 - s_waitcnt vscnt(0)
3792 atomicrmw-no-return-value
3799 fence-paired-atomic).
3800 - s_waitcnt lgkmcnt(0)
3811 fence-paired-atomic).
3812 - Must happen before
3826 fence-paired-atomic.
3830 - If CU wavefront execution mode, omit.
3836 fence acquire - agent *none* 1. s_waitcnt lgkmcnt(0) & 1. s_waitcnt lgkmcnt(0) &
3837 - system vmcnt(0) vmcnt(0) & vscnt(0)
3839 - If OpenCL and - If OpenCL and
3840 address space is address space is
3841 not generic, omit not generic, omit
3842 lgkmcnt(0). lgkmcnt(0).
3846 vmcnt(0) and vscnt(0).
3847 - However, since LLVM - However, since LLVM
3848 currently has no currently has no
3849 address space on address space on
3850 the fence need to the fence need to
3851 conservatively conservatively
3852 always generate always generate
3853 (see comment for (see comment for
3854 previous fence). previous fence).
3855 - Could be split into
3864 - s_waitcnt vmcnt(0)
3875 fence-paired-atomic).
3876 - s_waitcnt lgkmcnt(0)
3887 fence-paired-atomic).
3888 - Must happen before
3902 fence-paired-atomic.
3903 - Could be split into
3906 vscnt(0) and s_waitcnt
3912 - s_waitcnt vmcnt(0)
3917 atomicrmw-with-return-value
3924 fence-paired-atomic).
3925 - s_waitcnt vscnt(0)
3929 atomicrmw-no-return-value
3936 fence-paired-atomic).
3937 - s_waitcnt lgkmcnt(0)
3948 fence-paired-atomic).
3949 - Must happen before
3963 fence-paired-atomic.
3965 2. buffer_wbinvl1_vol 2. buffer_gl0_inv;
3968 - Must happen before any - Must happen before any
3969 following global/generic following global/generic
3971 atomic/store/store atomic/store/store
3972 atomic/atomicrmw. atomic/atomicrmw.
3973 - Ensures that - Ensures that
3974 following loads following loads
3975 will not see stale will not see stale
3976 global data. global data.
3979 ----------------------------------------------------------------------------------------------------------------------
3980 store atomic release - singlethread - global 1. buffer/global/ds/flat_store 1. buffer/global/ds/flat_store
3983 store atomic release - workgroup - global 1. s_waitcnt lgkmcnt(0) 1. s_waitcnt lgkmcnt(0) &
3986 - If CU wavefront execution mode, omit vmcnt and
3988 - If OpenCL, omit. - If OpenCL, omit
3996 - Could be split into
3999 vscnt(0) and s_waitcnt
4005 - s_waitcnt vmcnt(0)
4008 global/generic load/load
4010 atomicrmw-with-return-value.
4011 - s_waitcnt vscnt(0)
4017 atomicrmw-no-return-value.
4018 - s_waitcnt lgkmcnt(0)
4025 - Must happen before - Must happen before
4026 the following the following
4028 - Ensures that all - Ensures that all
4029 memory operations memory operations
4031 completed before completed before
4032 performing the performing the
4033 store that is being store that is being
4036 2. buffer/global/flat_store 2. buffer/global_store
4037 store atomic release - workgroup - local 1. waitcnt vmcnt(0) & vscnt(0)
4039 - If CU wavefront execution mode, omit.
4041 - Could be split into
4043 vmcnt(0) and s_waitcnt
4049 - s_waitcnt vmcnt(0)
4052 global/generic load/load
4054 atomicrmw-with-return-value.
4055 - s_waitcnt vscnt(0)
4060 atomicrmw-no-return-value.
4061 - Must happen before
4072 1. ds_store 2. ds_store
4073 store atomic release - workgroup - generic 1. s_waitcnt lgkmcnt(0) 1. s_waitcnt lgkmcnt(0) &
4076 - If CU wavefront execution mode, omit vmcnt and
4078 - If OpenCL, omit. - If OpenCL, omit
4086 - Could be split into
4089 vscnt(0) and s_waitcnt
4095 - s_waitcnt vmcnt(0)
4098 global/generic load/load
4100 atomicrmw-with-return-value.
4101 - s_waitcnt vscnt(0)
4107 atomicrmw-no-return-value.
4108 - s_waitcnt lgkmcnt(0)
4111 local/generic load/store/load
4112 atomic/store atomic/atomicrmw.
4113 - Must happen before - Must happen before
4114 the following the following
4116 - Ensures that all - Ensures that all
4117 memory operations memory operations
4119 completed before completed before
4120 performing the performing the
4121 store that is being store that is being
4124 2. flat_store 2. flat_store
4125 store atomic release - agent - global 1. s_waitcnt lgkmcnt(0) & 1. s_waitcnt lgkmcnt(0) &
4126 - system - generic vmcnt(0) vmcnt(0) & vscnt(0)
4128 - If OpenCL, omit - If OpenCL, omit
4129 lgkmcnt(0). lgkmcnt(0).
4130 - Could be split into - Could be split into
4131 separate s_waitcnt separate s_waitcnt
4132 vmcnt(0) and vmcnt(0), s_waitcnt vscnt(0)
4133 s_waitcnt and s_waitcnt
4134 lgkmcnt(0) to allow lgkmcnt(0) to allow
4135 them to be them to be
4136 independently moved independently moved
4137 according to the according to the
4138 following rules. following rules.
4139 - s_waitcnt vmcnt(0) - s_waitcnt vmcnt(0)
4140 must happen after must happen after
4141 any preceding any preceding
4142 global/generic global/generic
4143 load/store/load load/load
4144 atomic/store atomic/
4145 atomic/atomicrmw. atomicrmw-with-return-value.
4146 - s_waitcnt vscnt(0)
4151 atomicrmw-no-return-value.
4152 - s_waitcnt lgkmcnt(0) - s_waitcnt lgkmcnt(0)
4153 must happen after must happen after
4154 any preceding any preceding
4155 local/generic local/generic
4156 load/store/load load/store/load
4157 atomic/store atomic/store
4158 atomic/atomicrmw. atomic/atomicrmw.
4159 - Must happen before - Must happen before
4160 the following the following
4162 - Ensures that all - Ensures that all
4163 memory operations memory operations
4164 to memory have to memory have
4165 completed before completed before
4166 performing the performing the
4167 store that is being store that is being
4170 2. buffer/global/ds/flat_store 2. buffer/global/ds/flat_store
4171 atomicrmw release - singlethread - global 1. buffer/global/ds/flat_atomic 1. buffer/global/ds/flat_atomic
4174 atomicrmw release - workgroup - global 1. s_waitcnt lgkmcnt(0) 1. s_waitcnt lgkmcnt(0) &
4177 - If CU wavefront execution mode, omit vmcnt and
4187 - Could be split into
4190 vscnt(0) and s_waitcnt
4196 - s_waitcnt vmcnt(0)
4199 global/generic load/load
4201 atomicrmw-with-return-value.
4202 - s_waitcnt vscnt(0)
4208 atomicrmw-no-return-value.
4209 - s_waitcnt lgkmcnt(0)
4216 - Must happen before - Must happen before
4217 the following the following
4218 atomicrmw. atomicrmw.
4219 - Ensures that all - Ensures that all
4220 memory operations memory operations
4222 completed before completed before
4223 performing the performing the
4224 atomicrmw that is atomicrmw that is
4225 being released. being released.
4227 2. buffer/global/flat_atomic 2. buffer/global_atomic
4228 atomicrmw release - workgroup - local 1. waitcnt vmcnt(0) & vscnt(0)
4230 - If CU wavefront execution mode, omit.
4232 - Could be split into
4234 vmcnt(0) and s_waitcnt
4240 - s_waitcnt vmcnt(0)
4243 global/generic load/load
4245 atomicrmw-with-return-value.
4246 - s_waitcnt vscnt(0)
4251 atomicrmw-no-return-value.
4252 - Must happen before
4263 1. ds_atomic 2. ds_atomic
4264 atomicrmw release - workgroup - generic 1. s_waitcnt lgkmcnt(0) 1. s_waitcnt lgkmcnt(0) &
4267 - If CU wavefront execution mode, omit vmcnt and
4269 - If OpenCL, omit. - If OpenCL, omit
4277 - Could be split into
4280 vscnt(0) and s_waitcnt
4286 - s_waitcnt vmcnt(0)
4289 global/generic load/load
4291 atomicrmw-with-return-value.
4292 - s_waitcnt vscnt(0)
4298 atomicrmw-no-return-value.
4299 - s_waitcnt lgkmcnt(0)
4302 local/generic load/store/load
4303 atomic/store atomic/atomicrmw.
4304 - Must happen before - Must happen before
4305 the following the following
4306 atomicrmw. atomicrmw.
4307 - Ensures that all - Ensures that all
4308 memory operations memory operations
4310 completed before completed before
4311 performing the performing the
4312 atomicrmw that is atomicrmw that is
4313 being released. being released.
4315 2. flat_atomic 2. flat_atomic
4316 atomicrmw release - agent - global 1. s_waitcnt lgkmcnt(0) & 1. s_waitcnt lkkmcnt(0) &
4317 - system - generic vmcnt(0) vmcnt(0) & vscnt(0)
4319 - If OpenCL, omit - If OpenCL, omit
4320 lgkmcnt(0). lgkmcnt(0).
4321 - Could be split into - Could be split into
4322 separate s_waitcnt separate s_waitcnt
4323 vmcnt(0) and vmcnt(0), s_waitcnt
4324 s_waitcnt vscnt(0) and s_waitcnt
4325 lgkmcnt(0) to allow lgkmcnt(0) to allow
4326 them to be them to be
4327 independently moved independently moved
4328 according to the according to the
4329 following rules. following rules.
4330 - s_waitcnt vmcnt(0) - s_waitcnt vmcnt(0)
4331 must happen after must happen after
4332 any preceding any preceding
4333 global/generic global/generic
4334 load/store/load load/load atomic/
4335 atomic/store atomicrmw-with-return-value.
4337 - s_waitcnt vscnt(0)
4342 atomicrmw-no-return-value.
4343 - s_waitcnt lgkmcnt(0) - s_waitcnt lgkmcnt(0)
4344 must happen after must happen after
4345 any preceding any preceding
4346 local/generic local/generic
4347 load/store/load load/store/load
4348 atomic/store atomic/store
4349 atomic/atomicrmw. atomic/atomicrmw.
4350 - Must happen before - Must happen before
4351 the following the following
4352 atomicrmw. atomicrmw.
4353 - Ensures that all - Ensures that all
4354 memory operations memory operations
4355 to global and local to global and local
4356 have completed have completed
4357 before performing before performing
4358 the atomicrmw that the atomicrmw that
4359 is being released. is being released.
4361 2. buffer/global/ds/flat_atomic 2. buffer/global/ds/flat_atomic
4362 fence release - singlethread *none* *none* *none*
4364 fence release - workgroup *none* 1. s_waitcnt lgkmcnt(0) 1. s_waitcnt lgkmcnt(0) &
4367 - If CU wavefront execution mode, omit vmcnt and
4369 - If OpenCL and - If OpenCL and
4370 address space is address space is
4371 not generic, omit. not generic, omit
4376 vmcnt(0) and vscnt(0).
4377 - However, since LLVM - However, since LLVM
4378 currently has no currently has no
4379 address space on address space on
4380 the fence need to the fence need to
4381 conservatively conservatively
4382 always generate. If always generate. If
4383 fence had an fence had an
4384 address space then address space then
4385 set to address set to address
4386 space of OpenCL space of OpenCL
4387 fence flag, or to fence flag, or to
4388 generic if both generic if both
4389 local and global local and global
4391 specified. specified.
4398 - Could be split into
4401 vscnt(0) and s_waitcnt
4407 - s_waitcnt vmcnt(0)
4413 atomicrmw-with-return-value.
4414 - s_waitcnt vscnt(0)
4419 atomicrmw-no-return-value.
4420 - s_waitcnt lgkmcnt(0)
4425 atomic/store atomic/
4427 - Must happen before - Must happen before
4428 any following store any following store
4429 atomic/atomicrmw atomic/atomicrmw
4430 with an equal or with an equal or
4431 wider sync scope wider sync scope
4432 and memory ordering and memory ordering
4433 stronger than stronger than
4434 unordered (this is unordered (this is
4435 termed the termed the
4436 fence-paired-atomic). fence-paired-atomic).
4437 - Ensures that all - Ensures that all
4438 memory operations memory operations
4440 completed before completed before
4441 performing the performing the
4443 fence-paired-atomic. fence-paired-atomic.
4445 fence release - agent *none* 1. s_waitcnt lgkmcnt(0) & 1. s_waitcnt lgkmcnt(0) &
4446 - system vmcnt(0) vmcnt(0) & vscnt(0)
4448 - If OpenCL and - If OpenCL and
4449 address space is address space is
4450 not generic, omit not generic, omit
4451 lgkmcnt(0). lgkmcnt(0).
4452 - If OpenCL and - If OpenCL and
4453 address space is address space is
4454 local, omit local, omit
4455 vmcnt(0). vmcnt(0) and vscnt(0).
4456 - However, since LLVM - However, since LLVM
4457 currently has no currently has no
4458 address space on address space on
4459 the fence need to the fence need to
4460 conservatively conservatively
4461 always generate. If always generate. If
4462 fence had an fence had an
4463 address space then address space then
4464 set to address set to address
4465 space of OpenCL space of OpenCL
4466 fence flag, or to fence flag, or to
4467 generic if both generic if both
4468 local and global local and global
4470 specified. specified.
4471 - Could be split into - Could be split into
4472 separate s_waitcnt separate s_waitcnt
4473 vmcnt(0) and vmcnt(0), s_waitcnt
4474 s_waitcnt vscnt(0) and s_waitcnt
4475 lgkmcnt(0) to allow lgkmcnt(0) to allow
4476 them to be them to be
4477 independently moved independently moved
4478 according to the according to the
4479 following rules. following rules.
4480 - s_waitcnt vmcnt(0) - s_waitcnt vmcnt(0)
4481 must happen after must happen after
4482 any preceding any preceding
4483 global/generic global/generic
4484 load/store/load load/load atomic/
4485 atomic/store atomicrmw-with-return-value.
4487 - s_waitcnt vscnt(0)
4492 atomicrmw-no-return-value.
4493 - s_waitcnt lgkmcnt(0) - s_waitcnt lgkmcnt(0)
4494 must happen after must happen after
4495 any preceding any preceding
4496 local/generic local/generic
4497 load/store/load load/store/load
4498 atomic/store atomic/store
4499 atomic/atomicrmw. atomic/atomicrmw.
4500 - Must happen before - Must happen before
4501 any following store any following store
4502 atomic/atomicrmw atomic/atomicrmw
4503 with an equal or with an equal or
4504 wider sync scope wider sync scope
4505 and memory ordering and memory ordering
4506 stronger than stronger than
4507 unordered (this is unordered (this is
4508 termed the termed the
4509 fence-paired-atomic). fence-paired-atomic).
4510 - Ensures that all - Ensures that all
4511 memory operations memory operations
4513 completed before completed before
4514 performing the performing the
4516 fence-paired-atomic. fence-paired-atomic.
4518 **Acquire-Release Atomic**
4519 ----------------------------------------------------------------------------------------------------------------------
4520 atomicrmw acq_rel - singlethread - global 1. buffer/global/ds/flat_atomic 1. buffer/global/ds/flat_atomic
4523 atomicrmw acq_rel - workgroup - global 1. s_waitcnt lgkmcnt(0) 1. s_waitcnt lgkmcnt(0) &
4526 - If CU wavefront execution mode, omit vmcnt and
4528 - If OpenCL, omit. - If OpenCL, omit
4529 s_waitcnt lgkmcnt(0).
4530 - Must happen after - Must happen after
4531 any preceding any preceding
4532 local/generic local/generic
4533 load/store/load load/store/load
4534 atomic/store atomic/store
4535 atomic/atomicrmw. atomic/atomicrmw.
4536 - Could be split into
4539 vscnt(0) and s_waitcnt
4545 - s_waitcnt vmcnt(0)
4548 global/generic load/load
4550 atomicrmw-with-return-value.
4551 - s_waitcnt vscnt(0)
4557 atomicrmw-no-return-value.
4558 - s_waitcnt lgkmcnt(0)
4561 local/generic load/store/load
4562 atomic/store atomic/atomicrmw.
4563 - Must happen before - Must happen before
4564 the following the following
4565 atomicrmw. atomicrmw.
4566 - Ensures that all - Ensures that all
4567 memory operations memory operations
4569 completed before completed before
4570 performing the performing the
4571 atomicrmw that is atomicrmw that is
4572 being released. being released.
4574 2. buffer/global/flat_atomic 2. buffer/global_atomic
4575 3. s_waitcnt vm/vscnt(0)
4577 - If CU wavefront execution mode, omit vm/vscnt.
4578 - Use vmcnt if atomic with
4579 return and vscnt if atomic
4582 - Must happen before
4594 - If CU wavefront execution mode, omit.
4600 atomicrmw acq_rel - workgroup - local 1. waitcnt vmcnt(0) & vscnt(0)
4602 - If CU wavefront execution mode, omit.
4604 - Could be split into
4606 vmcnt(0) and s_waitcnt
4612 - s_waitcnt vmcnt(0)
4615 global/generic load/load
4617 atomicrmw-with-return-value.
4618 - s_waitcnt vscnt(0)
4623 atomicrmw-no-return-value.
4624 - Must happen before
4635 1. ds_atomic 2. ds_atomic
4636 2. s_waitcnt lgkmcnt(0) 3. s_waitcnt lgkmcnt(0)
4638 - If OpenCL, omit. - If OpenCL, omit.
4639 - Must happen before - Must happen before
4640 any following the following
4641 global/generic buffer_gl0_inv.
4645 - Ensures any - Ensures any
4646 following global following global
4647 data read is no data read is no
4648 older than the load older than the load
4649 atomic value being atomic value being
4654 - If CU wavefront execution mode, omit.
4661 atomicrmw acq_rel - workgroup - generic 1. s_waitcnt lgkmcnt(0) 1. s_waitcnt lgkmcnt(0) &
4664 - If CU wavefront execution mode, omit vmcnt and
4666 - If OpenCL, omit. - If OpenCL, omit
4674 - Could be split into
4677 vscnt(0) and s_waitcnt
4683 - s_waitcnt vmcnt(0)
4686 global/generic load/load
4688 atomicrmw-with-return-value.
4689 - s_waitcnt vscnt(0)
4695 atomicrmw-no-return-value.
4696 - s_waitcnt lgkmcnt(0)
4699 local/generic load/store/load
4700 atomic/store atomic/atomicrmw.
4701 - Must happen before - Must happen before
4702 the following the following
4703 atomicrmw. atomicrmw.
4704 - Ensures that all - Ensures that all
4705 memory operations memory operations
4707 completed before completed before
4708 performing the performing the
4709 atomicrmw that is atomicrmw that is
4710 being released. being released.
4712 2. flat_atomic 2. flat_atomic
4713 3. s_waitcnt lgkmcnt(0) 3. s_waitcnt lgkmcnt(0) &
4716 - If CU wavefront execution mode, omit vm/vscnt.
4717 - If OpenCL, omit. - If OpenCL, omit
4719 - Must happen before - Must happen before
4720 any following the following
4721 global/generic buffer_gl0_inv.
4725 - Ensures any - Ensures any
4726 following global following global
4727 data read is no data read is no
4728 older than the load older than the load
4729 atomic value being atomic value being
4734 - If CU wavefront execution mode, omit.
4740 atomicrmw acq_rel - agent - global 1. s_waitcnt lgkmcnt(0) & 1. s_waitcnt lgkmcnt(0) &
4741 - system vmcnt(0) vmcnt(0) & vscnt(0)
4743 - If OpenCL, omit - If OpenCL, omit
4744 lgkmcnt(0). lgkmcnt(0).
4745 - Could be split into - Could be split into
4746 separate s_waitcnt separate s_waitcnt
4747 vmcnt(0) and vmcnt(0), s_waitcnt
4748 s_waitcnt vscnt(0) and s_waitcnt
4749 lgkmcnt(0) to allow lgkmcnt(0) to allow
4750 them to be them to be
4751 independently moved independently moved
4752 according to the according to the
4753 following rules. following rules.
4754 - s_waitcnt vmcnt(0) - s_waitcnt vmcnt(0)
4755 must happen after must happen after
4756 any preceding any preceding
4757 global/generic global/generic
4758 load/store/load load/load atomic/
4759 atomic/store atomicrmw-with-return-value.
4761 - s_waitcnt vscnt(0)
4766 atomicrmw-no-return-value.
4767 - s_waitcnt lgkmcnt(0) - s_waitcnt lgkmcnt(0)
4768 must happen after must happen after
4769 any preceding any preceding
4770 local/generic local/generic
4771 load/store/load load/store/load
4772 atomic/store atomic/store
4773 atomic/atomicrmw. atomic/atomicrmw.
4774 - Must happen before - Must happen before
4775 the following the following
4776 atomicrmw. atomicrmw.
4777 - Ensures that all - Ensures that all
4778 memory operations memory operations
4779 to global have to global have
4780 completed before completed before
4781 performing the performing the
4782 atomicrmw that is atomicrmw that is
4783 being released. being released.
4785 2. buffer/global/flat_atomic 2. buffer/global_atomic
4786 3. s_waitcnt vmcnt(0) 3. s_waitcnt vm/vscnt(0)
4788 - Use vmcnt if atomic with
4789 return and vscnt if atomic
4792 - Must happen before - Must happen before
4794 buffer_wbinvl1_vol. buffer_gl*_inv.
4795 - Ensures the - Ensures the
4796 atomicrmw has atomicrmw has
4797 completed before completed before
4798 invalidating the invalidating the
4801 4. buffer_wbinvl1_vol 4. buffer_gl0_inv;
4804 - Must happen before - Must happen before
4805 any following any following
4806 global/generic global/generic
4808 atomic/atomicrmw. atomic/atomicrmw.
4809 - Ensures that - Ensures that
4810 following loads following loads
4811 will not see stale will not see stale
4812 global data. global data.
4814 atomicrmw acq_rel - agent - generic 1. s_waitcnt lgkmcnt(0) & 1. s_waitcnt lgkmcnt(0) &
4815 - system vmcnt(0) vmcnt(0) & vscnt(0)
4817 - If OpenCL, omit - If OpenCL, omit
4818 lgkmcnt(0). lgkmcnt(0).
4819 - Could be split into - Could be split into
4820 separate s_waitcnt separate s_waitcnt
4821 vmcnt(0) and vmcnt(0), s_waitcnt
4822 s_waitcnt vscnt(0) and s_waitcnt
4823 lgkmcnt(0) to allow lgkmcnt(0) to allow
4824 them to be them to be
4825 independently moved independently moved
4826 according to the according to the
4827 following rules. following rules.
4828 - s_waitcnt vmcnt(0) - s_waitcnt vmcnt(0)
4829 must happen after must happen after
4830 any preceding any preceding
4831 global/generic global/generic
4832 load/store/load load/load atomic
4833 atomic/store atomicrmw-with-return-value.
4835 - s_waitcnt vscnt(0)
4840 atomicrmw-no-return-value.
4841 - s_waitcnt lgkmcnt(0) - s_waitcnt lgkmcnt(0)
4842 must happen after must happen after
4843 any preceding any preceding
4844 local/generic local/generic
4845 load/store/load load/store/load
4846 atomic/store atomic/store
4847 atomic/atomicrmw. atomic/atomicrmw.
4848 - Must happen before - Must happen before
4849 the following the following
4850 atomicrmw. atomicrmw.
4851 - Ensures that all - Ensures that all
4852 memory operations memory operations
4854 completed before completed before
4855 performing the performing the
4856 atomicrmw that is atomicrmw that is
4857 being released. being released.
4859 2. flat_atomic 2. flat_atomic
4860 3. s_waitcnt vmcnt(0) & 3. s_waitcnt vm/vscnt(0) &
4861 lgkmcnt(0) lgkmcnt(0)
4863 - If OpenCL, omit - If OpenCL, omit
4864 lgkmcnt(0). lgkmcnt(0).
4865 - Use vmcnt if atomic with
4866 return and vscnt if atomic
4868 - Must happen before - Must happen before
4870 buffer_wbinvl1_vol. buffer_gl*_inv.
4871 - Ensures the - Ensures the
4872 atomicrmw has atomicrmw has
4873 completed before completed before
4874 invalidating the invalidating the
4877 4. buffer_wbinvl1_vol 4. buffer_gl0_inv;
4880 - Must happen before - Must happen before
4881 any following any following
4882 global/generic global/generic
4884 atomic/atomicrmw. atomic/atomicrmw.
4885 - Ensures that - Ensures that
4886 following loads following loads
4887 will not see stale will not see stale
4888 global data. global data.
4890 fence acq_rel - singlethread *none* *none* *none*
4892 fence acq_rel - workgroup *none* 1. s_waitcnt lgkmcnt(0) 1. s_waitcnt lgkmcnt(0) &
4895 - If CU wavefront execution mode, omit vmcnt and
4897 - If OpenCL and - If OpenCL and
4898 address space is address space is
4899 not generic, omit. not generic, omit
4904 vmcnt(0) and vscnt(0).
4905 - However, - However,
4906 since LLVM since LLVM
4907 currently has no currently has no
4908 address space on address space on
4909 the fence need to the fence need to
4910 conservatively conservatively
4911 always generate always generate
4912 (see comment for (see comment for
4913 previous fence). previous fence).
4920 - Could be split into
4923 vscnt(0) and s_waitcnt
4929 - s_waitcnt vmcnt(0)
4935 atomicrmw-with-return-value.
4936 - s_waitcnt vscnt(0)
4941 atomicrmw-no-return-value.
4942 - s_waitcnt lgkmcnt(0)
4947 atomic/store atomic/
4949 - Must happen before - Must happen before
4950 any following any following
4951 global/generic global/generic
4953 atomic/store/store atomic/store/store
4954 atomic/atomicrmw. atomic/atomicrmw.
4955 - Ensures that all - Ensures that all
4956 memory operations memory operations
4958 completed before completed before
4959 performing any performing any
4960 following global following global
4961 memory operations. memory operations.
4962 - Ensures that the - Ensures that the
4964 local/generic load local/generic load
4965 atomic/atomicrmw atomic/atomicrmw
4966 with an equal or with an equal or
4967 wider sync scope wider sync scope
4968 and memory ordering and memory ordering
4969 stronger than stronger than
4970 unordered (this is unordered (this is
4971 termed the termed the
4972 acquire-fence-paired-atomic acquire-fence-paired-atomic
4973 ) has completed ) has completed
4974 before following before following
4975 global memory global memory
4976 operations. This operations. This
4977 satisfies the satisfies the
4978 requirements of requirements of
4980 - Ensures that all - Ensures that all
4981 previous memory previous memory
4982 operations have operations have
4983 completed before a completed before a
4985 local/generic store local/generic store
4986 atomic/atomicrmw atomic/atomicrmw
4987 with an equal or with an equal or
4988 wider sync scope wider sync scope
4989 and memory ordering and memory ordering
4990 stronger than stronger than
4991 unordered (this is unordered (this is
4992 termed the termed the
4993 release-fence-paired-atomic release-fence-paired-atomic
4994 ). This satisfies the ). This satisfies the
4995 requirements of requirements of
4997 - Must happen before
5001 acquire-fence-paired
5002 atomic has completed
5011 acquire-fence-paired-atomic.
5015 - If CU wavefront execution mode, omit.
5021 fence acq_rel - agent *none* 1. s_waitcnt lgkmcnt(0) & 1. s_waitcnt lgkmcnt(0) &
5022 - system vmcnt(0) vmcnt(0) & vscnt(0)
5024 - If OpenCL and - If OpenCL and
5025 address space is address space is
5026 not generic, omit not generic, omit
5027 lgkmcnt(0). lgkmcnt(0).
5031 vmcnt(0) and vscnt(0).
5032 - However, since LLVM - However, since LLVM
5033 currently has no currently has no
5034 address space on address space on
5035 the fence need to the fence need to
5036 conservatively conservatively
5037 always generate always generate
5038 (see comment for (see comment for
5039 previous fence). previous fence).
5040 - Could be split into - Could be split into
5041 separate s_waitcnt separate s_waitcnt
5042 vmcnt(0) and vmcnt(0), s_waitcnt
5043 s_waitcnt vscnt(0) and s_waitcnt
5044 lgkmcnt(0) to allow lgkmcnt(0) to allow
5045 them to be them to be
5046 independently moved independently moved
5047 according to the according to the
5048 following rules. following rules.
5049 - s_waitcnt vmcnt(0) - s_waitcnt vmcnt(0)
5050 must happen after must happen after
5051 any preceding any preceding
5052 global/generic global/generic
5053 load/store/load load/load
5054 atomic/store atomic/
5055 atomic/atomicrmw. atomicrmw-with-return-value.
5056 - s_waitcnt vscnt(0)
5061 atomicrmw-no-return-value.
5062 - s_waitcnt lgkmcnt(0) - s_waitcnt lgkmcnt(0)
5063 must happen after must happen after
5064 any preceding any preceding
5065 local/generic local/generic
5066 load/store/load load/store/load
5067 atomic/store atomic/store
5068 atomic/atomicrmw. atomic/atomicrmw.
5069 - Must happen before - Must happen before
5070 the following the following
5071 buffer_wbinvl1_vol. buffer_gl*_inv.
5072 - Ensures that the - Ensures that the
5074 global/local/generic global/local/generic
5076 atomic/atomicrmw atomic/atomicrmw
5077 with an equal or with an equal or
5078 wider sync scope wider sync scope
5079 and memory ordering and memory ordering
5080 stronger than stronger than
5081 unordered (this is unordered (this is
5082 termed the termed the
5083 acquire-fence-paired-atomic acquire-fence-paired-atomic
5084 ) has completed ) has completed
5085 before invalidating before invalidating
5086 the cache. This the caches. This
5087 satisfies the satisfies the
5088 requirements of requirements of
5090 - Ensures that all - Ensures that all
5091 previous memory previous memory
5092 operations have operations have
5093 completed before a completed before a
5095 global/local/generic global/local/generic
5097 atomic/atomicrmw atomic/atomicrmw
5098 with an equal or with an equal or
5099 wider sync scope wider sync scope
5100 and memory ordering and memory ordering
5101 stronger than stronger than
5102 unordered (this is unordered (this is
5103 termed the termed the
5104 release-fence-paired-atomic release-fence-paired-atomic
5105 ). This satisfies the ). This satisfies the
5106 requirements of requirements of
5109 2. buffer_wbinvl1_vol 2. buffer_gl0_inv;
5112 - Must happen before - Must happen before
5113 any following any following
5114 global/generic global/generic
5116 atomic/store/store atomic/store/store
5117 atomic/atomicrmw. atomic/atomicrmw.
5118 - Ensures that - Ensures that
5119 following loads following loads
5120 will not see stale will not see stale
5121 global data. This global data. This
5122 satisfies the satisfies the
5123 requirements of requirements of
5126 **Sequential Consistent Atomic**
5127 ----------------------------------------------------------------------------------------------------------------------
5128 load atomic seq_cst - singlethread - global *Same as corresponding *Same as corresponding
5129 - wavefront - local load atomic acquire, load atomic acquire,
5130 - generic except must generated except must generated
5131 all instructions even all instructions even
5132 for OpenCL.* for OpenCL.*
5133 load atomic seq_cst - workgroup - global 1. s_waitcnt lgkmcnt(0) 1. s_waitcnt lgkmcnt(0) &
5134 - generic vmcnt(0) & vscnt(0)
5136 - If CU wavefront execution mode, omit vmcnt and
5138 - Could be split into
5141 vscnt(0) and s_waitcnt
5147 - Must - waitcnt lgkmcnt(0) must
5148 happen after happen after
5150 global/generic load local load
5151 atomic/store atomic/store
5152 atomic/atomicrmw atomic/atomicrmw
5153 with memory with memory
5154 ordering of seq_cst ordering of seq_cst
5155 and with equal or and with equal or
5156 wider sync scope. wider sync scope.
5157 (Note that seq_cst (Note that seq_cst
5158 fences have their fences have their
5159 own s_waitcnt own s_waitcnt
5160 lgkmcnt(0) and so do lgkmcnt(0) and so do
5161 not need to be not need to be
5162 considered.) considered.)
5168 atomicrmw-with-return-value
5182 global/generic store
5184 atomicrmw-no-return-value
5195 - Ensures any - Ensures any
5197 sequential sequential
5198 consistent local consistent global/local
5199 memory instructions memory instructions
5200 have completed have completed
5201 before executing before executing
5202 this sequentially this sequentially
5203 consistent consistent
5204 instruction. This instruction. This
5205 prevents reordering prevents reordering
5206 a seq_cst store a seq_cst store
5207 followed by a followed by a
5208 seq_cst load. (Note seq_cst load. (Note
5209 that seq_cst is that seq_cst is
5210 stronger than stronger than
5211 acquire/release as acquire/release as
5212 the reordering of the reordering of
5213 load acquire load acquire
5214 followed by a store followed by a store
5215 release is release is
5216 prevented by the prevented by the
5217 waitcnt of waitcnt of
5218 the release, but the release, but
5219 there is nothing there is nothing
5220 preventing a store preventing a store
5221 release followed by release followed by
5222 load acquire from load acquire from
5223 competing out of competing out of
5226 2. *Following 2. *Following
5227 instructions same as instructions same as
5228 corresponding load corresponding load
5229 atomic acquire, atomic acquire,
5230 except must generated except must generated
5231 all instructions even all instructions even
5232 for OpenCL.* for OpenCL.*
5233 load atomic seq_cst - workgroup - local *Same as corresponding
5234 load atomic acquire,
5235 except must generated
5236 all instructions even
5239 1. s_waitcnt vmcnt(0) & vscnt(0)
5241 - If CU wavefront execution mode, omit.
5242 - Could be split into
5244 vmcnt(0) and s_waitcnt
5255 atomicrmw-with-return-value
5269 global/generic store
5271 atomicrmw-no-return-value
5314 instructions same as
5317 except must generated
5318 all instructions even
5321 load atomic seq_cst - agent - global 1. s_waitcnt lgkmcnt(0) & 1. s_waitcnt lgkmcnt(0) &
5322 - system - generic vmcnt(0) vmcnt(0) & vscnt(0)
5324 - Could be split into - Could be split into
5325 separate s_waitcnt separate s_waitcnt
5326 vmcnt(0) vmcnt(0), s_waitcnt
5327 and s_waitcnt vscnt(0) and s_waitcnt
5328 lgkmcnt(0) to allow lgkmcnt(0) to allow
5329 them to be them to be
5330 independently moved independently moved
5331 according to the according to the
5332 following rules. following rules.
5333 - waitcnt lgkmcnt(0) - waitcnt lgkmcnt(0)
5334 must happen after must happen after
5336 global/generic load local load
5337 atomic/store atomic/store
5338 atomic/atomicrmw atomic/atomicrmw
5339 with memory with memory
5340 ordering of seq_cst ordering of seq_cst
5341 and with equal or and with equal or
5342 wider sync scope. wider sync scope.
5343 (Note that seq_cst (Note that seq_cst
5344 fences have their fences have their
5345 own s_waitcnt own s_waitcnt
5346 lgkmcnt(0) and so do lgkmcnt(0) and so do
5347 not need to be not need to be
5348 considered.) considered.)
5349 - waitcnt vmcnt(0) - waitcnt vmcnt(0)
5350 must happen after must happen after
5352 global/generic load global/generic load
5353 atomic/store atomic/
5354 atomic/atomicrmw atomicrmw-with-return-value
5355 with memory with memory
5356 ordering of seq_cst ordering of seq_cst
5357 and with equal or and with equal or
5358 wider sync scope. wider sync scope.
5359 (Note that seq_cst (Note that seq_cst
5360 fences have their fences have their
5361 own s_waitcnt own s_waitcnt
5362 vmcnt(0) and so do vmcnt(0) and so do
5363 not need to be not need to be
5364 considered.) considered.)
5368 global/generic store
5370 atomicrmw-no-return-value
5381 - Ensures any - Ensures any
5383 sequential sequential
5384 consistent global consistent global
5385 memory instructions memory instructions
5386 have completed have completed
5387 before executing before executing
5388 this sequentially this sequentially
5389 consistent consistent
5390 instruction. This instruction. This
5391 prevents reordering prevents reordering
5392 a seq_cst store a seq_cst store
5393 followed by a followed by a
5394 seq_cst load. (Note seq_cst load. (Note
5395 that seq_cst is that seq_cst is
5396 stronger than stronger than
5397 acquire/release as acquire/release as
5398 the reordering of the reordering of
5399 load acquire load acquire
5400 followed by a store followed by a store
5401 release is release is
5402 prevented by the prevented by the
5403 waitcnt of waitcnt of
5404 the release, but the release, but
5405 there is nothing there is nothing
5406 preventing a store preventing a store
5407 release followed by release followed by
5408 load acquire from load acquire from
5409 competing out of competing out of
5412 2. *Following 2. *Following
5413 instructions same as instructions same as
5414 corresponding load corresponding load
5415 atomic acquire, atomic acquire,
5416 except must generated except must generated
5417 all instructions even all instructions even
5418 for OpenCL.* for OpenCL.*
5419 store atomic seq_cst - singlethread - global *Same as corresponding *Same as corresponding
5420 - wavefront - local store atomic release, store atomic release,
5421 - workgroup - generic except must generated except must generated
5422 all instructions even all instructions even
5423 for OpenCL.* for OpenCL.*
5424 store atomic seq_cst - agent - global *Same as corresponding *Same as corresponding
5425 - system - generic store atomic release, store atomic release,
5426 except must generated except must generated
5427 all instructions even all instructions even
5428 for OpenCL.* for OpenCL.*
5429 atomicrmw seq_cst - singlethread - global *Same as corresponding *Same as corresponding
5430 - wavefront - local atomicrmw acq_rel, atomicrmw acq_rel,
5431 - workgroup - generic except must generated except must generated
5432 all instructions even all instructions even
5433 for OpenCL.* for OpenCL.*
5434 atomicrmw seq_cst - agent - global *Same as corresponding *Same as corresponding
5435 - system - generic atomicrmw acq_rel, atomicrmw acq_rel,
5436 except must generated except must generated
5437 all instructions even all instructions even
5438 for OpenCL.* for OpenCL.*
5439 fence seq_cst - singlethread *none* *Same as corresponding *Same as corresponding
5440 - wavefront fence acq_rel, fence acq_rel,
5441 - workgroup except must generated except must generated
5442 - agent all instructions even all instructions even
5443 - system for OpenCL.* for OpenCL.*
5444 ============ ============ ============== ========== =============================== ==================================
5446 The memory order also adds the single thread optimization constrains defined in
5448 :ref:`amdgpu-amdhsa-memory-model-single-thread-optimization-constraints-gfx6-gfx10-table`.
5450 .. table:: AMDHSA Memory Model Single Thread Optimization Constraints GFX6-GFX10
5451 :name: amdgpu-amdhsa-memory-model-single-thread-optimization-constraints-gfx6-gfx10-table
5453 ============ ==============================================================
5454 LLVM Memory Optimization Constraints
5456 ============ ==============================================================
5459 acquire - If a load atomic/atomicrmw then no following load/load
5460 atomic/store/ store atomic/atomicrmw/fence instruction can
5461 be moved before the acquire.
5462 - If a fence then same as load atomic, plus no preceding
5463 associated fence-paired-atomic can be moved after the fence.
5464 release - If a store atomic/atomicrmw then no preceding load/load
5465 atomic/store/ store atomic/atomicrmw/fence instruction can
5466 be moved after the release.
5467 - If a fence then same as store atomic, plus no following
5468 associated fence-paired-atomic can be moved before the
5470 acq_rel Same constraints as both acquire and release.
5471 seq_cst - If a load atomic then same constraints as acquire, plus no
5472 preceding sequentially consistent load atomic/store
5473 atomic/atomicrmw/fence instruction can be moved after the
5475 - If a store atomic then the same constraints as release, plus
5476 no following sequentially consistent load atomic/store
5477 atomic/atomicrmw/fence instruction can be moved before the
5479 - If an atomicrmw/fence then same constraints as acq_rel.
5480 ============ ==============================================================
5485 For code objects generated by AMDGPU backend for HSA [HSA]_ compatible runtimes
5486 (such as ROCm [AMD-ROCm]_), the runtime installs a trap handler that supports
5487 the ``s_trap`` instruction with the following usage:
5489 .. table:: AMDGPU Trap Handler for AMDHSA OS
5490 :name: amdgpu-trap-handler-for-amdhsa-os-table
5492 =================== =============== =============== =======================
5493 Usage Code Sequence Trap Handler Description
5495 =================== =============== =============== =======================
5496 reserved ``s_trap 0x00`` Reserved by hardware.
5497 ``debugtrap(arg)`` ``s_trap 0x01`` ``SGPR0-1``: Reserved for HSA
5498 ``queue_ptr`` ``debugtrap``
5499 ``VGPR0``: intrinsic (not
5500 ``arg`` implemented).
5501 ``llvm.trap`` ``s_trap 0x02`` ``SGPR0-1``: Causes dispatch to be
5502 ``queue_ptr`` terminated and its
5503 associated queue put
5504 into the error state.
5505 ``llvm.debugtrap`` ``s_trap 0x03`` - If debugger not
5515 - If the debugger is
5517 the debug trap to be
5521 the halt state until
5524 reserved ``s_trap 0x04`` Reserved.
5525 reserved ``s_trap 0x05`` Reserved.
5526 reserved ``s_trap 0x06`` Reserved.
5527 debugger breakpoint ``s_trap 0x07`` Reserved for debugger
5529 reserved ``s_trap 0x08`` Reserved.
5530 reserved ``s_trap 0xfe`` Reserved.
5531 reserved ``s_trap 0xff`` Reserved.
5532 =================== =============== =============== =======================
5537 This section provides code conventions used when the target triple OS is
5538 ``amdpal`` (see :ref:`amdgpu-target-triples`) for passing runtime parameters
5539 from the application/runtime to each invocation of a hardware shader. These
5540 parameters include both generic, application-controlled parameters called
5541 *user data* as well as system-generated parameters that are a product of the
5542 draw or dispatch execution.
5547 Each hardware stage has a set of 32-bit *user data registers* which can be
5548 written from a command buffer and then loaded into SGPRs when waves are launched
5549 via a subsequent dispatch or draw operation. This is the way most arguments are
5550 passed from the application/runtime to a hardware shader.
5555 Compute shader user data mappings are simpler than graphics shaders, and have a
5558 Note that there are always 10 available *user data entries* in registers -
5559 entries beyond that limit must be fetched from memory (via the spill table
5560 pointer) by the shader.
5562 .. table:: PAL Compute Shader User Data Registers
5563 :name: pal-compute-user-data-registers
5565 ============= ================================
5566 User Register Description
5567 ============= ================================
5568 0 Global Internal Table (32-bit pointer)
5569 1 Per-Shader Internal Table (32-bit pointer)
5570 2 - 11 Application-Controlled User Data (10 32-bit values)
5571 12 Spill Table (32-bit pointer)
5572 13 - 14 Thread Group Count (64-bit pointer)
5574 ============= ================================
5579 Graphics pipelines support a much more flexible user data mapping:
5581 .. table:: PAL Graphics Shader User Data Registers
5582 :name: pal-graphics-user-data-registers
5584 ============= ================================
5585 User Register Description
5586 ============= ================================
5587 0 Global Internal Table (32-bit pointer)
5588 + Per-Shader Internal Table (32-bit pointer)
5589 + 1-15 Application Controlled User Data
5590 (1-15 Contiguous 32-bit Values in Registers)
5591 + Spill Table (32-bit pointer)
5592 + Draw Index (First Stage Only)
5593 + Vertex Offset (First Stage Only)
5594 + Instance Offset (First Stage Only)
5595 ============= ================================
5597 The placement of the global internal table remains fixed in the first *user
5598 data SGPR register*. Otherwise all parameters are optional, and can be mapped
5599 to any desired *user data SGPR register*, with the following regstrictions:
5601 * Draw Index, Vertex Offset, and Instance Offset can only be used by the first
5602 activehardware stage in a graphics pipeline (i.e. where the API vertex
5605 * Application-controlled user data must be mapped into a contiguous range of
5606 user data registers.
5608 * The application-controlled user data range supports compaction remapping, so
5609 only *entries* that are actually consumed by the shader must be assigned to
5610 corresponding *registers*. Note that in order to support an efficient runtime
5611 implementation, the remapping must pack *registers* in the same order as
5612 *entries*, with unused *entries* removed.
5614 .. _pal_global_internal_table:
5616 Global Internal Table
5617 ~~~~~~~~~~~~~~~~~~~~~
5619 The global internal table is a table of *shader resource descriptors* (SRDs) that
5620 define how certain engine-wide, runtime-managed resources should be accessed
5621 from a shader. The majority of these resources have HW-defined formats, and it
5622 is up to the compiler to write/read data as required by the target hardware.
5624 The following table illustrates the required format:
5626 .. table:: PAL Global Internal Table
5627 :name: pal-git-table
5629 ============= ================================
5631 ============= ================================
5632 0-3 Graphics Scratch SRD
5633 4-7 Compute Scratch SRD
5634 8-11 ES/GS Ring Output SRD
5635 12-15 ES/GS Ring Input SRD
5636 16-19 GS/VS Ring Output #0
5637 20-23 GS/VS Ring Output #1
5638 24-27 GS/VS Ring Output #2
5639 28-31 GS/VS Ring Output #3
5640 32-35 GS/VS Ring Input SRD
5641 36-39 Tessellation Factor Buffer SRD
5642 40-43 Off-Chip LDS Buffer SRD
5643 44-47 Off-Chip Param Cache Buffer SRD
5644 48-51 Sample Position Buffer SRD
5645 52 vaRange::ShadowDescriptorTable High Bits
5646 ============= ================================
5648 The pointer to the global internal table passed to the shader as user data
5649 is a 32-bit pointer. The top 32 bits should be assumed to be the same as
5650 the top 32 bits of the pipeline, so the shader may use the program
5651 counter's top 32 bits.
5656 This section provides code conventions used when the target triple OS is
5657 empty (see :ref:`amdgpu-target-triples`).
5662 For code objects generated by AMDGPU backend for non-amdhsa OS, the runtime does
5663 not install a trap handler. The ``llvm.trap`` and ``llvm.debugtrap``
5664 instructions are handled as follows:
5666 .. table:: AMDGPU Trap Handler for Non-AMDHSA OS
5667 :name: amdgpu-trap-handler-for-non-amdhsa-os-table
5669 =============== =============== ===========================================
5670 Usage Code Sequence Description
5671 =============== =============== ===========================================
5672 llvm.trap s_endpgm Causes wavefront to be terminated.
5673 llvm.debugtrap *none* Compiler warning given that there is no
5674 trap handler installed.
5675 =============== =============== ===========================================
5685 When the language is OpenCL the following differences occur:
5687 1. The OpenCL memory model is used (see :ref:`amdgpu-amdhsa-memory-model`).
5688 2. The AMDGPU backend appends additional arguments to the kernel's explicit
5689 arguments for the AMDHSA OS (see
5690 :ref:`opencl-kernel-implicit-arguments-appended-for-amdhsa-os-table`).
5691 3. Additional metadata is generated
5692 (see :ref:`amdgpu-amdhsa-code-object-metadata`).
5694 .. table:: OpenCL kernel implicit arguments appended for AMDHSA OS
5695 :name: opencl-kernel-implicit-arguments-appended-for-amdhsa-os-table
5697 ======== ==== ========= ===========================================
5698 Position Byte Byte Description
5700 ======== ==== ========= ===========================================
5701 1 8 8 OpenCL Global Offset X
5702 2 8 8 OpenCL Global Offset Y
5703 3 8 8 OpenCL Global Offset Z
5704 4 8 8 OpenCL address of printf buffer
5705 5 8 8 OpenCL address of virtual queue used by
5707 6 8 8 OpenCL address of AqlWrap struct used by
5709 7 8 8 Pointer argument used for Multi-gird
5711 ======== ==== ========= ===========================================
5718 When the language is HCC the following differences occur:
5720 1. The HSA memory model is used (see :ref:`amdgpu-amdhsa-memory-model`).
5722 .. _amdgpu-assembler:
5727 AMDGPU backend has LLVM-MC based assembler which is currently in development.
5728 It supports AMDGCN GFX6-GFX10.
5730 This section describes general syntax for instructions and operands.
5738 AMDGPU/AMDGPUAsmGFX7
5739 AMDGPU/AMDGPUAsmGFX8
5740 AMDGPU/AMDGPUAsmGFX9
5741 AMDGPU/AMDGPUAsmGFX10
5742 AMDGPUModifierSyntax
5744 AMDGPUInstructionSyntax
5745 AMDGPUInstructionNotation
5747 An instruction has the following :doc:`syntax<AMDGPUInstructionSyntax>`:
5749 ``<``\ *opcode*\ ``> <``\ *operand0*\ ``>, <``\ *operand1*\ ``>,... <``\ *modifier0*\ ``> <``\ *modifier1*\ ``>...``
5751 :doc:`Operands<AMDGPUOperandSyntax>` are normally comma-separated while
5752 :doc:`modifiers<AMDGPUModifierSyntax>` are space-separated.
5754 The order of *operands* and *modifiers* is fixed.
5755 Most *modifiers* are optional and may be omitted.
5757 See detailed instruction syntax description for :doc:`GFX7<AMDGPU/AMDGPUAsmGFX7>`,
5758 :doc:`GFX8<AMDGPU/AMDGPUAsmGFX8>`, :doc:`GFX9<AMDGPU/AMDGPUAsmGFX9>`
5759 and :doc:`GFX10<AMDGPU/AMDGPUAsmGFX10>`.
5761 Note that features under development are not included in this description.
5763 For more information about instructions, their semantics and supported combinations of
5764 operands, refer to one of instruction set architecture manuals
5765 [AMD-GCN-GFX6]_, [AMD-GCN-GFX7]_, [AMD-GCN-GFX8]_, [AMD-GCN-GFX9]_ and
5771 Detailed description of operands may be found :doc:`here<AMDGPUOperandSyntax>`.
5776 Detailed description of modifiers may be found :doc:`here<AMDGPUModifierSyntax>`.
5778 Instruction Examples
5779 ~~~~~~~~~~~~~~~~~~~~
5784 .. code-block:: nasm
5786 ds_add_u32 v2, v4 offset:16
5787 ds_write_src2_b64 v2 offset0:4 offset1:8
5788 ds_cmpst_f32 v2, v4, v6
5789 ds_min_rtn_f64 v[8:9], v2, v[4:5]
5792 For full list of supported instructions, refer to "LDS/GDS instructions" in ISA Manual.
5797 .. code-block:: nasm
5799 flat_load_dword v1, v[3:4]
5800 flat_store_dwordx3 v[3:4], v[5:7]
5801 flat_atomic_swap v1, v[3:4], v5 glc
5802 flat_atomic_cmpswap v1, v[3:4], v[5:6] glc slc
5803 flat_atomic_fmax_x2 v[1:2], v[3:4], v[5:6] glc
5805 For full list of supported instructions, refer to "FLAT instructions" in ISA Manual.
5810 .. code-block:: nasm
5812 buffer_load_dword v1, off, s[4:7], s1
5813 buffer_store_dwordx4 v[1:4], v2, ttmp[4:7], s1 offen offset:4 glc tfe
5814 buffer_store_format_xy v[1:2], off, s[4:7], s1
5816 buffer_atomic_inc v1, v2, s[8:11], s4 idxen offset:4 slc
5818 For full list of supported instructions, refer to "MUBUF Instructions" in ISA Manual.
5823 .. code-block:: nasm
5825 s_load_dword s1, s[2:3], 0xfc
5826 s_load_dwordx8 s[8:15], s[2:3], s4
5827 s_load_dwordx16 s[88:103], s[2:3], s4
5831 For full list of supported instructions, refer to "Scalar Memory Operations" in ISA Manual.
5836 .. code-block:: nasm
5839 s_mov_b64 s[0:1], 0x80000000
5841 s_wqm_b64 s[2:3], s[4:5]
5842 s_bcnt0_i32_b64 s1, s[2:3]
5843 s_swappc_b64 s[2:3], s[4:5]
5844 s_cbranch_join s[4:5]
5846 For full list of supported instructions, refer to "SOP1 Instructions" in ISA Manual.
5851 .. code-block:: nasm
5853 s_add_u32 s1, s2, s3
5854 s_and_b64 s[2:3], s[4:5], s[6:7]
5855 s_cselect_b32 s1, s2, s3
5856 s_andn2_b32 s2, s4, s6
5857 s_lshr_b64 s[2:3], s[4:5], s6
5858 s_ashr_i32 s2, s4, s6
5859 s_bfm_b64 s[2:3], s4, s6
5860 s_bfe_i64 s[2:3], s[4:5], s6
5861 s_cbranch_g_fork s[4:5], s[6:7]
5863 For full list of supported instructions, refer to "SOP2 Instructions" in ISA Manual.
5868 .. code-block:: nasm
5871 s_bitcmp1_b32 s1, s2
5872 s_bitcmp0_b64 s[2:3], s4
5875 For full list of supported instructions, refer to "SOPC Instructions" in ISA Manual.
5880 .. code-block:: nasm
5885 s_waitcnt 0 ; Wait for all counters to be 0
5886 s_waitcnt vmcnt(0) & expcnt(0) & lgkmcnt(0) ; Equivalent to above
5887 s_waitcnt vmcnt(1) ; Wait for vmcnt counter to be 1.
5891 s_sendmsg sendmsg(MSG_INTERRUPT)
5894 For full list of supported instructions, refer to "SOPP Instructions" in ISA Manual.
5896 Unless otherwise mentioned, little verification is performed on the operands
5897 of SOPP Instructions, so it is up to the programmer to be familiar with the
5898 range or acceptable values.
5903 For vector ALU instruction opcodes (VOP1, VOP2, VOP3, VOPC, VOP_DPP, VOP_SDWA),
5904 the assembler will automatically use optimal encoding based on its operands.
5905 To force specific encoding, one can add a suffix to the opcode of the instruction:
5907 * _e32 for 32-bit VOP1/VOP2/VOPC
5908 * _e64 for 64-bit VOP3
5910 * _sdwa for VOP_SDWA
5912 VOP1/VOP2/VOP3/VOPC examples:
5914 .. code-block:: nasm
5917 v_mov_b32_e32 v1, v2
5919 v_cvt_f64_i32_e32 v[1:2], v2
5920 v_floor_f32_e32 v1, v2
5921 v_bfrev_b32_e32 v1, v2
5922 v_add_f32_e32 v1, v2, v3
5923 v_mul_i32_i24_e64 v1, v2, 3
5924 v_mul_i32_i24_e32 v1, -3, v3
5925 v_mul_i32_i24_e32 v1, -100, v3
5926 v_addc_u32 v1, s[0:1], v2, v3, s[2:3]
5927 v_max_f16_e32 v1, v2, v3
5931 .. code-block:: nasm
5933 v_mov_b32 v0, v0 quad_perm:[0,2,1,1]
5934 v_sin_f32 v0, v0 row_shl:1 row_mask:0xa bank_mask:0x1 bound_ctrl:0
5935 v_mov_b32 v0, v0 wave_shl:1
5936 v_mov_b32 v0, v0 row_mirror
5937 v_mov_b32 v0, v0 row_bcast:31
5938 v_mov_b32 v0, v0 quad_perm:[1,3,0,1] row_mask:0xa bank_mask:0x1 bound_ctrl:0
5939 v_add_f32 v0, v0, |v0| row_shl:1 row_mask:0xa bank_mask:0x1 bound_ctrl:0
5940 v_max_f16 v1, v2, v3 row_shl:1 row_mask:0xa bank_mask:0x1 bound_ctrl:0
5944 .. code-block:: nasm
5946 v_mov_b32 v1, v2 dst_sel:BYTE_0 dst_unused:UNUSED_PRESERVE src0_sel:DWORD
5947 v_min_u32 v200, v200, v1 dst_sel:WORD_1 dst_unused:UNUSED_PAD src0_sel:BYTE_1 src1_sel:DWORD
5948 v_sin_f32 v0, v0 dst_unused:UNUSED_PAD src0_sel:WORD_1
5949 v_fract_f32 v0, |v0| dst_sel:DWORD dst_unused:UNUSED_PAD src0_sel:WORD_1
5950 v_cmpx_le_u32 vcc, v1, v2 src0_sel:BYTE_2 src1_sel:WORD_0
5952 For full list of supported instructions, refer to "Vector ALU instructions".
5955 Remove once we switch to code object v3 by default.
5957 .. _amdgpu-amdhsa-assembler-predefined-symbols-v2:
5959 Code Object V2 Predefined Symbols (-mattr=-code-object-v3)
5960 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5962 .. warning:: Code Object V2 is not the default code object version emitted by
5963 this version of LLVM. For a description of the predefined symbols available
5964 with the default configuration (Code Object V3) see
5965 :ref:`amdgpu-amdhsa-assembler-predefined-symbols-v3`.
5967 The AMDGPU assembler defines and updates some symbols automatically. These
5968 symbols do not affect code generation.
5970 .option.machine_version_major
5971 +++++++++++++++++++++++++++++
5973 Set to the GFX major generation number of the target being assembled for. For
5974 example, when assembling for a "GFX9" target this will be set to the integer
5975 value "9". The possible GFX major generation numbers are presented in
5976 :ref:`amdgpu-processors`.
5978 .option.machine_version_minor
5979 +++++++++++++++++++++++++++++
5981 Set to the GFX minor generation number of the target being assembled for. For
5982 example, when assembling for a "GFX810" target this will be set to the integer
5983 value "1". The possible GFX minor generation numbers are presented in
5984 :ref:`amdgpu-processors`.
5986 .option.machine_version_stepping
5987 ++++++++++++++++++++++++++++++++
5989 Set to the GFX stepping generation number of the target being assembled for.
5990 For example, when assembling for a "GFX704" target this will be set to the
5991 integer value "4". The possible GFX stepping generation numbers are presented
5992 in :ref:`amdgpu-processors`.
5997 Set to zero each time a
5998 :ref:`amdgpu-amdhsa-assembler-directive-amdgpu_hsa_kernel` directive is
5999 encountered. At each instruction, if the current value of this symbol is less
6000 than or equal to the maximum VPGR number explicitly referenced within that
6001 instruction then the symbol value is updated to equal that VGPR number plus
6007 Set to zero each time a
6008 :ref:`amdgpu-amdhsa-assembler-directive-amdgpu_hsa_kernel` directive is
6009 encountered. At each instruction, if the current value of this symbol is less
6010 than or equal to the maximum VPGR number explicitly referenced within that
6011 instruction then the symbol value is updated to equal that SGPR number plus
6014 .. _amdgpu-amdhsa-assembler-directives-v2:
6016 Code Object V2 Directives (-mattr=-code-object-v3)
6017 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
6019 .. warning:: Code Object V2 is not the default code object version emitted by
6020 this version of LLVM. For a description of the directives supported with
6021 the default configuration (Code Object V3) see
6022 :ref:`amdgpu-amdhsa-assembler-directives-v3`.
6024 AMDGPU ABI defines auxiliary data in output code object. In assembly source,
6025 one can specify them with assembler directives.
6027 .hsa_code_object_version major, minor
6028 +++++++++++++++++++++++++++++++++++++
6030 *major* and *minor* are integers that specify the version of the HSA code
6031 object that will be generated by the assembler.
6033 .hsa_code_object_isa [major, minor, stepping, vendor, arch]
6034 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
6037 *major*, *minor*, and *stepping* are all integers that describe the instruction
6038 set architecture (ISA) version of the assembly program.
6040 *vendor* and *arch* are quoted strings. *vendor* should always be equal to
6041 "AMD" and *arch* should always be equal to "AMDGPU".
6043 By default, the assembler will derive the ISA version, *vendor*, and *arch*
6044 from the value of the -mcpu option that is passed to the assembler.
6046 .. _amdgpu-amdhsa-assembler-directive-amdgpu_hsa_kernel:
6048 .amdgpu_hsa_kernel (name)
6049 +++++++++++++++++++++++++
6051 This directives specifies that the symbol with given name is a kernel entry point
6052 (label) and the object should contain corresponding symbol of type STT_AMDGPU_HSA_KERNEL.
6057 This directive marks the beginning of a list of key / value pairs that are used
6058 to specify the amd_kernel_code_t object that will be emitted by the assembler.
6059 The list must be terminated by the *.end_amd_kernel_code_t* directive. For
6060 any amd_kernel_code_t values that are unspecified a default value will be
6061 used. The default value for all keys is 0, with the following exceptions:
6063 - *amd_code_version_major* defaults to 1.
6064 - *amd_kernel_code_version_minor* defaults to 2.
6065 - *amd_machine_kind* defaults to 1.
6066 - *amd_machine_version_major*, *machine_version_minor*, and
6067 *amd_machine_version_stepping* are derived from the value of the -mcpu option
6068 that is passed to the assembler.
6069 - *kernel_code_entry_byte_offset* defaults to 256.
6070 - *wavefront_size* defaults 6 for all targets before GFX10. For GFX10 onwards
6071 defaults to 6 if target feature ``wavefrontsize64`` is enabled, otherwise 5.
6072 Note that wavefront size is specified as a power of two, so a value of **n**
6073 means a size of 2^ **n**.
6074 - *call_convention* defaults to -1.
6075 - *kernarg_segment_alignment*, *group_segment_alignment*, and
6076 *private_segment_alignment* default to 4. Note that alignments are specified
6077 as a power of 2, so a value of **n** means an alignment of 2^ **n**.
6078 - *enable_wgp_mode* defaults to 1 if target feature ``cumode`` is disabled for
6080 - *enable_mem_ordered* defaults to 1 for GFX10 onwards.
6082 The *.amd_kernel_code_t* directive must be placed immediately after the
6083 function label and before any instructions.
6085 For a full list of amd_kernel_code_t keys, refer to AMDGPU ABI document,
6086 comments in lib/Target/AMDGPU/AmdKernelCodeT.h and test/CodeGen/AMDGPU/hsa.s.
6088 .. _amdgpu-amdhsa-assembler-example-v2:
6090 Code Object V2 Example Source Code (-mattr=-code-object-v3)
6091 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
6093 .. warning:: Code Object V2 is not the default code object version emitted by
6094 this version of LLVM. For a description of the directives supported with
6095 the default configuration (Code Object V3) see
6096 :ref:`amdgpu-amdhsa-assembler-example-v3`.
6098 Here is an example of a minimal assembly source file, defining one HSA kernel:
6100 .. code-block:: none
6102 .hsa_code_object_version 1,0
6103 .hsa_code_object_isa
6108 .amdgpu_hsa_kernel hello_world
6113 enable_sgpr_kernarg_segment_ptr = 1
6115 compute_pgm_rsrc1_vgprs = 0
6116 compute_pgm_rsrc1_sgprs = 0
6117 compute_pgm_rsrc2_user_sgpr = 2
6118 compute_pgm_rsrc1_wgp_mode = 0
6119 compute_pgm_rsrc1_mem_ordered = 0
6120 compute_pgm_rsrc1_fwd_progress = 1
6121 .end_amd_kernel_code_t
6123 s_load_dwordx2 s[0:1], s[0:1] 0x0
6124 v_mov_b32 v0, 3.14159
6125 s_waitcnt lgkmcnt(0)
6128 flat_store_dword v[1:2], v0
6131 .size hello_world, .Lfunc_end0-hello_world
6133 .. _amdgpu-amdhsa-assembler-predefined-symbols-v3:
6135 Code Object V3 Predefined Symbols (-mattr=+code-object-v3)
6136 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
6138 The AMDGPU assembler defines and updates some symbols automatically. These
6139 symbols do not affect code generation.
6141 .amdgcn.gfx_generation_number
6142 +++++++++++++++++++++++++++++
6144 Set to the GFX major generation number of the target being assembled for. For
6145 example, when assembling for a "GFX9" target this will be set to the integer
6146 value "9". The possible GFX major generation numbers are presented in
6147 :ref:`amdgpu-processors`.
6149 .amdgcn.gfx_generation_minor
6150 ++++++++++++++++++++++++++++
6152 Set to the GFX minor generation number of the target being assembled for. For
6153 example, when assembling for a "GFX810" target this will be set to the integer
6154 value "1". The possible GFX minor generation numbers are presented in
6155 :ref:`amdgpu-processors`.
6157 .amdgcn.gfx_generation_stepping
6158 +++++++++++++++++++++++++++++++
6160 Set to the GFX stepping generation number of the target being assembled for.
6161 For example, when assembling for a "GFX704" target this will be set to the
6162 integer value "4". The possible GFX stepping generation numbers are presented
6163 in :ref:`amdgpu-processors`.
6165 .. _amdgpu-amdhsa-assembler-symbol-next_free_vgpr:
6167 .amdgcn.next_free_vgpr
6168 ++++++++++++++++++++++
6170 Set to zero before assembly begins. At each instruction, if the current value
6171 of this symbol is less than or equal to the maximum VGPR number explicitly
6172 referenced within that instruction then the symbol value is updated to equal
6173 that VGPR number plus one.
6175 May be used to set the `.amdhsa_next_free_vpgr` directive in
6176 :ref:`amdhsa-kernel-directives-table`.
6178 May be set at any time, e.g. manually set to zero at the start of each kernel.
6180 .. _amdgpu-amdhsa-assembler-symbol-next_free_sgpr:
6182 .amdgcn.next_free_sgpr
6183 ++++++++++++++++++++++
6185 Set to zero before assembly begins. At each instruction, if the current value
6186 of this symbol is less than or equal the maximum SGPR number explicitly
6187 referenced within that instruction then the symbol value is updated to equal
6188 that SGPR number plus one.
6190 May be used to set the `.amdhsa_next_free_spgr` directive in
6191 :ref:`amdhsa-kernel-directives-table`.
6193 May be set at any time, e.g. manually set to zero at the start of each kernel.
6195 .. _amdgpu-amdhsa-assembler-directives-v3:
6197 Code Object V3 Directives (-mattr=+code-object-v3)
6198 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
6200 Directives which begin with ``.amdgcn`` are valid for all ``amdgcn``
6201 architecture processors, and are not OS-specific. Directives which begin with
6202 ``.amdhsa`` are specific to ``amdgcn`` architecture processors when the
6203 ``amdhsa`` OS is specified. See :ref:`amdgpu-target-triples` and
6204 :ref:`amdgpu-processors`.
6206 .amdgcn_target <target>
6207 +++++++++++++++++++++++
6209 Optional directive which declares the target supported by the containing
6210 assembler source file. Valid values are described in
6211 :ref:`amdgpu-amdhsa-code-object-target-identification`. Used by the assembler
6212 to validate command-line options such as ``-triple``, ``-mcpu``, and those
6213 which specify target features.
6215 .amdhsa_kernel <name>
6216 +++++++++++++++++++++
6218 Creates a correctly aligned AMDHSA kernel descriptor and a symbol,
6219 ``<name>.kd``, in the current location of the current section. Only valid when
6220 the OS is ``amdhsa``. ``<name>`` must be a symbol that labels the first
6221 instruction to execute, and does not need to be previously defined.
6223 Marks the beginning of a list of directives used to generate the bytes of a
6224 kernel descriptor, as described in :ref:`amdgpu-amdhsa-kernel-descriptor`.
6225 Directives which may appear in this list are described in
6226 :ref:`amdhsa-kernel-directives-table`. Directives may appear in any order, must
6227 be valid for the target being assembled for, and cannot be repeated. Directives
6228 support the range of values specified by the field they reference in
6229 :ref:`amdgpu-amdhsa-kernel-descriptor`. If a directive is not specified, it is
6230 assumed to have its default value, unless it is marked as "Required", in which
6231 case it is an error to omit the directive. This list of directives is
6232 terminated by an ``.end_amdhsa_kernel`` directive.
6234 .. table:: AMDHSA Kernel Assembler Directives
6235 :name: amdhsa-kernel-directives-table
6237 ======================================================== =================== ============ ===================
6238 Directive Default Supported On Description
6239 ======================================================== =================== ============ ===================
6240 ``.amdhsa_group_segment_fixed_size`` 0 GFX6-GFX10 Controls GROUP_SEGMENT_FIXED_SIZE in
6241 :ref:`amdgpu-amdhsa-kernel-descriptor-gfx6-gfx10-table`.
6242 ``.amdhsa_private_segment_fixed_size`` 0 GFX6-GFX10 Controls PRIVATE_SEGMENT_FIXED_SIZE in
6243 :ref:`amdgpu-amdhsa-kernel-descriptor-gfx6-gfx10-table`.
6244 ``.amdhsa_user_sgpr_private_segment_buffer`` 0 GFX6-GFX10 Controls ENABLE_SGPR_PRIVATE_SEGMENT_BUFFER in
6245 :ref:`amdgpu-amdhsa-kernel-descriptor-gfx6-gfx10-table`.
6246 ``.amdhsa_user_sgpr_dispatch_ptr`` 0 GFX6-GFX10 Controls ENABLE_SGPR_DISPATCH_PTR in
6247 :ref:`amdgpu-amdhsa-kernel-descriptor-gfx6-gfx10-table`.
6248 ``.amdhsa_user_sgpr_queue_ptr`` 0 GFX6-GFX10 Controls ENABLE_SGPR_QUEUE_PTR in
6249 :ref:`amdgpu-amdhsa-kernel-descriptor-gfx6-gfx10-table`.
6250 ``.amdhsa_user_sgpr_kernarg_segment_ptr`` 0 GFX6-GFX10 Controls ENABLE_SGPR_KERNARG_SEGMENT_PTR in
6251 :ref:`amdgpu-amdhsa-kernel-descriptor-gfx6-gfx10-table`.
6252 ``.amdhsa_user_sgpr_dispatch_id`` 0 GFX6-GFX10 Controls ENABLE_SGPR_DISPATCH_ID in
6253 :ref:`amdgpu-amdhsa-kernel-descriptor-gfx6-gfx10-table`.
6254 ``.amdhsa_user_sgpr_flat_scratch_init`` 0 GFX6-GFX10 Controls ENABLE_SGPR_FLAT_SCRATCH_INIT in
6255 :ref:`amdgpu-amdhsa-kernel-descriptor-gfx6-gfx10-table`.
6256 ``.amdhsa_user_sgpr_private_segment_size`` 0 GFX6-GFX10 Controls ENABLE_SGPR_PRIVATE_SEGMENT_SIZE in
6257 :ref:`amdgpu-amdhsa-kernel-descriptor-gfx6-gfx10-table`.
6258 ``.amdhsa_wavefront_size32`` Target GFX10 Controls ENABLE_WAVEFRONT_SIZE32 in
6259 Feature :ref:`amdgpu-amdhsa-kernel-descriptor-gfx6-gfx10-table`.
6262 ``.amdhsa_system_sgpr_private_segment_wavefront_offset`` 0 GFX6-GFX10 Controls ENABLE_SGPR_PRIVATE_SEGMENT_WAVEFRONT_OFFSET in
6263 :ref:`amdgpu-amdhsa-compute_pgm_rsrc2-gfx6-gfx10-table`.
6264 ``.amdhsa_system_sgpr_workgroup_id_x`` 1 GFX6-GFX10 Controls ENABLE_SGPR_WORKGROUP_ID_X in
6265 :ref:`amdgpu-amdhsa-compute_pgm_rsrc2-gfx6-gfx10-table`.
6266 ``.amdhsa_system_sgpr_workgroup_id_y`` 0 GFX6-GFX10 Controls ENABLE_SGPR_WORKGROUP_ID_Y in
6267 :ref:`amdgpu-amdhsa-compute_pgm_rsrc2-gfx6-gfx10-table`.
6268 ``.amdhsa_system_sgpr_workgroup_id_z`` 0 GFX6-GFX10 Controls ENABLE_SGPR_WORKGROUP_ID_Z in
6269 :ref:`amdgpu-amdhsa-compute_pgm_rsrc2-gfx6-gfx10-table`.
6270 ``.amdhsa_system_sgpr_workgroup_info`` 0 GFX6-GFX10 Controls ENABLE_SGPR_WORKGROUP_INFO in
6271 :ref:`amdgpu-amdhsa-compute_pgm_rsrc2-gfx6-gfx10-table`.
6272 ``.amdhsa_system_vgpr_workitem_id`` 0 GFX6-GFX10 Controls ENABLE_VGPR_WORKITEM_ID in
6273 :ref:`amdgpu-amdhsa-compute_pgm_rsrc2-gfx6-gfx10-table`.
6274 Possible values are defined in
6275 :ref:`amdgpu-amdhsa-system-vgpr-work-item-id-enumeration-values-table`.
6276 ``.amdhsa_next_free_vgpr`` Required GFX6-GFX10 Maximum VGPR number explicitly referenced, plus one.
6277 Used to calculate GRANULATED_WORKITEM_VGPR_COUNT in
6278 :ref:`amdgpu-amdhsa-compute_pgm_rsrc1-gfx6-gfx10-table`.
6279 ``.amdhsa_next_free_sgpr`` Required GFX6-GFX10 Maximum SGPR number explicitly referenced, plus one.
6280 Used to calculate GRANULATED_WAVEFRONT_SGPR_COUNT in
6281 :ref:`amdgpu-amdhsa-compute_pgm_rsrc1-gfx6-gfx10-table`.
6282 ``.amdhsa_reserve_vcc`` 1 GFX6-GFX10 Whether the kernel may use the special VCC SGPR.
6283 Used to calculate GRANULATED_WAVEFRONT_SGPR_COUNT in
6284 :ref:`amdgpu-amdhsa-compute_pgm_rsrc1-gfx6-gfx10-table`.
6285 ``.amdhsa_reserve_flat_scratch`` 1 GFX7-GFX10 Whether the kernel may use flat instructions to access
6286 scratch memory. Used to calculate
6287 GRANULATED_WAVEFRONT_SGPR_COUNT in
6288 :ref:`amdgpu-amdhsa-compute_pgm_rsrc1-gfx6-gfx10-table`.
6289 ``.amdhsa_reserve_xnack_mask`` Target GFX8-GFX10 Whether the kernel may trigger XNACK replay.
6290 Feature Used to calculate GRANULATED_WAVEFRONT_SGPR_COUNT in
6291 Specific :ref:`amdgpu-amdhsa-compute_pgm_rsrc1-gfx6-gfx10-table`.
6293 ``.amdhsa_float_round_mode_32`` 0 GFX6-GFX10 Controls FLOAT_ROUND_MODE_32 in
6294 :ref:`amdgpu-amdhsa-compute_pgm_rsrc1-gfx6-gfx10-table`.
6295 Possible values are defined in
6296 :ref:`amdgpu-amdhsa-floating-point-rounding-mode-enumeration-values-table`.
6297 ``.amdhsa_float_round_mode_16_64`` 0 GFX6-GFX10 Controls FLOAT_ROUND_MODE_16_64 in
6298 :ref:`amdgpu-amdhsa-compute_pgm_rsrc1-gfx6-gfx10-table`.
6299 Possible values are defined in
6300 :ref:`amdgpu-amdhsa-floating-point-rounding-mode-enumeration-values-table`.
6301 ``.amdhsa_float_denorm_mode_32`` 0 GFX6-GFX10 Controls FLOAT_DENORM_MODE_32 in
6302 :ref:`amdgpu-amdhsa-compute_pgm_rsrc1-gfx6-gfx10-table`.
6303 Possible values are defined in
6304 :ref:`amdgpu-amdhsa-floating-point-denorm-mode-enumeration-values-table`.
6305 ``.amdhsa_float_denorm_mode_16_64`` 3 GFX6-GFX10 Controls FLOAT_DENORM_MODE_16_64 in
6306 :ref:`amdgpu-amdhsa-compute_pgm_rsrc1-gfx6-gfx10-table`.
6307 Possible values are defined in
6308 :ref:`amdgpu-amdhsa-floating-point-denorm-mode-enumeration-values-table`.
6309 ``.amdhsa_dx10_clamp`` 1 GFX6-GFX10 Controls ENABLE_DX10_CLAMP in
6310 :ref:`amdgpu-amdhsa-compute_pgm_rsrc1-gfx6-gfx10-table`.
6311 ``.amdhsa_ieee_mode`` 1 GFX6-GFX10 Controls ENABLE_IEEE_MODE in
6312 :ref:`amdgpu-amdhsa-compute_pgm_rsrc1-gfx6-gfx10-table`.
6313 ``.amdhsa_fp16_overflow`` 0 GFX9-GFX10 Controls FP16_OVFL in
6314 :ref:`amdgpu-amdhsa-compute_pgm_rsrc1-gfx6-gfx10-table`.
6315 ``.amdhsa_workgroup_processor_mode`` Target GFX10 Controls ENABLE_WGP_MODE in
6316 Feature :ref:`amdgpu-amdhsa-kernel-descriptor-gfx6-gfx10-table`.
6319 ``.amdhsa_memory_ordered`` 1 GFX10 Controls MEM_ORDERED in
6320 :ref:`amdgpu-amdhsa-compute_pgm_rsrc1-gfx6-gfx10-table`.
6321 ``.amdhsa_forward_progress`` 0 GFX10 Controls FWD_PROGRESS in
6322 :ref:`amdgpu-amdhsa-compute_pgm_rsrc1-gfx6-gfx10-table`.
6323 ``.amdhsa_exception_fp_ieee_invalid_op`` 0 GFX6-GFX10 Controls ENABLE_EXCEPTION_IEEE_754_FP_INVALID_OPERATION in
6324 :ref:`amdgpu-amdhsa-compute_pgm_rsrc2-gfx6-gfx10-table`.
6325 ``.amdhsa_exception_fp_denorm_src`` 0 GFX6-GFX10 Controls ENABLE_EXCEPTION_FP_DENORMAL_SOURCE in
6326 :ref:`amdgpu-amdhsa-compute_pgm_rsrc2-gfx6-gfx10-table`.
6327 ``.amdhsa_exception_fp_ieee_div_zero`` 0 GFX6-GFX10 Controls ENABLE_EXCEPTION_IEEE_754_FP_DIVISION_BY_ZERO in
6328 :ref:`amdgpu-amdhsa-compute_pgm_rsrc2-gfx6-gfx10-table`.
6329 ``.amdhsa_exception_fp_ieee_overflow`` 0 GFX6-GFX10 Controls ENABLE_EXCEPTION_IEEE_754_FP_OVERFLOW in
6330 :ref:`amdgpu-amdhsa-compute_pgm_rsrc2-gfx6-gfx10-table`.
6331 ``.amdhsa_exception_fp_ieee_underflow`` 0 GFX6-GFX10 Controls ENABLE_EXCEPTION_IEEE_754_FP_UNDERFLOW in
6332 :ref:`amdgpu-amdhsa-compute_pgm_rsrc2-gfx6-gfx10-table`.
6333 ``.amdhsa_exception_fp_ieee_inexact`` 0 GFX6-GFX10 Controls ENABLE_EXCEPTION_IEEE_754_FP_INEXACT in
6334 :ref:`amdgpu-amdhsa-compute_pgm_rsrc2-gfx6-gfx10-table`.
6335 ``.amdhsa_exception_int_div_zero`` 0 GFX6-GFX10 Controls ENABLE_EXCEPTION_INT_DIVIDE_BY_ZERO in
6336 :ref:`amdgpu-amdhsa-compute_pgm_rsrc2-gfx6-gfx10-table`.
6337 ======================================================== =================== ============ ===================
6342 Optional directive which declares the contents of the ``NT_AMDGPU_METADATA``
6343 note record (see :ref:`amdgpu-elf-note-records-table-v3`).
6345 The contents must be in the [YAML]_ markup format, with the same structure and
6346 semantics described in :ref:`amdgpu-amdhsa-code-object-metadata-v3`.
6348 This directive is terminated by an ``.end_amdgpu_metadata`` directive.
6350 .. _amdgpu-amdhsa-assembler-example-v3:
6352 Code Object V3 Example Source Code (-mattr=+code-object-v3)
6353 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
6355 Here is an example of a minimal assembly source file, defining one HSA kernel:
6357 .. code-block:: none
6359 .amdgcn_target "amdgcn-amd-amdhsa--gfx900+xnack" // optional
6364 .type hello_world,@function
6366 s_load_dwordx2 s[0:1], s[0:1] 0x0
6367 v_mov_b32 v0, 3.14159
6368 s_waitcnt lgkmcnt(0)
6371 flat_store_dword v[1:2], v0
6374 .size hello_world, .Lfunc_end0-hello_world
6378 .amdhsa_kernel hello_world
6379 .amdhsa_user_sgpr_kernarg_segment_ptr 1
6380 .amdhsa_next_free_vgpr .amdgcn.next_free_vgpr
6381 .amdhsa_next_free_sgpr .amdgcn.next_free_sgpr
6390 - .name: hello_world
6391 .symbol: hello_world.kd
6392 .kernarg_segment_size: 48
6393 .group_segment_fixed_size: 0
6394 .private_segment_fixed_size: 0
6395 .kernarg_segment_align: 4
6399 .max_flat_workgroup_size: 256
6401 .end_amdgpu_metadata
6403 If an assembly source file contains multiple kernels and/or functions, the
6404 :ref:`amdgpu-amdhsa-assembler-symbol-next_free_vgpr` and
6405 :ref:`amdgpu-amdhsa-assembler-symbol-next_free_sgpr` symbols may be reset using
6406 the ``.set <symbol>, <expression>`` directive. For example, in the case of two
6407 kernels, where ``function1`` is only called from ``kernel1`` it is sufficient
6408 to group the function with the kernel that calls it and reset the symbols
6409 between the two connected components:
6411 .. code-block:: none
6413 .amdgcn_target "amdgcn-amd-amdhsa--gfx900+xnack" // optional
6415 // gpr tracking symbols are implicitly set to zero
6420 .type kern0,@function
6425 .size kern0, .Lkern0_end-kern0
6429 .amdhsa_kernel kern0
6431 .amdhsa_next_free_vgpr .amdgcn.next_free_vgpr
6432 .amdhsa_next_free_sgpr .amdgcn.next_free_sgpr
6435 // reset symbols to begin tracking usage in func1 and kern1
6436 .set .amdgcn.next_free_vgpr, 0
6437 .set .amdgcn.next_free_sgpr, 0
6443 .type func1,@function
6446 s_setpc_b64 s[30:31]
6448 .size func1, .Lfunc1_end-func1
6452 .type kern1,@function
6456 s_add_u32 s4, s4, func1@rel32@lo+4
6457 s_addc_u32 s5, s5, func1@rel32@lo+4
6458 s_swappc_b64 s[30:31], s[4:5]
6462 .size kern1, .Lkern1_end-kern1
6466 .amdhsa_kernel kern1
6468 .amdhsa_next_free_vgpr .amdgcn.next_free_vgpr
6469 .amdhsa_next_free_sgpr .amdgcn.next_free_sgpr
6472 These symbols cannot identify connected components in order to automatically
6473 track the usage for each kernel. However, in some cases careful organization of
6474 the kernels and functions in the source file means there is minimal additional
6475 effort required to accurately calculate GPR usage.
6477 Additional Documentation
6478 ========================
6480 .. [AMD-RADEON-HD-2000-3000] `AMD R6xx shader ISA <http://developer.amd.com/wordpress/media/2012/10/R600_Instruction_Set_Architecture.pdf>`__
6481 .. [AMD-RADEON-HD-4000] `AMD R7xx shader ISA <http://developer.amd.com/wordpress/media/2012/10/R700-Family_Instruction_Set_Architecture.pdf>`__
6482 .. [AMD-RADEON-HD-5000] `AMD Evergreen shader ISA <http://developer.amd.com/wordpress/media/2012/10/AMD_Evergreen-Family_Instruction_Set_Architecture.pdf>`__
6483 .. [AMD-RADEON-HD-6000] `AMD Cayman/Trinity shader ISA <http://developer.amd.com/wordpress/media/2012/10/AMD_HD_6900_Series_Instruction_Set_Architecture.pdf>`__
6484 .. [AMD-GCN-GFX6] `AMD Southern Islands Series ISA <http://developer.amd.com/wordpress/media/2012/12/AMD_Southern_Islands_Instruction_Set_Architecture.pdf>`__
6485 .. [AMD-GCN-GFX7] `AMD Sea Islands Series ISA <http://developer.amd.com/wordpress/media/2013/07/AMD_Sea_Islands_Instruction_Set_Architecture.pdf>`_
6486 .. [AMD-GCN-GFX8] `AMD GCN3 Instruction Set Architecture <http://amd-dev.wpengine.netdna-cdn.com/wordpress/media/2013/12/AMD_GCN3_Instruction_Set_Architecture_rev1.1.pdf>`__
6487 .. [AMD-GCN-GFX9] `AMD "Vega" Instruction Set Architecture <http://developer.amd.com/wordpress/media/2013/12/Vega_Shader_ISA_28July2017.pdf>`__
6488 .. [AMD-GCN-GFX10] AMD "Navi" Instruction Set Architecture *TBA*
6490 ttye Add link when made public.
6491 .. [AMD-ROCm] `ROCm: Open Platform for Development, Discovery and Education Around GPU Computing <http://gpuopen.com/compute-product/rocm/>`__
6492 .. [AMD-ROCm-github] `ROCm github <http://github.com/RadeonOpenCompute>`__
6493 .. [HSA] `Heterogeneous System Architecture (HSA) Foundation <http://www.hsafoundation.com/>`__
6494 .. [ELF] `Executable and Linkable Format (ELF) <http://www.sco.com/developers/gabi/>`__
6495 .. [DWARF] `DWARF Debugging Information Format <http://dwarfstd.org/>`__
6496 .. [YAML] `YAML Ain't Markup Language (YAML™) Version 1.2 <http://www.yaml.org/spec/1.2/spec.html>`__
6497 .. [MsgPack] `Message Pack <http://www.msgpack.org/>`__
6498 .. [OpenCL] `The OpenCL Specification Version 2.0 <http://www.khronos.org/registry/cl/specs/opencl-2.0.pdf>`__
6499 .. [HRF] `Heterogeneous-race-free Memory Models <http://benedictgaster.org/wp-content/uploads/2014/01/asplos269-FINAL.pdf>`__
6500 .. [CLANG-ATTR] `Attributes in Clang <http://clang.llvm.org/docs/AttributeReference.html>`__
OSDN Git Service
