AMDGPU : Update AMDGPU Trap Handler ABI.

[wdng]

Summary

AMDGPU : Update AMDGPU Trap Handler ABI.

[wdng]

Upload a full diff.

[wdng]

Ping.

[wdng]

This comment was removed by wdng.

[arsenm]

docs/AMDGPUUsage.rst

288–289

" OS is obtained from the appropriate element of the target triple HSA OS" is redundant and confusing. HSA is the OS component of the triple

288–289

Just HSA?

290

s/always enabled/enabled by default/. S_TRAP should be lowercase. More precise would be to say it emits s_trap for llvm.trap/llvm.debugtrap

[tony-tye]

docs/AMDGPUUsage.rst

288–289

Move this section up to after the address space section rather than in the middle of the sections that describe the assembler usage.

288–289

Why is this here? It is not related to the OS values of the target triple.

288–289

This would probably be better formatted as a table. Perhaps a column for "Trap Code", a column for "Name", a column for "Trap Handler Inputs", and a column for "Description".

288–289

This is not the name of a target triple OS. Suggest using a section name such as "Non-HSA OS" or "Other OSs".

288–289

Or HSA OS?

290

I think the runtime trap handler supports the s_trap instruction with the following codes. Currently the compiler only generates two of the codes, but the trap handler ABI nevertheless defines all 4 codes.

[wdng]

Modify texts based on reviews.

[arsenm]

docs/AMDGPUUsage.rst

58

Lowercase instruction names. I'm not sure it's worth mentioning the non-HSA path since it isn't really implemented or used

[tony-tye]

docs/AMDGPUUsage.rst

36–59

How about using the following for this section:

Trap Handler ABI
----------------
The OS element of the target triple controls the trap handler behavior.

HSA OS
^^^^^^
For code objects generated by AMDGPU back-end for the HSA OS, the runtime installs a trap handler that supports the s_trap instruction with the following usage:

   ======================== ============= ========================== ===================
   Usage                    Code Sequence Trap Handler Inputs        Description
   ======================== ============= ========================== ===================
   debugger breakpoint      s_trap 0                                 If debugger is not installed causes dispatch to be terminated and its associated queue put into the error state.
   llvm.trap                s_trap 1      SGPR0-1: queue_ptr         Causes dispatch to be terminated and its associated queue put into the error state.
   llvm.debugtrap           s_trap 2      SGPR0-1: queue_ptr         If debugger not installed handled same as llvm.trap.
   HSA debugtrap(user_code) s_trap 3      SGPR0-1: queue_ptr         Used for HSA debugtrap intrinsic (not implemented).
                                          VGPR0: user code
   ======================== ============= ========================== ===================

Non-HSA OS
^^^^^^^^^^
For code objects generated by AMDGPU back-end for non-HSA OS, the runtime does not install a trap handler. The llvm.trap and llvm.debugtrap instructions are handler as follows:

   ======================== ============= ==========================
   Usage                    Code Sequence Description
   ======================== ============= ==========================
   llvm.trap                s_endpgm      Causes wavefront to be terminated.
   llvm.debugtrap           s_nop         No operation. Warning generated that there is no trap handler installed.
   ======================== ============= ==========================

58

The non-HSA path does seem to be implemented and will behave as described, so seems reasonable to document it since we are documenting the HSA path.

[kzhuravl]

docs/AMDGPUUsage.rst

36–59

Make sure it is 80 cols long too.

[kzhuravl]

docs/AMDGPUUsage.rst

36–59

Make sure it is 80 cols long too. -> Make sure it is not longer than 80 columns.

[tony-tye]

docs/AMDGPUUsage.rst

36–59

On checking it appears that the trap id codes need correcting to the following, with a corresponding change in the llvm.trap and llvm.debugtrap implementation:

======================== ============= ========================== ===================
Usage                    Code Sequence Trap Handler Inputs        Description
======================== ============= ========================== ===================
reserved                 s_trap 0x00                              Reserved by hardware.
HSA debugtrap(arg)       s_trap 0x01   SGPR0-1: queue_ptr         Reserved for HSA debugtrap intrinsic (not implemented).
                                       VGPR0: arg
