+section: codegen

+synopsis: Improve ``-fcheck-prim-bounds`` runtime error messages

+issues: #26964 #24617

+mrs: !16130

+

+description: {

+  When an array access instrumented by ``-fcheck-prim-bounds`` fails at

+  runtime, the program now reports the failing primop, the offending index and

+  the array size, and exits with a normal non-zero status. Previously it

+  aborted with an "internal error" framed as a GHC bug, even though such

+  failures are almost always caused by incorrect use of unsafe primops in user

+  or library code.

+}

+        withCurrentPrimOpName, getCurrentPrimOpName,

+              , fcs_prim_op       :: Maybe String        -- ^ Source name of the primop currently being

+                                                         --   compiled, used by -fcheck-prim-bounds error

+                                                         --   messages.

+               , fcs_prim_op       = Nothing

+-- ----------------------------------------------------------------------------

+-- Track the primop currently being compiled

+

+-- | The source name of the primop currently being compiled (e.g.

+-- @"writeArray#"@), if any. Used to produce informative @-fcheck-prim-bounds@

+-- error messages.

+getCurrentPrimOpName :: FCode (Maybe String)

+getCurrentPrimOpName = fcs_prim_op <$> getFCodeState

+

+withCurrentPrimOpName :: String -> FCode a -> FCode a

+withCurrentPrimOpName name code = do

+        fstate <- getFCodeState

+        withFCodeState code (fstate {fcs_prim_op = Just name})

+

+import GHC.StgToCmm.Lit ( newStringCLit )

+import GHC.Types.Name.Occurrence ( occNameString )

+  -- When -fcheck-prim-bounds is on, record the primop name so that any

+  -- bounds-check failure handler emitted while compiling it can name it in the

+  -- error message. Guarded by the flag so that the common (unchecked) case pays

+  -- nothing: no name thunk, no FCodeState update.

+  if stgToCmmDoBoundsCheck cfg

+    then withCurrentPrimOpName (occNameString (primOpOcc primop)) (f res_ty)

+    else f res_ty

+        name <- fromMaybe "<unknown primop>" <$> getCurrentPrimOpName

+        nameLbl <- newStringCLit name

+          emitCCallNeverReturns []

+            (mkLblExpr mkMemcpyRangeOverlapLabel)

+            [ (CmmLit nameLbl, AddrHint) ]

+-- | Emit a call to the RTS @rtsOutOfBoundsAccess@ bounds-check failure

+-- handler, passing the offending index, the number of accessed elements and

+-- the array size, so that the runtime can produce an informative error

+-- message. The name of the offending primop is read from the code generator

+-- environment (see 'withCurrentPrimOpName').

+emitBoundsCheckFailed :: CmmExpr  -- ^ accessed index

+                      -> CmmExpr  -- ^ number of accessed elements

+                      -> CmmExpr  -- ^ array size (in elements)

+                      -> FCode ()

+emitBoundsCheckFailed idx count sz = do

+    name <- fromMaybe "<unknown primop>" <$> getCurrentPrimOpName

+    nameLbl <- newStringCLit name

+    emitCCallNeverReturns []

+      (mkLblExpr mkOutOfBoundsAccessLabel)

+      [ (idx,            NoHint)

+      , (count,          NoHint)

+      , (sz,             NoHint)

+      , (CmmLit nameLbl, AddrHint) ]

+

+      emitBoundsCheckFailed idx (mkIntExpr platform 1) sz

+      emitBoundsCheckFailed idx len arrSize

+    which terminates the program when an out-of-bounds access is detected.

+

+    When a check fails, the program prints a message naming the offending

+    primop together with the offending index and the array size, and exits

+    with a non-zero status, for example::

+

+        myprog: writeArray#: array access out of bounds:

+            index 5 is not within [0, 3).

+        This is usually caused by incorrect use of unsafe primops in user or library code.

+

+    The message does not identify the enclosing function or module. To obtain a

+    backtrace pinpointing the failing call, build with profiling and run with

+    ``+RTS -xc`` (see :ref:`prof-time-options`), or use :ghc-flag:`-finfo-table-map`

+    together with ``+RTS -xc``.

+    the primary means of catching out-of-bounds accesses. Currently only the

+    native code generator is instrumented; the JavaScript backend is unaffected

+    by this flag.

+// `op` is the source name of the primop being checked (e.g. "casIntArray#").

+// NB: in some callers `ind` is a byte offset rather than an element index, so

+// the index reported here may be in bytes. count is 1 since these checks cover

+// a single access.

+#define ASSERT_IN_BOUNDS(op, ind, sz) \

+    if (ind >= sz) { ccall rtsOutOfBoundsAccess(ind, 1, sz, op); }

+#define ASSERT_IN_BOUNDS(op, ind, sz)

+    ASSERT_IN_BOUNDS("casIntArray#", ind + WDS(1) - 1, StgArrBytes_bytes(arr));

+    ASSERT_IN_BOUNDS("casInt8Array#", ind, StgArrBytes_bytes(arr));

+    ASSERT_IN_BOUNDS("casInt16Array#", ind + 1, StgArrBytes_bytes(arr));

