1 //===-- EmulateInstruction.h ------------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef lldb_EmulateInstruction_h_
11 #define lldb_EmulateInstruction_h_
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"
22 namespace lldb_private {
24 //----------------------------------------------------------------------
25 /// @class EmulateInstruction EmulateInstruction.h
26 /// "lldb/Core/EmulateInstruction.h"
27 /// @brief A class that allows emulation of CPU opcodes.
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.
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
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.
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.
58 /// Clients must be prepared that not all instructions for an
59 /// Instruction Set Architecture (ISA) will be emulated.
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.
67 /// Implementing all of the instructions that affect the PC can then
68 /// allow single step prediction support.
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.
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 //----------------------------------------------------------------------
85 class EmulateInstruction : public PluginInterface {
87 static EmulateInstruction *FindPlugin(const ArchSpec &arch,
88 InstructionType supported_inst_type,
89 const char *plugin_name);
93 // Read an instruction opcode from memory
96 // Usually used for writing a register value whose source value is an
100 // Exclusively used when saving a register to the stack as part of the
102 eContextPushRegisterOnStack,
104 // Exclusively used when restoring a register off the stack as part of
106 eContextPopRegisterOffStack,
108 // Add or subtract a value from the stack
109 eContextAdjustStackPointer,
111 // Adjust the frame pointer for the current frame
112 eContextSetFramePointer,
114 // Typically in an epilogue sequence. Copy the frame pointer back
115 // into the stack pointer, use SP for CFA calculations again.
116 eContextRestoreStackPointer,
118 // Add or subtract a value from a base address register (other than SP)
119 eContextAdjustBaseRegister,
121 // Add or subtract a value from the PC or store a value to the PC.
124 // Used in WriteRegister callbacks to indicate where the
125 eContextRegisterPlusOffset,
127 // Used in WriteMemory callback to indicate where the data came from
128 eContextRegisterStore,
130 eContextRegisterLoad,
132 // Used when performing a PC-relative branch where the
133 eContextRelativeBranchImmediate,
135 // Used when performing an absolute branch where the
136 eContextAbsoluteBranchRegister,
138 // Used when performing a supervisor call to an operating system to
139 // provide a service:
140 eContextSupervisorCall,
142 // Used when performing a MemU operation to read the PC-relative offset
144 eContextTableBranchReadMemory,
146 // Used when random bits are written into a register
147 eContextWriteRegisterRandomBits,
149 // Used when random bits are written to memory
150 eContextWriteMemoryRandomBits,
156 eContextReturnFromException
160 eInfoTypeRegisterPlusOffset,
161 eInfoTypeRegisterPlusIndirectOffset,
162 eInfoTypeRegisterToRegisterPlusOffset,
163 eInfoTypeRegisterToRegisterPlusIndirectOffset,
164 eInfoTypeRegisterRegisterOperands,
168 eInfoTypeImmediateSigned,
170 eInfoTypeISAAndImmediate,
171 eInfoTypeISAAndImmediateSigned,
178 enum InfoType info_type;
180 struct RegisterPlusOffset {
181 RegisterInfo reg; // base register
182 int64_t signed_offset; // signed offset added to base register
183 } RegisterPlusOffset;
185 struct RegisterPlusIndirectOffset {
186 RegisterInfo base_reg; // base register number
187 RegisterInfo offset_reg; // offset register kind
188 } RegisterPlusIndirectOffset;
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;
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;
202 struct RegisterRegisterOperands {
204 operand1; // register containing first operand for binary op
206 operand2; // register containing second operand for binary op
207 } RegisterRegisterOperands;
209 int64_t signed_offset; // signed offset by which to adjust self (for
212 RegisterInfo reg; // plain register
214 uint64_t unsigned_immediate; // unsigned immediate value
215 int64_t signed_immediate; // signed immediate value
217 lldb::addr_t address; // direct address
219 struct ISAAndImmediate {
221 uint32_t unsigned_data32; // immediate data
224 struct ISAAndImmediateSigned {
226 int32_t signed_data32; // signed immediate data
227 } ISAAndImmediateSigned;
232 Context() : type(eContextInvalid), info_type(eInfoTypeNoArgs) {}
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;
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;
247 void SetRegisterToRegisterPlusOffset(RegisterInfo data_reg,
248 RegisterInfo base_reg,
250 info_type = eInfoTypeRegisterToRegisterPlusOffset;
251 info.RegisterToRegisterPlusOffset.data_reg = data_reg;
252 info.RegisterToRegisterPlusOffset.base_reg = base_reg;
253 info.RegisterToRegisterPlusOffset.offset = offset;
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;
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;
272 void SetOffset(int64_t signed_offset) {
273 info_type = eInfoTypeOffset;
274 info.signed_offset = signed_offset;
277 void SetRegister(RegisterInfo reg) {
278 info_type = eInfoTypeRegister;
282 void SetImmediate(uint64_t immediate) {
283 info_type = eInfoTypeImmediate;
284 info.unsigned_immediate = immediate;
287 void SetImmediateSigned(int64_t signed_immediate) {
288 info_type = eInfoTypeImmediateSigned;
289 info.signed_immediate = signed_immediate;
292 void SetAddress(lldb::addr_t address) {
293 info_type = eInfoTypeAddress;
294 info.address = address;
296 void SetISAAndImmediate(uint32_t isa, uint32_t data) {
297 info_type = eInfoTypeISAAndImmediate;
298 info.ISAAndImmediate.isa = isa;
299 info.ISAAndImmediate.unsigned_data32 = data;
302 void SetISAAndImmediateSigned(uint32_t isa, int32_t data) {
303 info_type = eInfoTypeISAAndImmediateSigned;
304 info.ISAAndImmediateSigned.isa = isa;
305 info.ISAAndImmediateSigned.signed_data32 = data;
308 void SetISA(uint32_t isa) {
309 info_type = eInfoTypeISA;
313 void SetNoArgs() { info_type = eInfoTypeNoArgs; }
315 void Dump(Stream &s, EmulateInstruction *instruction) const;
318 typedef size_t (*ReadMemoryCallback)(EmulateInstruction *instruction,
319 void *baton, const Context &context,
320 lldb::addr_t addr, void *dst,
323 typedef size_t (*WriteMemoryCallback)(EmulateInstruction *instruction,
324 void *baton, const Context &context,
325 lldb::addr_t addr, const void *dst,
328 typedef bool (*ReadRegisterCallback)(EmulateInstruction *instruction,
330 const RegisterInfo *reg_info,
331 RegisterValue ®_value);
333 typedef bool (*WriteRegisterCallback)(EmulateInstruction *instruction,
334 void *baton, const Context &context,
335 const RegisterInfo *reg_info,
336 const RegisterValue ®_value);
338 // Type to represent the condition of an instruction. The UINT32 value is
340 // unconditional case and all other value can be used in an architecture
342 typedef uint32_t InstructionCondition;
343 static const InstructionCondition UnconditionalCondition = UINT32_MAX;
345 EmulateInstruction(const ArchSpec &arch);
347 ~EmulateInstruction() override = default;
349 //----------------------------------------------------------------------
350 // Mandatory overrides
351 //----------------------------------------------------------------------
353 SupportsEmulatingInstructionsOfType(InstructionType inst_type) = 0;
355 virtual bool SetTargetTriple(const ArchSpec &arch) = 0;
357 virtual bool ReadInstruction() = 0;
359 virtual bool EvaluateInstruction(uint32_t evaluate_options) = 0;
361 virtual InstructionCondition GetInstructionCondition() {
362 return UnconditionalCondition;
365 virtual bool TestEmulation(Stream *out_stream, ArchSpec &arch,
366 OptionValueDictionary *test_data) = 0;
368 virtual bool GetRegisterInfo(lldb::RegisterKind reg_kind, uint32_t reg_num,
369 RegisterInfo ®_info) = 0;
371 //----------------------------------------------------------------------
372 // Optional overrides
373 //----------------------------------------------------------------------
374 virtual bool SetInstruction(const Opcode &insn_opcode,
375 const Address &inst_addr, Target *target);
377 virtual bool CreateFunctionEntryUnwind(UnwindPlan &unwind_plan);
379 static const char *TranslateRegister(lldb::RegisterKind reg_kind,
380 uint32_t reg_num, std::string ®_name);
382 //----------------------------------------------------------------------
383 // RegisterInfo variants
384 //----------------------------------------------------------------------
385 bool ReadRegister(const RegisterInfo *reg_info, RegisterValue ®_value);
387 uint64_t ReadRegisterUnsigned(const RegisterInfo *reg_info,
388 uint64_t fail_value, bool *success_ptr);
390 bool WriteRegister(const Context &context, const RegisterInfo *ref_info,
391 const RegisterValue ®_value);
393 bool WriteRegisterUnsigned(const Context &context,
394 const RegisterInfo *reg_info, uint64_t reg_value);
396 //----------------------------------------------------------------------
397 // Register kind and number variants
398 //----------------------------------------------------------------------
399 bool ReadRegister(lldb::RegisterKind reg_kind, uint32_t reg_num,
400 RegisterValue ®_value);
402 bool WriteRegister(const Context &context, lldb::RegisterKind reg_kind,
403 uint32_t reg_num, const RegisterValue ®_value);
405 uint64_t ReadRegisterUnsigned(lldb::RegisterKind reg_kind, uint32_t reg_num,
406 uint64_t fail_value, bool *success_ptr);
408 bool WriteRegisterUnsigned(const Context &context,
409 lldb::RegisterKind reg_kind, uint32_t reg_num,
412 size_t ReadMemory(const Context &context, lldb::addr_t addr, void *dst,
415 uint64_t ReadMemoryUnsigned(const Context &context, lldb::addr_t addr,
416 size_t byte_size, uint64_t fail_value,
419 bool WriteMemory(const Context &context, lldb::addr_t addr, const void *src,
422 bool WriteMemoryUnsigned(const Context &context, lldb::addr_t addr,
423 uint64_t uval, size_t uval_byte_size);
425 uint32_t GetAddressByteSize() const { return m_arch.GetAddressByteSize(); }
427 lldb::ByteOrder GetByteOrder() const { return m_arch.GetByteOrder(); }
429 const Opcode &GetOpcode() const { return m_opcode; }
431 lldb::addr_t GetAddress() const { return m_addr; }
433 const ArchSpec &GetArchitecture() const { return m_arch; }
435 static size_t ReadMemoryFrame(EmulateInstruction *instruction, void *baton,
436 const Context &context, lldb::addr_t addr,
437 void *dst, size_t length);
439 static size_t WriteMemoryFrame(EmulateInstruction *instruction, void *baton,
440 const Context &context, lldb::addr_t addr,
441 const void *dst, size_t length);
443 static bool ReadRegisterFrame(EmulateInstruction *instruction, void *baton,
444 const RegisterInfo *reg_info,
445 RegisterValue ®_value);
447 static bool WriteRegisterFrame(EmulateInstruction *instruction, void *baton,
448 const Context &context,
449 const RegisterInfo *reg_info,
450 const RegisterValue ®_value);
452 static size_t ReadMemoryDefault(EmulateInstruction *instruction, void *baton,
453 const Context &context, lldb::addr_t addr,
454 void *dst, size_t length);
456 static size_t WriteMemoryDefault(EmulateInstruction *instruction, void *baton,
457 const Context &context, lldb::addr_t addr,
458 const void *dst, size_t length);
460 static bool ReadRegisterDefault(EmulateInstruction *instruction, void *baton,
461 const RegisterInfo *reg_info,
462 RegisterValue ®_value);
464 static bool WriteRegisterDefault(EmulateInstruction *instruction, void *baton,
465 const Context &context,
466 const RegisterInfo *reg_info,
467 const RegisterValue ®_value);
469 void SetBaton(void *baton);
471 void SetCallbacks(ReadMemoryCallback read_mem_callback,
472 WriteMemoryCallback write_mem_callback,
473 ReadRegisterCallback read_reg_callback,
474 WriteRegisterCallback write_reg_callback);
476 void SetReadMemCallback(ReadMemoryCallback read_mem_callback);
478 void SetWriteMemCallback(WriteMemoryCallback write_mem_callback);
480 void SetReadRegCallback(ReadRegisterCallback read_reg_callback);
482 void SetWriteRegCallback(WriteRegisterCallback write_reg_callback);
484 static bool GetBestRegisterKindAndNumber(const RegisterInfo *reg_info,
485 lldb::RegisterKind ®_kind,
488 static uint32_t GetInternalRegisterNumber(RegisterContext *reg_ctx,
489 const RegisterInfo ®_info);
494 ReadMemoryCallback m_read_mem_callback;
495 WriteMemoryCallback m_write_mem_callback;
496 ReadRegisterCallback m_read_reg_callback;
497 WriteRegisterCallback m_write_reg_callback;
502 //------------------------------------------------------------------
503 // For EmulateInstruction only
504 //------------------------------------------------------------------
505 DISALLOW_COPY_AND_ASSIGN(EmulateInstruction);
508 } // namespace lldb_private
510 #endif // lldb_EmulateInstruction_h_