shm

Documentation

Overview

Package shm implements sysv shared memory segments.

Known missing features:

• SHM_LOCK/SHM_UNLOCK are no-ops. The sentry currently doesn't implement memory locking in general.

• SHM_HUGETLB and related flags for shmget(2) are ignored. There's no easy way to implement hugetlb support on a per-map basis, and it has no impact on correctness.

• SHM_NORESERVE for shmget(2) is ignored, the sentry doesn't implement swap so it's meaningless to reserve space for swap.

• No per-process segment size enforcement. This feature probably isn't used much anyways, since Linux sets the per-process limits to the system-wide limits by default.

Lock ordering: mm.mappingMu -> shm registry lock -> shm lock

Index

• Constants
• type AttachOpts
• type Registry
  • func NewRegistry(userNS *auth.UserNamespace) *Registry
  • func (r *Registry) FindByID(id ipc.ID) *Shm
  • func (r *Registry) FindOrCreate(ctx context.Context, pid int32, key ipc.Key, size uint64, mode linux.FileMode, ...) (*Shm, error)
  • func (r *Registry) IPCInfo() *linux.ShmParams
  • func (r *Registry) Release(ctx context.Context)
  • func (r *Registry) ShmInfo() *linux.ShmInfo
• type Shm
  • func (s *Shm) AddMapping(ctx context.Context, _ memmap.MappingSpace, _ hostarch.AddrRange, _ uint64, ...) error
  • func (s *Shm) ConfigureAttach(ctx context.Context, addr hostarch.Addr, opts AttachOpts) (memmap.MMapOpts, error)
  • func (*Shm) CopyMapping(context.Context, memmap.MappingSpace, hostarch.AddrRange, hostarch.AddrRange, ...) error
  • func (s *Shm) DecRef(ctx context.Context)
  • func (s *Shm) Destroy()
  • func (s *Shm) DeviceID() uint64
  • func (s *Shm) EffectiveSize() uint64
  • func (s *Shm) ID() ipc.ID
  • func (s *Shm) IPCStat(ctx context.Context) (*linux.ShmidDS, error)
  • func (s *Shm) InodeID() uint64
  • func (s *Shm) InvalidateUnsavable(ctx context.Context) error
  • func (s *Shm) Lock()
  • func (s *Shm) MappedName(ctx context.Context) string
  • func (s *Shm) MarkDestroyed(ctx context.Context)
  • func (s *Shm) Msync(context.Context, memmap.MappableRange) error
  • func (s *Shm) Object() *ipc.Object
  • func (s *Shm) RemoveMapping(ctx context.Context, _ memmap.MappingSpace, _ hostarch.AddrRange, _ uint64, ...)
  • func (s *Shm) Set(ctx context.Context, ds *linux.ShmidDS) error
  • func (s *Shm) Translate(ctx context.Context, required, optional memmap.MappableRange, ...) ([]memmap.Translation, error)
  • func (s *Shm) Unlock()

Constants

const (
	// CtxDeviceID is a Context.Value key for kernel.Kernel.sysVShmDevID, which
	// this package cannot refer to due to dependency cycles.
	CtxDeviceID contextID = iota
)

Types

type AttachOpts

type AttachOpts struct {
	Execute  bool
	Readonly bool
	Remap    bool
}

AttachOpts describes various flags passed to shmat(2).

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

Registry tracks all shared memory segments in an IPC namespace. The registry provides the mechanisms for creating and finding segments, and reporting global shm parameters.

+stateify savable

func NewRegistry

func NewRegistry(userNS *auth.UserNamespace) *Registry

NewRegistry creates a new shm registry.

func (*Registry) FindByID

func (r *Registry) FindByID(id ipc.ID) *Shm

FindByID looks up a segment given an ID.

FindByID returns a reference on Shm.

func (*Registry) FindOrCreate

func (r *Registry) FindOrCreate(ctx context.Context, pid int32, key ipc.Key, size uint64, mode linux.FileMode, private, create, exclusive bool) (*Shm, error)

FindOrCreate looks up or creates a segment in the registry. It's functionally analogous to open(2).

FindOrCreate returns a reference on Shm.

func (*Registry) IPCInfo

func (r *Registry) IPCInfo() *linux.ShmParams

IPCInfo reports global parameters for sysv shared memory segments on this system. See shmctl(IPC_INFO).

func (*Registry) Release

func (r *Registry) Release(ctx context.Context)

Release drops the self-reference of each active shm segment in the registry. It is called when the kernel.IPCNamespace containing r is being destroyed.

func (*Registry) ShmInfo

func (r *Registry) ShmInfo() *linux.ShmInfo

ShmInfo reports linux-specific global parameters for sysv shared memory segments on this system. See shmctl(SHM_INFO).

