Re: [PATCH] Document the ThreadInfo remote protocol queries

[Michael Snyder <msnyder at cygnus dot com>]

Andrew Cagney wrote:
> 
> Michael Snyder wrote:
> >
> > The following patch adds documentation to gdb.texinfo for the new
> > remote protocol queries "ThreadInfo" and "ThreadExtraInfo"
> > described in my previous patch.
> >
> > 2000-03-20  Michael Snyder  <msnyder@cleaver.cygnus.com>
> >
> >         * gdb.texinfo: Add new queries ThreadInfo and ThreadExtraInfo.
> 
> > ! @item all thread ids
> > ! @tab @code{q}@code{fThreadInfo}
> > ! @item
> > ! @tab @code{q}@code{sThreadInfo}
> >   @tab
> > + Obtain a list of active thread ids from the target (OS).  Since there
> > + may be too many active threads to fit into one reply packet, this query
> > + works iteratively: it may require more than one query/reply sequence to
> > + obtain the entire list of threads.  The first query of the sequence will
> > + be the @code{qf}@code{ThreadInfo} query; subsequent queries in the
> > + sequence will be the @code{qs}@code{ThreadInfo} query.
> >   @item
> > ! @tab
> > ! @tab NOTE: replaces the @code{qL} query (see below).
> >   @item
> > ! @tab reply @code{m}@var{<id>}
> > ! @tab A single thread id
> > ! @item
> > ! @tab reply @code{m}@var{<id>,}@var{<id>...}
> > ! @tab a comma-separated list of thread ids
> > ! @item
> > ! @tab reply @code{l}
> > ! @tab (lower case 'el') denotes end of list.
> > ! @item
> > ! @tab
> > ! @tab
> > ! In response to each query, the target will reply with a list of one
> > ! or more thread ids, in big-endian hex, separated by commas.  GDB will
> > ! respond to each reply with a request for more thread ids (using the
> > ! @code{qs} form of the query), until the target responds with @code{l}
> > ! (lower-case el, for @code{'last'}).
> > !
> > ! @item extra thread info
> > ! @tab @code{qfThreadExtraInfo,}@var{<id>}
> > ! @tab
> > ! @item
> > ! @tab
> > ! @tab
> > ! Where @var{<id>} is a thread-id in big-endian hex.
> > ! Obtain a printable string description of a thread's attributes from
> > ! the target OS.  This string may contain anything that the target OS
> > ! thinks is interesting for @value{GDBN} to tell the user about the thread.
> > ! The string is displayed in @value{GDBN}'s @samp{info threads} display.
> > ! Some examples of possible thread extra info strings are "Runnable", or
> > ! "Blocked on Mutex".
> > ! @item
> > ! @tab reply @var{XX...}
> > ! @tab
> > ! Where @var{XX...} is a hex encoding of @sc{ascii} data, comprising the
> > ! printable string containing the extra information about the thread's
> > ! attributes.
> >
> >   @item query @var{LIST} or @var{threadLIST} @strong{(deprecated)}
> >   @tab @code{q}@code{L}@var{startflag}@var{threadcount}@var{nextthread}
> 
> An additional note on these versions of thread queries.  While
> significantly better than the ``qL'' packet these commands still have
> problems.  I'll add notes expanding on this.  Briefly, however:
> 
>         o       Per the query packet spec, they should be
>                 prefixed with a UCASE letter if they
>                 are to be official GDB packets.
> 
>         o       The ``sThread..'' command assumes
>                 that the GDB protocol is reliable
>                 which it is not.  GDB can re-issue
>                 a ``sThread'' request and this can
>                 lead to GDB and the target falling
>                 out of sync.

How about if the 'sThread' request were to be suffixed with
the last thread ID received?

> with regard to ``qfThreadExtraInfo''.  As far as I know its not been
> deployed in the field.  Is there any reason to not name it correctly
> from the start  (``qThreadExtraInfo'')?

Only that it conflicts with the tracepoint messages, 
which all begin with qT (see tracepoint.c).

				Michael