[PowerPC] Document requirements for VSX feature

[deliverable/binutils-gdb.git] / gdb / doc / gdb.texinfo

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index c49a7745f848c82b61e913698ad0f2ff2e97ba1b..944a2c43837348260471bf07ebcbb801dab0e159 100644 (file)
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -7830,15 +7830,75 @@ same as for the @command{frame} command (@pxref{Selection, ,Selecting
 a Frame}).  The selected frame remains unchanged by this command.
 
 @kindex info args
 a Frame}).  The selected frame remains unchanged by this command.
 
 @kindex info args

-@item info args
+@item info args [-q]

 Print the arguments of the selected frame, each on a separate line.
 
 Print the arguments of the selected frame, each on a separate line.
 

-@item info locals
+The optional flag @samp{-q}, which stands for @samp{quiet}, disables
+printing header information and messages explaining why no argument
+have been printed.
+
+@item info args [-q] [-t @var{type_regexp}] [@var{regexp}]
+Like @kbd{info args}, but only print the arguments selected
+with the provided regexp(s).
+
+If @var{regexp} is provided, print only the arguments whose names
+match the regular expression @var{regexp}.
+
+If @var{type_regexp} is provided, print only the arguments whose
+types, as printed by the @code{whatis} command, match
+the regular expression @var{type_regexp}.
+If @var{type_regexp} contains space(s), it should be enclosed in
+quote characters.  If needed, use backslash to escape the meaning
+of special characters or quotes.
+
+If both @var{regexp} and @var{type_regexp} are provided, an argument
+is printed only if its name matches @var{regexp} and its type matches
+@var{type_regexp}.
+
+@item info locals [-q]

 @kindex info locals
 Print the local variables of the selected frame, each on a separate
 line.  These are all variables (declared either static or automatic)
 accessible at the point of execution of the selected frame.
 
 @kindex info locals
 Print the local variables of the selected frame, each on a separate
 line.  These are all variables (declared either static or automatic)
 accessible at the point of execution of the selected frame.
 

+The optional flag @samp{-q}, which stands for @samp{quiet}, disables
+printing header information and messages explaining why no local variables
+have been printed.
+
+@item info locals [-q] [-t @var{type_regexp}] [@var{regexp}]
+Like @kbd{info locals}, but only print the local variables selected
+with the provided regexp(s).
+
+If @var{regexp} is provided, print only the local variables whose names
+match the regular expression @var{regexp}.
+
+If @var{type_regexp} is provided, print only the local variables whose
+types, as printed by the @code{whatis} command, match
+the regular expression @var{type_regexp}.
+If @var{type_regexp} contains space(s), it should be enclosed in
+quote characters.  If needed, use backslash to escape the meaning
+of special characters or quotes.
+
+If both @var{regexp} and @var{type_regexp} are provided, a local variable
+is printed only if its name matches @var{regexp} and its type matches
+@var{type_regexp}.
+
+The command @kbd{info locals -q -t @var{type_regexp}} can usefully be
+combined with the commands @kbd{frame apply} and @kbd{thread apply}.
+For example, your program might use Resource Acquisition Is
+Initialization types (RAII) such as @code{lock_something_t}: each
+local variable of type @code{lock_something_t} automatically places a
+lock that is destroyed when the variable goes out of scope.  You can
+then list all acquired locks in your program by doing
+@smallexample
+thread apply all -s frame apply all -s info locals -q -t lock_something_t
+@end smallexample
+@noindent
+or the equivalent shorter form
+@smallexample
+tfaas i lo -q -t lock_something_t
+@end smallexample
+

 @end table
 
 @node Frame Apply
 @end table
 
 @node Frame Apply


@@ -17101,7 +17161,8 @@ the following example:
 (@value{GDBP}) info task 2
 Ada Task: 0x807c468
 Name: task_1
 (@value{GDBP}) info task 2
 Ada Task: 0x807c468
 Name: task_1

-Thread: 0x807f378
+Thread: 0
+LWP: 0x1fac

 Parent: 1 (main_task)
 Base Priority: 15
 State: Runnable
 Parent: 1 (main_task)
 Base Priority: 15
 State: Runnable


@@ -17920,32 +17981,73 @@ debugging information, organized into two lists: files whose symbols
 have already been read, and files whose symbols will be read when needed.
 
 @kindex info functions
 have already been read, and files whose symbols will be read when needed.
 
 @kindex info functions

