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

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

[Hui Zhu]

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

Hi,

This is patch for the doc about ReportAsync.

Thanks,
Hui

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

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

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

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

--- a/doc/gdb.texinfo
+++ b/doc/gdb.texinfo
@@ -33568,6 +33568,7 @@ Show the current setting of the target w
 * Host I/O Packets::
 * Interrupts::
 * Notification Packets::
+* ReportAsync Packets::
 * Remote Non-Stop::
 * Packet Acknowledgment::
 * Examples::
@@ -35474,6 +35475,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::
@@ -36571,6 +36576,26 @@ 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 includes @dfn{reportasync},
+packets that the stub can report status or do an operation in any time.
+If the stub supports @dfn{reportasync}, it should report that to
+@value{GDBN} by including @samp{ReportAsync+} in its @samp{qSupported}
+response (@pxref{qSupported}).
+
+When the stub want send @dfn{reportasync} packets, it send shake hands
+packet @samp{^} to @value{GDBN}.
+If @value{GDBN} reply a @samp{^}, the shake hands is successful.
+If not, the shake hands is fail and this packet need to be handle
+as a simple packet.
+
+After shake hands, the stub can send packet to @value{GDBN}, the packet
+format is same with simple remote serial protocol.
+
 @node Remote Non-Stop
 @section Remote Protocol Support for Non-Stop Mode
 

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

[Eli Zaretskii]

> Date: Sat, 17 Mar 2012 16:52:34 +0800
> From: Hui Zhu <hui_zhu@mentor.com>
> CC: Stan Shebs <stan_shebs@mentor.com>
> 
> This is patch for the doc about ReportAsync.

Thanks.

> +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?

> +When the stub want send @dfn{reportasync} packets, it send shake hands
> +packet @samp{^} to @value{GDBN}.

 When the stub wants to send a @samp{reportasync} packet, it first sends
 a handshake packet @samp{^} to @value{GDBN}.

> +If @value{GDBN} reply a @samp{^}, the shake hands is successful.

 If @value{GDBN} replies with a @samp{^}, the handshake is successful.

> +If not, the shake hands is fail and this packet need to be handle
> +as a simple packet.

 If not, the handshake fails, and the @samp{reportasync} packet needs
 to be handled as a simple packet.

And I don't understand what you mean by "needs to be handled as a
simple packet".  If that's a reference to something discussed earlier
in the manual, please add here a cross-reference to that part.

> +After shake hands, the stub can send packet to @value{GDBN}, the packet
> +format is same with simple remote serial protocol.

 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.

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

[Hui Zhu]

Hi Eli,

Thank you for your help.

On 03/17/12 18:12, Eli Zaretskii wrote:
>> Date: Sat, 17 Mar 2012 16:52:34 +0800
>> From: Hui Zhu<hui_zhu@mentor.com>
>> CC: Stan Shebs<stan_shebs@mentor.com>
>>
>> This is patch for the doc about ReportAsync.
>
> Thanks.
>
>> +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.

I didn't have good words on this part to make it more clear.  Could you 
help me with it?

>
>   When the stub wants to send a @samp{reportasync} packet, it first sends
>   a handshake packet @samp{^} to @value{GDBN}.
>
>> +If @value{GDBN} reply a @samp{^}, the shake hands is successful.
>
>   If @value{GDBN} replies with a @samp{^}, the handshake is successful.
>
>> +If not, the shake hands is fail and this packet need to be handle
>> +as a simple packet.
>
>   If not, the handshake fails, and the @samp{reportasync} packet needs
>   to be handled as a simple packet.

I will fix them.

>
> And I don't understand what you mean by "needs to be handled as a
> simple packet".  If that's a reference to something discussed earlier
> in the manual, please add here a cross-reference to that part.

That means when the stub send a shake hands package ^ and wait the 
reply, if it got a package that is not ^.  Then the shake hands is fail. 
  It need give up this shake hands and begin to handle this packet that 
it just get.
For example:
Stub send a ^ to GDB.  It readchar, and got a $.  It should not drop 
this $, After that, it will got "c#csum".  It need handle the package 
"$c#csum".
My words in the doc is not very clear, could you help me with it?

