llvm/lldb/include/lldb/Core/EmulateInstruction.h

//===-- EmulateInstruction.h ------------------------------------*- C++ -*-===//
//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//

#ifndef LLDB_CORE_EMULATEINSTRUCTION_H
#define LLDB_CORE_EMULATEINSTRUCTION_H

#include <optional>
#include <string>

#include "lldb/Core/Address.h"
#include "lldb/Core/Opcode.h"
#include "lldb/Core/PluginInterface.h"
#include "lldb/Utility/ArchSpec.h"
#include "lldb/lldb-defines.h"
#include "lldb/lldb-enumerations.h"
#include "lldb/lldb-private-enumerations.h"
#include "lldb/lldb-private-types.h"
#include "lldb/lldb-types.h"

#include <cstddef>
#include <cstdint>

namespace lldb_private {
class OptionValueDictionary;
class RegisterContext;
class RegisterValue;
class Stream;
class Target;
class UnwindPlan;

/// \class EmulateInstruction EmulateInstruction.h
/// "lldb/Core/EmulateInstruction.h"
/// A class that allows emulation of CPU opcodes.
///
/// This class is a plug-in interface that is accessed through the standard
/// static FindPlugin function call in the EmulateInstruction class. The
/// FindPlugin takes a target triple and returns a new object if there is a
/// plug-in that supports the architecture and OS. Four callbacks and a baton
/// are provided. The four callbacks are read register, write register, read
/// memory and write memory.
///
/// This class is currently designed for these main use cases: - Auto
/// generation of Call Frame Information (CFI) from assembly code - Predicting
/// single step breakpoint locations - Emulating instructions for breakpoint
/// traps
///
/// Objects can be asked to read an instruction which will cause a call to the
/// read register callback to get the PC, followed by a read memory call to
/// read the opcode. If ReadInstruction () returns true, then a call to
/// EmulateInstruction::EvaluateInstruction () can be made. At this point the
/// EmulateInstruction subclass will use all of the callbacks to emulate an
/// instruction.
///
/// Clients that provide the callbacks can either do the read/write
/// registers/memory to actually emulate the instruction on a real or virtual
/// CPU, or watch for the EmulateInstruction::Context which is context for the
/// read/write register/memory which explains why the callback is being
/// called. Examples of a context are: "pushing register 3 onto the stack at
/// offset -12", or "adjusting stack pointer by -16". This extra context
/// allows the generation of
/// CFI information from assembly code without having to actually do
/// the read/write register/memory.
///
/// Clients must be prepared that not all instructions for an Instruction Set
/// Architecture (ISA) will be emulated.
///
/// Subclasses at the very least should implement the instructions that save
/// and restore registers onto the stack and adjustment to the stack pointer.
/// By just implementing a few instructions for an ISA that are the typical
/// prologue opcodes, you can then generate CFI using a class that will soon
/// be available.
///
/// Implementing all of the instructions that affect the PC can then allow
/// single step prediction support.
///
/// Implementing all of the instructions allows for emulation of opcodes for
/// breakpoint traps and will pave the way for "thread centric" debugging. The
/// current debugging model is "process centric" where all threads must be
/// stopped when any thread is stopped; when hitting software breakpoints we
/// must disable the breakpoint by restoring the original breakpoint opcode,
/// single stepping and restoring the breakpoint trap. If all threads were
/// allowed to run then other threads could miss the breakpoint.
///
/// This class centralizes the code that usually is done in separate code
/// paths in a debugger (single step prediction, finding save restore
/// locations of registers for unwinding stack frame variables) and emulating
/// the instruction is just a bonus.

class EmulateInstruction : public PluginInterface { … };

} // namespace lldb_private

#endif // LLDB_CORE_EMULATEINSTRUCTION_H