From 1d41d75cb6f1e78eedf871801a351e8be761daff Mon Sep 17 00:00:00 2001 From: Doug Evans Date: Sat, 3 Dec 2011 18:01:50 +0000 Subject: [PATCH] * lib/gdb.exp (gdb_run_cmd, gdb_start_cmd, run_to_main): Add comments. (gdb_step_for_stub): Add comments. --- gdb/testsuite/ChangeLog | 5 +++++ gdb/testsuite/lib/gdb.exp | 47 +++++++++++++++++++++++++++++++++++++++-------- 2 files changed, 44 insertions(+), 8 deletions(-) diff --git a/gdb/testsuite/ChangeLog b/gdb/testsuite/ChangeLog index 80f7440..a2c160c 100644 --- a/gdb/testsuite/ChangeLog +++ b/gdb/testsuite/ChangeLog @@ -1,3 +1,8 @@ +2011-12-03 Doug Evans + + * lib/gdb.exp (gdb_run_cmd, gdb_start_cmd, run_to_main): Add comments. + (gdb_step_for_stub): Add comments. + 2011-12-02 Maciej W. Rozycki * lib/gdb.exp (gdb_expect): Pass all the exception conditions up diff --git a/gdb/testsuite/lib/gdb.exp b/gdb/testsuite/lib/gdb.exp index 8ac32db..1823e00 100644 --- a/gdb/testsuite/lib/gdb.exp +++ b/gdb/testsuite/lib/gdb.exp @@ -187,14 +187,15 @@ proc delete_breakpoints {} { } } - -# # Generic run command. # # The second pattern below matches up to the first newline *only*. # Using ``.*$'' could swallow up output that we attempt to match # elsewhere. # +# N.B. This function does not wait for gdb to return to the prompt, +# that is the caller's responsibility. + proc gdb_run_cmd {args} { global gdb_prompt @@ -300,6 +301,9 @@ proc gdb_run_cmd {args} { # Generic start command. Return 0 if we could start the program, -1 # if we could not. +# +# N.B. This function does not wait for gdb to return to the prompt, +# that is the caller's responsibility. proc gdb_start_cmd {args} { global gdb_prompt @@ -451,12 +455,14 @@ proc runto { function args } { return 1 } +# Ask gdb to run until we hit a breakpoint at main. +# The case where the target uses stubs has to be handled +# specially--if it uses stubs, assuming we hit +# breakpoint() and just step out of the function. # -# runto_main -- ask gdb to run until we hit a breakpoint at main. -# The case where the target uses stubs has to be handled -# specially--if it uses stubs, assuming we hit -# breakpoint() and just step out of the function. -# +# N.B. This function deletes all existing breakpoints. +# If you don't want that, use gdb_start_cmd. + proc runto_main { } { global gdb_prompt global decimal @@ -472,7 +478,6 @@ proc runto_main { } { return 1 } - ### Continue, and expect to hit a breakpoint. ### Report a pass or fail, depending on whether it seems to have ### worked. Use NAME as part of the test name; each call to @@ -3142,6 +3147,32 @@ proc setup_kfail_for_target { PR target } { } } +# Test programs for embedded (often "bare board") systems sometimes use a +# "stub" either embedded in the test program itself or in the boot rom. +# The job of the stub is to implement the remote protocol to communicate +# with gdb and control the inferior. To initiate the remote protocol +# session with gdb the stub needs to be given control by the inferior. +# They do this by calling a function that typically triggers a trap +# from main that transfers control to the stub. +# The purpose of this function, gdb_step_for_stub, is to step out of +# that function ("breakpoint" in the example below) and back into main. +# +# Example: +# +# int +# main () +# { +# #ifdef usestubs +# set_debug_traps (); /* install trap handlers for stub */ +# breakpoint (); /* trigger a trap to give the stub control */ +# #endif +# /* test program begins here */ +# } +# +# Note that one consequence of this design is that a breakpoint on "main" +# does not Just Work (because if the target could stop there you still have +# to step past the calls to set_debug_traps,breakpoint). + proc gdb_step_for_stub { } { global gdb_prompt; -- 2.7.4