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