Documentation
¶
Overview ¶
Package memmap defines semantics for memory mappings.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CheckTranslateResult ¶
func CheckTranslateResult(required, optional MappableRange, ts []Translation, terr error) error
CheckTranslateResult returns an error if (ts, terr) does not satisfy all postconditions for Mappable.Translate(required, optional).
Preconditions: As for Mappable.Translate.
Types ¶
type BusError ¶
type BusError struct {
// Err is the original error.
Err error
}
BusError may be returned by implementations of Mappable.Translate for errors that should result in SIGBUS delivery if they cause application page fault handling to fail.
type InvalidateOpts ¶
type InvalidateOpts struct {
// InvalidatePrivate is true if private pages in the invalidated region
// should also be discarded, causing their data to be lost.
InvalidatePrivate bool
}
InvalidateOpts holds options to MappingSpace.Invalidate.
type MMapOpts ¶
type MMapOpts struct {
// Length is the length of the mapping.
Length uint64
// MappingIdentity controls the lifetime of Mappable, and provides
// properties of the mapping shown in /proc/[pid]/maps. If MMapOpts is used
// to successfully create a memory mapping, a reference is taken on
// MappingIdentity.
MappingIdentity MappingIdentity
// Mappable is the Mappable to be mapped. If Mappable is nil, the mapping
// is anonymous. If Mappable is not nil, it must remain valid as long as a
// reference is held on MappingIdentity.
Mappable Mappable
// Offset is the offset into Mappable to map. If Mappable is nil, Offset is
// ignored.
Offset uint64
// Addr is the suggested address for the mapping.
Addr usermem.Addr
// Fixed specifies whether this is a fixed mapping (it must be located at
// Addr).
Fixed bool
// Unmap specifies whether existing mappings in the range being mapped may
// be replaced. If Unmap is true, Fixed must be true.
Unmap bool
// Perms is the set of permissions to the applied to this mapping.
Perms usermem.AccessType
// MaxPerms limits the set of permissions that may ever apply to this
// mapping. If Mappable is not nil, all memmap.Translations returned by
// Mappable.Translate must support all accesses in MaxPerms.
//
// Preconditions: MaxAccessType should be an effective AccessType, as
// access cannot be limited beyond effective AccessTypes.
MaxPerms usermem.AccessType
// Private is true if writes to the mapping should be propagated to a copy
// that is exclusive to the MemoryManager.
Private bool
// GrowsDown is true if the mapping should be automatically expanded
// downward on guard page faults.
GrowsDown bool
// Precommit is true if the platform should eagerly commit resources to the
// mapping (see platform.AddressSpace.MapFile).
Precommit bool
// Hint is the name used for the mapping in /proc/[pid]/maps. If Hint is
// empty, MappingIdentity.MappedName() will be used instead.
//
// TODO: Replace entirely with MappingIdentity?
Hint string
}
MMapOpts specifies a request to create a memory mapping.
type Mappable ¶
type Mappable interface {
// AddMapping notifies the Mappable of a mapping from addresses ar in ms to
// offsets [offset, offset+ar.Length()) in this Mappable.
//
// Preconditions: offset+ar.Length() does not overflow.
AddMapping(ctx context.Context, ms MappingSpace, ar usermem.AddrRange, offset uint64) error
// RemoveMapping notifies the Mappable of the removal of a mapping from
// addresses ar in ms to offsets [offset, offset+ar.Length()) in this
// Mappable.
//
// Preconditions: offset+ar.Length() does not overflow. The removed mapping
// must exist.
RemoveMapping(ctx context.Context, ms MappingSpace, ar usermem.AddrRange, offset uint64)
// CopyMapping notifies the Mappable of an attempt to copy a mapping in ms
// from srcAR to dstAR. For most Mappables, this is equivalent to
// AddMapping.
//
// CopyMapping is only called when a mapping is copied within a given
// MappingSpace; it is analogous to Linux's vm_operations_struct::mremap.
//
// Preconditions: offset+dstAR.Length() does not overflow. The mapping at
// srcAR must exist.
CopyMapping(ctx context.Context, ms MappingSpace, srcAR, dstAR usermem.AddrRange, offset uint64) error
// Translate returns the Mappable's current mappings for at least the range
// of offsets specified by required, and at most the range of offsets
// specified by optional. at is the set of access types that may be
// performed using the returned Translations. If not all required offsets
// are translated, it returns a non-nil error explaining why. Returned
// translations, and any mappings returned by platform.File.MapInternal for
// translated platform.Files, are valid until invalidated by a call back to
// MappingSpace.Invalidate or until the caller removes its mapping of the
// translated range.
//
// Preconditions: required.Length() > 0. optional.IsSupersetOf(required).
// required and optional must be page-aligned. The caller must have
// established a mapping for all of the queried offsets via a previous call
// to AddMapping. The caller is responsible for ensuring that calls to
// Translate synchronize with invalidation.
//
// Postconditions: See CheckTranslateResult.
Translate(ctx context.Context, required, optional MappableRange, at usermem.AccessType) ([]Translation, error)
// InvalidateUnsavable requests that the Mappable invalidate Translations
// that cannot be preserved across save/restore.
//
// Invariant: InvalidateUnsavable never races with concurrent calls to any
// other Mappable methods.
InvalidateUnsavable(ctx context.Context) error
}
Mappable represents a memory-mappable object, a mutable mapping from uint64 offsets to (platform.File, uint64 File offset) pairs.
See mm/mm.go for Mappable's place in the lock order.
Preconditions: For all Mappable methods, usermem.AddrRanges and MappableRanges must be non-empty (Length() != 0), and usermem.Addrs and Mappable offsets must be page-aligned.
type MappingIdentity ¶
type MappingIdentity interface {
// MappingIdentity is reference-counted.
refs.RefCounter
// MappedName returns the application-visible name shown in
// /proc/[pid]/maps.
MappedName(ctx context.Context) string
// DeviceID returns the device number shown in /proc/[pid]/maps.
DeviceID() uint64
// InodeID returns the inode number shown in /proc/[pid]/maps.
InodeID() uint64
// Msync has the same semantics as fs.FileOperations.Fsync(ctx,
// int64(mr.Start), int64(mr.End-1), fs.SyncData).
// (fs.FileOperations.Fsync() takes an inclusive end, but mr.End is
// exclusive, hence mr.End-1.) It is defined rather than Fsync so that
// implementors don't need to depend on the fs package for fs.SyncType.
Msync(ctx context.Context, mr MappableRange) error
}
MappingIdentity controls the lifetime of a Mappable, and provides information about the Mappable for /proc/[pid]/maps. It is distinct from Mappable because all Mappables that are coherent must compare equal to support the implementation of shared futexes, but different MappingIdentities may represent the same Mappable, in the same way that multiple fs.Files may represent the same fs.Inode. (This similarity is not coincidental; fs.File implements MappingIdentity, and some fs.InodeOperations implement Mappable.)
type MappingOfRange ¶
type MappingOfRange struct {
MappingSpace MappingSpace
AddrRange usermem.AddrRange
}
MappingOfRange represents a mapping of a MappableRange.
func (MappingOfRange) String ¶
func (r MappingOfRange) String() string
String implements fmt.Stringer.String.
type MappingSpace ¶
type MappingSpace interface {
// Invalidate is called to notify the MappingSpace that values returned by
// previous calls to Mappable.Translate for offsets mapped by addresses in
// ar are no longer valid.
//
// Invalidate must not take any locks preceding mm.MemoryManager.activeMu
// in the lock order.
//
// Preconditions: ar.Length() != 0. ar must be page-aligned.
Invalidate(ar usermem.AddrRange, opts InvalidateOpts)
}
MappingSpace represents a mutable mapping from usermem.Addrs to (Mappable, uint64 offset) pairs.
type MappingsOfRange ¶
type MappingsOfRange map[MappingOfRange]struct{}
MappingsOfRange is the value type of MappingSet, and represents the set of all mappings of the corresponding MappableRange.
Using a map offers O(1) lookups in RemoveMapping and mappingSetFunctions.Merge.
type Translation ¶
type Translation struct {
// Source is the translated range in the Mappable.
Source MappableRange
// File is the mapped file. When the Translation is invalidated, pages
// mapped by File.MapInto must be unmapped, and pages mapped by
// File.MapInternal become invalid.
File platform.File
// Offset is the offset into File at which this Translation begins.
Offset uint64
}
Translations are returned by Mappable.Translate.
Source Files