aboutsummaryrefslogtreecommitdiff
path: root/gdb/doc
diff options
context:
space:
mode:
authorAndrew Burgess <aburgess@redhat.com>2022-02-14 14:40:52 +0000
committerAndrew Burgess <aburgess@redhat.com>2022-07-11 12:02:54 +0100
commit4cbe4ca5da5cd7e1e6331ce11f024bf3c07b9744 (patch)
tree8c0bf2715ee9bc1c477005ba81c50cc22c59990e /gdb/doc
parent81384924cdcc9eb2676dd9084b76845d7d0e0759 (diff)
downloadgdb-4cbe4ca5da5cd7e1e6331ce11f024bf3c07b9744.zip
gdb-4cbe4ca5da5cd7e1e6331ce11f024bf3c07b9744.tar.gz
gdb-4cbe4ca5da5cd7e1e6331ce11f024bf3c07b9744.tar.bz2
gdb: add support for disassembler styling using libopcodes
This commit extends GDB to make use of libopcodes styling support where available, currently this is just i386 based architectures, and RISC-V. For architectures that don't support styling using libopcodes GDB will fall back to using the Python Pygments package, when the package is available. The new libopcodes based styling has the disassembler identify parts of the disassembled instruction, e.g. registers, immediates, mnemonics, etc, and can style these components differently. Additionally, as the styling is now done in GDB we can add settings to allow the user to configure which colours are used right from the GDB CLI. There's some new maintenance commands: maintenance set libopcodes-styling enabled on|off maintenance show libopcodes-styling These can be used to manually disable use of libopcodes styling. This is a maintenance command as it's not anticipated that a user should need to do this. But, this could be useful for testing, or, in some rare cases, a user might want to override the Python hook used for disassembler styling, and then disable libopcode styling so that GDB falls back to using Python. Right now I would consider this second use case a rare situation, which is why I think a maintenance command is appropriate. When libopcodes is being used for styling then the user can make use of the following new styles: set/show style disassembler comment set/show style disassembler immediate set/show style disassembler mnemonic set/show style disassembler register The disassembler also makes use of the 'address' and 'function' styles to style some parts of the disassembler output. I have also added the following aliases though: set/show style disassembler address set/show style disassembler symbol these are aliases for: set/show style address set/show style function respectively, and exist to make it easier for users to discover disassembler related style settings. The 'address' style is used to style numeric addresses in the disassembler output, while the 'symbol' or 'function' style is used to style the names of symbols in disassembler output. As not every architecture supports libopcodes styling, the maintenance setting 'libopcodes-styling enabled' has an "auto-off" type behaviour. Consider this GDB session: (gdb) show architecture The target architecture is set to "auto" (currently "i386:x86-64"). (gdb) maintenance show libopcodes-styling enabled Use of libopcodes styling support is "on". the setting defaults to "on" for architectures that support libopcodes based styling. (gdb) set architecture sparc The target architecture is set to "sparc". (gdb) maintenance show libopcodes-styling enabled Use of libopcodes styling support is "off" (not supported on architecture "sparc") the setting will show as "off" if the user switches to an architecture that doesn't support libopcodes styling. The underlying setting is still "on" at this point though, if the user switches back to i386:x86-64 then the setting would go back to being "on". (gdb) maintenance set libopcodes-styling enabled off (gdb) maintenance show libopcodes-styling enabled Use of libopcodes styling support is "off". now the setting is "off" for everyone, even if the user switches back to i386:x86-64 the setting will still show as "off". (gdb) maintenance set libopcodes-styling enabled on Use of libopcodes styling not supported on architecture "sparc". (gdb) maintenance show libopcodes-styling enabled Use of libopcodes styling support is "off". attempting to switch the setting "on" for an unsupported architecture will give an error, and the setting will remain "off". (gdb) set architecture auto The target architecture is set to "auto" (currently "i386:x86-64"). (gdb) maintenance show libopcodes-styling enabled Use of libopcodes styling support is "off". (gdb) maintenance set libopcodes-styling enabled on (gdb) maintenance show libopcodes-styling enabled Use of libopcodes styling support is "on". the user will need to switch back to a supported architecture before they can one again turn this setting "on".
Diffstat (limited to 'gdb/doc')
-rw-r--r--gdb/doc/gdb.texinfo102
1 files changed, 98 insertions, 4 deletions
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 7a4e337..86394f6 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -26526,6 +26526,7 @@ then it will be used.
@item show style sources
Show the current state of source code styling.
+@anchor{style_disassembler_enabled}
@item set style disassembler enabled @samp{on|off}
Enable or disable disassembler styling. This affects whether
disassembler output, such as the output of the @code{disassemble}
@@ -26533,13 +26534,32 @@ command, is styled. Disassembler styling only works if styling in
general is enabled (with @code{set style enabled on}), and if a source
highlighting library is available to @value{GDBN}.
-To highlight disassembler output, @value{GDBN} must be compiled with
-Python support, and the Python Pygments package must be available. If
-these requirements are not met then @value{GDBN} will not highlight
-disassembler output, even when this option is @samp{on}.
+The two source highlighting libraries that @value{GDBN} could use to
+style disassembler output are; @value{GDBN}'s builtin disassembler, or
+the Python Pygments package.
+
+@value{GDBN}'s first choice will be to use the builtin disassembler
+for styling, this usually provides better results, being able to style
+different types of instruction operands differently. However, the
+builtin disassembler is not able to style all architectures.
+
+For architectures that the builtin disassembler is unable to style,
+@value{GDBN} will fall back to use the Python Pygments package where
+possible. In order to use the Python Pygments package, @value{GDBN}
+must be built with Python support, and the Pygments package must be
+installed.
+
+If neither of these options are available then @value{GDBN} will
+produce unstyled disassembler output, even when this setting is
+@samp{on}.
+
+To discover if the current architecture supports styling using the
+builtin disassembler library see @ref{maint_libopcodes_styling,,@kbd{maint
+show libopcodes-styling enabled}}.
@item show style disassembler enabled
Show the current state of disassembler styling.
+
@end table
Subcommands of @code{set style} control specific forms of styling.
@@ -26584,6 +26604,11 @@ Control the styling of function names. These are managed with the
@code{set style function} family of commands. By default, this
style's foreground color is yellow.
+This style is also used for symbol names in styled disassembler output
+if @value{GDBN} is using its builtin disassembler library for styling
+(@pxref{style_disassembler_enabled,,@kbd{set style disassembler
+enabled}}).
+
@item variable
Control the styling of variable names. These are managed with the
@code{set style variable} family of commands. By default, this style's
@@ -26594,6 +26619,11 @@ Control the styling of addresses. These are managed with the
@code{set style address} family of commands. By default, this style's
foreground color is blue.
+This style is also used for addresses in styled disassembler output
+if @value{GDBN} is using its builtin disassembler library for styling
+(@pxref{style_disassembler_enabled,,@kbd{set style disassembler
+enabled}}).
+
@item version
Control the styling of @value{GDBN}'s version number text. By
default, this style's foreground color is magenta and it has bold
@@ -26642,6 +26672,47 @@ general styling to @value{GDBN}. @xref{TUI Configuration}.
Control the styling of the active TUI border; that is, the TUI window
that has the focus.
+@item disassembler comment
+Control the styling of comments in the disassembler output. These are
+managed with the @code{set style disassembler comment} family of
+commands. This style is only used when @value{GDBN} is styling using
+its builtin disassembler library
+(@pxref{style_disassembler_enabled,,@kbd{set style disassembler
+enabled}}). By default, this style's intensity is dim, and its
+foreground color is white.
+
+@item disassembler immediate
+Control the styling of numeric operands in the disassembler output.
+These are managed with the @code{set style disassembler immediate}
+family of commands. This style is not used for instruction operands
+that represent addresses, in that case the @samp{disassembler address}
+style is used. This style is only used when @value{GDBN} is styling
+using its builtin disassembler library. By default, this style's
+foreground color is blue.
+
+@item disassembler address
+Control the styling of address operands in the disassembler output.
+This is an alias for the @samp{address} style.
+
+@item disassembler symbol
+Control the styling of symbol names in the disassembler output. This
+is an alias for the @samp{function} style.
+
+@item disassembler mnemonic
+Control the styling of instruction mnemonics in the disassembler
+output. These are managed with the @code{set style disassembler
+mnemonic} family of commands. This style is also used for assembler
+directives, e.g.@: @code{.byte}, @code{.word}, etc. This style is
+only used when @value{GDBN} is styling using its builtin disassembler
+library. By default, this style's foreground color is green.
+
+@item disassembler register
+Control the styling of register operands in the disassembler output.
+These are managed with the @code{set style disassembler register}
+family of commands. This style is only used when @value{GDBN} is
+styling using its builtin disassembler library. By default, this style's
+foreground color is red.
+
@end table
@node Numbers
@@ -40415,6 +40486,29 @@ This option is useful for debugging @value{GDBN}'s use of the Pygments
library when @value{GDBN} is linked against the GNU Source Highlight
library.
+@anchor{maint_libopcodes_styling}
+@kindex maint set libopcodes-styling enabled
+@kindex maint show libopcodes-styling enabled
+@item maint set libopcodes-styling enabled @r{[}on|off@r{]}
+@itemx maint show libopcodes-styling enabled
+Control whether @value{GDBN} should use its builtin disassembler
+(@file{libopcodes}) to style disassembler output (@pxref{Output
+Styling}). The builtin disassembler does not support styling for all
+architectures.
+
+When this option is @samp{off} the builtin disassembler will not be
+used for styling, @value{GDBN} will fall back to using the Python
+Pygments package if possible.
+
+Trying to set this option @samp{on} for an architecture that the
+builtin disassembler is unable to style will give an error, otherwise,
+the builtin disassembler will be used to style disassembler output.
+
+This option is @samp{on} by default for supported architectures.
+
+This option is useful for debugging @value{GDBN}'s use of the Pygments
+library when @value{GDBN} is built for an architecture that supports
+styling with the builtin disassembler
@kindex maint space
@cindex memory used by commands
@item maint space @var{value}