Re: [PATCH] Document the ThreadInfo remote protocol queries

[Andrew Cagney <ac131313 at cygnus dot com>]

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.

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'')?

	Andrew