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/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"
22 namespace lldb_private {
24 //----------------------------------------------------------------------
25 /// @class EmulateInstruction EmulateInstruction.h "lldb/Core/EmulateInstruction.h"
26 /// @brief A class that allows emulation of CPU opcodes.
28 /// This class is a plug-in interface that is accessed through the
29 /// standard static FindPlugin function call in the EmulateInstruction
30 /// class. The FindPlugin takes a target triple and returns a new object
31 /// if there is a plug-in that supports the architecture and OS. Four
32 /// callbacks and a baton are provided. The four callbacks are read
33 /// register, write register, read memory and write memory.
35 /// This class is currently designed for these main use cases:
36 /// - Auto generation of Call Frame Information (CFI) from assembly code
37 /// - Predicting single step breakpoint locations
38 /// - Emulating instructions for breakpoint traps
40 /// Objects can be asked to read an instruction which will cause a call
41 /// to the read register callback to get the PC, followed by a read
42 /// memory call to read the opcode. If ReadInstruction () returns true,
43 /// then a call to EmulateInstruction::EvaluateInstruction () can be
44 /// made. At this point the EmulateInstruction subclass will use all of
45 /// the callbacks to emulate an instruction.
47 /// Clients that provide the callbacks can either do the read/write
48 /// registers/memory to actually emulate the instruction on a real or
49 /// virtual CPU, or watch for the EmulateInstruction::Context which
50 /// is context for the read/write register/memory which explains why
51 /// the callback is being called. Examples of a context are:
52 /// "pushing register 3 onto the stack at offset -12", or "adjusting
53 /// stack pointer by -16". This extra context allows the generation of
54 /// CFI information from assembly code without having to actually do
55 /// the read/write register/memory.
57 /// Clients must be prepared that not all instructions for an
58 /// Instruction Set Architecture (ISA) will be emulated.
60 /// Subclasses at the very least should implement the instructions that
61 /// save and restore registers onto the stack and adjustment to the stack
62 /// pointer. By just implementing a few instructions for an ISA that are
63 /// the typical prologue opcodes, you can then generate CFI using a
64 /// class that will soon be available.
66 /// Implementing all of the instructions that affect the PC can then
67 /// allow single step prediction support.
69 /// Implementing all of the instructions allows for emulation of opcodes
70 /// for breakpoint traps and will pave the way for "thread centric"
71 /// debugging. The current debugging model is "process centric" where
72 /// all threads must be stopped when any thread is stopped; when
73 /// hitting software breakpoints we must disable the breakpoint by
74 /// restoring the original breakpoint opcode, single stepping and
75 /// restoring the breakpoint trap. If all threads were allowed to run
76 /// then other threads could miss the breakpoint.
78 /// This class centralizes the code that usually is done in separate
79 /// code paths in a debugger (single step prediction, finding save
80 /// restore locations of registers for unwinding stack frame variables)
81 /// and emulating the instruction is just a bonus.
82 //----------------------------------------------------------------------
84 class EmulateInstruction :
85 public PluginInterface
89 static EmulateInstruction*
90 FindPlugin (const ArchSpec &arch,
91 InstructionType supported_inst_type,
92 const char *plugin_name);
97 // Read an instruction opcode from memory
100 // Usually used for writing a register value whose source value is an
104 // Exclusively used when saving a register to the stack as part of the
106 eContextPushRegisterOnStack,
108 // Exclusively used when restoring a register off the stack as part of
110 eContextPopRegisterOffStack,
112 // Add or subtract a value from the stack
113 eContextAdjustStackPointer,
115 // Adjust the frame pointer for the current frame
116 eContextSetFramePointer,
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,
179 enum InfoType info_type;
182 struct RegisterPlusOffset
184 RegisterInfo reg; // base register
185 int64_t signed_offset; // signed offset added to base register
186 } RegisterPlusOffset;
188 struct RegisterPlusIndirectOffset
190 RegisterInfo base_reg; // base register number
191 RegisterInfo offset_reg; // offset register kind
192 } RegisterPlusIndirectOffset;
194 struct RegisterToRegisterPlusOffset
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;
201 struct RegisterToRegisterPlusIndirectOffset
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;
208 struct RegisterRegisterOperands
210 RegisterInfo operand1; // register containing first operand for binary op
211 RegisterInfo operand2; // register containing second operand for binary op
212 } RegisterRegisterOperands;
214 int64_t signed_offset; // signed offset by which to adjust self (for registers only)
216 RegisterInfo reg; // plain register
218 uint64_t unsigned_immediate;// unsigned immediate value
219 int64_t signed_immediate; // signed immediate value
221 lldb::addr_t address; // direct address
223 struct ISAAndImmediate
226 uint32_t unsigned_data32; // immediate data
229 struct ISAAndImmediateSigned
232 int32_t signed_data32; // signed immediate data
233 } ISAAndImmediateSigned;
239 type (eContextInvalid),
240 info_type (eInfoTypeNoArgs)
245 SetRegisterPlusOffset (RegisterInfo base_reg,
246 int64_t signed_offset)
248 info_type = eInfoTypeRegisterPlusOffset;
249 info.RegisterPlusOffset.reg = base_reg;
250 info.RegisterPlusOffset.signed_offset = signed_offset;
254 SetRegisterPlusIndirectOffset (RegisterInfo base_reg,
255 RegisterInfo offset_reg)
257 info_type = eInfoTypeRegisterPlusIndirectOffset;
258 info.RegisterPlusIndirectOffset.base_reg = base_reg;
259 info.RegisterPlusIndirectOffset.offset_reg = offset_reg;
263 SetRegisterToRegisterPlusOffset (RegisterInfo data_reg,
264 RegisterInfo base_reg,
267 info_type = eInfoTypeRegisterToRegisterPlusOffset;
268 info.RegisterToRegisterPlusOffset.data_reg = data_reg;
269 info.RegisterToRegisterPlusOffset.base_reg = base_reg;
270 info.RegisterToRegisterPlusOffset.offset = offset;
274 SetRegisterToRegisterPlusIndirectOffset (RegisterInfo base_reg,
275 RegisterInfo offset_reg,
276 RegisterInfo data_reg)
278 info_type = eInfoTypeRegisterToRegisterPlusIndirectOffset;
279 info.RegisterToRegisterPlusIndirectOffset.base_reg = base_reg;
280 info.RegisterToRegisterPlusIndirectOffset.offset_reg = offset_reg;
281 info.RegisterToRegisterPlusIndirectOffset.data_reg = data_reg;
285 SetRegisterRegisterOperands (RegisterInfo op1_reg,
286 RegisterInfo op2_reg)
288 info_type = eInfoTypeRegisterRegisterOperands;
289 info.RegisterRegisterOperands.operand1 = op1_reg;
290 info.RegisterRegisterOperands.operand2 = op2_reg;
294 SetOffset (int64_t signed_offset)
296 info_type = eInfoTypeOffset;
297 info.signed_offset = signed_offset;
301 SetRegister (RegisterInfo reg)
303 info_type = eInfoTypeRegister;
308 SetImmediate (uint64_t immediate)
310 info_type = eInfoTypeImmediate;
311 info.unsigned_immediate = immediate;
315 SetImmediateSigned (int64_t signed_immediate)
317 info_type = eInfoTypeImmediateSigned;
318 info.signed_immediate = signed_immediate;
322 SetAddress (lldb::addr_t address)
324 info_type = eInfoTypeAddress;
325 info.address = address;
328 SetISAAndImmediate (uint32_t isa, uint32_t data)
330 info_type = eInfoTypeISAAndImmediate;
331 info.ISAAndImmediate.isa = isa;
332 info.ISAAndImmediate.unsigned_data32 = data;
336 SetISAAndImmediateSigned (uint32_t isa, int32_t data)
338 info_type = eInfoTypeISAAndImmediateSigned;
339 info.ISAAndImmediateSigned.isa = isa;
340 info.ISAAndImmediateSigned.signed_data32 = data;
344 SetISA (uint32_t isa)
346 info_type = eInfoTypeISA;
353 info_type = eInfoTypeNoArgs;
358 EmulateInstruction *instruction) const;
362 typedef size_t (*ReadMemoryCallback) (EmulateInstruction *instruction,
364 const Context &context,
369 typedef size_t (*WriteMemoryCallback) (EmulateInstruction *instruction,
371 const Context &context,
376 typedef bool (*ReadRegisterCallback) (EmulateInstruction *instruction,
378 const RegisterInfo *reg_info,
379 RegisterValue ®_value);
381 typedef bool (*WriteRegisterCallback) (EmulateInstruction *instruction,
383 const Context &context,
384 const RegisterInfo *reg_info,
385 const RegisterValue ®_value);
387 EmulateInstruction (const ArchSpec &arch);
389 ~EmulateInstruction() override = default;
391 //----------------------------------------------------------------------
392 // Mandatory overrides
393 //----------------------------------------------------------------------
395 SupportsEmulatingInstructionsOfType (InstructionType inst_type) = 0;
398 SetTargetTriple (const ArchSpec &arch) = 0;
401 ReadInstruction () = 0;
404 EvaluateInstruction (uint32_t evaluate_options) = 0;
407 IsInstructionConditional() { return false; }
410 TestEmulation (Stream *out_stream, ArchSpec &arch, OptionValueDictionary *test_data) = 0;
413 GetRegisterInfo (lldb::RegisterKind reg_kind, uint32_t reg_num, RegisterInfo ®_info) = 0;
415 //----------------------------------------------------------------------
416 // Optional overrides
417 //----------------------------------------------------------------------
419 SetInstruction (const Opcode &insn_opcode, const Address &inst_addr, Target *target);
422 CreateFunctionEntryUnwind (UnwindPlan &unwind_plan);
425 TranslateRegister (lldb::RegisterKind reg_kind, uint32_t reg_num, std::string ®_name);
427 //----------------------------------------------------------------------
428 // RegisterInfo variants
429 //----------------------------------------------------------------------
431 ReadRegister (const RegisterInfo *reg_info,
432 RegisterValue& reg_value);
435 ReadRegisterUnsigned (const RegisterInfo *reg_info,
440 WriteRegister (const Context &context,
441 const RegisterInfo *ref_info,
442 const RegisterValue& reg_value);
445 WriteRegisterUnsigned (const Context &context,
446 const RegisterInfo *reg_info,
449 //----------------------------------------------------------------------
450 // Register kind and number variants
451 //----------------------------------------------------------------------
453 ReadRegister (lldb::RegisterKind reg_kind,
455 RegisterValue& reg_value);
458 WriteRegister (const Context &context,
459 lldb::RegisterKind reg_kind,
461 const RegisterValue& reg_value);
464 ReadRegisterUnsigned (lldb::RegisterKind reg_kind,
470 WriteRegisterUnsigned (const Context &context,
471 lldb::RegisterKind reg_kind,
477 ReadMemory (const Context &context,
483 ReadMemoryUnsigned (const Context &context,
490 WriteMemory (const Context &context,
496 WriteMemoryUnsigned (const Context &context,
499 size_t uval_byte_size);
502 GetAddressByteSize () const
504 return m_arch.GetAddressByteSize();
508 GetByteOrder () const
510 return m_arch.GetByteOrder();
526 GetArchitecture () const
532 ReadMemoryFrame (EmulateInstruction *instruction,
534 const Context &context,
540 WriteMemoryFrame (EmulateInstruction *instruction,
542 const Context &context,
548 ReadRegisterFrame (EmulateInstruction *instruction,
550 const RegisterInfo *reg_info,
551 RegisterValue ®_value);
555 WriteRegisterFrame (EmulateInstruction *instruction,
557 const Context &context,
558 const RegisterInfo *reg_info,
559 const RegisterValue ®_value);
562 ReadMemoryDefault (EmulateInstruction *instruction,
564 const Context &context,
570 WriteMemoryDefault (EmulateInstruction *instruction,
572 const Context &context,
578 ReadRegisterDefault (EmulateInstruction *instruction,
580 const RegisterInfo *reg_info,
581 RegisterValue ®_value);
585 WriteRegisterDefault (EmulateInstruction *instruction,
587 const Context &context,
588 const RegisterInfo *reg_info,
589 const RegisterValue ®_value);
592 SetBaton (void *baton);
595 SetCallbacks (ReadMemoryCallback read_mem_callback,
596 WriteMemoryCallback write_mem_callback,
597 ReadRegisterCallback read_reg_callback,
598 WriteRegisterCallback write_reg_callback);
601 SetReadMemCallback (ReadMemoryCallback read_mem_callback);
604 SetWriteMemCallback (WriteMemoryCallback write_mem_callback);
607 SetReadRegCallback (ReadRegisterCallback read_reg_callback);
610 SetWriteRegCallback (WriteRegisterCallback write_reg_callback);
613 GetBestRegisterKindAndNumber (const RegisterInfo *reg_info,
614 lldb::RegisterKind ®_kind,
618 GetInternalRegisterNumber (RegisterContext *reg_ctx,
619 const RegisterInfo ®_info);
624 ReadMemoryCallback m_read_mem_callback;
625 WriteMemoryCallback m_write_mem_callback;
626 ReadRegisterCallback m_read_reg_callback;
627 WriteRegisterCallback m_write_reg_callback;
632 //------------------------------------------------------------------
633 // For EmulateInstruction only
634 //------------------------------------------------------------------
635 DISALLOW_COPY_AND_ASSIGN (EmulateInstruction);
638 } // namespace lldb_private
640 #endif // lldb_EmulateInstruction_h_