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 //----------------------------------------------------------------------
  23 /// @class EmulateInstruction EmulateInstruction.h "lldb/Core/EmulateInstruction.h"
  24 /// @brief A class that allows emulation of CPU opcodes.
  25 ///
  26 /// This class is a plug-in interface that is accessed through the
  27 /// standard static FindPlugin function call in the EmulateInstruction
  28 /// class. The FindPlugin takes a target triple and returns a new object
  29 /// if there is a plug-in that supports the architecture and OS. Four
  30 /// callbacks and a baton are provided. The four callbacks are read
  31 /// register, write register, read memory and write memory.
  32 ///
  33 /// This class is currently designed for these main use cases:
  34 /// - Auto generation of Call Frame Information (CFI) from assembly code
  35 /// - Predicting single step breakpoint locations
  36 /// - Emulating instructions for breakpoint traps
  37 ///
  38 /// Objects can be asked to read an instruction which will cause a call
  39 /// to the read register callback to get the PC, followed by a read
  40 /// memory call to read the opcode. If ReadInstruction () returns true,
  41 /// then a call to EmulateInstruction::EvaluateInstruction () can be
  42 /// made. At this point the EmulateInstruction subclass will use all of
  43 /// the callbacks to emulate an instruction.
  44 ///
  45 /// Clients that provide the callbacks can either do the read/write
  46 /// registers/memory to actually emulate the instruction on a real or
  47 /// virtual CPU, or watch for the EmulateInstruction::Context which
  48 /// is context for the read/write register/memory which explains why
  49 /// the callback is being called. Examples of a context are:
  50 /// "pushing register 3 onto the stack at offset -12", or "adjusting
  51 /// stack pointer by -16". This extra context allows the generation of
  52 /// CFI information from assembly code without having to actually do
  53 /// the read/write register/memory.
  54 ///
  55 /// Clients must be prepared that not all instructions for an
  56 /// Instruction Set Architecture (ISA) will be emulated.
  57 ///
  58 /// Subclasses at the very least should implement the instructions that
  59 /// save and restore registers onto the stack and adjustment to the stack
  60 /// pointer. By just implementing a few instructions for an ISA that are
  61 /// the typical prologue opcodes, you can then generate CFI using a
  62 /// class that will soon be available.
  63 ///
  64 /// Implementing all of the instructions that affect the PC can then
  65 /// allow single step prediction support.
  66 ///
  67 /// Implementing all of the instructions allows for emulation of opcodes
  68 /// for breakpoint traps and will pave the way for "thread centric"
  69 /// debugging. The current debugging model is "process centric" where
  70 /// all threads must be stopped when any thread is stopped; when
  71 /// hitting software breakpoints we must disable the breakpoint by
  72 /// restoring the original breakpoint opcde, single stepping and
  73 /// restoring the breakpoint trap. If all threads were allowed to run
  74 /// then other threads could miss the breakpoint.
  75 ///
  76 /// This class centralizes the code that usually is done in separate
  77 /// code paths in a debugger (single step prediction, finding save
  78 /// restore locations of registers for unwinding stack frame variables)
  79 /// and emulating the intruction is just a bonus.
  80 //----------------------------------------------------------------------
  81
  82 namespace lldb_private {
  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 instruciton 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;   // immdiate data
 227             } ISAAndImmediate;
 228
 229             struct ISAAndImmediateSigned
 230             {
 231                 uint32_t isa;
 232                 int32_t signed_data32;      // signed immdiate data
 233             } ISAAndImmediateSigned;
 234
 235             uint32_t isa;
 236
 237         } info;
 238
 239         Context () :
 240             type (eContextInvalid),
 241             info_type (eInfoTypeNoArgs)
 242         {
 243         }
 244
 245         void
 246         SetRegisterPlusOffset (RegisterInfo base_reg,
 247                                int64_t signed_offset)
 248         {
 249             info_type = eInfoTypeRegisterPlusOffset;
 250             info.RegisterPlusOffset.reg = base_reg;
 251             info.RegisterPlusOffset.signed_offset = signed_offset;
 252         }
 253
 254         void
 255         SetRegisterPlusIndirectOffset (RegisterInfo base_reg,
 256                                        RegisterInfo offset_reg)
 257         {
 258             info_type = eInfoTypeRegisterPlusIndirectOffset;
 259             info.RegisterPlusIndirectOffset.base_reg   = base_reg;
 260             info.RegisterPlusIndirectOffset.offset_reg = offset_reg;
 261         }
 262
 263         void
 264         SetRegisterToRegisterPlusOffset (RegisterInfo data_reg,
 265                                          RegisterInfo base_reg,
 266                                          int64_t offset)
 267         {
 268             info_type = eInfoTypeRegisterToRegisterPlusOffset;
 269             info.RegisterToRegisterPlusOffset.data_reg = data_reg;
 270             info.RegisterToRegisterPlusOffset.base_reg = base_reg;
 271             info.RegisterToRegisterPlusOffset.offset   = offset;
 272         }
 273
 274         void
 275         SetRegisterToRegisterPlusIndirectOffset (RegisterInfo base_reg,
 276                                                  RegisterInfo offset_reg,
 277                                                  RegisterInfo data_reg)
 278         {
 279             info_type = eInfoTypeRegisterToRegisterPlusIndirectOffset;
 280             info.RegisterToRegisterPlusIndirectOffset.base_reg   = base_reg;
 281             info.RegisterToRegisterPlusIndirectOffset.offset_reg = offset_reg;
 282             info.RegisterToRegisterPlusIndirectOffset.data_reg   = data_reg;
 283         }
 284
 285         void
 286         SetRegisterRegisterOperands (RegisterInfo op1_reg,
 287                                      RegisterInfo op2_reg)
 288         {
 289             info_type = eInfoTypeRegisterRegisterOperands;
 290             info.RegisterRegisterOperands.operand1 = op1_reg;
 291             info.RegisterRegisterOperands.operand2 = op2_reg;
 292         }
 293
 294         void
 295         SetOffset (int64_t signed_offset)
 296         {
 297             info_type = eInfoTypeOffset;
 298             info.signed_offset = signed_offset;
 299         }
 300
 301         void
 302         SetRegister (RegisterInfo reg)
 303         {
 304             info_type = eInfoTypeRegister;
 305             info.reg = reg;
 306         }
 307
 308         void
 309         SetImmediate (uint64_t immediate)
 310         {
 311             info_type = eInfoTypeImmediate;
 312             info.unsigned_immediate = immediate;
 313         }
 314
 315         void
 316         SetImmediateSigned (int64_t signed_immediate)
 317         {
 318             info_type = eInfoTypeImmediateSigned;
 319             info.signed_immediate = signed_immediate;
 320         }
 321
 322         void
 323         SetAddress (lldb::addr_t address)
 324         {
 325             info_type = eInfoTypeAddress;
 326             info.address = address;
 327         }
 328         void
 329         SetISAAndImmediate (uint32_t isa, uint32_t data)
 330         {
 331             info_type = eInfoTypeISAAndImmediate;
 332             info.ISAAndImmediate.isa = isa;
 333             info.ISAAndImmediate.unsigned_data32 = data;
 334         }
 335
 336         void
 337         SetISAAndImmediateSigned (uint32_t isa, int32_t data)
 338         {
 339             info_type = eInfoTypeISAAndImmediateSigned;
 340             info.ISAAndImmediateSigned.isa = isa;
 341             info.ISAAndImmediateSigned.signed_data32 = data;
 342         }
 343
 344         void
 345         SetISA (uint32_t isa)
 346         {
 347             info_type = eInfoTypeISA;
 348             info.isa = isa;
 349         }
 350
 351         void
 352         SetNoArgs ()
 353         {
 354             info_type = eInfoTypeNoArgs;
 355         }
 356
 357         void
 358         Dump (Stream &s,
 359               EmulateInstruction *instruction) const;
 360
 361     };
 362
 363     typedef size_t (*ReadMemoryCallback) (EmulateInstruction *instruction,
 364                                           void *baton,
 365                                           const Context &context,
 366                                           lldb::addr_t addr,
 367                                           void *dst,
 368                                           size_t length);
 369
 370     typedef size_t (*WriteMemoryCallback) (EmulateInstruction *instruction,
 371                                            void *baton,
 372                                            const Context &context,
 373                                            lldb::addr_t addr,
 374                                            const void *dst,
 375                                            size_t length);
 376
 377     typedef bool   (*ReadRegisterCallback)  (EmulateInstruction *instruction,
 378                                              void *baton,
 379                                              const RegisterInfo *reg_info,
 380                                              RegisterValue &reg_value);
 381
 382     typedef bool   (*WriteRegisterCallback) (EmulateInstruction *instruction,
 383                                              void *baton,
 384                                              const Context &context,
 385                                              const RegisterInfo *reg_info,
 386                                              const RegisterValue &reg_value);
 387
 388     EmulateInstruction (const ArchSpec &arch);
 389
 390     virtual ~EmulateInstruction()
 391     {
 392     }
 393     //----------------------------------------------------------------------
 394     // Mandatory overrides
 395     //----------------------------------------------------------------------
 396     virtual bool
 397     SupportsEmulatingIntructionsOfType (InstructionType inst_type) = 0;
 398
 399     virtual bool
 400     SetTargetTriple (const ArchSpec &arch) = 0;
 401
 402     virtual bool
 403     ReadInstruction () = 0;
 404
 405     virtual bool
 406     EvaluateInstruction (uint32_t evaluate_options) = 0;
 407
 408     virtual bool
 409     TestEmulation (Stream *out_stream, ArchSpec &arch, OptionValueDictionary *test_data) = 0;
 410
 411     virtual bool
 412     GetRegisterInfo (uint32_t reg_kind, uint32_t reg_num, RegisterInfo &reg_info) = 0;
 413
 414     //----------------------------------------------------------------------
 415     // Optional overrides
 416     //----------------------------------------------------------------------
 417     virtual bool
 418     SetInstruction (const Opcode &insn_opcode, const Address &inst_addr, Target *target);
 419
 420     virtual bool
 421     CreateFunctionEntryUnwind (UnwindPlan &unwind_plan);
 422
 423     static const char *
 424     TranslateRegister (uint32_t reg_kind, uint32_t reg_num, std::string &reg_name);
 425
 426     //----------------------------------------------------------------------
 427     // RegisterInfo variants
 428     //----------------------------------------------------------------------
 429     bool
 430     ReadRegister (const RegisterInfo *reg_info,
 431                   RegisterValue& reg_value);
 432
 433     uint64_t
 434     ReadRegisterUnsigned (const RegisterInfo *reg_info,
 435                           uint64_t fail_value,
 436                           bool *success_ptr);
 437
 438     bool
 439     WriteRegister (const Context &context,
 440                    const RegisterInfo *ref_info,
 441                    const RegisterValue& reg_value);
 442
 443     bool
 444     WriteRegisterUnsigned (const Context &context,
 445                            const RegisterInfo *reg_info,
 446                            uint64_t reg_value);
 447
 448     //----------------------------------------------------------------------
 449     // Register kind and number variants
 450     //----------------------------------------------------------------------
 451     bool
 452     ReadRegister (uint32_t reg_kind,
 453                   uint32_t reg_num,
 454                   RegisterValue& reg_value);
 455
 456     bool
 457     WriteRegister (const Context &context,
 458                    uint32_t reg_kind,
 459                    uint32_t reg_num,
 460                    const RegisterValue& reg_value);
 461
 462     uint64_t
 463     ReadRegisterUnsigned (uint32_t reg_kind,
 464                           uint32_t reg_num,
 465                           uint64_t fail_value,
 466                           bool *success_ptr);
 467
 468     bool
 469     WriteRegisterUnsigned (const Context &context,
 470                            uint32_t reg_kind,
 471                            uint32_t reg_num,
 472                            uint64_t reg_value);
 473
 474
 475     size_t
 476     ReadMemory (const Context &context,
 477                 lldb::addr_t addr,
 478                 void *dst,
 479                 size_t dst_len);
 480
 481     uint64_t
 482     ReadMemoryUnsigned (const Context &context,
 483                         lldb::addr_t addr,
 484                         size_t byte_size,
 485                         uint64_t fail_value,
 486                         bool *success_ptr);
 487
 488     bool
 489     WriteMemory (const Context &context,
 490                  lldb::addr_t addr,
 491                  const void *src,
 492                  size_t src_len);
 493
 494     bool
 495     WriteMemoryUnsigned (const Context &context,
 496                          lldb::addr_t addr,
 497                          uint64_t uval,
 498                          size_t uval_byte_size);
 499
 500     uint32_t
 501     GetAddressByteSize () const
 502     {
 503         return m_arch.GetAddressByteSize();
 504     }
 505
 506     lldb::ByteOrder
 507     GetByteOrder () const
 508     {
 509         return m_arch.GetByteOrder();
 510     }
 511
 512     const Opcode &
 513     GetOpcode () const
 514     {
 515         return m_opcode;
 516     }
 517
 518     lldb::addr_t
 519     GetAddress () const
 520     {
 521         return m_addr;
 522     }
 523
 524     const ArchSpec &
 525     GetArchitecture () const
 526     {
 527         return m_arch;
 528     }
 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                                   uint32_t &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
 632 private:
 633     //------------------------------------------------------------------
 634     // For EmulateInstruction only
 635     //------------------------------------------------------------------
 636     DISALLOW_COPY_AND_ASSIGN (EmulateInstruction);
 637 };
 638
 639 }   // namespace lldb_private
 640
 641 #endif  // lldb_EmulateInstruction_h_