debug

Documentation

Overview

Package debug provides the portable interface to a program being debugged.

Index

• type Array
  • func (a Array) Element(index uint64) Var
  • func (a Array) Len() uint64
• type Channel
  • func (m Channel) Element(index uint64) Var
• type File
• type Frame
  • func (f Frame) String() string
• type Func
• type Goroutine
  • func (g *Goroutine) String() string
• type GoroutineStatus
  • func (g GoroutineStatus) String() string
• type Interface
• type LocalVar
• type Map
• type Param
• type Pointer
• type Program
• type Slice
• type Status
• type String
• type Struct
• type StructField
• type Value
• type Var

Types

type Array

type Array struct {
	ElementTypeID uint64
	Address       uint64
	Length        uint64 // Number of elements in the array
	StrideBits    uint64 // Number of bits between array entries
}

Array is a Value representing an array.

func (Array) Element

func (a Array) Element(index uint64) Var

Element returns a Var referring to the given element of the array.

func (Array) Len

func (a Array) Len() uint64

Len returns the number of elements in the array.

type Channel

type Channel struct {
	ElementTypeID uint64
	Address       uint64 // Location of the channel struct in memory.
	Buffer        uint64 // Location of the buffer; zero for nil channels.
	Length        uint64 // Number of elements stored in the channel buffer.
	Capacity      uint64 // Capacity of the buffer; zero for unbuffered channels.
	Stride        uint64 // Number of bytes between buffer entries.
	BufferStart   uint64 // Index in the buffer of the element at the head of the queue.
}

Channel is a Value representing a channel.

func (Channel) Element

func (m Channel) Element(index uint64) Var

Element returns a Var referring to the given element of the channel's queue. If the channel is unbuffered, nil, or if the index is too large, returns a Var with Address == 0.

type File

type File interface {
	io.ReaderAt
	io.WriterAt
	io.Closer
}

The File interface provides access to file-like resources in the program. It implements only ReaderAt and WriterAt, not Reader and Writer, because random access is a far more common pattern for things like symbol tables, and because enormous address space of virtual memory makes routines like io.Copy dangerous.

type Frame

type Frame struct {
	// PC is the hardware program counter.
	PC uint64
	// SP is the hardware stack pointer.
	SP uint64
	// File and Line are the source code location of the PC.
	File string
	Line uint64
	// Function is the name of this frame's function.
	Function string
	// FunctionStart is the starting PC of the function.
	FunctionStart uint64
	// Params contains the function's parameters.
	Params []Param
	// Vars contains the function's local variables.
	Vars []LocalVar
}

func (Frame) String

func (f Frame) String() string

type Func

type Func struct {
	Address uint64
}

Func is a Value representing a func.

type Goroutine

type Goroutine struct {
	ID           int64
	Status       GoroutineStatus
	StatusString string // A human-readable string explaining the status in more detail.
	Function     string // Name of the goroutine function.
	Caller       string // Name of the function that created this goroutine.
	StackFrames  []Frame
}

func (*Goroutine) String

func (g *Goroutine) String() string

type GoroutineStatus

type GoroutineStatus byte

const (
	Running GoroutineStatus = iota
	Queued
	Blocked
)

func (GoroutineStatus) String

func (g GoroutineStatus) String() string

type Interface

type Interface struct{}

Interface is a Value representing an interface.

type LocalVar

type LocalVar struct {
	Name string
	Var  Var
}

LocalVar is a local variable of a function.

type Map

type Map struct {
	TypeID  uint64
	Address uint64
	Length  uint64 // Number of elements in the map.
}

Map is a Value representing a map.

type Param

type Param struct {
	Name string
	Var  Var
}

Param is a parameter of a function.

type Pointer

type Pointer struct {
	TypeID  uint64 // A type identifier, opaque to the user.
	Address uint64 // The address of the variable.
}

Pointer is a Value representing a pointer. Note that the TypeID field will be the type of the variable being pointed to, not the type of this pointer.

type Program

