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