builder

Documentation

Overview

Package builder contains the Builder type to build replay payloads.

Index

• Constants
• type Builder
  • func New(memoryLayout *device.MemoryLayout) *Builder
  • func (b *Builder) AllocateMemory(size uint64) value.Pointer
  • func (b *Builder) AllocateTemporaryMemory(size uint64) value.Pointer
  • func (b *Builder) AllocateTemporaryMemoryChunks(sizes []uint64) (ptrs []value.Pointer, size uint64)
  • func (b *Builder) BeginCommand(cmdID, threadID uint64)
  • func (b *Builder) Buffer(count int) value.Pointer
  • func (b *Builder) Build(ctx context.Context) (protocol.Payload, ResponseDecoder, error)
  • func (b *Builder) Call(f FunctionInfo)
  • func (b *Builder) Clone(index int)
  • func (b *Builder) CommitCommand()
  • func (b *Builder) Copy(size uint64)
  • func (b *Builder) Load(ty protocol.Type, addr value.Pointer)
  • func (b *Builder) MapMemory(rng memory.Range)
  • func (b *Builder) MemoryLayout() *device.MemoryLayout
  • func (b *Builder) Pop(count uint32)
  • func (b *Builder) Post(addr value.Pointer, size uint64, p Postback)
  • func (b *Builder) Push(val value.Value)
  • func (b *Builder) ReserveMemory(rng memory.Range)
  • func (b *Builder) RevertCommand(err error)
  • func (b *Builder) Store(addr value.Pointer)
  • func (b *Builder) StorePointer(idx value.PointerIndex, ptr value.Pointer)
  • func (b *Builder) Strcpy(maxCount uint64)
  • func (b *Builder) String(s string) value.Pointer
  • func (b *Builder) UnmapMemory(rng memory.Range)
  • func (b *Builder) Write(rng memory.Range, resourceID id.ID)
• type FunctionInfo
• type Postback
• type ResponseDecoder

Constants

const ErrInvalidResource = fault.Const("Invaid resource")

Types

type Builder

type Builder struct {

	// Remappings is a map of a arbitrary keys to pointers. Typically, this is
	// used as a map of observed values to values that are only known at replay
	// execution time, such as driver generated handles.
	// The Remappings field is not accessed by the Builder and can be used in any
	// way the developer requires.
	Remappings map[interface{}]value.Pointer
	// contains filtered or unexported fields
}

Builder is used to build the Payload to send to the replay virtual machine. The builder has a number of methods for mutating the virtual machine stack, invoking functions and posting back data.

func New

func New(memoryLayout *device.MemoryLayout) *Builder

New returns a newly constructed Builder configured to replay on a target with the specified MemoryLayout.

func (*Builder) AllocateMemory

func (b *Builder) AllocateMemory(size uint64) value.Pointer

AllocateMemory allocates and returns a pointer to a block of memory in the volatile address-space big enough to hold size bytes. The memory will be allocated for the entire replay duration and cannot be freed.

func (*Builder) AllocateTemporaryMemory

func (b *Builder) AllocateTemporaryMemory(size uint64) value.Pointer

AllocateTemporaryMemory allocates and returns a pointer to a block of memory in the temporary volatile address-space big enough to hold size bytes. The memory block will be freed on the next call to CommitCommand/AbortCommand, upon which reading or writing to this memory will result in undefined behavior. TODO: REMOVE

func (*Builder) AllocateTemporaryMemoryChunks

func (b *Builder) AllocateTemporaryMemoryChunks(sizes []uint64) (ptrs []value.Pointer, size uint64)

AllocateTemporaryMemoryChunks allocates a contiguous block of memory in the temporary volatile address-space big enough to hold all the specified chunks sizes, in sequential order. AllocateTemporaryMemoryChunks returns a pointer to each of the allocated chunks and the size of the entire allocation. The allocation block will be freed on the next call to CommitCommand/AbortCommand upon which reading or writing to this memory will result in undefined behavior. TODO: REMOVE

func (*Builder) BeginCommand

func (b *Builder) BeginCommand(cmdID, threadID uint64)

BeginCommand should be called before building any replay instructions.

func (*Builder) Buffer

func (b *Builder) Buffer(count int) value.Pointer

Buffer returns a pointer to a block of memory in holding the count number of previously pushed values. If all the values are constant, then the buffer will be held in the constant address-space, otherwise the buffer will be built in the temporary address-space.

func (*Builder) Build

func (b *Builder) Build(ctx context.Context) (protocol.Payload, ResponseDecoder, error)

Build compiles the replay instructions, returning a Payload that can be sent to the replay virtual-machine and a ResponseDecoder for interpreting the responses.

