From d192b37306c0aeb5882002c1aae0f1f480254a41 Mon Sep 17 00:00:00 2001 From: Joel Brobecker Date: Fri, 13 Dec 2013 07:01:33 +0100 Subject: [PATCH] Move GDB/MI commands related to support-query to their own @node. A number of commands provide the capability to query the debugger about support for various features, and one of them in particular (-list-features), is expected to grow as new features get added. -list-target-features should also grow a bit over time, but probably slower. These commands deserve their own section and @node. gdb/doc/ChangeLog: * gdb.texinfo (GDB/MI): Add "GDB/MI Support Commands" entry in menu. (GDB/MI Variable Objects): Adjust reference to "-list-features" command, now in a new node. (GDB/MI Support Commands): New node, with its contents being extracted from the "GDB/MI Miscellaneous Commands" node. A small paragraph introducing the section is also added at the start. (GDB/MI Miscellaneous Commands): Delete the description of the -info-gdb-mi-command, -list-features and -list-target-features commands, now hosted in the "GDB/MI Support Commands" node. --- gdb/doc/ChangeLog | 14 +++ gdb/doc/gdb.texinfo | 298 +++++++++++++++++++++++--------------------- 2 files changed, 168 insertions(+), 144 deletions(-) diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index 7db94e7424..e157df8ee6 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,17 @@ +2013-12-23 Joel Brobecker + + * gdb.texinfo (GDB/MI): Add "GDB/MI Support Commands" entry + in menu. + (GDB/MI Variable Objects): Adjust reference to "-list-features" + command, now in a new node. + (GDB/MI Support Commands): New node, with its contents being + extracted from the "GDB/MI Miscellaneous Commands" node. + A small paragraph introducing the section is also added at + the start. + (GDB/MI Miscellaneous Commands): Delete the description of the + -info-gdb-mi-command, -list-features and -list-target-features + commands, now hosted in the "GDB/MI Support Commands" node. + 2013-12-12 Siva Chandra Reddy PR python/16113 diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index b7551c2af1..29f1cfc4c1 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -28845,6 +28845,7 @@ may repeat one or more times. * GDB/MI Target Manipulation:: * GDB/MI File Transfer Commands:: * GDB/MI Ada Exceptions Commands:: +* GDB/MI Support Commands:: * GDB/MI Miscellaneous Commands:: @end menu @@ -33003,7 +33004,7 @@ select a visualizer by following the built-in process a varobj is created, and so ordinarily is not needed. This feature is only available if Python support is enabled. The MI -command @code{-list-features} (@pxref{GDB/MI Miscellaneous Commands}) +command @code{-list-features} (@pxref{GDB/MI Support Commands}) can be used to check this. @subsubheading Example @@ -35028,6 +35029,158 @@ raises an exception are described at @ref{Ada Exception GDB/MI Catchpoint Commands}. +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Support Commands +@section @sc{gdb/mi} Support Commands + +Since new commands and features get regularly added to @sc{gdb/mi}, +some commands are available to help front-ends query the debugger +about support for these capabilities. Similarly, it is also possible +to query @value{GDBN} about target support of certain features. + +@subheading The @code{-info-gdb-mi-command} Command +@cindex @code{-info-gdb-mi-command} +@findex -info-gdb-mi-command + +@subsubheading Synopsis + +@smallexample + -info-gdb-mi-command @var{cmd_name} +@end smallexample + +Query support for the @sc{gdb/mi} command named @var{cmd_name}. + +Note that the dash (@code{-}) starting all @sc{gdb/mi} commands +is technically not part of the command name (@pxref{GDB/MI Input +Syntax}), and thus should be omitted in @var{cmd_name}. However, +for ease of use, this command also accepts the form with the leading +dash. + +@subsubheading @value{GDBN} Command + +There is no corresponding @value{GDBN} command. + +@subsubheading Result + +The result is a tuple. There is currently only one field: + +@table @samp +@item exists +This field is equal to @code{"true"} if the @sc{gdb/mi} command exists, +@code{"false"} otherwise. + +@end table + +@subsubheading Example + +Here is an example where the @sc{gdb/mi} command does not exist: + +@smallexample +-info-gdb-mi-command unsupported-command +^done,command=@{exists="false"@} +@end smallexample + +@noindent +And here is an example where the @sc{gdb/mi} command is known +to the debugger: + +@smallexample +-info-gdb-mi-command symbol-list-lines +^done,command=@{exists="true"@} +@end smallexample + +@subheading The @code{-list-features} Command +@findex -list-features +@cindex supported @sc{gdb/mi} features, list + +Returns a list of particular features of the MI protocol that +this version of gdb implements. A feature can be a command, +or a new field in an output of some command, or even an +important bugfix. While a frontend can sometimes detect presence +of a feature at runtime, it is easier to perform detection at debugger +startup. + +The command returns a list of strings, with each string naming an +available feature. Each returned string is just a name, it does not +have any internal structure. The list of possible feature names +is given below. + +Example output: + +@smallexample +(gdb) -list-features +^done,result=["feature1","feature2"] +@end smallexample + +The current list of features is: + +@table @samp +@item frozen-varobjs +Indicates support for the @code{-var-set-frozen} command, as well +as possible presense of the @code{frozen} field in the output +of @code{-varobj-create}. +@item pending-breakpoints +Indicates support for the @option{-f} option to the @code{-break-insert} +command. +@item python +Indicates Python scripting support, Python-based +pretty-printing commands, and possible presence of the +@samp{display_hint} field in the output of @code{-var-list-children} +@item thread-info +Indicates support for the @code{-thread-info} command. +@item data-read-memory-bytes +Indicates support for the @code{-data-read-memory-bytes} and the +@code{-data-write-memory-bytes} commands. +@item breakpoint-notifications +Indicates that changes to breakpoints and breakpoints created via the +CLI will be announced via async records. +@item ada-task-info +Indicates support for the @code{-ada-task-info} command. +@item language-option +Indicates that all @sc{gdb/mi} commands accept the @option{--language} +option (@pxref{Context management}). +@item info-gdb-mi-command +Indicates support for the @code{-info-gdb-mi-command} command. +@item undefined-command-error-code +Indicates support for the "undefined-command" error code in error result +records, produced when trying to execute an undefined @sc{gdb/mi} command +(@pxref{GDB/MI Result Records}). +@item exec-run-start-option +Indicates that the @code{-exec-run} command supports the @option{--start} +option (@pxref{GDB/MI Program Execution}). +@end table + +@subheading The @code{-list-target-features} Command +@findex -list-target-features + +Returns a list of particular features that are supported by the +target. Those features affect the permitted MI commands, but +unlike the features reported by the @code{-list-features} command, the +features depend on which target GDB is using at the moment. Whenever +a target can change, due to commands such as @code{-target-select}, +@code{-target-attach} or @code{-exec-run}, the list of target features +may change, and the frontend should obtain it again. +Example output: + +@smallexample +(gdb) -list-target-features +^done,result=["async"] +@end smallexample + +The current list of features is: + +@table @samp +@item async +Indicates that the target is capable of asynchronous command +execution, which means that @value{GDBN} will accept further commands +while the target is running. + +@item reverse +Indicates that the target is capable of reverse execution. +@xref{Reverse Execution}, for more information. + +@end table + @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @node GDB/MI Miscellaneous Commands @section Miscellaneous @sc{gdb/mi} Commands @@ -35169,149 +35322,6 @@ default shows this information when you start an interactive session. (gdb) @end smallexample -@subheading The @code{-info-gdb-mi-command} Command -@cindex @code{-info-gdb-mi-command} -@findex -info-gdb-mi-command - -@subsubheading Synopsis - -@smallexample - -info-gdb-mi-command @var{cmd_name} -@end smallexample - -Query support for the @sc{gdb/mi} command named @var{cmd_name}. - -Note that the dash (@code{-}) starting all @sc{gdb/mi} commands -is technically not part of the command name (@pxref{GDB/MI Input -Syntax}), and thus should be omitted in @var{cmd_name}. However, -for ease of use, this command also accepts the form with the leading -dash. - -@subsubheading @value{GDBN} Command - -There is no corresponding @value{GDBN} command. - -@subsubheading Result - -The result is a tuple. There is currently only one field: - -@table @samp -@item exists -This field is equal to @code{"true"} if the @sc{gdb/mi} command exists, -@code{"false"} otherwise. - -@end table - -@subsubheading Example - -Here is an example where the @sc{gdb/mi} command does not exist: - -@smallexample --info-gdb-mi-command unsupported-command -^done,command=@{exists="false"@} -@end smallexample - -@noindent -And here is an example where the @sc{gdb/mi} command is known -to the debugger: - -@smallexample --info-gdb-mi-command symbol-list-lines -^done,command=@{exists="true"@} -@end smallexample - -@subheading The @code{-list-features} Command -@findex -list-features -@cindex supported @sc{gdb/mi} features, list - -Returns a list of particular features of the MI protocol that -this version of gdb implements. A feature can be a command, -or a new field in an output of some command, or even an -important bugfix. While a frontend can sometimes detect presence -of a feature at runtime, it is easier to perform detection at debugger -startup. - -The command returns a list of strings, with each string naming an -available feature. Each returned string is just a name, it does not -have any internal structure. The list of possible feature names -is given below. - -Example output: - -@smallexample -(gdb) -list-features -^done,result=["feature1","feature2"] -@end smallexample - -The current list of features is: - -@table @samp -@item frozen-varobjs -Indicates support for the @code{-var-set-frozen} command, as well -as possible presense of the @code{frozen} field in the output -of @code{-varobj-create}. -@item pending-breakpoints -Indicates support for the @option{-f} option to the @code{-break-insert} -command. -@item python -Indicates Python scripting support, Python-based -pretty-printing commands, and possible presence of the -@samp{display_hint} field in the output of @code{-var-list-children} -@item thread-info -Indicates support for the @code{-thread-info} command. -@item data-read-memory-bytes -Indicates support for the @code{-data-read-memory-bytes} and the -@code{-data-write-memory-bytes} commands. -@item breakpoint-notifications -Indicates that changes to breakpoints and breakpoints created via the -CLI will be announced via async records. -@item ada-task-info -Indicates support for the @code{-ada-task-info} command. -@item language-option -Indicates that all @sc{gdb/mi} commands accept the @option{--language} -option (@pxref{Context management}). -@item info-gdb-mi-command -Indicates support for the @code{-info-gdb-mi-command} command. -@item undefined-command-error-code -Indicates support for the "undefined-command" error code in error result -records, produced when trying to execute an undefined @sc{gdb/mi} command -(@pxref{GDB/MI Result Records}). -@item exec-run-start-option -Indicates that the @code{-exec-run} command supports the @option{--start} -option (@pxref{GDB/MI Program Execution}). -@end table - -@subheading The @code{-list-target-features} Command -@findex -list-target-features - -Returns a list of particular features that are supported by the -target. Those features affect the permitted MI commands, but -unlike the features reported by the @code{-list-features} command, the -features depend on which target GDB is using at the moment. Whenever -a target can change, due to commands such as @code{-target-select}, -@code{-target-attach} or @code{-exec-run}, the list of target features -may change, and the frontend should obtain it again. -Example output: - -@smallexample -(gdb) -list-target-features -^done,result=["async"] -@end smallexample - -The current list of features is: - -@table @samp -@item async -Indicates that the target is capable of asynchronous command -execution, which means that @value{GDBN} will accept further commands -while the target is running. - -@item reverse -Indicates that the target is capable of reverse execution. -@xref{Reverse Execution}, for more information. - -@end table - @subheading The @code{-list-thread-groups} Command @findex -list-thread-groups