llvm.trap                s_trap 0x02   SGPR0-1: queue_ptr         Causes dispatch to be terminated and its associated queue put into the error state.
llvm.debugtrap           s_trap 0x03   SGPR0-1: queue_ptr         If debugger not installed handled same as llvm.trap.
debugger breakpoint      s_trap 0x07                              Reserved for debugger breakpoints.
debugger                 s_trap 0x08                              Reserved for debugger.  
debugger                 s_trap 0xfe                              Reserved for debugger.  
debugger                 s_trap 0xff                              Reserved for debugger.  
======================== ============= ========================== ===================

[tony-tye]

docs/AMDGPUUsage.rst

36–60

Here is text suggestion limited to 80 cols:

Trap Handler ABI
----------------
The OS element of the target triple controls the trap handler behavior.

HSA OS
^^^^^^
For code objects generated by AMDGPU back-end for the HSA OS, the runtime
installs a trap handler that supports the s_trap instruction with the following
usage:

 +--------------+-------------+-------------------+----------------------------+
 |Usage         |Code Sequence|Trap Handler Inputs|Description                 |
 +==============+=============+===================+============================+
 |reserved      |s_trap 0x00  |                   |Reserved by hardware.       |
 +--------------+-------------+-------------------+----------------------------+
 |HSA debugtrap |s_trap 0x01  |SGPR0-1: queue_ptr |Reserved for HSA debugtrap  |
 |(arg)         |             |VGPR0: arg         |intrinsic (not implemented).|
 +--------------+-------------+-------------------+----------------------------+
 |llvm.trap     |s_trap 0x02  |SGPR0-1: queue_ptr |Causes dispatch to be       |
 |              |             |                   |terminated and its          |
 |              |             |                   |associated queue put into   |
 |              |             |                   |the error state.            |
 +--------------+-------------+-------------------+----------------------------+
 |llvm.debugtrap| s_trap 0x03 |SGPR0-1: queue_ptr |If debugger not installed   |
 |              |             |                   |handled same as llvm.trap.  |
 +--------------+-------------+-------------------+----------------------------+
 |debugger      |s_trap 0x07  |                   |Reserved for debugger       |
 |breakpoint    |             |                   |breakpoints.                |
 +--------------+-------------+-------------------+----------------------------+
 |debugger      |s_trap 0x08  |                   |Reserved for debugger.      |
 +--------------+-------------+-------------------+----------------------------+
 |debugger      |s_trap 0xfe  |                   |Reserved for debugger.      |
 +--------------+-------------+-------------------+----------------------------+
 |debugger      |s_trap 0xff  |                   |Reserved for debugger.      |
 +--------------+-------------+-------------------+----------------------------+

Non-HSA OS
^^^^^^^^^^
For code objects generated by AMDGPU back-end for non-HSA OS, the runtime does
not install a trap handler. The llvm.trap and llvm.debugtrap instructions are
handler as follows:

   =============== ============= ===============================================
   Usage           Code Sequence Description
   =============== ============= ===============================================
   llvm.trap       s_endpgm      Causes wavefront to be terminated.
   llvm.debugtrap  s_nop         No operation. Compiler warning generated that
                                 there is no trap handler installed.
   =============== ============= ===============================================

Non-HSA OS
^^^^^^^^^^
For code objects generated by AMDGPU back-end for non-HSA OS, the runtime does
not install a trap handler. The llvm.trap and llvm.debugtrap instructions are
handler as follows:

   =============== ============= ===============================================
   Usage           Code Sequence Description
   =============== ============= ===============================================
   llvm.trap       s_endpgm      Causes wavefront to be terminated.
   llvm.debugtrap  s_nop         No operation. Compiler warning generated that
                                 there is no trap handler installed.
   =============== ============= ===============================================

[wdng]

Modification based on Tony's suggestion.

[tony-tye]

LGTM

docs/AMDGPUUsage.rst

The AMDGPU back-end uses the following address space mapping:
    3             Local
    4             Generic (Flat)
    5             Region
    ============= ============================================
 
 The terminology in the table, aside from the region memory space, is from the
 OpenCL standard.
 