type Program interface {
	// Open opens a virtual file associated with the process.
	// Names are things like "text", "mem", "fd/2".
	// Mode is one of "r", "w", "rw".
	// Return values are open File and error.
	// When the target binary is re-run, open files are
	// automatically updated to refer to the corresponding
	// file in the new process.
	Open(name string, mode string) (File, error)

	// Run abandons the current running process, if any,
	// and execs a new instance of the target binary file
	// (which may have changed underfoot).
	// Breakpoints and open files are re-established.
	// The call hangs until the program stops executing,
	// at which point it returns the program status.
	// args contains the command-line arguments for the process.
	Run(args ...string) (Status, error)

	// Stop stops execution of the current process but
	// does not kill it.
	Stop() (Status, error)

	// Resume resumes execution of a stopped process.
	// The call hangs until the program stops executing,
	// at which point it returns the program status.
	Resume() (Status, error)

	// Kill kills the current process.
	Kill() (Status, error)

	// Breakpoint sets a breakpoint at the specified address.
	Breakpoint(address uint64) (PCs []uint64, err error)

	// BreakpointAtFunction sets a breakpoint at the start of the specified function.
	BreakpointAtFunction(name string) (PCs []uint64, err error)

	// BreakpointAtLine sets a breakpoint at the specified source line.
	BreakpointAtLine(file string, line uint64) (PCs []uint64, err error)

	// DeleteBreakpoints removes the breakpoints at the specified addresses.
	// Addresses where no breakpoint is set are ignored.
	DeleteBreakpoints(pcs []uint64) error

	// Eval evaluates the expression (typically an address) and returns
	// its string representation(s). Multivalued expressions such as
	// matches for regular expressions return multiple values.
	// TODO: change this to multiple functions with more specific names.
	// Syntax:
	//	re:regexp
	//		Returns a list of symbol names that match the expression
	//	addr:symbol
	//		Returns a one-element list holding the hexadecimal
	//		("0x1234") value of the address of the symbol
	//	val:symbol
	//		Returns a one-element list holding the formatted
	//		value of the symbol
	//	0x1234, 01234, 467
	//		Returns a one-element list holding the name of the
	//		symbol ("main.foo") at that address (hex, octal, decimal).
	Eval(expr string) ([]string, error)

	// Evaluate evaluates an expression.  Accepts a subset of Go expression syntax:
	// basic literals, identifiers, parenthesized expressions, and most operators.
	// Only the len function call is available.
	//
	// The expression can refer to local variables and function parameters of the
	// function where the program is stopped.
	//
	// On success, the type of the value returned will be one of:
	// int8, int16, int32, int64, uint8, uint16, uint32, uint64, float32, float64,
	// complex64, complex128, bool, Pointer, Array, Slice, String, Map, Struct,
	// Channel, Func, or Interface.
	Evaluate(e string) (Value, error)

	// Frames returns up to count stack frames from where the program
	// is currently stopped.
	Frames(count int) ([]Frame, error)

	// VarByName returns a Var referring to a global variable with the given name.
	// TODO: local variables
	VarByName(name string) (Var, error)

	// Value gets the value of a variable by reading the program's memory.
	Value(v Var) (Value, error)

	// MapElement returns Vars for the key and value of a map element specified by
	// a 0-based index.
	MapElement(m Map, index uint64) (Var, Var, error)

	// Goroutines gets the current goroutines.
	Goroutines() ([]*Goroutine, error)
}

Program is the interface to a (possibly remote) program being debugged. The process (if any) and text file associated with it may change during the session, but many resources are associated with the Program rather than process or text file so they persist across debuggging runs.

type Slice

type Slice struct {
	Array
	Capacity uint64
}

Slice is a Value representing a slice.

type Status

type Status struct {
	PC, SP uint64
}

type String

type String struct {
	// Length contains the length of the remote string, in bytes.
	Length uint64
	// String contains the string itself; it may be truncated to fewer bytes than the value of the Length field.
	String string
}

String is a Value representing a string. TODO: a method to access more of a truncated string.

type Struct

type Struct struct {
	Fields []StructField
}

Struct is a Value representing a struct.

type StructField

type StructField struct {
	Name string
	Var  Var
}

StructField represents a field in a struct object.

type Value

type Value interface{}

A value read from a remote program.

type Var

type Var struct {
	TypeID  uint64 // A type identifier, opaque to the user.
	Address uint64 // The address of the variable.
}

A reference to a variable in a program. TODO: handle variables stored in registers