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