+Trap Handler ABI
+----------------
+The OS element of the target triple controls the trap handler behavior.
+
+HSA OS
+^^^^^^
+For the HSA OS, the AMDGPU back-end emits s_trap for llvm.trap/llvm.debugtrap.
+Runtime trap handler supports the s_trap instruction with the following codes.
+Currently the compiler only generates two of the codes, but the trap handler
+ABI nevertheless defines all 4 codes.
+
+   ===================== ============= ============================================
+   Name                  Trap Code     Trap Handler Inputs
+   ===================== ============= ============================================
+   TrapCodeBreakPoint    0             Used for debugger breakpoint. If debugger is not installed causes dispatch to be terminated and its associated queue put into the error state.
+   TrapCodeLLVMTrap      1             Used for llvm.trap..queue_ptr is in SGPR0-1. Causes dispatch to be terminated and its associated queue put into the error state.
+   TrapCodeLLVMDebugTrap 2             Used for llvm.debugtrap. queue_ptr is in SGPR0-1. If debugger not installed handled same as llvm.trap.
+   TrapCodeHSADebugTrap  3             Used for HSA DEBUGTRAP. queue_ptr is in SGPR0-1, the user code is in VGPR0.
+   ===================== ============= ============================================
+
+Non-HSA OS
+^^^^^^^^^^
+For Graphics, S_ENDPGM is generated for llvm.trap. S_NOP is generated for
+llvm.debugtrap together with a warning that there is no trap handler installed.
+
 
 Assembler
 =========
 
 AMDGPU backend has LLVM-MC based assembler which is currently in development.
 It supports Southern Islands ISA, Sea Islands and Volcanic Islands.
 
 This document describes general syntax for instructions and operands. For more
.. code-block:: nasm
 
   v_mov_b32 v1, v2 dst_sel:BYTE_0 dst_unused:UNUSED_PRESERVE src0_sel:DWORD
   v_min_u32 v200, v200, v1 dst_sel:WORD_1 dst_unused:UNUSED_PAD src0_sel:BYTE_1 src1_sel:DWORD
   v_sin_f32 v0, v0 dst_unused:UNUSED_PAD src0_sel:WORD_1
   v_fract_f32 v0, |v0| dst_sel:DWORD dst_unused:UNUSED_PAD src0_sel:WORD_1
   v_cmpx_le_u32 vcc, v1, v2 src0_sel:BYTE_2 src1_sel:WORD_0
 
 For full list of supported instructions, refer to "Vector ALU instructions".
 
-Trap Handler ABI
-----------------
-The Trap Handler suppored is implemented differently based on the host OS. OS
-is obtained from the appropriate element of the target triple HSA OS:
-
-.. code-block:: c++
-
-  enum TrapHandlerAbi {
-    TrapHandlerAbiNone = 0,
-    TrapHandlerAbiHsa = 1
-  };
-
-  TrapHandlerAbi getTrapHandlerAbi() const {
-    return isAmdHsaOS() ? TrapHandlerAbiHsa : TrapHandlerAbiNone;
-  }
-
-For HSA OS, a trap handler is always enabled and that the following S_TRAP immediate
-operand codes are supported:
-
-.. code-block:: c++
-
-  enum TrapCode {
-    TrapCodeBreakPoint = 0,
-    TrapCodeLLVMTrap = 1,
-    TrapCodeLLVMDebugTrap = 2,
-    TrapCodeHSADebugTrap = 3
-  };
-
-- 0: Used for debugger breakpoint. If debugger is not installed causes dispatch
-  to be terminated and its associated queue put into the error state.
-- 1: Used for llvm.trap..queue_ptr is in SGPR0-1. Causes dispatch to be
-  terminated and its associated queue put into the error state.
-- 2: Used for llvm.debugtrap. queue_ptr is in SGPR0-1. If debugger not installed
-  handled same as llvm.trap.
-- 3: Used for HSA DEBUGTRAP. queue_ptr is in SGPR0-1, the user code is in VGPR0.
-
-Graphics
-^^^^^^^^
-For Graphics, S_ENDPGM is generated for llvm.trap. S_NOP is generated for
-llvm.debugtrap together with a warning that there is no trap handler installed.
-
 HSA Code Object Directives
 --------------------------
 
 AMDGPU ABI defines auxiliary data in output code object. In assembly source,
 one can specify them with assembler directives.
 
 .hsa_code_object_version major, minor
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 *major* and *minor* are integers that specify the version of the HSA code