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