gdb/disasm.h

   1 /* Disassemble support for GDB.
   2    Copyright (C) 2002-2022 Free Software Foundation, Inc.
   3
   4    This file is part of GDB.
   5
   6    This program is free software; you can redistribute it and/or modify
   7    it under the terms of the GNU General Public License as published by
   8    the Free Software Foundation; either version 3 of the License, or
   9    (at your option) any later version.
  10
  11    This program is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14    GNU General Public License for more details.
  15
  16    You should have received a copy of the GNU General Public License
  17    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  18
  19 #ifndef DISASM_H
  20 #define DISASM_H
  21
  22 #include "dis-asm.h"
  23 #include "disasm-flags.h"
  24
  25 struct gdbarch;
  26 struct ui_out;
  27 struct ui_file;
  28
  29 /* A wrapper around a disassemble_info and a gdbarch.  This is the core
  30    set of data that all disassembler sub-classes will need.  This class
  31    doesn't actually implement the disassembling process, that is something
  32    that sub-classes will do, with each sub-class doing things slightly
  33    differently.
  34
  35    The constructor of this class is protected, you should not create
  36    instances of this class directly, instead create an instance of an
  37    appropriate sub-class.  */
  38
  39 struct gdb_disassemble_info
  40 {
  41   DISABLE_COPY_AND_ASSIGN (gdb_disassemble_info);
  42
  43   /* Return the gdbarch we are disassembling for.  */
  44   struct gdbarch *arch ()
  45   { return m_gdbarch; }
  46
  47   /* Return a pointer to the disassemble_info, this will be needed for
  48      passing into the libopcodes disassembler.  */
  49   struct disassemble_info *disasm_info ()
  50   { return &m_di; }
  51
  52 protected:
  53
  54   /* Types for the function callbacks within m_di.  */
  55   using read_memory_ftype = decltype (disassemble_info::read_memory_func);
  56   using memory_error_ftype = decltype (disassemble_info::memory_error_func);
  57   using print_address_ftype = decltype (disassemble_info::print_address_func);
  58   using fprintf_ftype = decltype (disassemble_info::fprintf_func);
  59   using fprintf_styled_ftype = decltype (disassemble_info::fprintf_styled_func);
  60
  61   /* Constructor, many fields in m_di are initialized from GDBARCH.  STREAM
  62      is where the output of the disassembler will be written too, the
  63      remaining arguments are function callbacks that are written into
  64      m_di.  Of these function callbacks FPRINTF_FUNC and
  65      FPRINTF_STYLED_FUNC must not be nullptr.  If READ_MEMORY_FUNC,
  66      MEMORY_ERROR_FUNC, or PRINT_ADDRESS_FUNC are nullptr, then that field
  67      within m_di is left with its default value (see the libopcodes
  68      function init_disassemble_info for the defaults).  */
  69   gdb_disassemble_info (struct gdbarch *gdbarch,
  70                         struct ui_file *stream,
  71                         read_memory_ftype read_memory_func,
  72                         memory_error_ftype memory_error_func,
  73                         print_address_ftype print_address_func,
  74                         fprintf_ftype fprintf_func,
  75                         fprintf_styled_ftype fprintf_styled_func);
  76
  77   /* Destructor.  */
  78   virtual ~gdb_disassemble_info ();
  79
  80   /* The stream that disassembler output is being written too.  */
  81   struct ui_file *stream ()
  82   { return (struct ui_file *) m_di.stream; }
  83
  84   /* Stores data required for disassembling instructions in
  85      opcodes.  */
  86   struct disassemble_info m_di;
  87
  88 private:
  89   /* The architecture we are disassembling for.  */
  90   struct gdbarch *m_gdbarch;
  91
  92   /* If we own the string in `m_di.disassembler_options', we do so
  93      using this field.  */
  94   std::string m_disassembler_options_holder;
  95 };
  96
  97 /* A wrapper around gdb_disassemble_info.  This class adds default
  98    print functions that are supplied to the disassemble_info within the
  99    parent class.  These default print functions write to the stream, which
 100    is also contained in the parent class.
 101
 102    As with the parent class, the constructor for this class is protected,
 103    you should not create instances of this class, but create an
 104    appropriate sub-class instead.  */
 105
 106 struct gdb_printing_disassembler : public gdb_disassemble_info
 107 {
 108   DISABLE_COPY_AND_ASSIGN (gdb_printing_disassembler);
 109
 110 protected:
 111
 112   /* Constructor.  All the arguments are just passed to the parent class.
 113      We also add the two print functions to the arguments passed to the
 114      parent.  See gdb_disassemble_info for a description of how the
 115      arguments are handled.  */
 116   gdb_printing_disassembler (struct gdbarch *gdbarch,
 117                              struct ui_file *stream,
 118                              read_memory_ftype read_memory_func,
 119                              memory_error_ftype memory_error_func,
 120                              print_address_ftype print_address_func)
 121     : gdb_disassemble_info (gdbarch, stream, read_memory_func,
 122                             memory_error_func, print_address_func,
 123                             fprintf_func, fprintf_styled_func)
 124   { /* Nothing.  */ }
 125
 126   /* Callback used as the disassemble_info's fprintf_func callback, this
 127      writes to STREAM, which will be m_di.stream.  */
 128   static int fprintf_func (void *stream, const char *format, ...)
 129     ATTRIBUTE_PRINTF(2,3);
 130
 131   /* Callback used as the disassemble_info's fprintf_styled_func callback,
 132      this writes to STREAM, which will be m_di.stream.  */
 133   static int fprintf_styled_func (void *stream,
 134                                   enum disassembler_style style,
 135                                   const char *format, ...)
 136     ATTRIBUTE_PRINTF(3,4);
 137 };
 138
 139 /* A basic disassembler that doesn't actually print anything.  */
 140
 141 struct gdb_non_printing_disassembler : public gdb_disassemble_info
 142 {
 143   gdb_non_printing_disassembler (struct gdbarch *gdbarch,
 144                                  read_memory_ftype read_memory_func)
 145     : gdb_disassemble_info (gdbarch, nullptr /* stream */,
 146                             read_memory_func,
 147                             nullptr /* memory_error_func */,
 148                             nullptr /* print_address_func */,
 149                             null_fprintf_func,
 150                             null_fprintf_styled_func)
 151   { /* Nothing.  */ }
 152
 153 private:
 154
 155   /* Callback used as the disassemble_info's fprintf_func callback, this
 156      doesn't write anything to STREAM, but just returns 0.  */
 157   static int null_fprintf_func (void *stream, const char *format, ...)
 158     ATTRIBUTE_PRINTF(2,3);
 159
 160   /* Callback used as the disassemble_info's fprintf_styled_func callback,
 161      , this doesn't write anything to STREAM, but just returns 0.  */
 162   static int null_fprintf_styled_func (void *stream,
 163                                        enum disassembler_style style,
 164                                        const char *format, ...)
 165     ATTRIBUTE_PRINTF(3,4);
 166 };
 167
 168 /* This is a helper class, for use as an additional base-class, by some of
 169    the disassembler classes below.  This class just defines a static method
 170    for reading from target memory, which can then be used by the various
 171    disassembler sub-classes.  */
 172
 173 struct gdb_disassembler_memory_reader
 174 {
 175   /* Implements the read_memory_func disassemble_info callback.  */
 176   static int dis_asm_read_memory (bfd_vma memaddr, gdb_byte *myaddr,
 177                                   unsigned int len,
 178                                   struct disassemble_info *info);
 179 };
 180
 181 /* A non-printing disassemble_info management class.  The disassemble_info
 182    setup by this class will not print anything to the output stream (there
 183    is no output stream), and the instruction to be disassembled will be
 184    read from target memory.  */
 185
 186 struct gdb_non_printing_memory_disassembler
 187   : public gdb_non_printing_disassembler,
 188     private gdb_disassembler_memory_reader
 189 {
 190   /* Constructor.  GDBARCH is the architecture to disassemble for.  */
 191   gdb_non_printing_memory_disassembler (struct gdbarch *gdbarch)
 192     :gdb_non_printing_disassembler (gdbarch, dis_asm_read_memory)
 193   { /* Nothing.  */ }
 194 };
 195
 196 /* A dissassembler class that provides 'print_insn', a method for
 197    disassembling a single instruction to the output stream.  */
 198
 199 struct gdb_disassembler : public gdb_printing_disassembler,
 200                           private gdb_disassembler_memory_reader
 201 {
 202   gdb_disassembler (struct gdbarch *gdbarch, struct ui_file *file)
 203     : gdb_disassembler (gdbarch, file, dis_asm_read_memory)
 204   { /* Nothing.  */ }
 205
 206   DISABLE_COPY_AND_ASSIGN (gdb_disassembler);
 207
 208   /* Disassemble a single instruction at MEMADDR to the ui_file* that was
 209      passed to the constructor.  If a memory error occurs while
 210      disassembling this instruction then an error will be thrown.  */
 211   int print_insn (CORE_ADDR memaddr, int *branch_delay_insns = NULL);
 212
 213 protected:
 214   gdb_disassembler (struct gdbarch *gdbarch, struct ui_file *file,
 215                     read_memory_ftype func);
 216
 217 private:
 218   /* This member variable is given a value by calling dis_asm_memory_error.
 219      If after calling into the libopcodes disassembler we get back a
 220      negative value (which indicates an error), then, if this variable has
 221      a value, we report a memory error to the user, otherwise, we report a
 222      non-memory error.  */
 223   gdb::optional<CORE_ADDR> m_err_memaddr;
 224
 225   /* Disassembler output is built up into this buffer.  Whether this
 226      string_file is created with styling support or not depends on the
 227      value of use_ext_lang_colorization_p, as well as whether disassembler
 228      styling in general is turned on, and also, whether *m_dest supports
 229      styling or not.  */
 230   string_file m_buffer;
 231
 232   /* The stream to which disassembler output will be written.  */
 233   ui_file *m_dest;
 234
 235   /* When true, m_buffer will be created without styling support,
 236      otherwise, m_buffer will be created with styling support.
 237
 238      This field will initially be true, but will be set to false if
 239      ext_lang_colorize_disasm fails to add styling at any time.
 240
 241      If the extension language is going to add the styling then m_buffer
 242      should be created without styling support, the extension language will
 243      then add styling at the end of the disassembly process.
 244
 245      If the extension language is not going to add the styling, then we
 246      create m_buffer with styling support, and GDB will add minimal styling
 247      (currently just to addresses and symbols) as it goes.  */
 248   static bool use_ext_lang_colorization_p;
 249
 250   static void dis_asm_memory_error (int err, bfd_vma memaddr,
 251                                     struct disassemble_info *info);
 252   static void dis_asm_print_address (bfd_vma addr,
 253                                      struct disassemble_info *info);
 254 };
 255
 256 /* An instruction to be disassembled.  */
 257
 258 struct disasm_insn
 259 {
 260   /* The address of the memory containing the instruction.  */
 261   CORE_ADDR addr;
 262
 263   /* An optional instruction number.  If non-zero, it is printed first.  */
 264   unsigned int number;
 265
 266   /* True if the instruction was executed speculatively.  */
 267   unsigned int is_speculative:1;
 268 };
 269
 270 extern void gdb_disassembly (struct gdbarch *gdbarch, struct ui_out *uiout,
 271                              gdb_disassembly_flags flags, int how_many,
 272                              CORE_ADDR low, CORE_ADDR high);
 273
 274 /* Print the instruction at address MEMADDR in debugged memory,
 275    on STREAM.  Returns the length of the instruction, in bytes,
 276    and, if requested, the number of branch delay slot instructions.  */
 277
 278 extern int gdb_print_insn (struct gdbarch *gdbarch, CORE_ADDR memaddr,
 279                            struct ui_file *stream, int *branch_delay_insns);
 280
 281 /* Class used to pretty-print instructions.  */
 282
 283 class gdb_pretty_print_disassembler
 284 {
 285 public:
 286   explicit gdb_pretty_print_disassembler (struct gdbarch *gdbarch,
 287                                           struct ui_out *uiout)
 288     : m_uiout (uiout),
 289       m_insn_stb (uiout->can_emit_style_escape ()),
 290       m_di (gdbarch, &m_insn_stb)
 291   {}
 292
 293   /* Prints the instruction INSN into the saved ui_out and returns the
 294      length of the printed instruction in bytes.  */
 295   int pretty_print_insn (const struct disasm_insn *insn,
 296                          gdb_disassembly_flags flags);
 297
 298 private:
 299   /* Returns the architecture used for disassembling.  */
 300   struct gdbarch *arch () { return m_di.arch (); }
 301
 302   /* The ui_out that is used by pretty_print_insn.  */
 303   struct ui_out *m_uiout;
 304
 305   /* The buffer used to build the instruction string.  The
 306      disassembler is initialized with this stream.  */
 307   string_file m_insn_stb;
 308
 309   /* The disassembler used for instruction printing.  */
 310   gdb_disassembler m_di;
 311
 312   /* The buffer used to build the raw opcodes string.  */
 313   string_file m_opcode_stb;
 314 };
 315
 316 /* Return the length in bytes of the instruction at address MEMADDR in
 317    debugged memory.  */
 318
 319 extern int gdb_insn_length (struct gdbarch *gdbarch, CORE_ADDR memaddr);
 320
 321 /* Return the length in bytes of INSN, originally at MEMADDR.  MAX_LEN
 322    is the size of the buffer containing INSN.  */
 323
 324 extern int gdb_buffered_insn_length (struct gdbarch *gdbarch,
 325                                      const gdb_byte *insn, int max_len,
 326                                      CORE_ADDR memaddr);
 327
 328 /* Returns GDBARCH's disassembler options.  */
 329
 330 extern char *get_disassembler_options (struct gdbarch *gdbarch);
 331
 332 /* Sets the active gdbarch's disassembler options to OPTIONS.  */
 333
 334 extern void set_disassembler_options (const char *options);
 335
 336 #endif