From 152fdac6aa4c88ddaf43a9b10952364a885b02a7 Mon Sep 17 00:00:00 2001
From: Bruce Perry <53018946+baperry2@users.noreply.github.com>
Date: Mon, 23 Oct 2023 11:18:33 -0600
Subject: [PATCH] update doc for amrex::Abort on GPU (#3605)

The docs on the behavior of amrex::Abort and related functions appear to
be out of date, so this clarifies that when running on GPU these
functions do not do anything when called from within GPU kernels unless
you compile in debug mode or with `USE_ASSERTION=TRUE`.
---
 Docs/sphinx_documentation/source/Basics.rst |  3 +++
 Docs/sphinx_documentation/source/GPU.rst    | 10 +++++++---
 2 files changed, 10 insertions(+), 3 deletions(-)

diff --git a/Docs/sphinx_documentation/source/Basics.rst b/Docs/sphinx_documentation/source/Basics.rst
index 1227b5f7b71..ebddd14f9b5 100644
--- a/Docs/sphinx_documentation/source/Basics.rst
+++ b/Docs/sphinx_documentation/source/Basics.rst
@@ -2812,3 +2812,6 @@ Backtrace files are produced by AMReX signal handler by default when
 segfault occurs or ``Abort`` is called.  If the application does not
 want AMReX to handle this, ``ParmParse`` parameter
 `amrex.signal_handling=0` can be used to disable it.
+
+See :ref:`sec:gpu:assertion` for considerations on using these functions in
+GPU-enabled code.
diff --git a/Docs/sphinx_documentation/source/GPU.rst b/Docs/sphinx_documentation/source/GPU.rst
index 56d540e63c4..90dbcc9f26f 100644
--- a/Docs/sphinx_documentation/source/GPU.rst
+++ b/Docs/sphinx_documentation/source/GPU.rst
@@ -1553,9 +1553,13 @@ Assertions and Error Checking
 To help debugging, we often use :cpp:`amrex::Assert` and
 :cpp:`amrex::Abort`.  These functions are GPU safe and can be used in
 GPU kernels.  However, implementing these functions requires additional
-GPU registers, which will reduce overall performance.  Therefore, it
-is preferred to implement such calls in debug mode only by wrapping the
-calls using ``#ifdef AMREX_DEBUG``.
+GPU registers, which will reduce overall performance.  Therefore, by
+default these functions and the macro ``AMREX_ALWAYS_ASSERT`` are no-ops
+for optimized builds (e.g., ``DEBUG=FALSE`` using the GNU Make build
+system) when called from kernels run on GPU. Calls to these functions from
+GPU kernels are active for debug builds and can optionally be activated
+at compile time for optimized builds (e.g., ``DEBUG=FALSE`` and
+``USE_ASSERTION=TRUE`` using the GNU Make build system).
 
 In CPU code, :cpp:`AMREX_GPU_ERROR_CHECK()` can be called
 to check the health of previous GPU launches.  This call