From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-lj1-f170.google.com (mail-lj1-f170.google.com [209.85.208.170]) by sourceware.org (Postfix) with ESMTPS id 25FBD3849ACC for ; Fri, 19 Apr 2024 15:13:53 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 25FBD3849ACC Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=palves.net Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=gmail.com ARC-Filter: OpenARC Filter v1.0.0 sourceware.org 25FBD3849ACC Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=209.85.208.170 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1713539638; cv=none; b=C9lH6KUc+cwpeXkO12yPzpz3IKwmSap2j1OrBzNMSfaKOJFPXbfPQPqDeqqPnWMQkrf5q2elYYyPlkdyxUt4XjYaXBGbFdKS1Zwf8LzGcRLTaHsWJKwZc2SBpso1j4MD/ckCNs83uHXYkWsSLu1OivhN9ldDEAMFP7glmXcc3Vg= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1713539638; c=relaxed/simple; bh=B6IqXihE2g+iWHFa0soxhah/j/0QO11E+9PuN8Eb//s=; h=From:To:Subject:Date:Message-ID:MIME-Version; b=UkClkltnedDX9BrC63SwpOadljUizbSGkcQB7Kmiw571SOEQHMNxoDPGcM6Ky1ucLTFQ5Pv2KlBIgrW1OHeJV+y7W5YwNskirEfcbEqBJ56Jr5uNeW22GGK4XR561wuUIMRt6YWTVwvaZYRq0h7IAXuGeuyW//ZzywLTC75j7ug= ARC-Authentication-Results: i=1; server2.sourceware.org Received: by mail-lj1-f170.google.com with SMTP id 38308e7fff4ca-2d9fe2b37acso28810241fa.2 for ; Fri, 19 Apr 2024 08:13:53 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1713539631; x=1714144431; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=uOheCFjcSjFkiA9M4GQ40PF3mK1k0NPOHIRl/keocrc=; b=T8G9570ndAQSLAtCVUvM4IbK0sNbjUjndn8+7WKEFM1HC5VBS8F4SNHeXXUayB+Ez9 9IqaawQnkYtY4y5Fu2dey+ouLGxSXMipPgvEMz43OR2T4vyhKUpYWxru44jCupacXkGG qKFCiO7asWs7y9q3uWNivfyXzHojxdXdcSvfltnIzGmEoh48cpHAOUEmmil1Q84gZjlY e4nQ8+pqA9vqKCJe3vyf6cgxFxBk/t4uGwIW6EqnEKMfd4GniMXJa4oY1ysS/aKEPuZn qZUdLi1oeCau6ze9GWVZCPi+uLqabICnk/QrFr+D/i0bcIVlZVnPks0L16SAzMD6X8X7 R2kQ== X-Gm-Message-State: AOJu0Yx25bpPlRA0NfHZRzRtuuFNndVqfQagua7RCIlU8BA2R+I3lEGm Fp5R2RyAX02dvDXct+sqgSrvrUVYXGJ58TxPFheIhqJMNjcqOhot1xD09mAy X-Google-Smtp-Source: AGHT+IHoRTbdeZ/0H8YPRTroh1fayuZzfVSrza97cwY+lwDCMfwlswCEDEvT+DCkH7wZHtlNBcDC4Q== X-Received: by 2002:a2e:a682:0:b0:2db:7b:1a7b with SMTP id q2-20020a2ea682000000b002db007b1a7bmr1372595lje.46.1713539630665; Fri, 19 Apr 2024 08:13:50 -0700 (PDT) Received: from localhost ([2001:8a0:f93d:b900:2438:d637:5572:c30a]) by smtp.gmail.com with UTF8SMTPSA id a12-20020a056000100c00b00349ceadededsm4678316wrx.16.2024.04.19.08.13.49 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Fri, 19 Apr 2024 08:13:50 -0700 (PDT) From: Pedro Alves To: gdb-patches@sourceware.org Cc: Jim Blandy , Mike Wrighton , Nathan Sidwell , Hafiz Abid Qadeer Subject: [PATCH 02/12] Centralize documentation of error and empty RSP responses Date: Fri, 19 Apr 2024 16:13:32 +0100 Message-ID: <20240419151342.1592474-3-pedro@palves.net> X-Mailer: git-send-email 2.43.2 In-Reply-To: <20240419151342.1592474-1-pedro@palves.net> References: <20240419151342.1592474-1-pedro@palves.net> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Spam-Status: No, score=-10.3 required=5.0 tests=BAYES_00,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM,GIT_PATCH_0,HEADER_FROM_DIFFERENT_DOMAINS,KAM_DMARC_STATUS,RCVD_IN_DNSWL_NONE,RCVD_IN_MSPIKE_H2,SPF_HELO_NONE,SPF_PASS,TXREP autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org List-Id: Currently, for each packet, we document the "E NN" response (error), and the empty response (unsupported). This patch centralizes that in a new "Standard Replies" section. In the "Packets", "General Query Packets", "Tracepoint Packets" sections, Remove explicit mention of empty and error replies, except when they provide detail not covered in Standard Replies. Note this hunk: -@item E @var{NN} -@var{NN} is errno and this one: -@item E00 -The request was malformed, or @var{annex} was invalid. - -@item E @var{nn} -The offset was invalid, or there was an error encountered reading the data. -The @var{nn} part is a hex-encoded @code{errno} value. were really documenting things that don't really work that way. The first is the documentation of the "m" packet. GDB does _not_ interpret the NN as an errno. It can't, in fact, because the remote/target errno numbers have nothing to do with GDB/host errno numbers in a cross debugging scenario. The second hunk above is from the documentation of qXfer. Again, GDB does not give any interpretation to the NN error code at all. Nor does GDBserver. And again, an errno number can't be interpreted in a cross debugging scenario. Change-Id: I973695c80809cdb5a5e8d5be8b78ba4d1ecdb513 Co-Authored-By: Jim Blandy Co-Authored-By: Mike Wrighton Co-Authored-By: Nathan Sidwell Co-Authored-By: Hafiz Abid Qadeer --- gdb/doc/gdb.texinfo | 244 +++++++------------------------------------- 1 file changed, 36 insertions(+), 208 deletions(-) diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index e9d54527c90..57260a5b2fa 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -40242,8 +40242,6 @@ The @var{gdb_jump_pad_head} is updated head of jumppad. Both of @var{target_address} and @var{gdb_jump_pad_head} are 8-byte long. The @var{fjump} contains a sequence of instructions jump to jumppad entry. The @var{fjump_size}, 4-byte long, is the size of @var{fjump}. -@item E @var{NN} -for an error @end table @@ -40262,8 +40260,6 @@ Asks in-process agent to probe the marker at @var{address}. Replies: @table @samp -@item E @var{NN} -for an error @end table @item unprobe_marker_at:@var{address} Asks in-process agent to unprobe the marker at @var{address}. @@ -42368,6 +42364,7 @@ Show the current setting of the target wait timeout. @menu * Overview:: +* Standard Replies:: * Packets:: * Stop Reply Packets:: * General Query Packets:: @@ -42508,14 +42505,8 @@ seven repeats (@samp{$}) can be expanded using a repeat count of only five (@samp{"}). For example, @samp{00000000} can be encoded as @samp{0*"00}. -The error response returned for some packets includes a two character -error number. That number is not well defined. - -@cindex empty response, for unsupported packets -For any @var{command} not supported by the stub, an empty response -(@samp{$#00}) should be returned. That way it is possible to extend the -protocol. A newer @value{GDBN} can tell if a packet is supported based -on that response. +See @ref{Standard Replies} for standard error responses, and how to +respond indicating a packet is not supported. In describing packets (and responses), each description has a template showing the overall syntax, followed by an explanation of the packet's @@ -42543,6 +42534,31 @@ the @samp{s} (step) command. Stubs that support multi-threading targets should support the @samp{vCont} command. All other commands are optional. +@node Standard Replies +@section Standard Replies + +The remote protocol specifies a few standard replies. All commands +support these, except as noted in the individual command descriptions. + +@table @asis + +@item empty response + +@cindex empty response, for unsupported packets +@cindex unsupported packets, empty response for +For any @var{command} not supported by the stub, an empty response +(@samp{$#00}) should be returned. That way it is possible to extend the +protocol. A newer @value{GDBN} can tell if a packet is supported based +on that response (but see also @ref{qSupported}). + +@item @samp{E @var{xx}} +An error has occurred; @var{xx} is a two-digit hexadecimal error +number. In almost all cases, the protocol does not specify the +meaning of the error numbers; @value{GDBN} usually ignores the +numbers, or displays them to the user without further interpretation. + +@end table + @node Packets @section Packets @@ -42630,8 +42646,6 @@ Reply: @table @samp @item OK The arguments were set. -@item E @var{NN} -An error occurred. @end table @item b @var{baud} @@ -42720,8 +42734,6 @@ Reply: @table @samp @item OK for success -@item E @var{NN} -for an error @end table @item F @var{RC},@var{EE},@var{CF};@var{XX} @@ -42768,8 +42780,6 @@ are available, and both have zero value: <- @code{xxxxxxxx00000000xxxxxxxx00000000} @end smallexample -@item E @var{NN} -for an error. @end table @item G @var{XX@dots{}} @@ -42781,8 +42791,6 @@ Reply: @table @samp @item OK for success -@item E @var{NN} -for an error @end table @item H @var{op} @var{thread-id} @@ -42799,8 +42807,6 @@ Reply: @table @samp @item OK for success -@item E @var{NN} -for an error @end table @c FIXME: JTC: @@ -42875,8 +42881,6 @@ Reply: Memory contents; each byte is transmitted as a two-digit hexadecimal number. The reply may contain fewer addressable memory units than requested if the server was able to read only part of the region of memory. -@item E @var{NN} -@var{NN} is errno @end table @item M @var{addr},@var{length}:@var{XX@dots{}} @@ -42888,10 +42892,8 @@ byte is transmitted as a two-digit hexadecimal number. Reply: @table @samp @item OK -for success -@item E @var{NN} -for an error (this includes the case where only part of the data was -written). +All the data was written successfully. (If only part of the data was +written, this command returns an error.) @end table @item p @var{n} @@ -42904,10 +42906,6 @@ Reply: @table @samp @item @var{XX@dots{}} the register's value -@item E @var{NN} -for an error -@item @w{} -Indicating an unrecognized @var{query}. @end table @item P @var{n@dots{}}=@var{r@dots{}} @@ -42921,8 +42919,6 @@ Reply: @table @samp @item OK for success -@item E @var{NN} -for an error @end table @item q @var{name} @var{params}@dots{} @@ -42982,8 +42978,6 @@ Reply: @table @samp @item OK thread is still alive -@item E @var{NN} -thread is dead @end table @item v @@ -43011,8 +43005,6 @@ This packet is only available in extended mode (@pxref{extended mode}). Reply: @table @samp -@item E @var{nn} -for an error @item @r{Any stop packet} for success in all-stop mode (@pxref{Stop Reply Packets}) @item OK @@ -43101,8 +43093,6 @@ Reply: @item vCont@r{[};@var{action}@dots{}@r{]} The @samp{vCont} packet is supported. Each @var{action} is a supported command in the @samp{vCont} packet. -@item @w{} -The @samp{vCont} packet is not supported. @end table @anchor{vCtrlC packet} @@ -43117,8 +43107,6 @@ variant. Reply: @table @samp -@item E @var{nn} -for an error @item OK for success @end table @@ -43143,8 +43131,6 @@ Reply: @table @samp @item OK for success -@item E @var{NN} -for an error @end table @item vFlashWrite:@var{addr}:@var{XX@dots{}} @@ -43167,8 +43153,6 @@ Reply: for success @item E.memtype for vFlashWrite addressing non-flash memory -@item E @var{NN} -for an error @end table @item vFlashDone @@ -43190,8 +43174,6 @@ supported; see @ref{multiprocess extensions}. Reply: @table @samp -@item E @var{nn} -for an error @item OK for success @end table @@ -43223,8 +43205,6 @@ This packet is only available in extended mode (@pxref{extended mode}). Reply: @table @samp -@item E @var{nn} -for an error @item @r{Any stop packet} for success (@pxref{Stop Reply Packets}) @end table @@ -43245,8 +43225,6 @@ Reply: @table @samp @item OK for success -@item E @var{NN} -for an error @end table @item z @var{type},@var{addr},@var{kind} @@ -43327,10 +43305,6 @@ Reply: @table @samp @item OK success -@item @w{} -not supported -@item E @var{NN} -for an error @end table @item z1,@var{addr},@var{kind} @@ -43352,10 +43326,6 @@ Reply: @table @samp @item OK success -@item @w{} -not supported -@item E @var{NN} -for an error @end table @item z2,@var{addr},@var{kind} @@ -43369,10 +43339,6 @@ Reply: @table @samp @item OK success -@item @w{} -not supported -@item E @var{NN} -for an error @end table @item z3,@var{addr},@var{kind} @@ -43386,10 +43352,6 @@ Reply: @table @samp @item OK success -@item @w{} -not supported -@item E @var{NN} -for an error @end table @item z4,@var{addr},@var{kind} @@ -43403,10 +43365,6 @@ Reply: @table @samp @item OK success -@item @w{} -not supported -@item E @var{NN} -for an error @end table @end table @@ -43776,8 +43734,6 @@ detect trailing zeros. Reply: @table @samp -@item E @var{NN} -An error (such as memory fault) @item C @var{crc32} The specified memory region's checksum is @var{crc32}. @end table @@ -43800,13 +43756,6 @@ Reply: @table @samp @item OK The request succeeded. - -@item E @var{nn} -An error occurred. The error number @var{nn} is given as hex digits. - -@item @w{} -An empty reply indicates that @samp{QDisableRandomization} is not supported -by the stub. @end table This packet is not probed by default; the remote stub must request it, @@ -43835,9 +43784,6 @@ Reply: @table @samp @item OK The request succeeded. - -@item E @var{nn} -An error occurred. The error number @var{nn} is given as hex digits. @end table This packet is not probed by default; the remote stub must request it, @@ -44027,12 +43973,6 @@ Reply: @item @var{XX}@dots{} Hex encoded (big endian) bytes representing the address of the thread local storage requested. - -@item E @var{nn} -An error occurred. The error number @var{nn} is given as hex digits. - -@item @w{} -An empty reply indicates that @samp{qGetTLSAddr} is not supported by the stub. @end table @item qGetTIBAddr:@var{thread-id} @@ -44047,13 +43987,6 @@ Reply: @item @var{XX}@dots{} Hex encoded (big endian) bytes representing the linear address of the thread information block. - -@item E @var{nn} -An error occurred. This means that either the thread was not found, or the -address could not be retrieved. - -@item @w{} -An empty reply indicates that @samp{qGetTIBAddr} is not supported by the stub. @end table @item qL @var{startflag} @var{threadcount} @var{nextthread} @@ -44093,20 +44026,15 @@ is architecture-specific. @var{type} is the type of tag the request wants to fetch. The type is a signed integer. +@value{GDBN} will only send this packet if the stub has advertised +support for memory tagging via @samp{qSupported}. + Reply: @table @samp @item @var{mxx}@dots{} Hex encoded sequence of uninterpreted bytes, @var{xx}@dots{}, representing the tags found in the requested memory range. -@item E @var{nn} -An error occurred. This means that fetching of memory tags failed for some -reason. - -@item @w{} -An empty reply indicates that @samp{qMemTags} is not supported by the stub, -although this should not happen given @value{GDBN} will only send this packet -if the stub has advertised support for memory tagging via @samp{qSupported}. @end table @cindex check if a given address is in a memory tagged region @@ -44171,20 +44099,14 @@ integer. interpreted by the target. Each pair of hex digits is interpreted as a single byte. +@value{GDBN} will only send this packet if the stub has advertised +support for memory tagging via @samp{qSupported}. + Reply: @table @samp @item OK The request was successful and the memory tag granules were modified accordingly. - -@item E @var{nn} -An error occurred. This means that modifying the memory tag granules failed -for some reason. - -@item @w{} -An empty reply indicates that @samp{QMemTags} is not supported by the stub, -although this should not happen given @value{GDBN} will only send this packet -if the stub has advertised support for memory tagging via @samp{qSupported}. @end table @item qOffsets @@ -44241,13 +44163,6 @@ Reply: @table @samp @item OK The request succeeded. - -@item E @var{nn} -An error occurred. The error number @var{nn} is given as hex digits. - -@item @w{} -An empty reply indicates that @samp{QNonStop} is not supported by -the stub. @end table This packet is not probed by default; the remote stub must request it, @@ -44284,13 +44199,6 @@ Reply: @table @samp @item OK The request succeeded. - -@item E @var{nn} -An error occurred. @var{nn} are hex digits. - -@item @w{} -An empty reply indicates that @samp{QCatchSyscalls} is not supported by -the stub. @end table Use of this packet is controlled by the @code{set remote catch-syscalls} @@ -44316,13 +44224,6 @@ Reply: @table @samp @item OK The request succeeded. - -@item E @var{nn} -An error occurred. The error number @var{nn} is given as hex digits. - -@item @w{} -An empty reply indicates that @samp{QPassSignals} is not supported by -the stub. @end table Use of this packet is controlled by the @code{set remote pass-signals} @@ -44358,13 +44259,6 @@ Reply: @table @samp @item OK The request succeeded. - -@item E @var{nn} -An error occurred. The error number @var{nn} is given as hex digits. - -@item @w{} -An empty reply indicates that @samp{QProgramSignals} is not supported -by the stub. @end table Use of this packet is controlled by the @code{set remote program-signals} @@ -44398,13 +44292,6 @@ Reply: @table @samp @item OK The request succeeded. - -@item E @var{nn} -An error occurred. The error number @var{nn} is given as hex digits. - -@item @w{} -An empty reply indicates that @samp{QThreadEvents} is not supported by -the stub. @end table Use of this packet is controlled by the @code{set remote thread-events} @@ -44487,13 +44374,6 @@ Reply: @table @samp @item OK The request succeeded. - -@item E @var{nn} -An error occurred. The error number @var{nn} is given as hex digits. - -@item @w{} -An empty reply indicates that @samp{QThreadOptions} is not supported by -the stub. @end table Use of this packet is controlled by the @code{set remote thread-options} @@ -44515,11 +44395,6 @@ Reply: A command response with no output. @item @var{OUTPUT} A command response with the hex encoded output string @var{OUTPUT}. -@item E @var{NN} -Indicate a badly formed request. The error number @var{NN} is given as -hex digits. -@item @w{} -An empty reply indicates that @samp{qRcmd} is not recognized. @end table (Note that the @code{qRcmd} packet's name is separated from the @@ -44544,10 +44419,6 @@ Reply: The pattern was not found. @item 1,address The pattern was found at @var{address}. -@item E @var{NN} -A badly formed request or an error was encountered while searching memory. -@item @w{} -An empty reply indicates that @samp{qSearch:memory} is not recognized. @end table @item QStartNoAckMode @@ -44563,8 +44434,6 @@ The stub has switched to no-acknowledgment mode. @value{GDBN} acknowledges this response, but neither the stub nor @value{GDBN} shall send or expect further @samp{+}/@samp{-} acknowledgments in the current connection. -@item @w{} -An empty reply indicates that the stub does not support no-acknowledgment mode. @end table @item qSupported @r{[}:@var{gdbfeature} @r{[};@var{gdbfeature}@r{]}@dots{} @r{]} @@ -44593,9 +44462,6 @@ Reply: The stub supports or does not support each returned @var{stubfeature}, depending on the form of each @var{stubfeature} (see below for the possible forms). -@item @w{} -An empty reply indicates that @samp{qSupported} is not recognized, -or that no features needed to be reported to @value{GDBN}. @end table The allowed forms for each feature (either a @var{gdbfeature} in the @@ -45316,17 +45182,6 @@ have fewer bytes than the @var{length} in the request. @item l The @var{offset} in the request is at the end of the data. There is no more data to be read. - -@item E00 -The request was malformed, or @var{annex} was invalid. - -@item E @var{nn} -The offset was invalid, or there was an error encountered reading the data. -The @var{nn} part is a hex-encoded @code{errno} value. - -@item @w{} -An empty reply indicates the @var{object} string was not recognized by -the stub, or that the object does not support reading. @end table Here are the specific requests of this form defined so far. All the @@ -45545,17 +45400,6 @@ Reply: @item @var{nn} @var{nn} (hex encoded) is the number of bytes written. This may be fewer bytes than supplied in the request. - -@item E00 -The request was malformed, or @var{annex} was invalid. - -@item E @var{nn} -The offset was invalid, or there was an error encountered writing the data. -The @var{nn} part is a hex-encoded @code{errno} value. - -@item @w{} -An empty reply indicates the @var{object} string was not -recognized by the stub, or that the object does not support writing. @end table Here are the specific requests of this form defined so far. All the @@ -45600,8 +45444,6 @@ Reply: The remote server attached to an existing process. @item 0 The remote server created a new process. -@item E @var{NN} -A badly formed request or an error was encountered. @end table @item Qbtrace:bts @@ -45805,8 +45647,6 @@ Replies: The packet was understood and carried out. @item qRelocInsn @xref{Tracepoint Packets,,Relocate instruction reply packet}. -@item @w{} -The packet was not recognized. @end table @item QTDP:-@var{n}:@var{addr}:@r{[}S@r{]}@var{action}@dots{}@r{[}-@r{]} @@ -45871,8 +45711,6 @@ Replies: The packet was understood and carried out. @item qRelocInsn @xref{Tracepoint Packets,,Relocate instruction reply packet}. -@item @w{} -The packet was not recognized. @end table @item QTDPsrc:@var{n}:@var{addr}:@var{type}:@var{start}:@var{slen}:@var{bytes} @@ -45989,8 +45827,6 @@ of 1 means that a fast tracepoint may be placed on any instruction regardless of size. @item E An error has occurred. -@item @w{} -An empty reply indicates that the request is not supported by the stub. @end table @item QTStart @@ -46199,11 +46035,6 @@ A single marker a comma-separated list of markers @item l (lower case letter @samp{L}) denotes end of list. -@item E @var{nn} -An error occurred. The error number @var{nn} is given as hex digits. -@item @w{} -An empty reply indicates that the request is not supported by the -stub. @end table The @var{address} is encoded in hex; @@ -46292,9 +46123,6 @@ Replies: @item qRelocInsn:@var{adjusted_size} Informs the stub the relocation is complete. The @var{adjusted_size} is the length in bytes of resulting relocated instruction sequence. -@item E @var{NN} -A badly formed request was detected, or an error was encountered while -relocating the instruction. @end table @node Host I/O Packets -- 2.43.2