From 8d22e6f3bbc042e8b5d8a8ca3c1132f51e38ac08 Mon Sep 17 00:00:00 2001
From: Wei Ding <wei.ding2@amd.com>
Date: Tue, 21 Feb 2017 18:48:01 +0000
Subject: [PATCH] AMDGPU : AMDGPU : Update AMDGPU Trap Handler ABI.

Differential Revision: http://reviews.llvm.org/D29913

git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@295745 91177308-0d34-0410-b5e6-96231b3b80d8
---
 docs/AMDGPUUsage.rst | 90 ++++++++++++++++++++++++--------------------
 1 file changed, 49 insertions(+), 41 deletions(-)

diff --git a/docs/AMDGPUUsage.rst b/docs/AMDGPUUsage.rst
index 54904d21f7a..ffb0e677e9a 100644
--- a/docs/AMDGPUUsage.rst
+++ b/docs/AMDGPUUsage.rst
@@ -33,6 +33,55 @@ The AMDGPU back-end uses the following address space mapping:
 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 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.
+   =============== ============= ===============================================
 
 Assembler
 =========
@@ -261,47 +310,6 @@ VOP_SDWA examples:
 
 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
 --------------------------