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

266–267

" 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

280

Just HSA?

282

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

264

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

269–278

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

280

Or HSA OS?

282

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.

288–301

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".

303

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

[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

 
 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:
+The OS element of the target triple controls the trap handler behavior. OS is
+obtained from the appropriate element of the target triple HSA OS:
 
 .. code-block:: c++
 

     return isAmdHsaOS() ? TrapHandlerAbiHsa : TrapHandlerAbiNone;
   }
 
-For HSA OS, a trap handler is always enabled and that the following S_TRAP immediate
-operand codes are supported:
+HSAOS
+^^^^^
+For the HSA OS a trap handler is always enabled and supports the S_TRAP
+instruction. The immediate operand of the S_TRAP instruction indicates the trap
+reason as follows:
 
 .. code-block:: c++