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     // Type to represent the condition of an instruction. The UINT32 value is reserved for the
 388     // unconditional case and all other value can be used in an architecture dependent way.
 389     typedef uint32_t InstructionCondition;
 390     static const InstructionCondition UnconditionalCondition = UINT32_MAX;
 391
 392     EmulateInstruction (const ArchSpec &arch);
 393
 394     ~EmulateInstruction() override = default;
 395
 396     //----------------------------------------------------------------------
 397     // Mandatory overrides
 398     //----------------------------------------------------------------------
 399     virtual bool
 400     SupportsEmulatingInstructionsOfType (InstructionType inst_type) = 0;
 401
 402     virtual bool
 403     SetTargetTriple (const ArchSpec &arch) = 0;
 404
 405     virtual bool
 406     ReadInstruction () = 0;
 407
 408     virtual bool
 409     EvaluateInstruction (uint32_t evaluate_options) = 0;
 410
 411     virtual InstructionCondition
 412     GetInstructionCondition() { return UnconditionalCondition; }
 413
 414     virtual bool
 415     TestEmulation (Stream *out_stream, ArchSpec &arch, OptionValueDictionary *test_data) = 0;
 416
 417     virtual bool
 418     GetRegisterInfo (lldb::RegisterKind reg_kind, uint32_t reg_num, RegisterInfo &reg_info) = 0;
 419
 420     //----------------------------------------------------------------------
 421     // Optional overrides
 422     //----------------------------------------------------------------------
 423     virtual bool
 424     SetInstruction (const Opcode &insn_opcode, const Address &inst_addr, Target *target);
 425
 426     virtual bool
 427     CreateFunctionEntryUnwind (UnwindPlan &unwind_plan);
 428
 429     static const char *
 430     TranslateRegister (lldb::RegisterKind reg_kind, uint32_t reg_num, std::string &reg_name);
 431
 432     //----------------------------------------------------------------------
 433     // RegisterInfo variants
 434     //----------------------------------------------------------------------
 435     bool
 436     ReadRegister (const RegisterInfo *reg_info,
 437                   RegisterValue& reg_value);
 438
 439     uint64_t
 440     ReadRegisterUnsigned (const RegisterInfo *reg_info,
 441                           uint64_t fail_value,
 442                           bool *success_ptr);
 443
 444     bool
 445     WriteRegister (const Context &context,
 446                    const RegisterInfo *ref_info,
 447                    const RegisterValue& reg_value);
 448
 449     bool
 450     WriteRegisterUnsigned (const Context &context,
 451                            const RegisterInfo *reg_info,
 452                            uint64_t reg_value);
 453
 454     //----------------------------------------------------------------------
 455     // Register kind and number variants
 456     //----------------------------------------------------------------------
 457     bool
 458     ReadRegister (lldb::RegisterKind reg_kind,
 459                   uint32_t reg_num,
 460                   RegisterValue& reg_value);
 461
 462     bool
 463     WriteRegister (const Context &context,
 464                    lldb::RegisterKind reg_kind,
 465                    uint32_t reg_num,
 466                    const RegisterValue& reg_value);
 467
 468     uint64_t
 469     ReadRegisterUnsigned (lldb::RegisterKind reg_kind,
 470                           uint32_t reg_num,
 471                           uint64_t fail_value,
 472                           bool *success_ptr);
 473
 474     bool
 475     WriteRegisterUnsigned (const Context &context,
 476                            lldb::RegisterKind reg_kind,
 477                            uint32_t reg_num,
 478                            uint64_t reg_value);
 479
 480
 481     size_t
 482     ReadMemory (const Context &context,
 483                 lldb::addr_t addr,
 484                 void *dst,
 485                 size_t dst_len);
 486
 487     uint64_t
 488     ReadMemoryUnsigned (const Context &context,
 489                         lldb::addr_t addr,
 490                         size_t byte_size,
 491                         uint64_t fail_value,
 492                         bool *success_ptr);
 493
 494     bool
 495     WriteMemory (const Context &context,
 496                  lldb::addr_t addr,
 497                  const void *src,
 498                  size_t src_len);
 499
 500     bool
 501     WriteMemoryUnsigned (const Context &context,
 502                          lldb::addr_t addr,
 503                          uint64_t uval,
 504                          size_t uval_byte_size);
 505
 506     uint32_t
 507     GetAddressByteSize () const
 508     {
 509         return m_arch.GetAddressByteSize();
 510     }
 511
 512     lldb::ByteOrder
 513     GetByteOrder () const
 514     {
 515         return m_arch.GetByteOrder();
 516     }
 517
 518     const Opcode &
 519     GetOpcode () const
 520     {
 521         return m_opcode;
 522     }
 523
 524     lldb::addr_t
 525     GetAddress () const
 526     {
 527         return m_addr;
 528     }
 529
 530     const ArchSpec &
 531     GetArchitecture () const
 532     {
 533         return m_arch;
 534     }
 535
 536     static size_t
 537     ReadMemoryFrame (EmulateInstruction *instruction,
 538                      void *baton,
 539                      const Context &context,
 540                      lldb::addr_t addr,
 541                      void *dst,
 542                      size_t length);
 543
 544     static size_t
 545     WriteMemoryFrame (EmulateInstruction *instruction,
 546                       void *baton,
 547                       const Context &context,
 548                       lldb::addr_t addr,
 549                       const void *dst,
 550                       size_t length);
 551
 552     static bool
 553     ReadRegisterFrame  (EmulateInstruction *instruction,
 554                         void *baton,
 555                         const RegisterInfo *reg_info,
 556                         RegisterValue &reg_value);
 557
 558
 559     static bool
 560     WriteRegisterFrame (EmulateInstruction *instruction,
 561                         void *baton,
 562                         const Context &context,
 563                         const RegisterInfo *reg_info,
 564                         const RegisterValue &reg_value);
 565
 566     static size_t
 567     ReadMemoryDefault (EmulateInstruction *instruction,
 568                        void *baton,
 569                        const Context &context,
 570                        lldb::addr_t addr,
 571                        void *dst,
 572                        size_t length);
 573
 574     static size_t
 575     WriteMemoryDefault (EmulateInstruction *instruction,
 576                         void *baton,
 577                         const Context &context,
 578                         lldb::addr_t addr,
 579                         const void *dst,
 580                         size_t length);
 581
 582     static bool
 583     ReadRegisterDefault  (EmulateInstruction *instruction,
 584                           void *baton,
 585                           const RegisterInfo *reg_info,
 586                           RegisterValue &reg_value);
 587
 588
 589     static bool
 590     WriteRegisterDefault (EmulateInstruction *instruction,
 591                           void *baton,
 592                           const Context &context,
 593                           const RegisterInfo *reg_info,
 594                           const RegisterValue &reg_value);
 595
 596     void
 597     SetBaton (void *baton);
 598
 599     void
 600     SetCallbacks (ReadMemoryCallback read_mem_callback,
 601                   WriteMemoryCallback write_mem_callback,
 602                   ReadRegisterCallback read_reg_callback,
 603                   WriteRegisterCallback write_reg_callback);
 604
 605     void
 606     SetReadMemCallback (ReadMemoryCallback read_mem_callback);
 607
 608     void
 609     SetWriteMemCallback (WriteMemoryCallback write_mem_callback);
 610
 611     void
 612     SetReadRegCallback (ReadRegisterCallback read_reg_callback);
 613
 614     void
 615     SetWriteRegCallback (WriteRegisterCallback write_reg_callback);
 616
 617     static bool
 618     GetBestRegisterKindAndNumber (const RegisterInfo *reg_info,
 619                                   lldb::RegisterKind &reg_kind,
 620                                   uint32_t &reg_num);
 621
 622     static uint32_t
 623     GetInternalRegisterNumber (RegisterContext *reg_ctx,
 624                                const RegisterInfo &reg_info);
 625
 626 protected:
 627     ArchSpec                m_arch;
 628     void *                  m_baton;
 629     ReadMemoryCallback      m_read_mem_callback;
 630     WriteMemoryCallback     m_write_mem_callback;
 631     ReadRegisterCallback    m_read_reg_callback;
 632     WriteRegisterCallback   m_write_reg_callback;
 633     lldb::addr_t            m_addr;
 634     Opcode                  m_opcode;
 635
 636 private:
 637     //------------------------------------------------------------------
 638     // For EmulateInstruction only
 639     //------------------------------------------------------------------
 640     DISALLOW_COPY_AND_ASSIGN (EmulateInstruction);
 641 };
 642
 643 } // namespace lldb_private
 644
 645 #endif // lldb_EmulateInstruction_h_