-@item info functions
+@item info functions [-q]

 Print the names and data types of all defined functions.
 Similarly to @samp{info types}, this command groups its output by source
 files and annotates each function definition with its source line
 number.
 
 Print the names and data types of all defined functions.
 Similarly to @samp{info types}, this command groups its output by source
 files and annotates each function definition with its source line
 number.
 

-@item info functions @var{regexp}
-Like @samp{info functions}, but only print the names and data types of
-functions whose names contain a match for regular expression
-@var{regexp}.  Thus, @samp{info fun step} finds all functions whose
+The optional flag @samp{-q}, which stands for @samp{quiet}, disables
+printing header information and messages explaining why no functions
+have been printed.
+
+@item info functions [-q] [-t @var{type_regexp}] [@var{regexp}]
+Like @samp{info functions}, but only print the names and data types
+of the functions selected with the provided regexp(s).
+
+If @var{regexp} is provided, print only the functions whose names
+match the regular expression @var{regexp}.
+Thus, @samp{info fun step} finds all functions whose

 names include @code{step}; @samp{info fun ^step} finds those whose names
 start with @code{step}.  If a function name contains characters that
 conflict with the regular expression language (e.g.@:
 @samp{operator*()}), they may be quoted with a backslash.
 
 names include @code{step}; @samp{info fun ^step} finds those whose names
 start with @code{step}.  If a function name contains characters that
 conflict with the regular expression language (e.g.@:
 @samp{operator*()}), they may be quoted with a backslash.
 

+If @var{type_regexp} is provided, print only the functions whose
+types, as printed by the @code{whatis} command, match
+the regular expression @var{type_regexp}.
+If @var{type_regexp} contains space(s), it should be enclosed in
+quote characters.  If needed, use backslash to escape the meaning
+of special characters or quotes.
+Thus, @samp{info fun -t '^int ('} finds the functions that return
+an integer; @samp{info fun -t '(.*int.*'} finds the functions that
+have an argument type containing int; @samp{info fun -t '^int (' ^step}
+finds the functions whose names start with @code{step} and that return
+int.
+
+If both @var{regexp} and @var{type_regexp} are provided, a function
+is printed only if its name matches @var{regexp} and its type matches
+@var{type_regexp}.
+
+

 @kindex info variables
 @kindex info variables

-@item info variables
+@item info variables [-q]

 Print the names and data types of all variables that are defined
 outside of functions (i.e.@: excluding local variables).
 The printed variables are grouped by source files and annotated with
 their respective source line numbers.
 
 Print the names and data types of all variables that are defined
 outside of functions (i.e.@: excluding local variables).
 The printed variables are grouped by source files and annotated with
 their respective source line numbers.
 

-@item info variables @var{regexp}
-Like @kbd{info variables}, but only print the names and data types of
-non-local variables whose names contain a match for regular expression
-@var{regexp}.
+The optional flag @samp{-q}, which stands for @samp{quiet}, disables
+printing header information and messages explaining why no variables
+have been printed.
+
+@item info variables [-q] [-t @var{type_regexp}] [@var{regexp}]
+Like @kbd{info variables}, but only print the variables selected
+with the provided regexp(s).
+
+If @var{regexp} is provided, print only the variables whose names
+match the regular expression @var{regexp}.
+
+If @var{type_regexp} is provided, print only the variables whose
+types, as printed by the @code{whatis} command, match
+the regular expression @var{type_regexp}.
+If @var{type_regexp} contains space(s), it should be enclosed in
+quote characters.  If needed, use backslash to escape the meaning
+of special characters or quotes.
+
+If both @var{regexp} and @var{type_regexp} are provided, an argument
+is printed only if its name matches @var{regexp} and its type matches
+@var{type_regexp}.

 
 @kindex info classes
 @cindex Objective-C, classes and selectors
 
 @kindex info classes
 @cindex Objective-C, classes and selectors


@@ -20829,15 +20931,6 @@ Note that this command has the same form as the command to connect
 to a serial line.  @value{GDBN} will automatically determine which
 kind of file you have specified and will make the appropriate kind
 of connection.
 to a serial line.  @value{GDBN} will automatically determine which
 kind of file you have specified and will make the appropriate kind
 of connection.

-The above command is identical to the command:
-
-@smallexample
-target remote unix::/tmp/gdb-socket1
-@end smallexample
-@noindent
-
-See below for the explanation of this syntax.
-

 This feature is not available if the host system does not support
 Unix domain sockets.
 
 This feature is not available if the host system does not support
 Unix domain sockets.
 


