[PATCH] Document remote protocol pid and thread id sizes

[PATCH] Document remote protocol pid and thread id sizes

[Tom Tromey]

The recent ptid work came from a bug where a problem was observed due
to sign extension.  That bug also suggested documenting the guaranteed
range of thread- and process-ids in the remote protocol.

This patch documents these as being 32-bit values at minimum.  I also
added static asserts to ensure this is true -- note that although
'int' may be 16 bit per the C standard, I doubt gdb would build on
such a host.

I didn't specify a maximum because it is host-dependent.  This is
perhaps something to change, and while I do have some work in this
area, it's quite invasive.  Also, while widening the range here would
be good, it would also be incompatible in a sense, where a newer
protocol implementation may end up using values not supported by older
versions of gdb.  Perhaps one idea would be to simply change these
both to int32_t and move on.

Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=33979
---
 gdb/doc/gdb.texinfo | 11 +++++++----
 gdbsupport/ptid.h   |  4 ++++
 2 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index a698b2b8451..04d761c904c 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -43463,7 +43463,8 @@ Several packets and replies include a @var{thread-id} field to identify
 a thread.  Normally these are positive numbers with a target-specific
 interpretation, formatted as big-endian hex strings.  A @var{thread-id}
 can also be a literal @samp{-1} to indicate all threads, or @samp{0} to
-pick any thread.
+pick any thread.  @value{GDBN} guarantees that values of up to 32 bits
+will work here.
 
 In addition, the remote protocol supports a multiprocess feature in
 which the @var{thread-id} syntax is extended to optionally include both
@@ -43475,9 +43476,11 @@ to indicate all processes or threads (respectively), or @samp{0} to
 indicate an arbitrary process or thread.  Specifying just a process, as
 @samp{p@var{pid}}, is equivalent to @samp{p@var{pid}.-1}.  It is an
 error to specify all processes but a specific thread, such as
-@samp{p-1.@var{tid}}.  Note that the @samp{p} prefix is @emph{not} used
-for those packets and replies explicitly documented to include a process
-ID, rather than a @var{thread-id}.
+@samp{p-1.@var{tid}}.  @value{GDBN} guarantees that values of up to 32
+bits will work for both @var{pid} and @var{tid}.  Note that the
+@samp{p} prefix is @emph{not} used for those packets and replies
+explicitly documented to include a process ID, rather than a
+@var{thread-id}.
 
 The multiprocess @var{thread-id} syntax extensions are only used if both
 @value{GDBN} and the stub report support for the @samp{multiprocess}
diff --git a/gdbsupport/ptid.h b/gdbsupport/ptid.h
index ef6da77eb7e..6872f433880 100644
--- a/gdbsupport/ptid.h
+++ b/gdbsupport/ptid.h
@@ -44,6 +44,10 @@ class ptid_t
   using lwp_type = long;
   using tid_type = ULONGEST;
 
+  /* These limits are documented in the manual.  */
+  static_assert (sizeof (pid_type) >= 4);
+  static_assert (sizeof (lwp_type) >= 4);
+
   /* Must have a trivial defaulted default constructor so that the
      type remains POD.  */
   ptid_t () noexcept = default;

base-commit: d243fb0029e28738abb3f933afbf01e1d0617d74
-- 
2.54.0

Re: [PATCH] Document remote protocol pid and thread id sizes

[Eli Zaretskii]

> From: Tom Tromey <tromey@adacore.com>
> Cc: Tom Tromey <tromey@adacore.com>
> Date: Thu,  2 Jul 2026 13:35:56 -0600
> 
> The recent ptid work came from a bug where a problem was observed due
> to sign extension.  That bug also suggested documenting the guaranteed
> range of thread- and process-ids in the remote protocol.
> 
> This patch documents these as being 32-bit values at minimum.  I also
> added static asserts to ensure this is true -- note that although
> 'int' may be 16 bit per the C standard, I doubt gdb would build on
> such a host.
> 
> I didn't specify a maximum because it is host-dependent.  This is
> perhaps something to change, and while I do have some work in this
> area, it's quite invasive.  Also, while widening the range here would
> be good, it would also be incompatible in a sense, where a newer
> protocol implementation may end up using values not supported by older
> versions of gdb.  Perhaps one idea would be to simply change these
> both to int32_t and move on.
> 
> Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=33979
> ---
>  gdb/doc/gdb.texinfo | 11 +++++++----
>  gdbsupport/ptid.h   |  4 ++++
>  2 files changed, 11 insertions(+), 4 deletions(-)

Thanks, the documentation part is okay.

Reviewed-By: Eli Zaretskii <eliz@gnu.org>

Re: [PATCH] Document remote protocol pid and thread id sizes

[Tom Tromey]

Eli> Thanks, the documentation part is okay.

Eli> Reviewed-By: Eli Zaretskii <eliz@gnu.org>

I'm checking this in.

Tom