From aef11345e4be223ed1094b67179746dc3c8b9821 Mon Sep 17 00:00:00 2001 From: Pedro Alves Date: Thu, 18 Apr 2024 20:22:36 +0100 Subject: [PATCH] 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 Co-Authored-By: Mike Wrighton Co-Authored-By: Nathan Sidwell Co-Authored-By: Hafiz Abid Qadeer Approved-By: Eli Zaretskii --- 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