type Shm

type Shm struct {
	// ShmRefs tracks the number of references to this segment.
	//
	// A segment holds a reference to itself until it is marked for
	// destruction.
	//
	// In addition to direct users, the MemoryManager will hold references
	// via MappingIdentity.
	ShmRefs
	// contains filtered or unexported fields
}

Shm represents a single shared memory segment.

Shm segments are backed directly by an allocation from platform memory. Segments are always mapped as a whole, greatly simplifying how mappings are tracked. However note that mremap and munmap calls may cause the vma for a segment to become fragmented; which requires special care when unmapping a segment. See mm/shm.go.

Segments persist until they are explicitly marked for destruction via MarkDestroyed().

Shm implements memmap.Mappable and memmap.MappingIdentity.

+stateify savable

func (*Shm) AddMapping

func (s *Shm) AddMapping(ctx context.Context, _ memmap.MappingSpace, _ hostarch.AddrRange, _ uint64, _ bool) error

AddMapping implements memmap.Mappable.AddMapping.

func (*Shm) ConfigureAttach

func (s *Shm) ConfigureAttach(ctx context.Context, addr hostarch.Addr, opts AttachOpts) (memmap.MMapOpts, error)

ConfigureAttach creates an mmap configuration for the segment with the requested attach options.

Postconditions: The returned MMapOpts are valid only as long as a reference continues to be held on s.

func (*Shm) CopyMapping

func (*Shm) CopyMapping(context.Context, memmap.MappingSpace, hostarch.AddrRange, hostarch.AddrRange, uint64, bool) error

CopyMapping implements memmap.Mappable.CopyMapping.

func (*Shm) DecRef

func (s *Shm) DecRef(ctx context.Context)

DecRef drops a reference on s.

Precondition: Caller must not hold s.mu.

func (*Shm) Destroy

func (s *Shm) Destroy()

Destroy implements ipc.Mechanism.Destroy. No work is performed on shm.Destroy because a different removal mechanism is used in shm. See Shm.MarkDestroyed.

func (*Shm) DeviceID

func (s *Shm) DeviceID() uint64

DeviceID implements memmap.MappingIdentity.DeviceID.

func (*Shm) EffectiveSize

func (s *Shm) EffectiveSize() uint64

EffectiveSize returns the size of the underlying shared memory segment. This may be larger than the requested size at creation, due to rounding to page boundaries.

func (*Shm) ID

func (s *Shm) ID() ipc.ID

ID returns object's ID.

func (*Shm) IPCStat

func (s *Shm) IPCStat(ctx context.Context) (*linux.ShmidDS, error)

IPCStat returns information about a shm. See shmctl(IPC_STAT).

func (*Shm) InodeID

func (s *Shm) InodeID() uint64

InodeID implements memmap.MappingIdentity.InodeID.

func (*Shm) InvalidateUnsavable

func (s *Shm) InvalidateUnsavable(ctx context.Context) error

InvalidateUnsavable implements memmap.Mappable.InvalidateUnsavable.

func (*Shm) Lock

func (s *Shm) Lock()

Lock implements ipc.Mechanism.Lock.

func (*Shm) MappedName

func (s *Shm) MappedName(ctx context.Context) string

MappedName implements memmap.MappingIdentity.MappedName.

func (*Shm) MarkDestroyed

func (s *Shm) MarkDestroyed(ctx context.Context)

MarkDestroyed marks a segment for destruction. The segment is actually destroyed once it has no references. MarkDestroyed may be called multiple times, and is safe to call after a segment has already been destroyed. See shmctl(IPC_RMID).

func (*Shm) Msync

func (s *Shm) Msync(context.Context, memmap.MappableRange) error

Msync implements memmap.MappingIdentity.Msync. Msync is a no-op for shm segments.

func (*Shm) Object

func (s *Shm) Object() *ipc.Object

Object implements ipc.Mechanism.Object.

func (*Shm) RemoveMapping

func (s *Shm) RemoveMapping(ctx context.Context, _ memmap.MappingSpace, _ hostarch.AddrRange, _ uint64, _ bool)

RemoveMapping implements memmap.Mappable.RemoveMapping.

func (*Shm) Set

func (s *Shm) Set(ctx context.Context, ds *linux.ShmidDS) error

Set modifies attributes for a segment. See shmctl(IPC_SET).

func (*Shm) Translate

func (s *Shm) Translate(ctx context.Context, required, optional memmap.MappableRange, at hostarch.AccessType) ([]memmap.Translation, error)

Translate implements memmap.Mappable.Translate.

func (*Shm) Unlock

func (s *Shm) Unlock()

Unlock implements ipc.mechanism.Unlock.

+checklocksignore