[binutils-gdb] Document conventions for describing packet syntax

[binutils-gdb] Document conventions for describing packet syntax

[Pedro Alves]

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

commit aef11345e4be223ed1094b67179746dc3c8b9821
Author: Pedro Alves <pedro@palves.net>
Date:   Thu Apr 18 20:22:36 2024 +0100

    Document conventions for describing packet syntax
    
    This comment documents conventions for describing packet syntax in the
    Overview section.
    
    Change-Id: I96198592601b24c983da563d143666137e4d0a4e
    Co-Authored-By: Jim Blandy <jimb@codesourcery.com>
    Co-Authored-By: Mike Wrighton <mike_wrighton@mentor.com>
    Co-Authored-By: Nathan Sidwell <nathan@codesourcery.com>
    Co-Authored-By: Hafiz Abid Qadeer <abidh@codesourcery.com>
    Approved-By: Eli Zaretskii <eliz@gnu.org>

Diff:
---
 gdb/doc/gdb.texinfo | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index b2e9faac82d..d7b8b3f1b61 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -42517,6 +42517,22 @@ For any @var{command} not supported by the stub, an empty response
 protocol.  A newer @value{GDBN} can tell if a packet is supported based
 on that response.
 
+In describing packets (commands and responses), each description has a
+template showing the overall syntax, followed by an explanation of the
+packet's meaning.  We include spaces in some of the templates for
+clarity; these are not part of the packet's syntax.  No @value{GDBN}
+packet uses spaces to separate its components.  For example, a
+template like @samp{foo @var{bar} @var{baz}} describes a packet
+beginning with the three ASCII bytes @samp{foo}, followed by a
+@var{bar}, followed directly by a @var{baz}.  @value{GDBN} does not
+transmit a space character between the @samp{foo} and the @var{bar},
+or between the @var{bar} and the @var{baz}.
+
+We place optional portions of a packet in [square brackets];
+for example, a template like @samp{c @r{[}@var{addr}@r{]}} describes a
+packet beginning with the single ASCII character @samp{c}, possibly
+followed by an @var{addr}.
+
 At a minimum, a stub is required to support the @samp{?} command to
 tell @value{GDBN} the reason for halting, @samp{g} and @samp{G}
 commands for register access, and the @samp{m} and @samp{M} commands