Re: [RFC/MI] Event Records vs Commands

[Keith Seitz <keiths at redhat dot com>]

On Sat, 15 Jun 2002, Andrew Cagney wrote:

> Try:
>
> ...want to document ``notify-async-output'' or (less likely?) replace it
> with ``event-async-output''.

This is the approach I've taken with my next attempt (which also includes
the fixes recommended by Eli, following the convention with two spaces
after @value{GDBN} -- if people want me to switch them all to use @., I
can submit separate patch for that).

> Async output is anything that isn't bound to ``^done'' et.al. >

But it seems to be bound to the prompt. Apple has changed their version so
that it is NOT bound to the prompt. We'll need to discuss this sometime
later.

Next round of comments, please.
Keith

Index: mi/gdbmi.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/mi/gdbmi.texinfo,v
retrieving revision 1.26
diff -p -r1.26 gdbmi.texinfo
*** mi/gdbmi.texinfo	25 Feb 2002 02:13:09 -0000	1.26
--- mi/gdbmi.texinfo	18 Jun 2002 18:26:24 -0000
*************** prefixed by @samp{+}.
*** 313,321 ****

  @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}
--- 313,321 ----

  @item
  @cindex notify output in @sc{gdb/mi}
! @var{notify-async-output} contains supplementary information (events) that the
! client should handle (e.g., a new breakpoint was inserted).  All notify
! 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

--- 388,395 ----

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

*************** 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


--- 495,526 ----
  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 out-of-band records.

  @table @code
! @item stop
! The inferior stopped.
! @c Need an example!
!
! @item breakpoint-create
! @itemx breakpoint-modify
! @itemx breakpoint-delete
! @itemx tracepoint-create
! @itemx tracepoint-modify
! @itemx 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:
! @smallexample
! =breakpoint-create,number="1"
! @end smallexample
!
! @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.
! @smallexample
! =architecture-changed
! @end smallexample
  @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
--- 599,609 ----
  @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 ****
--- 652,658 ----
  @smallexample
  (@value{GDBP})
  -break-condition 1 1
+ =breakpoint-modify,number="1"
  ^done
  (@value{GDBP})
  -break-list
*************** The corresponding @value{GDBN} command i
*** 663,668 ****
--- 690,696 ----
  @example
  (@value{GDBP})
  -break-delete 1
+ =breakpoint-delete,number="1"
  ^done
  (@value{GDBP})
  -break-list
*************** The corresponding @value{GDBN} command i
*** 698,703 ****
--- 726,732 ----
  @smallexample
  (@value{GDBP})
  -break-disable 2
+ =breakpoint-modify,number="2"
  ^done
  (@value{GDBP})
  -break-list
*************** The corresponding @value{GDBN} command i
*** 733,738 ****
--- 762,768 ----
  @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},
--- 838,843 ----
*************** 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",
--- 848,859 ----
  @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

--- 870,877 ----
  (@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
--- 980,987 ----
  @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
--- 998,1005 ----
  @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",
--- 1024,1031 ----
  @smallexample
  (@value{GDBP})
  -break-watch C
! =breakpoint-create,number="2"
! ^done
  (@value{GDBP})
  -break-list
  ^done,BreakpointTable=@{nr_rows="2",nr_cols="6",