| 1 | This is a collection of tests for GDB. |
| 2 | |
| 3 | The file gdb/README contains basic instructions on how to run the |
| 4 | testsuite, while this file documents additional options and controls |
| 5 | that are available. The GDB wiki may also have some pages with ideas |
| 6 | and suggestions. |
| 7 | |
| 8 | |
| 9 | Running the Testsuite |
| 10 | ********************* |
| 11 | |
| 12 | There are two ways to run the testsuite and pass additional parameters |
| 13 | to DejaGnu. The first is to do `make check' in the main build |
| 14 | directory and specifying the makefile variable `RUNTESTFLAGS': |
| 15 | |
| 16 | make check RUNTESTFLAGS='TRANSCRIPT=y gdb.base/a2-run.exp' |
| 17 | |
| 18 | The second is to cd to the testsuite directory and invoke the DejaGnu |
| 19 | `runtest' command directly. |
| 20 | |
| 21 | cd testsuite |
| 22 | make site.exp |
| 23 | runtest TRANSCRIPT=y |
| 24 | |
| 25 | (The `site.exp' file contains a handful of useful variables like host |
| 26 | and target triplets, and pathnames.) |
| 27 | |
| 28 | Parallel testing |
| 29 | **************** |
| 30 | |
| 31 | If not testing with a remote host (in DejaGnu's sense), you can run |
| 32 | the GDB test suite in a fully parallel mode. In this mode, each .exp |
| 33 | file runs separately and maybe simultaneously. The test suite ensures |
| 34 | that all the temporary files created by the test suite do not clash, |
| 35 | by putting them into separate directories. This mode is primarily |
| 36 | intended for use by the Makefile. |
| 37 | |
| 38 | For GNU make, the Makefile tries to run the tests in parallel mode if |
| 39 | any -j option is given. For a non-GNU make, tests are not |
| 40 | parallelized. |
| 41 | |
| 42 | If RUNTESTFLAGS is not empty, then by default the tests are |
| 43 | serialized. This can be overridden by either using the |
| 44 | `check-parallel' target in the Makefile, or by setting FORCE_PARALLEL |
| 45 | to any non-empty value: |
| 46 | |
| 47 | make check-parallel RUNTESTFLAGS="--target_board=native-gdbserver" |
| 48 | make check RUNTESTFLAGS="--target_board=native-gdbserver" FORCE_PARALLEL=1 |
| 49 | |
| 50 | If you want to use runtest directly instead of using the Makefile, see |
| 51 | the description of GDB_PARALLEL below. |
| 52 | |
| 53 | Racy testcases |
| 54 | ************** |
| 55 | |
| 56 | Sometimes, new testcases are added to the testsuite that are not |
| 57 | entirely deterministic, and can randomly pass or fail. We call them |
| 58 | "racy testcases", and they can be bothersome when one is comparing |
| 59 | different testsuite runs. In order to help identifying them, it is |
| 60 | possible to run the tests several times in a row and ask the testsuite |
| 61 | machinery to analyze the results. To do that, you need to specify the |
| 62 | RACY_ITER environment variable to make: |
| 63 | |
| 64 | make check RACY_ITER=5 -j4 |
| 65 | |
| 66 | The value assigned to RACY_ITER represents the number of times you |
| 67 | wish to run the tests in sequence (in the example above, the entire |
| 68 | testsuite will be executed 5 times in a row, in parallel). It is also |
| 69 | possible to check just a specific test: |
| 70 | |
| 71 | make check TESTS='gdb.base/default.exp' RACY_ITER=3 |
| 72 | |
| 73 | One can also decide to call the Makefile rules by hand inside the |
| 74 | gdb/testsuite directory, e.g.: |
| 75 | |
| 76 | make check-paralell-racy -j4 |
| 77 | |
| 78 | In which case the value of the DEFAULT_RACY_ITER variable (inside |
| 79 | gdb/testsuite/Makefile.in) will be used to determine how many |
| 80 | iterations will be run. |
| 81 | |
| 82 | After running the tests, you shall see a file name 'racy.sum' in the |
| 83 | gdb/testsuite directory. You can also inspect the generated *.log and |
| 84 | *.sum files by looking into the gdb/testsuite/racy_ouputs directory. |
| 85 | |
| 86 | If you already have *.sum files generated from previous testsuite runs |
| 87 | and you would like to analyze them without having to run the testsuite |
| 88 | again, you can also use the 'analyze-racy-logs.py' script directly. |
| 89 | It is located in the gdb/testsuite/ directory, and it expects a list |
| 90 | of two or more *.sum files to be provided as its argument. For |
| 91 | example: |
| 92 | |
| 93 | ./gdb/testsuite/analyze-racy-logs.py testsuite-01/gdb.sum \ |
| 94 | testsuite-02/gdb.sum testsuite-03/gdb.sum |
| 95 | |
| 96 | The script will output its analysis report to the standard output. |
| 97 | |
| 98 | Running the Performance Tests |
| 99 | ***************************** |
| 100 | |
| 101 | GDB Testsuite includes performance test cases, which are not run together |
| 102 | with other test cases, because performance test cases are slow and need |
| 103 | a quiet system. There are two ways to run the performance test cases. |
| 104 | The first is to do `make check-perf' in the main build directory: |
| 105 | |
| 106 | make check-perf RUNTESTFLAGS="solib.exp SOLIB_COUNT=8" |
| 107 | |
| 108 | The second is to cd to the testsuite directory and invoke the DejaGnu |
| 109 | `runtest' command directly. |
| 110 | |
| 111 | cd testsuite |
| 112 | make site.exp |
| 113 | runtest GDB_PERFTEST_MODE=both GDB_PERFTEST_TIMEOUT=4000 --directory=gdb.perf solib.exp SOLIB_COUNT=8 |
| 114 | |
| 115 | Only "compile", "run" and "both" are valid to GDB_PERFTEST_MODE. They |
| 116 | stand for "compile tests only", "run tests only", and "compile and run |
| 117 | tests" respectively. "both" is the default. GDB_PERFTEST_TIMEOUT |
| 118 | specify the timeout, which is 3000 in default. The result of |
| 119 | performance test is appended in `testsuite/perftest.log'. |
| 120 | |
| 121 | Testsuite Parameters |
| 122 | ******************** |
| 123 | |
| 124 | The following parameters are DejaGNU variables that you can set to |
| 125 | affect the testsuite run globally. |
| 126 | |
| 127 | TRANSCRIPT |
| 128 | |
| 129 | You may find it useful to have a transcript of the commands that the |
| 130 | testsuite sends to GDB, for instance if GDB crashes during the run, |
| 131 | and you want to reconstruct the sequence of commands. |
| 132 | |
| 133 | If the DejaGNU variable TRANSCRIPT is set (to any value), each |
| 134 | invocation of GDB during the test run will get a transcript file |
| 135 | written into the DejaGNU output directory. The file will have the |
| 136 | name transcript.<n>, where <n> is an integer. The first line of the |
| 137 | file shows the invocation command with all the options passed to it, |
| 138 | while subsequent lines are the GDB commands. A `make check' might |
| 139 | look like this: |
| 140 | |
| 141 | make check RUNTESTFLAGS=TRANSCRIPT=y |
| 142 | |
| 143 | The transcript may not be complete, as for instance tests of command |
| 144 | completion may show only partial command lines. |
| 145 | |
| 146 | GDB |
| 147 | |
| 148 | By default, the testsuite exercises the GDB in the build directory, |
| 149 | but you can set GDB to be a pathname to a different version. For |
| 150 | instance, |
| 151 | |
| 152 | make check RUNTESTFLAGS=GDB=/usr/bin/gdb |
| 153 | |
| 154 | runs the testsuite on the GDB in /usr/bin. |
| 155 | |
| 156 | GDBSERVER |
| 157 | |
| 158 | You can set GDBSERVER to be a particular GDBserver of interest, so for |
| 159 | instance |
| 160 | |
| 161 | make check RUNTESTFLAGS="GDB=/usr/bin/gdb GDBSERVER=/usr/bin/gdbserver" |
| 162 | |
| 163 | checks both the installed GDB and GDBserver. |
| 164 | |
| 165 | INTERNAL_GDBFLAGS |
| 166 | |
| 167 | Command line options passed to all GDB invocations. |
| 168 | |
| 169 | The default is "-nw -nx". |
| 170 | |
| 171 | `-nw' disables any of the windowed interfaces. |
| 172 | `-nx' disables ~/.gdbinit, so that it doesn't interfere with |
| 173 | the tests. |
| 174 | |
| 175 | This is actually considered an internal variable, and you |
| 176 | won't normally want to change it. However, in some situations, |
| 177 | this may be tweaked as a last resort if the testsuite doesn't |
| 178 | have direct support for the specifics of your environment. |
| 179 | The testsuite does not override a value provided by the user. |
| 180 | |
| 181 | As an example, when testing an installed GDB that has been |
| 182 | configured with `--with-system-gdbinit', like by default, |
| 183 | you do not want ~/.gdbinit to interfere with tests, but, you |
| 184 | may want the system .gdbinit file loaded. As there's no way to |
| 185 | ask the testsuite, or GDB, to load the system gdbinit but |
| 186 | not ~/.gdbinit, a workaround is then to remove `-nx' from |
| 187 | INTERNAL_GDBFLAGS, and point $HOME at a directory without |
| 188 | a .gdbinit. For example: |
| 189 | |
| 190 | cd testsuite |
| 191 | HOME=`pwd` runtest \ |
| 192 | GDB=/usr/bin/gdb \ |
| 193 | GDBSERVER=/usr/bin/gdbserver \ |
| 194 | INTERNAL_GDBFLAGS=-nw |
| 195 | |
| 196 | GDB_PARALLEL |
| 197 | |
| 198 | To use parallel testing mode without using the the Makefile, set |
| 199 | GDB_PARALLEL on the runtest command line to "yes". Before starting |
| 200 | the tests, you must ensure that the directories cache, outputs, and |
| 201 | temp in the test suite build directory are either empty or have been |
| 202 | deleted. cache in particular is used to share data across invocations |
| 203 | of runtest, and files there may affect the test results. The Makefile |
| 204 | automatically does these deletions. |
| 205 | |
| 206 | FORCE_PARALLEL |
| 207 | |
| 208 | Setting FORCE_PARALLEL to any non-empty value forces parallel testing |
| 209 | mode even if RUNTESTFLAGS is not empty. |
| 210 | |
| 211 | FORCE_SEPARATE_MI_TTY |
| 212 | |
| 213 | Setting FORCE_MI_SEPARATE_UI to 1 forces all MI testing to start GDB |
| 214 | in console mode, with MI running on a separate TTY, on a secondary UI |
| 215 | started with "new-ui". |
| 216 | |
| 217 | GDB_INOTIFY |
| 218 | |
| 219 | For debugging parallel mode, it is handy to be able to see when a test |
| 220 | case writes to a file outside of its designated output directory. |
| 221 | |
| 222 | If you have the inotify-tools package installed, you can set the |
| 223 | GDB_INOTIFY variable on the runtest command line. This will cause the |
| 224 | test suite to watch for parallel-unsafe file creations and report |
| 225 | them, both to stdout and in the test suite log file. |
| 226 | |
| 227 | This setting is only meaningful in conjunction with GDB_PARALLEL. |
| 228 | |
| 229 | TESTS |
| 230 | |
| 231 | This variable is used to specify which set of tests to run. |
| 232 | It is passed to make (not runtest) and its contents are a space separated |
| 233 | list of tests to run. |
| 234 | |
| 235 | If using GNU make then the contents are wildcard-expanded using |
| 236 | GNU make's $(wildcard) function. Test paths must be fully specified, |
| 237 | relative to the "testsuite" subdirectory. This allows one to run all |
| 238 | tests in a subdirectory by passing "gdb.subdir/*.exp", or more simply |
| 239 | by using the check-gdb.subdir target in the Makefile. |
| 240 | |
| 241 | If for some strange reason one wanted to run all tests that begin with |
| 242 | the letter "d" that is also possible: TESTS="*/d*.exp". |
| 243 | |
| 244 | Do not write */*.exp to specify all tests (assuming all tests are only |
| 245 | nested one level deep, which is not necessarily true). This will pick up |
| 246 | .exp files in ancillary directories like "lib" and "config". |
| 247 | Instead write gdb.*/*.exp. |
| 248 | |
| 249 | Example: |
| 250 | |
| 251 | make -j10 check TESTS="gdb.server/[s-w]*.exp */x*.exp" |
| 252 | |
| 253 | If not using GNU make then the value is passed directly to runtest. |
| 254 | If not specified, all tests are run. |
| 255 | |
| 256 | READ1 |
| 257 | |
| 258 | This make (not runtest) variable is used to specify whether the |
| 259 | testsuite preloads the read1.so library into expect. Any non-empty |
| 260 | value means true. See "Race detection" below. |
| 261 | |
| 262 | Race detection |
| 263 | ************** |
| 264 | |
| 265 | The testsuite includes a mechanism that helps detect test races. |
| 266 | |
| 267 | For example, say the program running under expect outputs "abcd", and |
| 268 | a test does something like this: |
| 269 | |
| 270 | expect { |
| 271 | "a.*c" { |
| 272 | } |
| 273 | "b" { |
| 274 | } |
| 275 | "a" { |
| 276 | } |
| 277 | } |
| 278 | |
| 279 | Which case happens to match depends on what expect manages to read |
| 280 | into its internal buffer in one go. If it manages to read three bytes |
| 281 | or more, then the first case matches. If it manages to read two |
| 282 | bytes, then the second case matches. If it manages to read only one |
| 283 | byte, then the third case matches. |
| 284 | |
| 285 | To help detect these cases, the race detection mechanism preloads a |
| 286 | library into expect that forces the `read' system call to always |
| 287 | return at most 1 byte. |
| 288 | |
| 289 | To enable this, either pass a non-empty value in the READ1 make |
| 290 | variable, or use the check-read1 make target instead of check. |
| 291 | |
| 292 | Examples: |
| 293 | |
| 294 | make -j10 check-read1 TESTS="*/paginate-*.exp" |
| 295 | make -j10 check READ1="1" |
| 296 | |
| 297 | Testsuite Configuration |
| 298 | *********************** |
| 299 | |
| 300 | It is possible to adjust the behavior of the testsuite by defining |
| 301 | the global variables listed below, either in a `site.exp' file, |
| 302 | or in a board file. |
| 303 | |
| 304 | gdb_test_timeout |
| 305 | |
| 306 | Defining this variable changes the default timeout duration used |
| 307 | during communication with GDB. More specifically, the global variable |
| 308 | used during testing is `timeout', but this variable gets reset to |
| 309 | `gdb_test_timeout' at the beginning of each testcase, which ensures |
| 310 | that any local change to `timeout' in a testcase does not affect |
| 311 | subsequent testcases. |
| 312 | |
| 313 | This global variable comes in handy when the debugger is slower than |
| 314 | normal due to the testing environment, triggering unexpected `TIMEOUT' |
| 315 | test failures. Examples include when testing on a remote machine, or |
| 316 | against a system where communications are slow. |
| 317 | |
| 318 | If not specifically defined, this variable gets automatically defined |
| 319 | to the same value as `timeout' during the testsuite initialization. |
| 320 | The default value of the timeout is defined in the file |
| 321 | `testsuite/config/unix.exp' (at least for Unix hosts; board files may |
| 322 | have their own values). |
| 323 | |
| 324 | gdb_reverse_timeout |
| 325 | |
| 326 | Defining this variable changes the default timeout duration when tests |
| 327 | under gdb.reverse directory are running. Process record and reverse |
| 328 | debugging is so slow that its tests have unexpected `TIMEOUT' test |
| 329 | failures. This global variable is useful to bump up the value of |
| 330 | `timeout' for gdb.reverse tests and doesn't cause any delay where |
| 331 | actual failures happen in the rest of the testsuite. |
| 332 | |
| 333 | |
| 334 | Board Settings |
| 335 | ************** |
| 336 | |
| 337 | DejaGNU includes the concept of a "board file", which specifies |
| 338 | testing details for a particular target (which are often bare circuit |
| 339 | boards, thus the name). |
| 340 | |
| 341 | In the GDB testsuite specifically, the board file may include a |
| 342 | number of "board settings" that test cases may check before deciding |
| 343 | whether to exercise a particular feature. For instance, a board |
| 344 | lacking any I/O devices, or perhaps simply having its I/O devices |
| 345 | not wired up, should set `noinferiorio'. |
| 346 | |
| 347 | Here are the supported board settings: |
| 348 | |
| 349 | gdb,cannot_call_functions |
| 350 | |
| 351 | The board does not support inferior call, that is, invoking inferior |
| 352 | functions in GDB. |
| 353 | |
| 354 | gdb,can_reverse |
| 355 | |
| 356 | The board supports reverse execution. |
| 357 | |
| 358 | gdb,no_hardware_watchpoints |
| 359 | |
| 360 | The board does not support hardware watchpoints. |
| 361 | |
| 362 | gdb,nofileio |
| 363 | |
| 364 | GDB is unable to intercept target file operations in remote and |
| 365 | perform them on the host. |
| 366 | |
| 367 | gdb,noinferiorio |
| 368 | |
| 369 | The board is unable to provide I/O capability to the inferior. |
| 370 | |
| 371 | gdb,noresults |
| 372 | |
| 373 | A program will not return an exit code or result code (or the value |
| 374 | of the result is undefined, and should not be looked at). |
| 375 | |
| 376 | gdb,nosignals |
| 377 | |
| 378 | The board does not support signals. |
| 379 | |
| 380 | gdb,skip_huge_test |
| 381 | |
| 382 | Skip time-consuming tests on the board with slow connection. |
| 383 | |
| 384 | gdb,skip_float_tests |
| 385 | |
| 386 | Skip tests related to floating point. |
| 387 | |
| 388 | gdb,use_precord |
| 389 | |
| 390 | The board supports process record. |
| 391 | |
| 392 | gdb_init_command |
| 393 | gdb_init_commands |
| 394 | |
| 395 | Commands to send to GDB every time a program is about to be run. The |
| 396 | first of these settings defines a single command as a string. The |
| 397 | second defines a TCL list of commands being a string each. The commands |
| 398 | are sent one by one in a sequence, first from `gdb_init_command', if any, |
| 399 | followed by individual commands from `gdb_init_command', if any, in this |
| 400 | list's order. |
| 401 | |
| 402 | gdb_server_prog |
| 403 | |
| 404 | The location of GDBserver. If GDBserver somewhere other than its |
| 405 | default location is used in test, specify the location of GDBserver in |
| 406 | this variable. The location is a file name for GDBserver, and may be |
| 407 | either absolute or relative to the testsuite subdirectory of the build |
| 408 | directory. |
| 409 | |
| 410 | in_proc_agent |
| 411 | |
| 412 | The location of the in-process agent (used for fast tracepoints and |
| 413 | other special tests). If the in-process agent of interest is anywhere |
| 414 | other than its default location, set this variable. The location is a |
| 415 | filename, and may be either absolute or relative to the testsuite |
| 416 | subdirectory of the build directory. |
| 417 | |
| 418 | noargs |
| 419 | |
| 420 | GDB does not support argument passing for inferior. |
| 421 | |
| 422 | no_long_long |
| 423 | |
| 424 | The board does not support type long long. |
| 425 | |
| 426 | use_cygmon |
| 427 | |
| 428 | The board is running the monitor Cygmon. |
| 429 | |
| 430 | use_gdb_stub |
| 431 | |
| 432 | The tests are running with a GDB stub. |
| 433 | |
| 434 | exit_is_reliable |
| 435 | |
| 436 | Set to true if GDB can assume that letting the program run to end |
| 437 | reliably results in program exits being reported as such, as opposed |
| 438 | to, e.g., the program ending in an infinite loop or the board |
| 439 | crashing/resetting. If not set, this defaults to $use_gdb_stub. In |
| 440 | other words, native targets are assumed reliable by default, and |
| 441 | remote stubs assumed unreliable. |
| 442 | |
| 443 | gdb,predefined_tsv |
| 444 | |
| 445 | The predefined trace state variables the board has. |
| 446 | |
| 447 | gdb,no_thread_names |
| 448 | |
| 449 | The target doesn't support thread names. |
| 450 | |
| 451 | Testsuite Organization |
| 452 | ********************** |
| 453 | |
| 454 | The testsuite is entirely contained in `gdb/testsuite'. The main |
| 455 | directory of the testsuite includes some makefiles and configury, but |
| 456 | these are minimal, and used for little besides cleaning up, since the |
| 457 | tests themselves handle the compilation of the programs that GDB will |
| 458 | run. |
| 459 | |
| 460 | The file `testsuite/lib/gdb.exp' contains common utility procs useful |
| 461 | for all GDB tests, while the directory testsuite/config contains |
| 462 | configuration-specific files, typically used for special-purpose |
| 463 | definitions of procs like `gdb_load' and `gdb_start'. |
| 464 | |
| 465 | The tests themselves are to be found in directories named |
| 466 | 'testsuite/gdb.* and subdirectories of those. The names of the test |
| 467 | files must always end with ".exp". DejaGNU collects the test files by |
| 468 | wildcarding in the test directories, so both subdirectories and |
| 469 | individual files typically get chosen and run in alphabetical order. |
| 470 | |
| 471 | The following lists some notable types of subdirectories and what they |
| 472 | are for. Since DejaGNU finds test files no matter where they are |
| 473 | located, and since each test file sets up its own compilation and |
| 474 | execution environment, this organization is simply for convenience and |
| 475 | intelligibility. |
| 476 | |
| 477 | gdb.base |
| 478 | |
| 479 | This is the base testsuite. The tests in it should apply to all |
| 480 | configurations of GDB (but generic native-only tests may live here). |
| 481 | The test programs should be in the subset of C that is both valid |
| 482 | ANSI/ISO C, and C++. |
| 483 | |
| 484 | gdb.<lang> |
| 485 | |
| 486 | Language-specific tests for any language besides C. Examples are |
| 487 | gdb.cp for C++ and gdb.rust for Rust. |
| 488 | |
| 489 | gdb.<platform> |
| 490 | |
| 491 | Non-portable tests. The tests are specific to a specific |
| 492 | configuration (host or target), such as eCos. |
| 493 | |
| 494 | gdb.arch |
| 495 | |
| 496 | Architecture-specific tests that are (usually) cross-platform. |
| 497 | |
| 498 | gdb.<subsystem> |
| 499 | |
| 500 | Tests that exercise a specific GDB subsystem in more depth. For |
| 501 | instance, gdb.disasm exercises various disassemblers, while |
| 502 | gdb.stabs tests pathways through the stabs symbol reader. |
| 503 | |
| 504 | gdb.perf |
| 505 | |
| 506 | GDB performance tests. |
| 507 | |
| 508 | Writing Tests |
| 509 | ************* |
| 510 | |
| 511 | In many areas, the GDB tests are already quite comprehensive; you |
| 512 | should be able to copy existing tests to handle new cases. Be aware |
| 513 | that older tests may use obsolete practices but have not yet been |
| 514 | updated. |
| 515 | |
| 516 | You should try to use `gdb_test' whenever possible, since it includes |
| 517 | cases to handle all the unexpected errors that might happen. However, |
| 518 | it doesn't cost anything to add new test procedures; for instance, |
| 519 | gdb.base/exprs.exp defines a `test_expr' that calls `gdb_test' |
| 520 | multiple times. |
| 521 | |
| 522 | Only use `send_gdb' and `gdb_expect' when absolutely necessary. Even |
| 523 | if GDB has several valid responses to a command, you can use |
| 524 | `gdb_test_multiple'. Like `gdb_test', `gdb_test_multiple' recognizes |
| 525 | internal errors and unexpected prompts. |
| 526 | |
| 527 | Do not write tests which expect a literal tab character from GDB. On |
| 528 | some operating systems (e.g. OpenBSD) the TTY layer expands tabs to |
| 529 | spaces, so by the time GDB's output reaches `expect' the tab is gone. |
| 530 | |
| 531 | The source language programs do *not* need to be in a consistent |
| 532 | style. Since GDB is used to debug programs written in many different |
| 533 | styles, it's worth having a mix of styles in the testsuite; for |
| 534 | instance, some GDB bugs involving the display of source lines might |
| 535 | never manifest themselves if the test programs used GNU coding style |
| 536 | uniformly. |
| 537 | |
| 538 | Some testcase results need more detailed explanation: |
| 539 | |
| 540 | KFAIL |
| 541 | |
| 542 | Use KFAIL for known problem of GDB itself. You must specify the GDB |
| 543 | bug report number, as in these sample tests: |
| 544 | |
| 545 | kfail "gdb/13392" "continue to marker 2" |
| 546 | |
| 547 | or |
| 548 | |
| 549 | setup_kfail gdb/13392 "*-*-*" |
| 550 | kfail "continue to marker 2" |
| 551 | |
| 552 | |
| 553 | XFAIL |
| 554 | |
| 555 | Short for "expected failure", this indicates a known problem with the |
| 556 | environment. This could include limitations of the operating system, |
| 557 | compiler version, and other components. |
| 558 | |
| 559 | This example from gdb.base/attach-pie-misread.exp is a sanity check |
| 560 | for the target environment: |
| 561 | |
| 562 | # On x86_64 it is commonly about 4MB. |
| 563 | if {$stub_size > 25000000} { |
| 564 | xfail "stub size $stub_size is too large" |
| 565 | return |
| 566 | } |
| 567 | |
| 568 | You should provide bug report number for the failing component of the |
| 569 | environment, if such bug report is available, as with this example |
| 570 | referring to a GCC problem: |
| 571 | |
| 572 | if {[test_compiler_info {gcc-[0-3]-*}] |
| 573 | || [test_compiler_info {gcc-4-[0-5]-*}]} { |
| 574 | setup_xfail "gcc/46955" *-*-* |
| 575 | } |
| 576 | gdb_test "python print ttype.template_argument(2)" "&C::c" |
| 577 | |
| 578 | Note that it is also acceptable, and often preferable, to avoid |
| 579 | running the test at all. This is the better option if the limitation |
| 580 | is intrinsic to the environment, rather than a bug expected to be |
| 581 | fixed in the near future. |
| 582 | |
| 583 | Local vs Remote vs Native |
| 584 | ************************* |
| 585 | |
| 586 | It's unfortunately easy to get confused in the testsuite about what's |
| 587 | native and what's not, what's remote and what's not. The confusion is |
| 588 | caused by the overlap in vocabulary between DejaGnu and GDB. |
| 589 | |
| 590 | From a DejaGnu point of view: |
| 591 | |
| 592 | - native: the host or target board is considered native if the its |
| 593 | triplet is the same as the build system's triplet, |
| 594 | |
| 595 | - remote: the host or target board is considered remote if it's |
| 596 | running on a different machine, and thus require ssh, for example, |
| 597 | to run commands, versus simply running commands directly. |
| 598 | |
| 599 | Note that they are not mutually exclusive, as you can have a remote |
| 600 | machine that has the same triplet as the build machine. |
| 601 | |
| 602 | From a GDB point of view: |
| 603 | |
| 604 | - native: when GDB uses system calls such as ptrace to interact |
| 605 | directly with processes on the same system its running on, |
| 606 | |
| 607 | - remote: when GDB speaks the RSP (Remote Serial Protocol) with |
| 608 | another program doing the ptrace stuff. |
| 609 | |
| 610 | Note that they are mutually exclusive. An inferior can only be either |
| 611 | debugged with the native target, or with the remote target a specific |
| 612 | time. |
| 613 | |
| 614 | That means that there are cases where the target is not remote for |
| 615 | DejaGnu, but is remote for GDB (e.g. running GDBserver on the same |
| 616 | machine). |
| 617 | |
| 618 | You can also have a remote target for DejaGnu, but native for GDB |
| 619 | (e.g. building on x86 a GDB that runs on ARM and running the |
| 620 | testsuite with a remote host). |
| 621 | |
| 622 | Therefore, care must be taken to check for the right kind of remote. |
| 623 | Use [is_remote target] to check whether the DejaGnu target board is |
| 624 | remote. When what you really want to know is whether GDB is using the |
| 625 | remote protocol, because feature X is only available when GDB debugs |
| 626 | natively, check gdb_protocol instead. |