@@ -20848,7 +20941,6 @@ Unix domain sockets.
 @itemx target remote @code{tcp4:@var{host}:@var{port}}
 @itemx target remote @code{tcp6:@var{host}:@var{port}}
 @itemx target remote @code{tcp6:@var{[host]}:@var{port}}
 @itemx target remote @code{tcp4:@var{host}:@var{port}}
 @itemx target remote @code{tcp6:@var{host}:@var{port}}
 @itemx target remote @code{tcp6:@var{[host]}:@var{port}}

-@itemx target remote @code{unix::@var{local-socket}}

 @itemx target extended-remote @code{@var{host}:@var{port}}
 @itemx target extended-remote @code{@var{[host]}:@var{port}}
 @itemx target extended-remote @code{tcp:@var{host}:@var{port}}
 @itemx target extended-remote @code{@var{host}:@var{port}}
 @itemx target extended-remote @code{@var{[host]}:@var{port}}
 @itemx target extended-remote @code{tcp:@var{host}:@var{port}}


@@ -20856,10 +20948,8 @@ Unix domain sockets.
 @itemx target extended-remote @code{tcp4:@var{host}:@var{port}}
 @itemx target extended-remote @code{tcp6:@var{host}:@var{port}}
 @itemx target extended-remote @code{tcp6:@var{[host]}:@var{port}}
 @itemx target extended-remote @code{tcp4:@var{host}:@var{port}}
 @itemx target extended-remote @code{tcp6:@var{host}:@var{port}}
 @itemx target extended-remote @code{tcp6:@var{[host]}:@var{port}}

-@itemx target extended-remote @code{unix::@var{local-socket}}

 @cindex @acronym{TCP} port, @code{target remote}
 @cindex @acronym{TCP} port, @code{target remote}

-Debug using a @acronym{TCP} connection to @var{port} on @var{host}
-or using the Unix domain socket @var{local-socket} on the local machine.
+Debug using a @acronym{TCP} connection to @var{port} on @var{host}.

 The @var{host} may be either a host name, a numeric @acronym{IPv4}
 address, or a numeric @acronym{IPv6} address (with or without the
 square brackets to separate the address from the port); @var{port}
 The @var{host} may be either a host name, a numeric @acronym{IPv4}
 address, or a numeric @acronym{IPv6} address (with or without the
 square brackets to separate the address from the port); @var{port}


@@ -20907,16 +20997,6 @@ target remote :1234
 @noindent
 
 Note that the colon is still required here.
 @noindent
 
 Note that the colon is still required here.

-Alternatively you can use a Unix domain socket:
-
-@smallexample
-target remote unix::/tmp/gdb-socket1
-@end smallexample
-@noindent
-
-This has the advantage that it'll not fail if the port number is already
-in use.
-

 
 @item target remote @code{udp:@var{host}:@var{port}}
 @itemx target remote @code{udp:@var{[host]}:@var{port}}
 
 @item target remote @code{udp:@var{host}:@var{port}}
 @itemx target remote @code{udp:@var{[host]}:@var{port}}


@@ -21097,19 +21177,9 @@ syntax is:
 target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ]
 @end smallexample
 
 target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ]
 @end smallexample
 

-@code{gdbserver} waits passively for the host @value{GDBN} to communicate
-with it.
-
-@var{comm} may take several forms:
-
-@table @code
-@item @var{device}
-A serial line device.
-
-@item -
-@itemx stdio
-To use the stdin/stdout of @code{gdbserver}.
-
+@var{comm} is either a device name (to use a serial line), or a TCP
+hostname and portnumber, or @code{-} or @code{stdio} to use
+stdin/stdout of @code{gdbserver}.

 For example, to debug Emacs with the argument
 @samp{foo.txt} and communicate with @value{GDBN} over the serial port
 @file{/dev/com1}:
 For example, to debug Emacs with the argument
 @samp{foo.txt} and communicate with @value{GDBN} over the serial port
 @file{/dev/com1}:


@@ -21118,27 +21188,8 @@ For example, to debug Emacs with the argument
 target> gdbserver /dev/com1 emacs foo.txt
 @end smallexample
 
 target> gdbserver /dev/com1 emacs foo.txt
 @end smallexample
 

