Re: [PATCH] Add autoload-breakpoints [3/7] ReportAsync-doc

[Hui Zhu <hui_zhu@mentor.com>]

[-- Attachment #1: Type: text/plain, Size: 3704 bytes --]

Hi Eli,

I post a new version patch according to your mail.  Please help me review.

Thanks,
Hui

2012-03-26  Hui Zhu  <hui_zhu@mentor.com>

	* gdb.texinfo (qSupported): Add ReportAsync.
	(Remote Serial Protocol): Add ReportAsync Packets.

On 03/22/12 10:48, Hui Zhu wrote:
> On 03/22/12 02:27, Eli Zaretskii wrote:
>>> Date: Wed, 21 Mar 2012 15:23:02 +0800
>>> From: Hui Zhu<hui_zhu@mentor.com>
>>> CC:<gdb-patches@sourceware.org>,<stan_shebs@mentor.com>
>>>
>>>>>>> +The @value{GDBN} remote serial protocol includes @dfn{reportasync},
>>>>>>> +packets that the stub can report status or do an operation in
>>>>>>> any time.
>>>>>>
>>>>>> I don't understand the "do an operation in any time" part. What does
>>>>>> it mean in practice?
>>>>>
>>>>> It is means that after gdb connected with the stub, the stub can
>>>>> report
>>>>> when the inferior is running and GDB is waiting it, or inferior is
>>>>> stoped and GDB just control it.
>>>>> It make the stub can report the status for any time.
>>>>
>>>> You mean, as in "asynchronously"?
>>>
>>> Yes, that is my mean.
>>
>> Then please use
>>
>> The @value{GDBN} remote serial protocol supports @dfn{reportasync}
>> that can be used asynchronously to report status or send commands.
>>
>>>> I still don't understand why you used the word "simple". "Simple" as
>>>> opposed to what other packet handling?
>>>
>>> Maybe "normal" is better. "Normal" as opposed to reportasync packets.
>>
>> "As usual" or "usual" would be better. But see below.
>>
>>>>>> After the handshake, the stub can send @samp{reportasync} packets to
>>>>>> @value{GDBN}, using the same packet format as in simple remote serial
>>>>>> protocol.
>>>>>>
>>>>>> Is this only for the failed handshake? If so, perhaps we need to tell
>>>>>> what happens when the handshake succeeds.
>>>>>
>>>>> No, this is for success.
>>>>
>>>> The problem here is that you again used "simple protocol", and before
>>>> that you mentioned "simple packet" when the handshake failed.
>>>>
>>>> So this again boils down to the same question: why do you use the word
>>>> "simple" in this context?
>>>
>>> Yes, it looks really odd even if change it to normal. That is because
>>> after shakes mode, the packet will use the normal format
>>
>> But you said
>>
>> After the handshake, the stub can send @samp{reportasync} packets to
>> @value{GDBN}, using the same packet format as in simple remote serial
>> protocol.
>>
>> which actually tells me that the "normal" packets are _not_ in
>> contrast with reportasync packets, since reportasync packets can be
>> sent in the "normal format". What am I missing?
>
> Yes, after success shake hands, the stub will send packet in normal
> format to GDB.
> If need, GDB will answer this packets in normal format.
>
> For example:
> static void
> remote_reportasync_handler (struct remote_state *rs)
> {
> int len;
> struct cleanup *old_chain
> = make_cleanup_restore_integer (&inside_reportasync_handler);
>
> /* Shake hands with remote part. */
> serial_write (remote_desc, "^", 1);
>
> inside_reportasync_handler = 1;
>
> if (getpkt_sane (&rs->buf, &rs->buf_size, 0) < 0)
> return;
>
> if (remote_debug)
> fprintf_unfiltered (gdb_stdlog, "ReportAsync: %s\n", rs->buf);
>
> if (strncmp (rs->buf, "QBDP", strlen ("QBDP")) == 0)
> {
> if (parse_autoload_breakpoint_definition_to_breakpoints
> (rs->buf + strlen ("QBDP")) == 0)
> putpkt ("OK");
> else
> putpkt ("E01");
> }
> else
> putpkt ("");
>
> do_cleanups (old_chain);
> }
>
> This function will be call when GDB got a ^ and is OK to shake hands.
> It call serial_write (remote_desc, "^", 1); to shake hands. Then call
> getpkt_sane to get the package from the stub. And use putpkt reply.
>
> Thanks,
> Hui



[-- Attachment #2: report-doc.txt --]
[-- Type: text/plain, Size: 1554 bytes --]

---
 doc/gdb.texinfo |   23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

--- a/doc/gdb.texinfo
+++ b/doc/gdb.texinfo
@@ -33661,6 +33661,7 @@ Show the current setting of the target w
 * Host I/O Packets::
 * Interrupts::
 * Notification Packets::
+* ReportAsync Packets::
 * Remote Non-Stop::
 * Packet Acknowledgment::
 * Examples::
@@ -35567,6 +35568,10 @@ to be enabled and disabled while a trace
 The remote stub supports the @samp{tracenz} bytecode for collecting strings.
 See @ref{Bytecode Descriptions} for details about the bytecode.
 
+@item ReportAsync
+The remote stub supports the @samp{ReportAsync} packet
+(@pxref{ReportAsync Packets}).
+
 @end table
 
 @item qSymbol::
@@ -36664,6 +36669,24 @@ for information on how these notificatio
 @value{GDBN}.
 @end table
 
+@node ReportAsync Packets
+@section ReportAsync Packets
+@cindex reportasync packets
+@cindex packets, reportasync
+
+The @value{GDBN} remote serial protocol supports @dfn{reportasync}
+that can be used asynchronously to report status or send commands.
+
+When the stub want send @dfn{reportasync} packets, it send shake hands
+packet @samp{^} to @value{GDBN}.
+If @value{GDBN} replies with a @samp{^}, the handshake is successful.
+If not, the handshake fails, and the @samp{reportasync} packet needs
+to be handled as usual.
+
+After the handshake, the stub can send @samp{reportasync} packets to
+@value{GDBN}, using the same packet format as in normal remote serial
+protocol.
+
 @node Remote Non-Stop
 @section Remote Protocol Support for Non-Stop Mode