[binutils-gdb] gdb/doc: Fix incorrect information in RSP doc

[binutils-gdb] gdb/doc: Fix incorrect information in RSP doc

[Ciaran Woodward]

https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;h=f908b93b48634083338eed5183ac519db8925b38

commit f908b93b48634083338eed5183ac519db8925b38
Author: Ciaran Woodward <ciaranwoodward@xmos.com>
Date:   Mon Apr 22 15:09:57 2024 +0000

    gdb/doc: Fix incorrect information in RSP doc
    
    The 'PacketSize' attribute of the qSupported packet was
    documented to be the maximum size of the packet including
    the frame and checksum bytes, however this is not how it
    was treated in the code. In reality, PacketSize is the
    maximum size of the data in the RSP packets, not including
    the framing or checksum bytes.
    
    For instance, GDB's remote.c treats it as the maximum
    number of data bytes.  See remote_read_bytes_1, where the
    size of the request is capped at PacketSize/2 (for
    hex-encoding).
    
    Also see gdbserver's server.cc, where the internal buffer
    is sized as PBUFSIZ and PBUFSIZ-1 is used as PacketSize.
    In gdbserver's case, the buffer is not used for any of the
    framing or checksum characters. (I am not certain where the -1
    comes from. I think it comes from back when there were no
    binary packets, so packets were treated as strings with
    null terminators).
    
    It also seems like gdbservers in the wild treat it in
    this way:
    
    Embocosm doc:
    https://www.embecosm.com/appnotes/ean4/embecosm-howto-rsp-server-ean4-issue-2.html#id3078000
    
    A quick glance over openocd's gdb_server.c gdb_put_packet_inner()
    function shows that the internal buffer also excludes the framing
    and checksum.
    
    Likewise, qEmu's gdbstub.c allocates PacketSize bytes for
    the internal packet contents, and PacketSize+4 for the
    full frame.
    
    Reviewed-By: Eli Zaretskii <eliz@gnu.org>
    Approved-By: Pedro Alves <pedro@palves.net>

Diff:
---
 gdb/doc/gdb.texinfo | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 31a531ee992..b2e9faac82d 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -44953,7 +44953,7 @@ These are the currently defined stub features, in more detail:
 The remote stub can accept packets up to at least @var{bytes} in
 length.  @value{GDBN} will send packets up to this size for bulk
 transfers, and will never send larger packets.  This is a limit on the
-data characters in the packet, including the frame and checksum.
+data characters in the packet, not including the frame and checksum.
 There is no trailing NUL byte in a remote protocol packet; if the stub
 stores packets in a NUL-terminated format, it should allow an extra
 byte in its buffer for the NUL.  If this stub feature is not supported,