-The @code{stdio} connection is useful when starting @code{gdbserver}
-with ssh:
-
-@smallexample
-(gdb) target remote | ssh -T hostname gdbserver - hello
-@end smallexample
-
-The @samp{-T} option to ssh is provided because we don't need a remote pty,
-and we don't want escape-character handling.  Ssh does this by default when
-a command is provided, the flag is provided to make it explicit.
-You could elide it if you want to.
-
-Programs started with stdio-connected gdbserver have @file{/dev/null} for
-@code{stdin}, and @code{stdout},@code{stderr} are sent back to gdb for
-display through a pipe connected to gdbserver.
-Both @code{stdout} and @code{stderr} use the same pipe.
-
-@item @var{host}:@var{port}
-@itemx tcp:@var{host}:@var{port}
-@itemx tcp4:@var{host}:@var{port}
-To use a @acronym{TCP} @acronym{IPv4} socket connection on port number @var{port}.
+@code{gdbserver} waits passively for the host @value{GDBN} to communicate
+with it.

 
 To use a TCP connection instead of a serial line:
 
 
 To use a TCP connection instead of a serial line:
 


@@ -21158,21 +21209,22 @@ conflicts with another service, @code{gdbserver} prints an error message
 and exits.}  You must use the same port number with the host @value{GDBN}
 @code{target remote} command.
 
 and exits.}  You must use the same port number with the host @value{GDBN}
 @code{target remote} command.
 

-
-@item tcp6:@var{host}:@var{port}
-To use a @acronym{TCP} @acronym{IPv6} socket connection on port number @var{port}.
-
-@item unix:@var{host}:@var{local-socket}
-To use a Unix domain socket.  This will create a socket with the file
-system entry @var{local-socket} and listen on that.  For example:
+The @code{stdio} connection is useful when starting @code{gdbserver}
+with ssh:

 
 @smallexample
 
 @smallexample

-target> gdbserver unix:localhost:/tmp/gdb-socket0 emacs foo.txt
+(gdb) target remote | ssh -T hostname gdbserver - hello

 @end smallexample
 
 @end smallexample
 

-@var{host} must either be the empty string or the literal string @code{localhost}.
-@end table
+The @samp{-T} option to ssh is provided because we don't need a remote pty,
+and we don't want escape-character handling.  Ssh does this by default when
+a command is provided, the flag is provided to make it explicit.
+You could elide it if you want to.

 
 

+Programs started with stdio-connected gdbserver have @file{/dev/null} for
+@code{stdin}, and @code{stdout},@code{stderr} are sent back to gdb for
+display through a pipe connected to gdbserver.
+Both @code{stdout} and @code{stderr} use the same pipe.

 
 @anchor{Attaching to a program}
 @subsubsection Attaching to a Running Program
 
 @anchor{Attaching to a program}
 @subsubsection Attaching to a Running Program


@@ -43178,11 +43230,13 @@ contain registers @samp{vr0} through @samp{vr31}, @samp{vscr},
 and @samp{vrsave}.
 
 The @samp{org.gnu.gdb.power.vsx} feature is optional.  It should
 and @samp{vrsave}.
 
 The @samp{org.gnu.gdb.power.vsx} feature is optional.  It should

-contain registers @samp{vs0h} through @samp{vs31h}.  @value{GDBN}
-will combine these registers with the floating point registers
-(@samp{f0} through @samp{f31}) and the altivec registers (@samp{vr0}
-through @samp{vr31}) to present the 128-bit wide registers @samp{vs0}
-through @samp{vs63}, the set of vector registers for POWER7.
+contain registers @samp{vs0h} through @samp{vs31h}.  @value{GDBN} will
+combine these registers with the floating point registers (@samp{f0}
+through @samp{f31}) and the altivec registers (@samp{vr0} through
+@samp{vr31}) to present the 128-bit wide registers @samp{vs0} through
+@samp{vs63}, the set of vector-scalar registers for POWER7.
+Therefore, this feature requires both @samp{org.gnu.gdb.power.fpu} and
+@samp{org.gnu.gdb.power.altivec}.

 
 The @samp{org.gnu.gdb.power.spe} feature is optional.  It should
 contain registers @samp{ev0h} through @samp{ev31h}, @samp{acc}, and
 
 The @samp{org.gnu.gdb.power.spe} feature is optional.  It should
 contain registers @samp{ev0h} through @samp{ev31h}, @samp{acc}, and