contrib/llvm/tools/lldb/include/lldb/Core/EmulateInstruction.h

   1 //===-- EmulateInstruction.h ------------------------------------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9
  10 #ifndef lldb_EmulateInstruction_h_
  11 #define lldb_EmulateInstruction_h_
  12
  13 #include <string>
  14
  15 #include "lldb/Core/ArchSpec.h"
  16 #include "lldb/Core/Opcode.h"
  17 #include "lldb/Core/PluginInterface.h"
  18
  19 #include "lldb/Core/Address.h"              // for Address
  20 #include "lldb/lldb-defines.h"              // for DISALLOW_COPY_AND_ASSIGN
  21 #include "lldb/lldb-enumerations.h"         // for RegisterKind, ByteOrder
  22 #include "lldb/lldb-private-enumerations.h" // for InstructionType
  23 #include "lldb/lldb-private-types.h"        // for RegisterInfo
  24 #include "lldb/lldb-types.h"                // for addr_t
  25
  26 #include <stddef.h> // for size_t
  27 #include <stdint.h> // for uint32_t, uint64_t, int64_t
  28 namespace lldb_private {
  29 class OptionValueDictionary;
  30 }
  31 namespace lldb_private {
  32 class RegisterContext;
  33 }
  34 namespace lldb_private {
  35 class RegisterValue;
  36 }
  37 namespace lldb_private {
  38 class Stream;
  39 }
  40 namespace lldb_private {
  41 class Target;
  42 }
  43 namespace lldb_private {
  44 class UnwindPlan;
  45 }
  46
  47 namespace lldb_private {
  48
  49 //----------------------------------------------------------------------
  50 /// @class EmulateInstruction EmulateInstruction.h
  51 /// "lldb/Core/EmulateInstruction.h"
  52 /// @brief A class that allows emulation of CPU opcodes.
  53 ///
  54 /// This class is a plug-in interface that is accessed through the
  55 /// standard static FindPlugin function call in the EmulateInstruction
  56 /// class. The FindPlugin takes a target triple and returns a new object
  57 /// if there is a plug-in that supports the architecture and OS. Four
  58 /// callbacks and a baton are provided. The four callbacks are read
  59 /// register, write register, read memory and write memory.
  60 ///
  61 /// This class is currently designed for these main use cases:
  62 /// - Auto generation of Call Frame Information (CFI) from assembly code
  63 /// - Predicting single step breakpoint locations
  64 /// - Emulating instructions for breakpoint traps
  65 ///
  66 /// Objects can be asked to read an instruction which will cause a call
  67 /// to the read register callback to get the PC, followed by a read
  68 /// memory call to read the opcode. If ReadInstruction () returns true,
  69 /// then a call to EmulateInstruction::EvaluateInstruction () can be
  70 /// made. At this point the EmulateInstruction subclass will use all of
  71 /// the callbacks to emulate an instruction.
  72 ///
  73 /// Clients that provide the callbacks can either do the read/write
  74 /// registers/memory to actually emulate the instruction on a real or
  75 /// virtual CPU, or watch for the EmulateInstruction::Context which
  76 /// is context for the read/write register/memory which explains why
  77 /// the callback is being called. Examples of a context are:
  78 /// "pushing register 3 onto the stack at offset -12", or "adjusting
  79 /// stack pointer by -16". This extra context allows the generation of
  80 /// CFI information from assembly code without having to actually do
  81 /// the read/write register/memory.
  82 ///
  83 /// Clients must be prepared that not all instructions for an
  84 /// Instruction Set Architecture (ISA) will be emulated.
  85 ///
  86 /// Subclasses at the very least should implement the instructions that
  87 /// save and restore registers onto the stack and adjustment to the stack
  88 /// pointer. By just implementing a few instructions for an ISA that are
  89 /// the typical prologue opcodes, you can then generate CFI using a
  90 /// class that will soon be available.
  91 ///
  92 /// Implementing all of the instructions that affect the PC can then
  93 /// allow single step prediction support.
  94 ///
  95 /// Implementing all of the instructions allows for emulation of opcodes
  96 /// for breakpoint traps and will pave the way for "thread centric"
  97 /// debugging. The current debugging model is "process centric" where
  98 /// all threads must be stopped when any thread is stopped; when
  99 /// hitting software breakpoints we must disable the breakpoint by
 100 /// restoring the original breakpoint opcode, single stepping and
 101 /// restoring the breakpoint trap. If all threads were allowed to run
 102 /// then other threads could miss the breakpoint.
 103 ///
 104 /// This class centralizes the code that usually is done in separate
 105 /// code paths in a debugger (single step prediction, finding save
 106 /// restore locations of registers for unwinding stack frame variables)
 107 /// and emulating the instruction is just a bonus.
 108 //----------------------------------------------------------------------
 109
 110 class EmulateInstruction : public PluginInterface {
 111 public:
 112   static EmulateInstruction *FindPlugin(const ArchSpec &arch,
 113                                         InstructionType supported_inst_type,
 114                                         const char *plugin_name);
 115
 116   enum ContextType {
 117     eContextInvalid = 0,
 118     // Read an instruction opcode from memory
 119     eContextReadOpcode,
 120
 121     // Usually used for writing a register value whose source value is an
 122     // immediate
 123     eContextImmediate,
 124
 125     // Exclusively used when saving a register to the stack as part of the
 126     // prologue
 127     eContextPushRegisterOnStack,
 128
 129     // Exclusively used when restoring a register off the stack as part of
 130     // the epilogue
 131     eContextPopRegisterOffStack,
 132
 133     // Add or subtract a value from the stack
 134     eContextAdjustStackPointer,
 135
 136     // Adjust the frame pointer for the current frame
 137     eContextSetFramePointer,
 138
 139     // Typically in an epilogue sequence.  Copy the frame pointer back
 140     // into the stack pointer, use SP for CFA calculations again.
 141     eContextRestoreStackPointer,
 142
 143     // Add or subtract a value from a base address register (other than SP)
 144     eContextAdjustBaseRegister,
 145
 146     // Add or subtract a value from the PC or store a value to the PC.
 147     eContextAdjustPC,
 148
 149     // Used in WriteRegister callbacks to indicate where the
 150     eContextRegisterPlusOffset,
 151
 152     // Used in WriteMemory callback to indicate where the data came from
 153     eContextRegisterStore,
 154
 155     eContextRegisterLoad,
 156
 157     // Used when performing a PC-relative branch where the
 158     eContextRelativeBranchImmediate,
 159
 160     // Used when performing an absolute branch where the
 161     eContextAbsoluteBranchRegister,
 162
 163     // Used when performing a supervisor call to an operating system to
 164     // provide a service:
 165     eContextSupervisorCall,
 166
 167     // Used when performing a MemU operation to read the PC-relative offset
 168     // from an address.
 169     eContextTableBranchReadMemory,
 170
 171     // Used when random bits are written into a register
 172     eContextWriteRegisterRandomBits,
 173
 174     // Used when random bits are written to memory
 175     eContextWriteMemoryRandomBits,
 176
 177     eContextArithmetic,
 178
 179     eContextAdvancePC,
 180
 181     eContextReturnFromException
 182   };
 183
 184   enum InfoType {
 185     eInfoTypeRegisterPlusOffset,
 186     eInfoTypeRegisterPlusIndirectOffset,
 187     eInfoTypeRegisterToRegisterPlusOffset,
 188     eInfoTypeRegisterToRegisterPlusIndirectOffset,
 189     eInfoTypeRegisterRegisterOperands,
 190     eInfoTypeOffset,
 191     eInfoTypeRegister,
 192     eInfoTypeImmediate,
 193     eInfoTypeImmediateSigned,
 194     eInfoTypeAddress,
 195     eInfoTypeISAAndImmediate,
 196     eInfoTypeISAAndImmediateSigned,
 197     eInfoTypeISA,
 198     eInfoTypeNoArgs
 199   } InfoType;
 200
 201   struct Context {
 202     ContextType type;
 203     enum InfoType info_type;
 204     union {
 205       struct RegisterPlusOffset {
 206         RegisterInfo reg;      // base register
 207         int64_t signed_offset; // signed offset added to base register
 208       } RegisterPlusOffset;
 209
 210       struct RegisterPlusIndirectOffset {
 211         RegisterInfo base_reg;   // base register number
 212         RegisterInfo offset_reg; // offset register kind
 213       } RegisterPlusIndirectOffset;
 214
 215       struct RegisterToRegisterPlusOffset {
 216         RegisterInfo data_reg; // source/target register for data
 217         RegisterInfo base_reg; // base register for address calculation
 218         int64_t offset;        // offset for address calculation
 219       } RegisterToRegisterPlusOffset;
 220
 221       struct RegisterToRegisterPlusIndirectOffset {
 222         RegisterInfo base_reg;   // base register for address calculation
 223         RegisterInfo offset_reg; // offset register for address calculation
 224         RegisterInfo data_reg;   // source/target register for data
 225       } RegisterToRegisterPlusIndirectOffset;
 226
 227       struct RegisterRegisterOperands {
 228         RegisterInfo
 229             operand1; // register containing first operand for binary op
 230         RegisterInfo
 231             operand2; // register containing second operand for binary op
 232       } RegisterRegisterOperands;
 233
 234       int64_t signed_offset; // signed offset by which to adjust self (for
 235                              // registers only)
 236
 237       RegisterInfo reg; // plain register
 238
 239       uint64_t unsigned_immediate; // unsigned immediate value
 240       int64_t signed_immediate;    // signed immediate value
 241
 242       lldb::addr_t address; // direct address
 243
 244       struct ISAAndImmediate {
 245         uint32_t isa;
 246         uint32_t unsigned_data32; // immediate data
 247       } ISAAndImmediate;
 248
 249       struct ISAAndImmediateSigned {
 250         uint32_t isa;
 251         int32_t signed_data32; // signed immediate data
 252       } ISAAndImmediateSigned;
 253
 254       uint32_t isa;
 255     } info;
 256
 257     Context() : type(eContextInvalid), info_type(eInfoTypeNoArgs) {}
 258
 259     void SetRegisterPlusOffset(RegisterInfo base_reg, int64_t signed_offset) {
 260       info_type = eInfoTypeRegisterPlusOffset;
 261       info.RegisterPlusOffset.reg = base_reg;
 262       info.RegisterPlusOffset.signed_offset = signed_offset;
 263     }
 264
 265     void SetRegisterPlusIndirectOffset(RegisterInfo base_reg,
 266                                        RegisterInfo offset_reg) {
 267       info_type = eInfoTypeRegisterPlusIndirectOffset;
 268       info.RegisterPlusIndirectOffset.base_reg = base_reg;
 269       info.RegisterPlusIndirectOffset.offset_reg = offset_reg;
 270     }
 271
 272     void SetRegisterToRegisterPlusOffset(RegisterInfo data_reg,
 273                                          RegisterInfo base_reg,
 274                                          int64_t offset) {
 275       info_type = eInfoTypeRegisterToRegisterPlusOffset;
 276       info.RegisterToRegisterPlusOffset.data_reg = data_reg;
 277       info.RegisterToRegisterPlusOffset.base_reg = base_reg;
 278       info.RegisterToRegisterPlusOffset.offset = offset;
 279     }
 280
 281     void SetRegisterToRegisterPlusIndirectOffset(RegisterInfo base_reg,
 282                                                  RegisterInfo offset_reg,
 283                                                  RegisterInfo data_reg) {
 284       info_type = eInfoTypeRegisterToRegisterPlusIndirectOffset;
 285       info.RegisterToRegisterPlusIndirectOffset.base_reg = base_reg;
 286       info.RegisterToRegisterPlusIndirectOffset.offset_reg = offset_reg;
 287       info.RegisterToRegisterPlusIndirectOffset.data_reg = data_reg;
 288     }
 289
 290     void SetRegisterRegisterOperands(RegisterInfo op1_reg,
 291                                      RegisterInfo op2_reg) {
 292       info_type = eInfoTypeRegisterRegisterOperands;
 293       info.RegisterRegisterOperands.operand1 = op1_reg;
 294       info.RegisterRegisterOperands.operand2 = op2_reg;
 295     }
 296
 297     void SetOffset(int64_t signed_offset) {
 298       info_type = eInfoTypeOffset;
 299       info.signed_offset = signed_offset;
 300     }
 301
 302     void SetRegister(RegisterInfo reg) {
 303       info_type = eInfoTypeRegister;
 304       info.reg = reg;
 305     }
 306
 307     void SetImmediate(uint64_t immediate) {
 308       info_type = eInfoTypeImmediate;
 309       info.unsigned_immediate = immediate;
 310     }
 311
 312     void SetImmediateSigned(int64_t signed_immediate) {
 313       info_type = eInfoTypeImmediateSigned;
 314       info.signed_immediate = signed_immediate;
 315     }
 316
 317     void SetAddress(lldb::addr_t address) {
 318       info_type = eInfoTypeAddress;
 319       info.address = address;
 320     }
 321     void SetISAAndImmediate(uint32_t isa, uint32_t data) {
 322       info_type = eInfoTypeISAAndImmediate;
 323       info.ISAAndImmediate.isa = isa;
 324       info.ISAAndImmediate.unsigned_data32 = data;
 325     }
 326
 327     void SetISAAndImmediateSigned(uint32_t isa, int32_t data) {
 328       info_type = eInfoTypeISAAndImmediateSigned;
 329       info.ISAAndImmediateSigned.isa = isa;
 330       info.ISAAndImmediateSigned.signed_data32 = data;
 331     }
 332
 333     void SetISA(uint32_t isa) {
 334       info_type = eInfoTypeISA;
 335       info.isa = isa;
 336     }
 337
 338     void SetNoArgs() { info_type = eInfoTypeNoArgs; }
 339
 340     void Dump(Stream &s, EmulateInstruction *instruction) const;
 341   };
 342
 343   typedef size_t (*ReadMemoryCallback)(EmulateInstruction *instruction,
 344                                        void *baton, const Context &context,
 345                                        lldb::addr_t addr, void *dst,
 346                                        size_t length);
 347
 348   typedef size_t (*WriteMemoryCallback)(EmulateInstruction *instruction,
 349                                         void *baton, const Context &context,
 350                                         lldb::addr_t addr, const void *dst,
 351                                         size_t length);
 352
 353   typedef bool (*ReadRegisterCallback)(EmulateInstruction *instruction,
 354                                        void *baton,
 355                                        const RegisterInfo *reg_info,
 356                                        RegisterValue &reg_value);
 357
 358   typedef bool (*WriteRegisterCallback)(EmulateInstruction *instruction,
 359                                         void *baton, const Context &context,
 360                                         const RegisterInfo *reg_info,
 361                                         const RegisterValue &reg_value);
 362
 363   // Type to represent the condition of an instruction. The UINT32 value is
 364   // reserved for the
 365   // unconditional case and all other value can be used in an architecture
 366   // dependent way.
 367   typedef uint32_t InstructionCondition;
 368   static const InstructionCondition UnconditionalCondition = UINT32_MAX;
 369
 370   EmulateInstruction(const ArchSpec &arch);
 371
 372   ~EmulateInstruction() override = default;
 373
 374   //----------------------------------------------------------------------
 375   // Mandatory overrides
 376   //----------------------------------------------------------------------
 377   virtual bool
 378   SupportsEmulatingInstructionsOfType(InstructionType inst_type) = 0;
 379
 380   virtual bool SetTargetTriple(const ArchSpec &arch) = 0;
 381
 382   virtual bool ReadInstruction() = 0;
 383
 384   virtual bool EvaluateInstruction(uint32_t evaluate_options) = 0;
 385
 386   virtual InstructionCondition GetInstructionCondition() {
 387     return UnconditionalCondition;
 388   }
 389
 390   virtual bool TestEmulation(Stream *out_stream, ArchSpec &arch,
 391                              OptionValueDictionary *test_data) = 0;
 392
 393   virtual bool GetRegisterInfo(lldb::RegisterKind reg_kind, uint32_t reg_num,
 394                                RegisterInfo &reg_info) = 0;
 395
 396   //----------------------------------------------------------------------
 397   // Optional overrides
 398   //----------------------------------------------------------------------
 399   virtual bool SetInstruction(const Opcode &insn_opcode,
 400                               const Address &inst_addr, Target *target);
 401
 402   virtual bool CreateFunctionEntryUnwind(UnwindPlan &unwind_plan);
 403
 404   static const char *TranslateRegister(lldb::RegisterKind reg_kind,
 405                                        uint32_t reg_num, std::string &reg_name);
 406
 407   //----------------------------------------------------------------------
 408   // RegisterInfo variants
 409   //----------------------------------------------------------------------
 410   bool ReadRegister(const RegisterInfo *reg_info, RegisterValue &reg_value);
 411
 412   uint64_t ReadRegisterUnsigned(const RegisterInfo *reg_info,
 413                                 uint64_t fail_value, bool *success_ptr);
 414
 415   bool WriteRegister(const Context &context, const RegisterInfo *ref_info,
 416                      const RegisterValue &reg_value);
 417
 418   bool WriteRegisterUnsigned(const Context &context,
 419                              const RegisterInfo *reg_info, uint64_t reg_value);
 420
 421   //----------------------------------------------------------------------
 422   // Register kind and number variants
 423   //----------------------------------------------------------------------
 424   bool ReadRegister(lldb::RegisterKind reg_kind, uint32_t reg_num,
 425                     RegisterValue &reg_value);
 426
 427   bool WriteRegister(const Context &context, lldb::RegisterKind reg_kind,
 428                      uint32_t reg_num, const RegisterValue &reg_value);
 429
 430   uint64_t ReadRegisterUnsigned(lldb::RegisterKind reg_kind, uint32_t reg_num,
 431                                 uint64_t fail_value, bool *success_ptr);
 432
 433   bool WriteRegisterUnsigned(const Context &context,
 434                              lldb::RegisterKind reg_kind, uint32_t reg_num,
 435                              uint64_t reg_value);
 436
 437   size_t ReadMemory(const Context &context, lldb::addr_t addr, void *dst,
 438                     size_t dst_len);
 439
 440   uint64_t ReadMemoryUnsigned(const Context &context, lldb::addr_t addr,
 441                               size_t byte_size, uint64_t fail_value,
 442                               bool *success_ptr);
 443
 444   bool WriteMemory(const Context &context, lldb::addr_t addr, const void *src,
 445                    size_t src_len);
 446
 447   bool WriteMemoryUnsigned(const Context &context, lldb::addr_t addr,
 448                            uint64_t uval, size_t uval_byte_size);
 449
 450   uint32_t GetAddressByteSize() const { return m_arch.GetAddressByteSize(); }
 451
 452   lldb::ByteOrder GetByteOrder() const { return m_arch.GetByteOrder(); }
 453
 454   const Opcode &GetOpcode() const { return m_opcode; }
 455
 456   lldb::addr_t GetAddress() const { return m_addr; }
 457
 458   const ArchSpec &GetArchitecture() const { return m_arch; }
 459
 460   static size_t ReadMemoryFrame(EmulateInstruction *instruction, void *baton,
 461                                 const Context &context, lldb::addr_t addr,
 462                                 void *dst, size_t length);
 463
 464   static size_t WriteMemoryFrame(EmulateInstruction *instruction, void *baton,
 465                                  const Context &context, lldb::addr_t addr,
 466                                  const void *dst, size_t length);
 467
 468   static bool ReadRegisterFrame(EmulateInstruction *instruction, void *baton,
 469                                 const RegisterInfo *reg_info,
 470                                 RegisterValue &reg_value);
 471
 472   static bool WriteRegisterFrame(EmulateInstruction *instruction, void *baton,
 473                                  const Context &context,
 474                                  const RegisterInfo *reg_info,
 475                                  const RegisterValue &reg_value);
 476
 477   static size_t ReadMemoryDefault(EmulateInstruction *instruction, void *baton,
 478                                   const Context &context, lldb::addr_t addr,
 479                                   void *dst, size_t length);
 480
 481   static size_t WriteMemoryDefault(EmulateInstruction *instruction, void *baton,
 482                                    const Context &context, lldb::addr_t addr,
 483                                    const void *dst, size_t length);
 484
 485   static bool ReadRegisterDefault(EmulateInstruction *instruction, void *baton,
 486                                   const RegisterInfo *reg_info,
 487                                   RegisterValue &reg_value);
 488
 489   static bool WriteRegisterDefault(EmulateInstruction *instruction, void *baton,
 490                                    const Context &context,
 491                                    const RegisterInfo *reg_info,
 492                                    const RegisterValue &reg_value);
 493
 494   void SetBaton(void *baton);
 495
 496   void SetCallbacks(ReadMemoryCallback read_mem_callback,
 497                     WriteMemoryCallback write_mem_callback,
 498                     ReadRegisterCallback read_reg_callback,
 499                     WriteRegisterCallback write_reg_callback);
 500
 501   void SetReadMemCallback(ReadMemoryCallback read_mem_callback);
 502
 503   void SetWriteMemCallback(WriteMemoryCallback write_mem_callback);
 504
 505   void SetReadRegCallback(ReadRegisterCallback read_reg_callback);
 506
 507   void SetWriteRegCallback(WriteRegisterCallback write_reg_callback);
 508
 509   static bool GetBestRegisterKindAndNumber(const RegisterInfo *reg_info,
 510                                            lldb::RegisterKind &reg_kind,
 511                                            uint32_t &reg_num);
 512
 513   static uint32_t GetInternalRegisterNumber(RegisterContext *reg_ctx,
 514                                             const RegisterInfo &reg_info);
 515
 516 protected:
 517   ArchSpec m_arch;
 518   void *m_baton;
 519   ReadMemoryCallback m_read_mem_callback;
 520   WriteMemoryCallback m_write_mem_callback;
 521   ReadRegisterCallback m_read_reg_callback;
 522   WriteRegisterCallback m_write_reg_callback;
 523   lldb::addr_t m_addr;
 524   Opcode m_opcode;
 525
 526 private:
 527   //------------------------------------------------------------------
 528   // For EmulateInstruction only
 529   //------------------------------------------------------------------
 530   DISALLOW_COPY_AND_ASSIGN(EmulateInstruction);
 531 };
 532
 533 } // namespace lldb_private
 534
 535 #endif // lldb_EmulateInstruction_h_