From 5d109cb197254aef802b186ba9c8b83155f1942e Mon Sep 17 00:00:00 2001 From: Derek Parker Date: Sat, 28 Mar 2020 10:39:32 -0700 Subject: [PATCH] *: Add some more documentation to exported types and methods --- pkg/dwarf/op/op.go | 4 +++- pkg/dwarf/op/regs.go | 1 + pkg/proc/amd64_arch.go | 7 ++++--- pkg/proc/arch.go | 23 +++++++++++++++++++++++ pkg/proc/i386_disasm.go | 2 ++ pkg/proc/registers.go | 4 ++++ 6 files changed, 37 insertions(+), 4 deletions(-) diff --git a/pkg/dwarf/op/op.go b/pkg/dwarf/op/op.go index ac6bd52e..0690e609 100644 --- a/pkg/dwarf/op/op.go +++ b/pkg/dwarf/op/op.go @@ -10,6 +10,8 @@ import ( "github.com/go-delve/delve/pkg/dwarf/util" ) +// Opcode represent a DWARF stack program instruction. +// See ./opcodes.go for a full list. type Opcode byte //go:generate go run ../../../scripts/gen-opcodes.go opcodes.table opcodes.go @@ -76,7 +78,7 @@ func ExecuteStackProgram(regs DwarfRegisters, instructions []byte, ptrSize int) return ctxt.stack[len(ctxt.stack)-1], nil, nil } -// PrettyPrint prints instructions to out. +// PrettyPrint prints the DWARF stack program instructions to `out`. func PrettyPrint(out io.Writer, instructions []byte) { in := bytes.NewBuffer(instructions) diff --git a/pkg/dwarf/op/regs.go b/pkg/dwarf/op/regs.go index aa19a30d..ee3b4573 100644 --- a/pkg/dwarf/op/regs.go +++ b/pkg/dwarf/op/regs.go @@ -5,6 +5,7 @@ import ( "encoding/binary" ) +// DwarfRegisters holds the value of stack program registers. type DwarfRegisters struct { StaticBase uint64 diff --git a/pkg/proc/amd64_arch.go b/pkg/proc/amd64_arch.go index 5f24361a..f7da8e49 100644 --- a/pkg/proc/amd64_arch.go +++ b/pkg/proc/amd64_arch.go @@ -110,15 +110,15 @@ func (a *AMD64) FixFrameUnwindContext(fctxt *frame.FrameContext, pc uint64, bi * return &frame.FrameContext{ RetAddrReg: amd64DwarfIPRegNum, Regs: map[uint64]frame.DWRule{ - amd64DwarfIPRegNum: frame.DWRule{ + amd64DwarfIPRegNum: { Rule: frame.RuleOffset, Offset: int64(-a.PtrSize()), }, - amd64DwarfBPRegNum: frame.DWRule{ + amd64DwarfBPRegNum: { Rule: frame.RuleOffset, Offset: int64(-2 * a.PtrSize()), }, - amd64DwarfSPRegNum: frame.DWRule{ + amd64DwarfSPRegNum: { Rule: frame.RuleValOffset, Offset: 0, }, @@ -426,6 +426,7 @@ func (a *AMD64) AddrAndStackRegsToDwarfRegisters(staticBase, pc, sp, bp, lr uint } } +// DwarfRegisterToString returns the name and value representation of the given register. func (a *AMD64) DwarfRegisterToString(i int, reg *op.DwarfRegister) (name string, floatingPoint bool, repr string) { name, ok := amd64DwarfToName[i] if !ok { diff --git a/pkg/proc/arch.go b/pkg/proc/arch.go index c915575d..4ff7c64f 100644 --- a/pkg/proc/arch.go +++ b/pkg/proc/arch.go @@ -8,20 +8,43 @@ import ( // Arch defines an interface for representing a // CPU architecture. type Arch interface { + // PtrSize returns the size of a pointer for the architecture. PtrSize() int + // MaxInstructionLength is the maximum size in bytes of an instruction. MaxInstructionLength() int + // AsmDecode decodes the assembly instruction starting at mem[0:] into asmInst. + // It assumes that the Loc and AtPC fields of asmInst have already been filled. AsmDecode(asmInst *AsmInstruction, mem []byte, regs Registers, memrw MemoryReadWriter, bi *BinaryInfo) error + // Prologues returns a list of stack split prologues + // that are inserted at function entry. Prologues() []opcodeSeq + // BreakpointInstruction is the instruction that will trigger a breakpoint trap for + // the given architecture. BreakpointInstruction() []byte + // BreakInstrMovesPC is true if hitting the breakpoint instruction advances the + // instruction counter by the size of the breakpoint instruction. BreakInstrMovesPC() bool + // BreakpointSize is the size of the breakpoint instruction for the given architecture. BreakpointSize() int + // DerefTLS is true if the G struct stored in the TLS section is a pointer + // and the address must be dereferenced to find to actual G struct. DerefTLS() bool + // FixFrameUnwindContext applies architecture specific rules for unwinding a stack frame + // on the given arch. FixFrameUnwindContext(*frame.FrameContext, uint64, *BinaryInfo) *frame.FrameContext + // SwitchStack will use the current frame to determine if it's time to + // switch between the system stack and the goroutine stack or vice versa. SwitchStack(it *stackIterator, callFrameRegs *op.DwarfRegisters) bool + // RegSize returns the size (in bytes) of register regnum. RegSize(uint64) int + // RegistersToDwarfRegisters maps hardware registers to DWARF registers. RegistersToDwarfRegisters(uint64, Registers) op.DwarfRegisters + // AddrAndStackRegsToDwarfRegisters returns DWARF registers from the passed in + // PC, SP, and BP registers in the format used by the DWARF expression interpreter. AddrAndStackRegsToDwarfRegisters(uint64, uint64, uint64, uint64, uint64) op.DwarfRegisters + // DwarfRegisterToString returns the name and value representation of the given register. DwarfRegisterToString(int, *op.DwarfRegister) (string, bool, string) + // InhibitStepInto returns whether StepBreakpoint can be set at pc. InhibitStepInto(bi *BinaryInfo, pc uint64) bool } diff --git a/pkg/proc/i386_disasm.go b/pkg/proc/i386_disasm.go index 3f560a2c..00ea32fa 100644 --- a/pkg/proc/i386_disasm.go +++ b/pkg/proc/i386_disasm.go @@ -14,6 +14,8 @@ func (i *I386) AsmDecode(asmInst *AsmInstruction, mem []byte, regs Registers, me return x86AsmDecode(asmInst, mem, regs, memrw, bi, 32) } +// Prologues returns a list of stack split prologues +// that are inserted at function entry. func (i *I386) Prologues() []opcodeSeq { return prologuesI386 } diff --git a/pkg/proc/registers.go b/pkg/proc/registers.go index 1bce1b19..b60f3438 100644 --- a/pkg/proc/registers.go +++ b/pkg/proc/registers.go @@ -33,10 +33,14 @@ type Register struct { Reg *op.DwarfRegister } +// AppendUint64Register will create a new Register struct with the name and value +// specified and append it to the `regs` slice. func AppendUint64Register(regs []Register, name string, value uint64) []Register { return append(regs, Register{name, op.DwarfRegisterFromUint64(value)}) } +// AppendBytesRegister will create a new Register struct with the name and value +// specified and append it to the `regs` slice. func AppendBytesRegister(regs []Register, name string, value []byte) []Register { return append(regs, Register{name, op.DwarfRegisterFromBytes(value)}) } -- GitLab