+    ASSERT_IN_BOUNDS("casInt32Array#", ind + 3, StgArrBytes_bytes(arr));

+    ASSERT_IN_BOUNDS("casInt64Array#", ind + 7, StgArrBytes_bytes(arr));

+    ASSERT_IN_BOUNDS("casArray#", ind, StgMutArrPtrs_ptrs(arr));

+        ASSERT_IN_BOUNDS("copySmallArray#", dst_off + n - 1, StgSmallMutArrPtrs_ptrs(dst));

+        ASSERT_IN_BOUNDS("copySmallArray#", src_off + n - 1, StgSmallMutArrPtrs_ptrs(src));

+        ASSERT_IN_BOUNDS("copySmallMutableArray#", dst_off + n - 1, StgSmallMutArrPtrs_ptrs(dst));

+        ASSERT_IN_BOUNDS("copySmallMutableArray#", src_off + n - 1, StgSmallMutArrPtrs_ptrs(src));

+    ASSERT_IN_BOUNDS("casSmallArray#", ind, StgSmallMutArrPtrs_ptrs(arr));

+rtsOutOfBoundsAccess(StgInt index, StgWord count, StgWord size, const char *op)

+    if (count <= 1) {

+        errorBelch("%s: array access out of bounds:\n"

+                   "    index %" FMT_Int " is not within [0, %" FMT_Word ").\n"

+                   "This is usually caused by incorrect use of unsafe primops "

+                   "in user or library code.",

+                   op, index, size);

+    } else {

+        errorBelch("%s: array access out of bounds:\n"

+                   "    range of %" FMT_Word " elements starting at index %" FMT_Int

+                   " is not within [0, %" FMT_Word ").\n"

+                   "This is usually caused by incorrect use of unsafe primops "

+                   "in user or library code.",

+                   op, count, index, size);

+    }

+    stg_exit(EXIT_FAILURE);

+rtsMemcpyRangeOverlap(const char *op)

+    errorBelch("%s: overlapping source and destination ranges in a "

+               "memcpy-using operation.\n"

+               "This is usually caused by incorrect use of unsafe primops "

+               "in user or library code.",

+               op);

+    stg_exit(EXIT_FAILURE);

+void rtsOutOfBoundsAccess(StgInt index, StgWord count, StgWord size, const char *op) STG_NORETURN;

+void rtsMemcpyRangeOverlap(const char *op) STG_NORETURN;

+{-# LANGUAGE UnboxedTuples #-}

+{-# LANGUAGE MagicHash #-}

+

+-- Test that -fcheck-prim-bounds reports the failing primop, the offending

+-- index and the array size. The negative index also checks that it is reported

+-- as a signed number (e.g. -1, not a huge unsigned word).

+

+module Main where

+

+import GHC.Exts

+import GHC.IO

+

+main :: IO ()

+main = do

+    IO $ \s0 ->

+      case newSmallArray# 5# () s0 of

+        (# s1, marr #) -> readSmallArray# marr (-1#) s1

+readSmallArray#: array access out of bounds:

+    index -1 is not within [0, 5).

+This is usually caused by incorrect use of unsafe primops in user or library code.

+{-# LANGUAGE UnboxedTuples #-}

+{-# LANGUAGE MagicHash #-}

+

+-- Test that -fcheck-prim-bounds reports a failing *range* access (count > 1)

+-- with the "range of N elements starting at index" wording. The source range

+-- is in bounds, but the destination range [6, 10) overruns the 8-byte array.

+

+module Main where

+

+import GHC.Exts

+import GHC.IO

+

+main :: IO ()

+main = IO $ \s0 ->

+  case newByteArray# 8# s0 of

+    (# s1, src #) ->

+      case newByteArray# 8# s1 of

+        (# s2, dst #) ->

+          case copyMutableByteArray# src 0# dst 6# 4# s2 of

+            s3 -> (# s3, () #)

+copyMutableByteArray#: array access out of bounds:

+    range of 4 elements starting at index 6 is not within [0, 8).

+This is usually caused by incorrect use of unsafe primops in user or library code.

+    # The native backend exits with EXIT_FAILURE (1); the JS backend still

+    # aborts with h$exitProcess(134) (the improved messages are native-only).

+         [ignore_stderr, omit_ghci, exit_code(134 if js_arch() else 1)],

+

+# Unlike the check_bounds_test cases above, these tests pin down the exact

+# -fcheck-prim-bounds error message. Drop the leading "<prog>: " prefix so the

+# tests don't depend on the binary's name/path (incl. Windows drive letters).

+def strip_prog_prefix(s):

+    return re.sub(r'(?m)^.*?(\w+#: array access)', r'\1', s)

+

+# T26964 checks the single-element message. T26964b checks the range variant.

+# Skipped on the JS backend, which emits no message and aborts with code 134.

+test('T26964',

+     [omit_ghci, js_skip, exit_code(1), normalise_errmsg_fun(strip_prog_prefix)],

+     compile_and_run, ['-fcheck-prim-bounds'])

+test('T26964b',

+     [omit_ghci, js_skip, exit_code(1), normalise_errmsg_fun(strip_prog_prefix)],

+     compile_and_run, ['-fcheck-prim-bounds'])