gdb: add -catch-hiperr to the Machine Interface (MI)

[amd-shahab]

Introduce a new MI command to catch HIP runtime errors that takes the form of:

  -catch-hiperr [ -c <condition> ] [ -t ]

Along with it the documentation is updated and new tests are added.

Motivation

Add Machine Interface for "catch hiperr".

Technical Details

Machine Interface allows other tools control GDB by sending it commands and reading its feedback. This was missing for the "catch hiperr" support that we added earlier.

Test Plan

New MI tests are added hip-catch-errors.exp.

Test Result

All the new tests are and "catch hiperr" tests are passing.

Running /data/work/src/dev/rocgdb/gdb/testsuite/gdb.rocm/hip-catch-errors.exp ...
PASS: gdb.rocm/hip-catch-errors.exp: mi_parsing: trailing -t in condition: mi-catch-hiperr
PASS: gdb.rocm/hip-catch-errors.exp: mi_parsing: trailing -t in condition: breakpoint info
PASS: gdb.rocm/hip-catch-errors.exp: mi_parsing: dangling -c: mi-catch-hiperr
PASS: gdb.rocm/hip-catch-errors.exp: mi_parsing: unknown option: mi-catch-hiperr
PASS: gdb.rocm/hip-catch-errors.exp: mi_parsing: dangling texts: mi-catch-hiperr
PASS: gdb.rocm/hip-catch-errors.exp: mi_parsing: dangling texts: breakpoint info
[ CLI tests in here ]
PASS: gdb.rocm/hip-catch-errors.exp: mi_test: simple catch: mi-catch-hiperr
PASS: gdb.rocm/hip-catch-errors.exp: mi_test: simple catch: breakpoint info
PASS: gdb.rocm/hip-catch-errors.exp: mi_test: simple catch: set argument
PASS: gdb.rocm/hip-catch-errors.exp: mi_test: simple catch
PASS: gdb.rocm/hip-catch-errors.exp: mi_test: temporary catch: mi-catch-hiperr
PASS: gdb.rocm/hip-catch-errors.exp: mi_test: temporary catch: breakpoint info
PASS: gdb.rocm/hip-catch-errors.exp: mi_test: temporary catch: set argument
PASS: gdb.rocm/hip-catch-errors.exp: mi_test: temporary catch
PASS: gdb.rocm/hip-catch-errors.exp: mi_test: conditional catch: mi-catch-hiperr
PASS: gdb.rocm/hip-catch-errors.exp: mi_test: conditional catch: breakpoint info
PASS: gdb.rocm/hip-catch-errors.exp: mi_test: conditional catch: set argument
PASS: gdb.rocm/hip-catch-errors.exp: mi_test: conditional catch
PASS: gdb.rocm/hip-catch-errors.exp: mi_test: temporary conditional catch: mi-catch-hiperr
PASS: gdb.rocm/hip-catch-errors.exp: mi_test: temporary conditional catch: breakpoint info
PASS: gdb.rocm/hip-catch-errors.exp: mi_test: temporary conditional catch: set argument
PASS: gdb.rocm/hip-catch-errors.exp: mi_test: temporary conditional catch

[lancesix]

First very quick remarks.

[lancesix]

usual parsing question… How do you differentiate -t as a flag after the condition v.s. -t being the unari - operator, i.e. hipErrorInvalidDevice - t?

[amd-shahab]

Debugging the code around the option parsing [1], reveals that the valid ways of passing arguments to options (in this example, condition to -c) is to not use any spaces in the argument or have them double-quoted. For instance, see the two alternatives below and how they end up setting the parameters:

# alt.1: no spaces
interpreter-exec mi '-catch-hiperr -c $_hiperr=hipErrorInvalidDevice-t -t'

mi_cmd_catch_hiperr (..., const char *const argv, int argc)
  argc: 3
  argv[0]: "-c"
  argv[1]: "$_hiperr==hipErrorInvalidDevice-t"
  argv[2]: "-t"
  .
  .
  .
  condition = "$_hiperr==hipErrorInvalidDevice-t"
  temp = true

---------------------------------------------------
# alt.2: double-quoted
interpreter-exec mi '-catch-hiperr -c "$_hiperr == hipErrorInvalidDevice - t" -t'

mi_cmd_catch_hiperr (..., const char *const argv, int argc)
  argc: 3
  argv[0]: "-c"
  argv[1]: "$_hiperr == hipErrorInvalidDevice - t"
  argv[2]: "-t"
  .
  .
  .
  condition = "$_hiperr == hipErrorInvalidDevice - t"
  temp = true

Any deviation from this and we'll end up with the wrong argc/argv to begin with:

interpreter-exec mi '-catch-hiperr -c $_hiperr == hipErrorInvalidDevice - t -t'

mi_cmd_catch_hiperr (..., const char *const argv, int argc)
  argc: 7
  argv[0]: "-c"
  argv[1]: "$_hiperr"
  argv[2]: "=="
  argv[3]: "hipErrorInvalidDevice"
  argv[4]: "-"
  argv[5]: "t"
  argv[6]: "-t"
  .
  .
  .
  condition = "$_hiperr"
  then "opt" in the for-loop [1] becomes negative and the loop is broken
  and we'll end up with a conditional catchpoint with $_hiperr as its condition.

[1] gdb/mi/mi-cmd-catch.c

void mi_cmd_catch_hiperr (const char *cmd, const char *const *argv, int argc)
{
  ...
  for (;;)
    {
      int opt = mi_getopt (cmd, argc, argv, opts, &oind, &oarg);

      if (opt < 0)
        break;

      switch ((enum opt) opt)
        {
        case OPT_CONDITION:
          condition = oarg;
          break;
        case OPT_TEMP:
          temp = true;
          break;
        }
    }
  ...
}

For the record, I've added -catch-hiperr -c "$_hiperr == hipErrorInvalidDevice -t" -t as a test now.

[amd-shahab]

• Use -catch-hiperr -c "$_hiperr == hipErrorInvalidDevice -t" -t as temporary conditional test
• Use mi_gdb_tests instead of gdb_test and gdb_test_multiple
• get rid of the rocm boiler plates (load_lib rocm.exp, require allow_hip_tests, and the standard_testfile .../prepare_for_testing ...)

[amd-shahab]

• doc: escape curly braces from MI output with @.
• doc: add right-hand-side space for the condition part.
• code: add hiperr-{code,name,text} fields for the MI output.
• doc: update to reflect hiperr-{code,name,text} fields.

[amd-shahab]

• code: get rid of catch_hiperr_mi() and use add_catch_hiperr() (former catch_hiperr_core())
• test: re-implement the existing 4 testcases with a table an a for-loop.
• test: consolidate chk_mi_catch_hiperr and chk_mi_bkpt procedures into hiperr_bkpt_re.

[amd-shahab]

• test: check the output of a triggered catchpoint (specially hiperr-{code,name})
• test: check the parsing of MI command by throwing some tricky and malformed commands

[lumachad]

Since we're trying to have a clean gdb.rocm testsuite with non-O0 optimization level, please check if this new test behaves well when executed with O1~O3 and -flto.

[amd-shahab]

• test: consolidate MI tests into hip-catch-errors.exp. Since now the test is looking for a triggered catchpoint, checking for the existence of the __hipOnError and initializing reference values have become necessary. this was already done in hip-catch-errors.exp.

[amd-shahab]

• add another patch that makes the test still pass under optimizations. now works with these flags:

-O0
-O1
-O2
-O3

-O0 -flto
-O1 -flto
-O2 -flto
-O3 -flto