From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 17815 invoked by alias); 31 May 2012 13:15:23 -0000 Received: (qmail 17486 invoked by uid 22791); 31 May 2012 13:15:18 -0000 X-SWARE-Spam-Status: No, hits=-4.1 required=5.0 tests=AWL,BAYES_00,FROM_12LTRDOM,KHOP_RCVD_UNTRUST,KHOP_THREADED,RCVD_IN_HOSTKARMA_W,RCVD_IN_HOSTKARMA_WL X-Spam-Check-By: sourceware.org Received: from relay1.mentorg.com (HELO relay1.mentorg.com) (192.94.38.131) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Thu, 31 May 2012 13:14:56 +0000 Received: from svr-orw-exc-10.mgc.mentorg.com ([147.34.98.58]) by relay1.mentorg.com with esmtp id 1Sa5DL-0006sf-Hv from Yao_Qi@mentor.com for gdb-patches@sourceware.org; Thu, 31 May 2012 06:14:55 -0700 Received: from SVR-ORW-FEM-04.mgc.mentorg.com ([147.34.97.41]) by SVR-ORW-EXC-10.mgc.mentorg.com with Microsoft SMTPSVC(6.0.3790.4675); Thu, 31 May 2012 06:14:29 -0700 Received: from localhost.localdomain (147.34.91.1) by svr-orw-fem-04.mgc.mentorg.com (147.34.97.41) with Microsoft SMTP Server id 14.1.289.1; Thu, 31 May 2012 06:14:54 -0700 From: Yao Qi To: Subject: [PATCH 3/3] Doc Date: Thu, 31 May 2012 13:15:00 -0000 Message-ID: <1338470075-12254-4-git-send-email-yao@codesourcery.com> In-Reply-To: <1338470075-12254-1-git-send-email-yao@codesourcery.com> References: <1338470075-12254-1-git-send-email-yao@codesourcery.com> MIME-Version: 1.0 Content-Type: text/plain X-IsSubscribed: yes Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2012-05/txt/msg01081.txt.bz2 This patch is about the commands of itsets, and syntax of itset. gdb/doc: 2012-05-03 Yao Qi * gdb.texinfo (ITSET): New node. (Maintenance Commands): Add for `maint info itsets'. (ITSET Syntax): New node. --- gdb/doc/gdb.texinfo | 137 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 137 insertions(+), 0 deletions(-) diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 014cfd8..582dec7 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -178,6 +178,7 @@ software in general. We will miss him. the operating system * Trace File Format:: GDB trace file format * Index Section Format:: .gdb_index section format +* ITSET Syntax:: Syntax of ITSET specification * Copying:: GNU General Public License says how you can copy and share GDB * GNU Free Documentation License:: The license for this documentation @@ -3261,6 +3262,7 @@ running or not, what process it is, and why it stopped. @menu * Breakpoints:: Breakpoints, watchpoints, and catchpoints * Continuing and Stepping:: Resuming execution +* ITSET:: ITSET * Skipping Over Functions and Files:: Skipping over functions and files * Signals:: Signals @@ -5129,6 +5131,65 @@ proceed until the function returns. An argument is a repeat count, as in @code{next}. @end table +@node ITSET +@section ITSET +@cindex itset +If a program with dozens, hundreds, or even thousands, of threads, +@value{GDBN} needs a concept for users to refer to a certain processes, +threads, and cores in a consistent way using a flexible syntax. This +is called inferior/process/thread/core set construct, or inferior/thread +set (I/T set or just itset) for short. For the details of the +specification of ITSET syntax, @pxref{ITSET Syntax}. + +@subsection itset commands + +@table @code +@kindex defset +@item defset @var{name} @var{spec} +Define a new named set. + +@kindex undefset @var{name} +@item undefset @var{name} +Undefine an existing named set. + +@kindex undefset -all +@item undefset -all +Undefine all existing named set. + +@kindex whichsets @r{[}@var{spec}@r{]} +@item whichsets @r{[}@var{spec}@r{]} +List all sets to which threads in the set @var{spec} belong to. If +@var{spec} is not set, list all sets to all threads belong to. + +@smallexample +(@value{GDBP}) whichsets t1 +i1.t1 (Thread 0x401ce6c0 (LWP 12089)) is in: stopped, all, curinf, itset-t1, itset-t1-t2 +@end smallexample + +@kindex viewset @r{[}@var{spec}@r{]} +@item viewset @r{[}@var{spec}@r{]} +List the menbers of the set @var{spec}. If @var{secp} is not set, it +lists the members of all named sets. +@smallexample +(@value{GDBP}) viewset t1 +t1 contains: + inferiors: 1 + threads: 1 + cores: 3 +@end smallexample + +@kindex info itsets @r{[}@var{range}@r{]} +@item info itsets @r{[}@var{range}@r{]} +Display the list of defined named itsets. The @var{range} can not only be +specific numbers, such as 1, 3, but also can be range, like 4-8. +@smallexample +(@value{GDBP}) info itsets 1 3 4-8 +@end smallexample + +@item @ref{maint info itsets} + +@end table + @node Skipping Over Functions and Files @section Skipping Over Functions and Files @cindex skipping over functions and files @@ -34283,6 +34344,21 @@ Shared library events. @end table +@kindex maint info itsets +@item @anchor{maint info itsets}maint info sets +Diplay the list of all defined named itsets, ubser-defined and built-in. +@smallexample +@value{GDBP} maint info itsets +Num Name What +-1 running running +-2 stopped stopped +-3 all all +-4 empty +-5 curinf curinf +1 itset-c1 c1 +2 itset-c2 c2 +@end smallexample + @kindex set displaced-stepping @kindex show displaced-stepping @cindex displaced stepping support @@ -40225,6 +40301,67 @@ symbol. A string in the constant pool is zero-terminated. @end enumerate +@node ITSET Syntax +@appendix ITSET Syntax +@cindex itset syntax +This section documents the syntax of ITSET, which is used to refer to +a set of inferiors, processes, threads and cores. This allows +@value{GDBN} command to be applied to a set or collection of inferiors, +processes, and threads, instead of just one thread/process or all at +a time. + +@subsection Syntax +Naturally, ITSET is composed by several @dfn{ITSET elements} and +@dfn{ITSET operators} among them. ITSET elements are composed by +@dfn{prefix letter}s and range or number. The table below is +about the supported prefix letters, + +@multitable @columnfractions .6 .6 +@item @strong{Prefix Letter} +@tab @strong{Description} +@item i @tab inferior +@item t @tab thread +@item a @tab Ada task +@item c @tab core +@end multitable + +Since ITSET is similar to general set, the ITSET operators are +similar to general set operators too, such as intersection +and union. The table below is about the supported operators, + +@multitable @columnfractions .6 .6 +@item @strong{Operator} +@tab @strong{Description} +@item . @tab intersection operator +@item , @tab union operator +@item ~ @tab negating operator +@item ! @tab specifies static itset +@item $ @tab represents current itset +@item () @tab defeat precedence +@end multitable + +The syntax follow this grammar: +@smallexample + ELEM = RANGE | NEG | PARENS_SET | '$' | NAME + NEG = '~' ELEM + PARENS_SET = '(' ITSET_ONE ')' + INTERS = ELEM ('.' ELEM)* + ITSET_ONE = INTERS (',' INTERS)* + ITSET = | ('!' ITSET_ONE) | ITSET_ONE +@end smallexample + +@subsection Examples + +@multitable @columnfractions .6 .6 +@item @strong{ITSET} @tab @strong{Description} +@item @var{t1-3} @tab Thread 1, 2, and 3 +@item @var{i1.t2} @tab Thread 2 in inferior 1 +@item @var{i1.t1-100.c1-2} @tab Threads 1 to 100 in inferior 1 running on core 1 to 2. +@item @var{workers.~c1-3} +@tab All in the user-defined set ``workers'', except those on core 1 to core 3. +@item @var{running.i1} @tab All running threads in inferior 1 +@end multitable + @include gpl.texi @node GNU Free Documentation License -- 1.7.0.4