[RFC/MI] Event Records vs Commands

Keith Seitz
2002-06-14T05:24:38Z

Hi,

This is the promised gdbmi.texinfo proposal that I referred to in:

http://sources.redhat.com/ml/gdb/2002-06/msg00106.html

This patch formalizes events in MI. Specifically, I propose to whack
notify-async-output from aync-record and add event-record to
out-of-band-record.

I've modified all the breakpoint command examples to reflect the fact that
breakpoint commands will no longer print information about the breakpoint.
Instead this information is retrieved from the event. For example:

- old way
(gdb)
-break-insert main
^done,bkpt={number="1",addr="0xdeadbeef",file="main.c",line="5"}
(gdb)

- new way
(gdb)
-break-insert main
=breakpoint-create,number="1"
(gdb)
-break-info 1
^done,BreakpointTable={...}

I have completed the changes to MI to accomplish this, and I will submit
these patches once this is all approved. I plan to check this all into my
interpreter branch (kseitz_interps-20020528-branch) until everything
is finalized. I will then migrate the whole (approved) thing into cvs
head.

Comments?
Keith

ChangeLog
2002-06-13 Keith Seitz <keiths@redhat.com>

* gdbmi.texinfo: Add event-record output syntax.
Remove notify-async-output.
Update all examples to show breakpoint events and
remove redundant breakpoint info on "-break-insert". The event
now supplies everything that is needed.

Patch
Index: gdbmi.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/mi/gdbmi.texinfo,v
retrieving revision 1.26
diff -p -r1.26 gdbmi.texinfo
*** gdbmi.texinfo 25 Feb 2002 02:13:09 -0000 1.26
--- gdbmi.texinfo 14 Jun 2002 05:06:28 -0000
*************** corresponding output for that command wi
*** 224,233 ****
@code{ [ @var{token} ] "^" @var{result-class} ( "," @var{result} )* @var{nl}}

@item @var{out-of-band-record} @expansion{}
! @code{@var{async-record} | @var{stream-record}}

@item @var{async-record} @expansion{}
! @code{@var{exec-async-output} | @var{status-async-output} | @var{notify-async-output}}

@item @var{exec-async-output} @expansion{}
@code{[ @var{token} ] "*" @var{async-output}}
--- 224,233 ----
@code{ [ @var{token} ] "^" @var{result-class} ( "," @var{result} )* @var{nl}}

@item @var{out-of-band-record} @expansion{}
! @code{@var{async-record} | @var{stream-record}} | @var{event-record}

@item @var{async-record} @expansion{}
! @code{@var{exec-async-output} | @var{status-async-output}}

@item @var{exec-async-output} @expansion{}
@code{[ @var{token} ] "*" @var{async-output}}
*************** corresponding output for that command wi
*** 235,243 ****
@item @var{status-async-output} @expansion{}
@code{[ @var{token} ] "+" @var{async-output}}

- @item @var{notify-async-output} @expansion{}
- @code{[ @var{token} ] "=" @var{async-output}}
-
@item @var{async-output} @expansion{}
@code{@var{async-class} ( "," @var{result} )* @var{nl}}

--- 235,240 ----
*************** depending on the needs---this is still i
*** 279,284 ****
--- 276,291 ----
@item @var{log-stream-output} @expansion{}
@code{"&" @var{c-string}}

+ @item @var{event-record} @expansion{}
+ @code{"=" @var{event}}
+
+ @item @var{event} @expansion{}
+ @code{@var{event-class} ( "," @var{value} )*}
+
+ @item @var{event-class} @expansion{}
+ @xref{GDB/MI Event Records, , @sc{gdb/mi} Event Records}, for a list of
+ supported events.
+
@item @var{nl} @expansion{}
@code{CR | CR-LF}

*************** prefixed by @samp{+}.
*** 312,321 ****
@samp{*}.

@item
! @cindex notify output in @sc{gdb/mi}
! @var{notify-async-output} contains supplementary information that the
! client should handle (e.g., a new breakpoint information). All notify
! output is prefixed by @samp{=}.

@item
@cindex console output in @sc{gdb/mi}
--- 319,328 ----
@samp{*}.

@item
! @cindex events in @sc{gdb/mi}
! @var{event-record} contains supplementary information that the
! client should handle (e.g., a new breakpoint was inserted). All events
! are prefixed by @samp{=}.

@item
@cindex console output in @sc{gdb/mi}
*************** Here's an example of a simple CLI comman
*** 386,392 ****

@example
-> -symbol-file xyz.exe
! <- *breakpoint,nr="3",address="0x123",source="a.c:123"
<- (@value{GDBP})
@end example

--- 395,402 ----

@example
-> -symbol-file xyz.exe
! <- =breakpoint-create,number="3"
! <- ^done
<- (@value{GDBP})
@end example

*************** an un-supported hybrid of @sc{gdb/mi} an
*** 425,430 ****
--- 435,441 ----
* GDB/MI Result Records::
* GDB/MI Stream Records::
* GDB/MI Out-of-band Records::
+ * GDB/MI Event Records::
@end menu

@node GDB/MI Result Records
*************** additional changes that have occurred.
*** 492,501 ****
consequence of @sc{gdb/mi} (e.g., a breakpoint modified) or a result of
target activity (e.g., target stopped).

! The following is a preliminary list of possible out-of-band records.

@table @code
! @item "*" "stop"
@end table

--- 503,544 ----
consequence of @sc{gdb/mi} (e.g., a breakpoint modified) or a result of
target activity (e.g., target stopped).