func (*Builder) Call

func (b *Builder) Call(f FunctionInfo)

Call will invoke the function f, popping all parameter values previously pushed to the stack with Push, starting with the first parameter. If f has a non-void return type, after invoking the function the return value of the function will be pushed on to the stack.

func (*Builder) Clone

func (b *Builder) Clone(index int)

Clone makes a copy of the n-th element from the top of the stack and pushes the copy to the top of the stack.

func (*Builder) CommitCommand

func (b *Builder) CommitCommand()

CommitCommand should be called after emitting the commands to replay a single command. CommitCommand frees all temporary allocated memory and clears the stack.

func (*Builder) Copy

func (b *Builder) Copy(size uint64)

Copy pops the target address and then the source address from the top of the stack, and then copies Count bytes from source to target.

func (*Builder) Load

func (b *Builder) Load(ty protocol.Type, addr value.Pointer)

Load loads the value of type ty from addr and then pushes the loaded value to the top of the stack.

func (*Builder) MapMemory

func (b *Builder) MapMemory(rng memory.Range)

MapMemory maps the memory range rng relative to the absolute pointer that is on the top of the stack. Any ObservedPointers that are used while the pointer is mapped will be automatically adjusted to the remapped address. The mapped memory range can be unmapped with a call to UnmapMemory.

func (*Builder) MemoryLayout

func (b *Builder) MemoryLayout() *device.MemoryLayout

MemoryLayout returns the memory layout for the target replay device.

func (*Builder) Pop

func (b *Builder) Pop(count uint32)

Pop removes the top count values from the top of the stack.

func (*Builder) Post

func (b *Builder) Post(addr value.Pointer, size uint64, p Postback)

Post posts size bytes from addr to the decoder d. The decoder d must consume all size bytes before returning; failure to do this will corrupt all subsequent postbacks.

func (*Builder) Push

func (b *Builder) Push(val value.Value)

Push pushes val to the top of the stack.

func (*Builder) ReserveMemory

func (b *Builder) ReserveMemory(rng memory.Range)

ReserveMemory adds rng as a memory range that needs allocating for replay.

func (*Builder) RevertCommand

func (b *Builder) RevertCommand(err error)

RevertCommand reverts all the instructions since the last call to BeginCommand. Any postbacks issued since the last call to BeginCommand will be called with the error err and a nil decoder.

func (*Builder) Store

func (b *Builder) Store(addr value.Pointer)

Store pops the value from the top of the stack and writes the value to addr.

func (*Builder) StorePointer

func (b *Builder) StorePointer(idx value.PointerIndex, ptr value.Pointer)

StorePointer writes ptr to the target pointer index. Pointers are stored in a separate address space and can only be loaded using PointerIndex values.

func (*Builder) Strcpy

func (b *Builder) Strcpy(maxCount uint64)

Strcpy pops the source address then the target address from the top of the stack, and then copies at most maxCount-1 bytes from source to target. If maxCount is greater than the source string length, then the target will be padded with 0s. The destination buffer will always be 0-terminated.

func (*Builder) String

func (b *Builder) String(s string) value.Pointer

String returns a pointer to a block of memory in the constant address-space holding the string s. The string will be stored with a null-terminating byte.

func (*Builder) UnmapMemory

func (b *Builder) UnmapMemory(rng memory.Range)

UnmapMemory unmaps the memory range rng that was previously mapped with a call to MapMemory. If the memory range is not exactly a range previously mapped with a call to MapMemory then this function panics.

func (*Builder) Write

func (b *Builder) Write(rng memory.Range, resourceID id.ID)

Write fills the memory range in capture address-space rng with the data of resourceID.

type FunctionInfo

type FunctionInfo struct {
	ApiIndex   uint8         // The index of the API this function belongs to.
	ID         uint16        // The unique identifier for the function.
	ReturnType protocol.Type // The returns type of the function.
	Parameters int           // The number of parameters for the function.
}

FunctionInfo holds the information about a function that can be called by the replay virtual-machine.

type Postback

type Postback func(d binary.Reader, err error) error

Postback decodes a single commands's postback, returning and carrying over errors. The Postback must decode all the data that was issued in the Post call before returning. If err is nil, then d is the Decoder to the postback data. If d is nil, then a previous postback failed to decode before decoding could begin for this postback and err holds the error.

type ResponseDecoder

type ResponseDecoder func(r io.Reader, err error)

ResponseDecoder decodes all postback responses from the replay virtual machine. If err is nil, then r is the Reader to the sequential postback data. If r is nil, then the postback data was absent or corrupted and err holds the error.