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