>
>> +After shake hands, the stub can send packet to @value{GDBN}, the packet
>> +format is same with simple remote serial protocol.
>
>   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.
What about I change it to:
After the handshake success, the stub can send @samp{reportasync} 
packets to @value{GDBN}, using the same packet format as in simple 
remote serial protocol.

Best,
Hui

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

[Eli Zaretskii]

> Date: Tue, 20 Mar 2012 21:25:07 +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"?

> > And I don't understand what you mean by "needs to be handled as a
> > simple packet".  If that's a reference to something discussed earlier
> > in the manual, please add here a cross-reference to that part.
> 
> That means when the stub send a shake hands package ^ and wait the 
> reply, if it got a package that is not ^.  Then the shake hands is fail. 
>   It need give up this shake hands and begin to handle this packet that 
> it just get.
> For example:
> Stub send a ^ to GDB.  It readchar, and got a $.  It should not drop 
> this $, After that, it will got "c#csum".  It need handle the package 
> "$c#csum".

I still don't understand why you used the word "simple".  "Simple" as
opposed to what other packet handling?

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

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

[Hui Zhu]

On 03/21/12 01:30, Eli Zaretskii wrote:
>> Date: Tue, 20 Mar 2012 21:25:07 +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.

>
>>> And I don't understand what you mean by "needs to be handled as a
>>> simple packet".  If that's a reference to something discussed earlier
>>> in the manual, please add here a cross-reference to that part.
>>
>> That means when the stub send a shake hands package ^ and wait the
>> reply, if it got a package that is not ^.  Then the shake hands is fail.
>>    It need give up this shake hands and begin to handle this packet that
>> it just get.
>> For example:
>> Stub send a ^ to GDB.  It readchar, and got a $.  It should not drop
>> this $, After that, it will got "c#csum".  It need handle the package
>> "$c#csum".
>
> 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.

>
>>>    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 in 
http://sourceware.org/gdb/current/onlinedocs/gdb/Overview.html.
The only different is:
If the shake hands mode fail, the packet will from GDB to the stub.
If the shake hands mode success, the packet will from the stub to GDB.

Thanks,
Hui

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

[Eli Zaretskii]

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

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

[Hui Zhu]

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

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

[Hui Zhu]

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

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

[Eli Zaretskii]

> Date: Mon, 26 Mar 2012 10:21:04 +0800
> From: Hui Zhu <hui_zhu@mentor.com>
> CC: <gdb-patches@sourceware.org>, <stan_shebs@mentor.com>
> 
> +When the stub want send @dfn{reportasync} packets, it send shake hands
> +packet @samp{^} to @value{GDBN}.

 When the stub wants to send @dfn{reportasync} packets, it should
 first send a handshake packet @samp{^} to @value{GDBN}.

OK with this change.

Thanks.

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

[Hui Zhu]

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

On 03/31/12 14:03, Eli Zaretskii wrote:
>> Date: Mon, 26 Mar 2012 10:21:04 +0800
>> From: Hui Zhu<hui_zhu@mentor.com>
>> CC:<gdb-patches@sourceware.org>,<stan_shebs@mentor.com>
>>
>> +When the stub want send @dfn{reportasync} packets, it send shake hands
>> +packet @samp{^} to @value{GDBN}.
>
>   When the stub wants to send @dfn{reportasync} packets, it should
>   first send a handshake packet @samp{^} to @value{GDBN}.
>
> OK with this change.
>
> Thanks.

Thanks for your help.  I post a new version that is updated according to 
your comments.

Best,
Hui

2012-04-02  Hui Zhu  <hui_zhu@mentor.com>

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

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

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

--- a/doc/gdb.texinfo
+++ b/doc/gdb.texinfo
@@ -33669,6 +33669,7 @@ Show the current setting of the target w
 * Host I/O Packets::
 * Interrupts::
 * Notification Packets::
+* ReportAsync Packets::
 * Remote Non-Stop::
 * Packet Acknowledgment::
 * Examples::
@@ -35575,6 +35576,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::
@@ -36672,6 +36677,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 wants to send @dfn{reportasync} packets, it should
+first send a handshake 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