! @node GDB/MI Event Records
! @subsection @sc{gdb/mi} Event Records
!
! @cindex event records in @sc{gdb/mi}
! @cindex @sc{gdb/mi}, event records
! @dfn{Event records} are used to notify the @sc{gdb/mi} client of any
! debugger state changes which may occur as a result of commands executed
! in @value{GDBN}. Events can be generated by any command, whether that command
! was executed in the @sc{gdb/mi} interpreter or the console interpreter.
!
! The following is a preliminary list of event records.

@table @code
! @item stop
! The inferior stopped.
! @c Need an example!
!
! @item breakpoint-create
! @item breakpoint-modify
! @item breakpoint-delete
! @item tracepoint-create
! @item tracepoint-modify
! @item tracepoint-delete
! A breakpoint or tracepoint was created, modified, or deleted. In all cases,
! the event will also report the @code{number} of the affected breakpoint/tracepoint:
! @example
! =breakpoint-create,number="1"
! @end example
!
! @item architecture-changed
! This event indicates that @value{GDBN} has changed architectures, and that
! the user interface may need to update certain views that are architecture-dependent,
! such as registers.
! @example
! =architecture-changed
! @end example
@end table

*************** The corresponding @value{GDBN} command i
*** 574,583 ****
@smallexample
(@value{GDBP})
-break-insert main
! ^done,bkpt=@{number="1",addr="0x000100d0",file="hello.c",line="5"@}
(@value{GDBP})
-break-after 1 3
! ~
^done
(@value{GDBP})
-break-list
--- 617,627 ----
@smallexample
(@value{GDBP})
-break-insert main
! =breakpoint-create,number="1"
! ^done
(@value{GDBP})
-break-after 1 3
! =breakpoint-modify,number="1"
^done
(@value{GDBP})
-break-list
*************** The corresponding @value{GDBN} command i
*** 626,631 ****
--- 670,676 ----
@smallexample
(@value{GDBP})
-break-condition 1 1
+ =breakpoint-modify,number="1"
^done
(@value{GDBP})
-break-list
*************** The corresponding @value{GDBN} command i
*** 663,668 ****
--- 708,714 ----
@example
(@value{GDBP})
-break-delete 1
+ =breakpoint-delete,number="1"
^done
(@value{GDBP})
-break-list
*************** The corresponding @value{GDBN} command i
*** 698,703 ****
--- 744,750 ----
@smallexample
(@value{GDBP})
-break-disable 2
+ =breakpoint-modify,number="2"
^done
(@value{GDBP})
-break-list
*************** The corresponding @value{GDBN} command i
*** 733,738 ****
--- 780,786 ----
@smallexample
(@value{GDBP})
-break-enable 2
+ =breakpoint-modify,number="2"
^done
(@value{GDBP})
-break-list
*************** given regular expression. Other flags a
*** 808,831 ****
expresson.
@end table

- @subsubheading Result
-
- The result is in the form:
-
- @example
- ^done,bkptno="@var{number}",func="@var{funcname}",
- file="@var{filename}",line="@var{lineno}"
- @end example
-
- @noindent
- where @var{number} is the @value{GDBN} number for this breakpoint, @var{funcname}
- is the name of the function where the breakpoint was inserted,
- @var{filename} is the name of the source file which contains this
- function, and @var{lineno} is the source line number within that file.
-
- Note: this format is open to change.
- @c An out-of-band breakpoint instead of part of the result?
-
@subsubheading @value{GDBN} Command

The corresponding @value{GDBN} commands are @samp{break}, @samp{tbreak},
--- 856,861 ----
*************** The corresponding @value{GDBN} commands
*** 836,845 ****
@smallexample
(@value{GDBP})
-break-insert main
! ^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@}
(@value{GDBP})
-break-insert -t foo
! ^done,bkpt=@{number="2",addr="0x00010774",file="recursive2.c",line="11"@}
(@value{GDBP})
-break-list
^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
--- 866,877 ----
@smallexample
(@value{GDBP})
-break-insert main
! =breakpoint-create,number="1"
! ^done
(@value{GDBP})
-break-insert -t foo
! =breakpoint-create,number="2"
! ^done
(@value{GDBP})
-break-list
^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
*************** addr="0x00010774",func="foo",file="recur
*** 856,862 ****
(@value{GDBP})
-break-insert -r foo.*
~int foo(int, int);
! ^done,bkpt=@{number="3",addr="0x00010774",file="recursive2.c",line="11"@}
(@value{GDBP})
@end smallexample

--- 888,895 ----
(@value{GDBP})
-break-insert -r foo.*
~int foo(int, int);
! =breakpoint-create,number="1"
! ^done
(@value{GDBP})
@end smallexample

*************** Setting a watchpoint on a variable in th
*** 965,971 ****
@smallexample
(@value{GDBP})
-break-watch x
! ^done,wpt=@{number="2",exp="x"@}
(@value{GDBP})
-exec-continue
^running
--- 998,1005 ----
@smallexample
(@value{GDBP})
-break-watch x
! =breakpoint-create,number="2"
! ^done
(@value{GDBP})
-exec-continue
^running
*************** for the watchpoint going out of scope.
*** 982,988 ****
@smallexample
(@value{GDBP})
-break-watch C
! ^done,wpt=@{number="5",exp="C"@}
(@value{GDBP})
-exec-continue
^running
--- 1016,1023 ----
@smallexample
(@value{GDBP})
-break-watch C
! =breakpoint-create,number="5"
! ^done
(@value{GDBP})
-exec-continue
^running
*************** deleted.
*** 1007,1013 ****
@smallexample
(@value{GDBP})
-break-watch C
! ^done,wpt=@{number="2",exp="C"@}
(@value{GDBP})
-break-list
^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
--- 1042,1049 ----
@smallexample
(@value{GDBP})
-break-watch C
! =breakpoint-create,number="2"
! ^done
(@value{GDBP})
-break-list
^done,BreakpointTable=@{nr_rows="2",nr_cols="6",