marshal

Documentation

Overview

Package marshal defines the Marshallable interface for serialize/deserializing go data structures to/from memory, according to the Linux ABI.

Implementations of this interface are typically automatically generated by tools/go_marshal. See the go_marshal README for details.

Index

• type CopyContext
• type Marshallable
• type StubMarshallable
  • func (StubMarshallable) CopyIn(cc CopyContext, addr usermem.Addr) (int, error)
  • func (StubMarshallable) CopyOut(cc CopyContext, addr usermem.Addr) (int, error)
  • func (StubMarshallable) CopyOutN(cc CopyContext, addr usermem.Addr, limit int) (int, error)
  • func (StubMarshallable) MarshalBytes(dst []byte)
  • func (StubMarshallable) MarshalUnsafe(dst []byte)
  • func (StubMarshallable) Packed() bool
  • func (StubMarshallable) SizeBytes() int
  • func (StubMarshallable) UnmarshalBytes(src []byte)
  • func (StubMarshallable) UnmarshalUnsafe(src []byte)
  • func (StubMarshallable) WriteTo(w io.Writer) (n int64, err error)

Types

type CopyContext

type CopyContext interface {
	// CopyScratchBuffer provides a task goroutine-local scratch buffer. See
	// kernel.CopyScratchBuffer.
	CopyScratchBuffer(size int) []byte

	// CopyOutBytes writes the contents of b to the task's memory. See
	// kernel.CopyOutBytes.
	CopyOutBytes(addr usermem.Addr, b []byte) (int, error)

	// CopyInBytes reads the contents of the task's memory to b. See
	// kernel.CopyInBytes.
	CopyInBytes(addr usermem.Addr, b []byte) (int, error)
}

CopyContext defines the memory operations required to marshal to and from user memory. Typically, kernel.Task is used to provide implementations for these operations.

type Marshallable

type Marshallable interface {
	io.WriterTo

	// SizeBytes is the size of the memory representation of a type in
	// marshalled form.
	//
	// SizeBytes must handle a nil receiver. Practically, this means SizeBytes
	// cannot deference any fields on the object implementing it (but will
	// likely make use of the type of these fields).
	SizeBytes() int

	// MarshalBytes serializes a copy of a type to dst.
	// Precondition: dst must be at least SizeBytes() in length.
	MarshalBytes(dst []byte)

	// UnmarshalBytes deserializes a type from src.
	// Precondition: src must be at least SizeBytes() in length.
	UnmarshalBytes(src []byte)

	// Packed returns true if the marshalled size of the type is the same as the
	// size it occupies in memory. This happens when the type has no fields
	// starting at unaligned addresses (should always be true by default for ABI
	// structs, verified by automatically generated tests when using
	// go_marshal), and has no fields marked `marshal:"unaligned"`.
	//
	// Packed must return the same result for all possible values of the type
	// implementing it. Violating this constraint implies the type doesn't have
	// a static memory layout, and will lead to memory corruption.
	// Go-marshal-generated code reuses the result of Packed for multiple values
	// of the same type.
	Packed() bool

	// MarshalUnsafe serializes a type by bulk copying its in-memory
	// representation to the dst buffer. This is only safe to do when the type
	// has no implicit padding, see Marshallable.Packed. When Packed would
	// return false, MarshalUnsafe should fall back to the safer but slower
	// MarshalBytes.
	// Precondition: dst must be at least SizeBytes() in length.
	MarshalUnsafe(dst []byte)

	// UnmarshalUnsafe deserializes a type by directly copying to the underlying
	// memory allocated for the object by the runtime.
	//
	// This allows much faster unmarshalling of types which have no implicit
	// padding, see Marshallable.Packed. When Packed would return false,
	// UnmarshalUnsafe should fall back to the safer but slower unmarshal
	// mechanism implemented in UnmarshalBytes.
	// Precondition: src must be at least SizeBytes() in length.
	UnmarshalUnsafe(src []byte)

	// CopyIn deserializes a Marshallable type from a task's memory. This may
	// only be called from a task goroutine. This is more efficient than calling
	// UnmarshalUnsafe on Marshallable.Packed types, as the type being
	// marshalled does not escape. The implementation should avoid creating
	// extra copies in memory by directly deserializing to the object's
	// underlying memory.
	//
	// If the copy-in from the task memory is only partially successful, CopyIn
	// should still attempt to deserialize as much data as possible. See comment
	// for UnmarshalBytes.
	CopyIn(cc CopyContext, addr usermem.Addr) (int, error)

	// CopyOut serializes a Marshallable type to a task's memory. This may only
	// be called from a task goroutine. This is more efficient than calling
	// MarshalUnsafe on Marshallable.Packed types, as the type being serialized
	// does not escape. The implementation should avoid creating extra copies in
	// memory by directly serializing from the object's underlying memory.
	//
	// The copy-out to the task memory may be partially successful, in which
	// case CopyOut returns how much data was serialized. See comment for
	// MarshalBytes for implications.
	CopyOut(cc CopyContext, addr usermem.Addr) (int, error)

	// CopyOutN is like CopyOut, but explicitly requests a partial
	// copy-out. Note that this may yield unexpected results for non-packed
	// types and the caller may only want to allow this for packed types. See
	// comment on MarshalBytes.
	//
	// The limit must be less than or equal to SizeBytes().
	CopyOutN(cc CopyContext, addr usermem.Addr, limit int) (int, error)
}

Marshallable represents operations on a type that can be marshalled to and from memory.

go-marshal automatically generates implementations for this interface for types marked as '+marshal'.

type StubMarshallable

type StubMarshallable struct{}

StubMarshallable implements the Marshallable interface. StubMarshallable is a convenient embeddable type for satisfying the marshallable interface, but provides no actual implementation. It is useful when the marshallable interface needs to be implemented manually, but the caller doesn't require the full marshallable interface.

func (StubMarshallable) CopyIn

func (StubMarshallable) CopyIn(cc CopyContext, addr usermem.Addr) (int, error)

CopyIn implements Marshallable.CopyIn.

func (StubMarshallable) CopyOut

func (StubMarshallable) CopyOut(cc CopyContext, addr usermem.Addr) (int, error)

CopyOut implements Marshallable.CopyOut.

func (StubMarshallable) CopyOutN

func (StubMarshallable) CopyOutN(cc CopyContext, addr usermem.Addr, limit int) (int, error)

CopyOutN implements Marshallable.CopyOutN.

func (StubMarshallable) MarshalBytes

func (StubMarshallable) MarshalBytes(dst []byte)

MarshalBytes implements Marshallable.MarshalBytes.

func (StubMarshallable) MarshalUnsafe

func (StubMarshallable) MarshalUnsafe(dst []byte)

MarshalUnsafe implements Marshallable.MarshalUnsafe.

func (StubMarshallable) Packed

func (StubMarshallable) Packed() bool

Packed implements Marshallable.Packed.

func (StubMarshallable) SizeBytes

func (StubMarshallable) SizeBytes() int

SizeBytes implements Marshallable.SizeBytes.

func (StubMarshallable) UnmarshalBytes

func (StubMarshallable) UnmarshalBytes(src []byte)

UnmarshalBytes implements Marshallable.UnmarshalBytes.

func (StubMarshallable) UnmarshalUnsafe

func (StubMarshallable) UnmarshalUnsafe(src []byte)

UnmarshalUnsafe implements Marshallable.UnmarshalUnsafe.

func (StubMarshallable) WriteTo

func (StubMarshallable) WriteTo(w io.Writer) (n int64, err error)

WriteTo implements Marshallable.WriteTo.