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 ContextContext239 Context () : 240 type (eContextInvalid), 241 info_type (eInfoTypeNoArgs) 242 { 243 } 244 245 void SetRegisterPlusOffsetContext246 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 SetRegisterPlusIndirectOffsetContext255 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 SetRegisterToRegisterPlusOffsetContext264 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 SetRegisterToRegisterPlusIndirectOffsetContext275 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 SetRegisterRegisterOperandsContext286 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 SetOffsetContext295 SetOffset (int64_t signed_offset) 296 { 297 info_type = eInfoTypeOffset; 298 info.signed_offset = signed_offset; 299 } 300 301 void SetRegisterContext302 SetRegister (RegisterInfo reg) 303 { 304 info_type = eInfoTypeRegister; 305 info.reg = reg; 306 } 307 308 void SetImmediateContext309 SetImmediate (uint64_t immediate) 310 { 311 info_type = eInfoTypeImmediate; 312 info.unsigned_immediate = immediate; 313 } 314 315 void SetImmediateSignedContext316 SetImmediateSigned (int64_t signed_immediate) 317 { 318 info_type = eInfoTypeImmediateSigned; 319 info.signed_immediate = signed_immediate; 320 } 321 322 void SetAddressContext323 SetAddress (lldb::addr_t address) 324 { 325 info_type = eInfoTypeAddress; 326 info.address = address; 327 } 328 void SetISAAndImmediateContext329 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 SetISAAndImmediateSignedContext337 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 SetISAContext345 SetISA (uint32_t isa) 346 { 347 info_type = eInfoTypeISA; 348 info.isa = isa; 349 } 350 351 void SetNoArgsContext352 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 ®_value); 381 382 typedef bool (*WriteRegisterCallback) (EmulateInstruction *instruction, 383 void *baton, 384 const Context &context, 385 const RegisterInfo *reg_info, 386 const RegisterValue ®_value); 387 388 EmulateInstruction (const ArchSpec &arch); 389 ~EmulateInstruction()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 ®_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 ®_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 GetAddressByteSize()501 GetAddressByteSize () const 502 { 503 return m_arch.GetAddressByteSize(); 504 } 505 506 lldb::ByteOrder GetByteOrder()507 GetByteOrder () const 508 { 509 return m_arch.GetByteOrder(); 510 } 511 512 const Opcode & GetOpcode()513 GetOpcode () const 514 { 515 return m_opcode; 516 } 517 518 lldb::addr_t GetAddress()519 GetAddress () const 520 { 521 return m_addr; 522 } 523 524 const ArchSpec & GetArchitecture()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 ®_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 ®_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 ®_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 ®_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 ®_kind, 615 uint32_t ®_num); 616 617 static uint32_t 618 GetInternalRegisterNumber (RegisterContext *reg_ctx, 619 const RegisterInfo ®_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_ 642