github.com/undoio/delve@v1.9.0/pkg/proc/interface.go (about)

     1  package proc
     2  
     3  import (
     4  	"sync"
     5  
     6  	"github.com/undoio/delve/pkg/elfwriter"
     7  	"github.com/undoio/delve/pkg/proc/internal/ebpf"
     8  )
     9  
    10  // Process represents the target of the debugger. This
    11  // target could be a system process, core file, etc.
    12  //
    13  // Implementations of Process are not required to be thread safe and users
    14  // of Process should not assume they are.
    15  // There is one exception to this rule: it is safe to call RequestManualStop
    16  // concurrently with ContinueOnce.
    17  type Process interface {
    18  	BinInfo() *BinaryInfo
    19  	EntryPoint() (uint64, error)
    20  
    21  	FindThread(threadID int) (Thread, bool)
    22  	ThreadList() []Thread
    23  
    24  	Breakpoints() *BreakpointMap
    25  
    26  	// Memory returns a memory read/writer for this process's memory.
    27  	Memory() MemoryReadWriter
    28  }
    29  
    30  // ProcessInternal holds a set of methods that need to be implemented by a
    31  // Delve backend. Methods in the Process interface are safe to be called by
    32  // clients of the 'proc' library, while all other methods are only called
    33  // directly within 'proc'.
    34  type ProcessInternal interface {
    35  	Process
    36  	// Valid returns true if this Process can be used. When it returns false it
    37  	// also returns an error describing why the Process is invalid (either
    38  	// ErrProcessExited or ErrProcessDetached).
    39  	Valid() (bool, error)
    40  	Detach(bool) error
    41  	ContinueOnce(*ContinueOnceContext) (trapthread Thread, stopReason StopReason, err error)
    42  
    43  	// RequestManualStop attempts to stop all the process' threads.
    44  	RequestManualStop(cctx *ContinueOnceContext) error
    45  
    46  	WriteBreakpoint(*Breakpoint) error
    47  	EraseBreakpoint(*Breakpoint) error
    48  
    49  	SupportsBPF() bool
    50  	SetUProbe(string, int64, []ebpf.UProbeArgMap) error
    51  	GetBufferedTracepoints() []ebpf.RawUProbeParams
    52  
    53  	// DumpProcessNotes returns ELF core notes describing the process and its threads.
    54  	// Implementing this method is optional.
    55  	DumpProcessNotes(notes []elfwriter.Note, threadDone func()) (bool, []elfwriter.Note, error)
    56  	// MemoryMap returns the memory map of the target process. This method must be implemented if CanDump is true.
    57  	MemoryMap() ([]MemoryMapEntry, error)
    58  
    59  	// StartCallInjection notifies the backend that we are about to inject a function call.
    60  	StartCallInjection() (func(), error)
    61  }
    62  
    63  // RecordingManipulation is an interface for manipulating process recordings.
    64  type RecordingManipulation interface {
    65  	// Recorded returns true if the current process is a recording and the path
    66  	// to the trace directory.
    67  	Recorded() (recorded bool, tracedir string)
    68  	// Direction changes execution direction.
    69  	ChangeDirection(Direction) error
    70  	// GetDirection returns the current direction of execution.
    71  	GetDirection() Direction
    72  	// When returns current recording position.
    73  	When() (string, error)
    74  	// Checkpoint sets a checkpoint at the current position.
    75  	Checkpoint(where string) (id int, err error)
    76  	// Checkpoints returns the list of currently set checkpoint.
    77  	Checkpoints() ([]Checkpoint, error)
    78  	// ClearCheckpoint removes a checkpoint.
    79  	ClearCheckpoint(id int) error
    80  }
    81  
    82  // RecordingManipulationInternal is an interface that a Delve backend can
    83  // implement if it is a recording.
    84  type RecordingManipulationInternal interface {
    85  	RecordingManipulation
    86  
    87  	// Restart restarts the recording from the specified position, or from the
    88  	// last checkpoint if pos == "".
    89  	// If pos starts with 'c' it's a checkpoint ID, otherwise it's an event
    90  	// number.
    91  	// Returns the new current thread after the restart has completed.
    92  	Restart(cctx *ContinueOnceContext, pos string) (Thread, error)
    93  }
    94  
    95  // Direction is the direction of execution for the target process.
    96  type Direction int8
    97  
    98  const (
    99  	// Forward direction executes the target normally.
   100  	Forward Direction = 0
   101  	// Backward direction executes the target in reverse.
   102  	Backward Direction = 1
   103  )
   104  
   105  // Checkpoint is a checkpoint
   106  type Checkpoint struct {
   107  	ID    int
   108  	When  string
   109  	Where string
   110  }
   111  
   112  // ContinueOnceContext is an object passed to ContinueOnce that the backend
   113  // can use to communicate with the target layer.
   114  type ContinueOnceContext struct {
   115  	ResumeChan chan<- struct{}
   116  	StopMu     sync.Mutex
   117  	// manualStopRequested is set if all the threads in the process were
   118  	// signalled to stop as a result of a Halt API call. Used to disambiguate
   119  	// why a thread is found to have stopped.
   120  	manualStopRequested bool
   121  }
   122  
   123  // CheckAndClearManualStopRequest will check for a manual
   124  // stop and then clear that state.
   125  func (cctx *ContinueOnceContext) CheckAndClearManualStopRequest() bool {
   126  	cctx.StopMu.Lock()
   127  	defer cctx.StopMu.Unlock()
   128  	msr := cctx.manualStopRequested
   129  	cctx.manualStopRequested = false
   130  	return msr
   131  }
   132  
   133  func (cctx *ContinueOnceContext) GetManualStopRequested() bool {
   134  	cctx.StopMu.Lock()
   135  	defer cctx.StopMu.Unlock()
   136  	return cctx.manualStopRequested
   137  }