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