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.  The
  62      remaining arguments are function callbacks that are written into m_di.
  63      Of these function callbacks FPRINTF_FUNC and FPRINTF_STYLED_FUNC must
  64      not be nullptr.  If READ_MEMORY_FUNC, MEMORY_ERROR_FUNC, or
  65      PRINT_ADDRESS_FUNC are nullptr, then that field within m_di is left
  66      with its default value (see the libopcodes function
  67      init_disassemble_info for the defaults).  */
  68   gdb_disassemble_info (struct gdbarch *gdbarch,
  69                         read_memory_ftype read_memory_func,
  70                         memory_error_ftype memory_error_func,
  71                         print_address_ftype print_address_func,
  72                         fprintf_ftype fprintf_func,
  73                         fprintf_styled_ftype fprintf_styled_func);
  74
  75   /* Destructor.  */
  76   virtual ~gdb_disassemble_info ();
  77
  78   /* Stores data required for disassembling instructions in
  79      opcodes.  */
  80   struct disassemble_info m_di;
  81
  82 private:
  83   /* The architecture we are disassembling for.  */
  84   struct gdbarch *m_gdbarch;
  85
  86   /* If we own the string in `m_di.disassembler_options', we do so
  87      using this field.  */
  88   std::string m_disassembler_options_holder;
  89 };
  90
  91 /* A wrapper around gdb_disassemble_info.  This class adds default
  92    print functions that are supplied to the disassemble_info within the
  93    parent class.  These default print functions write to the stream, which
  94    is also contained in the parent class.
  95
  96    As with the parent class, the constructor for this class is protected,
  97    you should not create instances of this class, but create an
  98    appropriate sub-class instead.  */
  99
 100 struct gdb_printing_disassembler : public gdb_disassemble_info
 101 {
 102   DISABLE_COPY_AND_ASSIGN (gdb_printing_disassembler);
 103
 104 protected:
 105
 106   /* The stream that disassembler output is being written too.  */
 107   struct ui_file *stream ()
 108   { return m_stream; }
 109
 110   /* Constructor.  All the arguments are just passed to the parent class.
 111      We also add the two print functions to the arguments passed to the
 112      parent.  See gdb_disassemble_info for a description of how the
 113      arguments are handled.  */
 114   gdb_printing_disassembler (struct gdbarch *gdbarch,
 115                              struct ui_file *stream,
 116                              read_memory_ftype read_memory_func,
 117                              memory_error_ftype memory_error_func,
 118                              print_address_ftype print_address_func)
 119     : gdb_disassemble_info (gdbarch, read_memory_func,
 120                             memory_error_func, print_address_func,
 121                             fprintf_func, fprintf_styled_func),
 122       m_stream (stream)
 123   {
 124     gdb_assert (stream != nullptr);
 125   }
 126
 127   /* Callback used as the disassemble_info's fprintf_func callback.  The
 128      DIS_INFO pointer is a pointer to a gdb_printing_disassembler object.
 129      Content is written to the m_stream extracted from DIS_INFO.  */
 130   static int fprintf_func (void *dis_info, const char *format, ...)
 131     ATTRIBUTE_PRINTF(2,3);
 132
 133   /* Callback used as the disassemble_info's fprintf_styled_func callback.
 134      The DIS_INFO pointer is a pointer to a gdb_printing_disassembler
 135      object.  Content is written to the m_stream extracted from DIS_INFO.  */
 136   static int fprintf_styled_func (void *dis_info,
 137                                   enum disassembler_style style,
 138                                   const char *format, ...)
 139     ATTRIBUTE_PRINTF(3,4);
 140
 141   /* Return true if the disassembler is considered inside a comment, false
 142      otherwise.  */
 143   bool in_comment_p () const
 144   { return m_in_comment; }
 145
 146   /* Set whether the disassembler should be considered as within comment
 147      text or not.  */
 148   void set_in_comment (bool c)
 149   { m_in_comment = c; }
 150
 151 private:
 152
 153   /* When libopcodes calls the fprintf_func and fprintf_styled_func
 154      callbacks, a 'void *' argument is passed.  We arrange, through our
 155      call to init_disassemble_info that this argument will be a pointer to
 156      a gdb_disassemble_info sub-class, specifically, a
 157      gdb_printing_disassembler pointer.  This helper function casts
 158      DIS_INFO to the correct type (with some asserts), and then returns the
 159      m_stream member variable.  */
 160   static ui_file *stream_from_gdb_disassemble_info (void *dis_info);
 161
 162   /* The stream to which output should be sent.  */
 163   struct ui_file *m_stream;
 164
 165   /* Are we inside a comment?  This will be set true if the disassembler
 166      uses styled output and emits a start of comment character.  It is up
 167      to the code that uses this disassembler class to reset this flag back
 168      to false at a suitable time (e.g. at the end of every line).  */
 169   bool m_in_comment;
 170 };
 171
 172 /* A basic disassembler that doesn't actually print anything.  */
 173
 174 struct gdb_non_printing_disassembler : public gdb_disassemble_info
 175 {
 176   gdb_non_printing_disassembler (struct gdbarch *gdbarch,
 177                                  read_memory_ftype read_memory_func)
 178     : gdb_disassemble_info (gdbarch,
 179                             read_memory_func,
 180                             nullptr /* memory_error_func */,
 181                             nullptr /* print_address_func */,
 182                             null_fprintf_func,
 183                             null_fprintf_styled_func)
 184   { /* Nothing.  */ }
 185
 186 private:
 187
 188   /* Callback used as the disassemble_info's fprintf_func callback, this
 189      doesn't write anything to STREAM, but just returns 0.  */
 190   static int null_fprintf_func (void *stream, const char *format, ...)
 191     ATTRIBUTE_PRINTF(2,3);
 192
 193   /* Callback used as the disassemble_info's fprintf_styled_func callback,
 194      , this doesn't write anything to STREAM, but just returns 0.  */
 195   static int null_fprintf_styled_func (void *stream,
 196                                        enum disassembler_style style,
 197                                        const char *format, ...)
 198     ATTRIBUTE_PRINTF(3,4);
 199 };
 200
 201 /* This is a helper class, for use as an additional base-class, by some of
 202    the disassembler classes below.  This class just defines a static method
 203    for reading from target memory, which can then be used by the various
 204    disassembler sub-classes.  */
 205
 206 struct gdb_disassembler_memory_reader
 207 {
 208   /* Implements the read_memory_func disassemble_info callback.  */
 209   static int dis_asm_read_memory (bfd_vma memaddr, gdb_byte *myaddr,
 210                                   unsigned int len,
 211                                   struct disassemble_info *info);
 212 };
 213
 214 /* A non-printing disassemble_info management class.  The disassemble_info
 215    setup by this class will not print anything to the output stream (there
 216    is no output stream), and the instruction to be disassembled will be
 217    read from target memory.  */
 218
 219 struct gdb_non_printing_memory_disassembler
 220   : public gdb_non_printing_disassembler,
 221     private gdb_disassembler_memory_reader
 222 {
 223   /* Constructor.  GDBARCH is the architecture to disassemble for.  */
 224   gdb_non_printing_memory_disassembler (struct gdbarch *gdbarch)
 225     :gdb_non_printing_disassembler (gdbarch, dis_asm_read_memory)
 226   { /* Nothing.  */ }
 227 };
 228
 229 /* A dissassembler class that provides 'print_insn', a method for
 230    disassembling a single instruction to the output stream.  */
 231
 232 struct gdb_disassembler : public gdb_printing_disassembler,
 233                           private gdb_disassembler_memory_reader
 234 {
 235   gdb_disassembler (struct gdbarch *gdbarch, struct ui_file *file)
 236     : gdb_disassembler (gdbarch, file, dis_asm_read_memory)
 237   { /* Nothing.  */ }
 238
 239   DISABLE_COPY_AND_ASSIGN (gdb_disassembler);
 240
 241   /* Disassemble a single instruction at MEMADDR to the ui_file* that was
 242      passed to the constructor.  If a memory error occurs while
 243      disassembling this instruction then an error will be thrown.  */
 244   int print_insn (CORE_ADDR memaddr, int *branch_delay_insns = NULL);
 245
 246 protected:
 247   gdb_disassembler (struct gdbarch *gdbarch, struct ui_file *file,
 248                     read_memory_ftype func);
 249
 250 private:
 251   /* This member variable is given a value by calling dis_asm_memory_error.
 252      If after calling into the libopcodes disassembler we get back a
 253      negative value (which indicates an error), then, if this variable has
 254      a value, we report a memory error to the user, otherwise, we report a
 255      non-memory error.  */
 256   gdb::optional<CORE_ADDR> m_err_memaddr;
 257
 258   /* Disassembler output is built up into this buffer.  Whether this
 259      string_file is created with styling support or not depends on the
 260      value of use_ext_lang_colorization_p, as well as whether disassembler
 261      styling in general is turned on, and also, whether *m_dest supports
 262      styling or not.  */
 263   string_file m_buffer;
 264
 265   /* The stream to which disassembler output will be written.  */
 266   ui_file *m_dest;
 267
 268   /* When true, m_buffer will be created without styling support,
 269      otherwise, m_buffer will be created with styling support.
 270
 271      This field will initially be true, but will be set to false if
 272      ext_lang_colorize_disasm fails to add styling at any time.
 273
 274      If the extension language is going to add the styling then m_buffer
 275      should be created without styling support, the extension language will
 276      then add styling at the end of the disassembly process.
 277
 278      If the extension language is not going to add the styling, then we
 279      create m_buffer with styling support, and GDB will add minimal styling
 280      (currently just to addresses and symbols) as it goes.  */
 281   static bool use_ext_lang_colorization_p;
 282
 283   static void dis_asm_memory_error (int err, bfd_vma memaddr,
 284                                     struct disassemble_info *info);
 285   static void dis_asm_print_address (bfd_vma addr,
 286                                      struct disassemble_info *info);
 287 };
 288
 289 /* An instruction to be disassembled.  */
 290
 291 struct disasm_insn
 292 {
 293   /* The address of the memory containing the instruction.  */
 294   CORE_ADDR addr;
 295
 296   /* An optional instruction number.  If non-zero, it is printed first.  */
 297   unsigned int number;
 298
 299   /* True if the instruction was executed speculatively.  */
 300   unsigned int is_speculative:1;
 301 };
 302
 303 extern void gdb_disassembly (struct gdbarch *gdbarch, struct ui_out *uiout,
 304                              gdb_disassembly_flags flags, int how_many,
 305                              CORE_ADDR low, CORE_ADDR high);
 306
 307 /* Print the instruction at address MEMADDR in debugged memory,
 308    on STREAM.  Returns the length of the instruction, in bytes,
 309    and, if requested, the number of branch delay slot instructions.  */
 310
 311 extern int gdb_print_insn (struct gdbarch *gdbarch, CORE_ADDR memaddr,
 312                            struct ui_file *stream, int *branch_delay_insns);
 313
 314 /* Class used to pretty-print instructions.  */
 315
 316 class gdb_pretty_print_disassembler
 317 {
 318 public:
 319   explicit gdb_pretty_print_disassembler (struct gdbarch *gdbarch,
 320                                           struct ui_out *uiout)
 321     : m_uiout (uiout),
 322       m_insn_stb (uiout->can_emit_style_escape ()),
 323       m_di (gdbarch, &m_insn_stb)
 324   {}
 325
 326   /* Prints the instruction INSN into the saved ui_out and returns the
 327      length of the printed instruction in bytes.  */
 328   int pretty_print_insn (const struct disasm_insn *insn,
 329                          gdb_disassembly_flags flags);
 330
 331 private:
 332   /* Returns the architecture used for disassembling.  */
 333   struct gdbarch *arch () { return m_di.arch (); }
 334
 335   /* The ui_out that is used by pretty_print_insn.  */
 336   struct ui_out *m_uiout;
 337
 338   /* The buffer used to build the instruction string.  The
 339      disassembler is initialized with this stream.  */
 340   string_file m_insn_stb;
 341
 342   /* The disassembler used for instruction printing.  */
 343   gdb_disassembler m_di;
 344
 345   /* The buffer used to build the raw opcodes string.  */
 346   string_file m_opcode_stb;
 347 };
 348
 349 /* Return the length in bytes of the instruction at address MEMADDR in
 350    debugged memory.  */
 351
 352 extern int gdb_insn_length (struct gdbarch *gdbarch, CORE_ADDR memaddr);
 353
 354 /* Return the length in bytes of INSN, originally at MEMADDR.  MAX_LEN
 355    is the size of the buffer containing INSN.  */
 356
 357 extern int gdb_buffered_insn_length (struct gdbarch *gdbarch,
 358                                      const gdb_byte *insn, int max_len,
 359                                      CORE_ADDR memaddr);
 360
 361 /* Returns GDBARCH's disassembler options.  */
 362
 363 extern char *get_disassembler_options (struct gdbarch *gdbarch);
 364
 365 /* Sets the active gdbarch's disassembler options to OPTIONS.  */
 366
 367 extern void set_disassembler_options (const char *options);
 368
 369 #endif