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

• type AttachOpts
• type ID
• type Key
• type Registry
  • func NewRegistry(userNS *auth.UserNamespace) *Registry
  • func (r *Registry) FindByID(id ID) *Shm
  • func (r *Registry) FindOrCreate(ctx context.Context, pid int32, key Key, size uint64, mode linux.FileMode, ...) (*Shm, error)
  • func (r *Registry) IPCInfo() *linux.ShmParams
  • func (r *Registry) ShmInfo() *linux.ShmInfo
• type Shm
  • func (s *Shm) AddMapping(ctx context.Context, _ memmap.MappingSpace, _ usermem.AddrRange, _ uint64, ...) error
  • func (s *Shm) ConfigureAttach(ctx context.Context, addr usermem.Addr, opts AttachOpts) (memmap.MMapOpts, error)
  • func (*Shm) CopyMapping(context.Context, memmap.MappingSpace, usermem.AddrRange, usermem.AddrRange, ...) error
  • func (s *Shm) DecRef()
  • func (s *Shm) DeviceID() uint64
  • func (s *Shm) EffectiveSize() uint64
  • 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) MappedName(ctx context.Context) string
  • func (s *Shm) MarkDestroyed()
  • func (s *Shm) Msync(context.Context, memmap.MappableRange) error
  • func (s *Shm) RemoveMapping(ctx context.Context, _ memmap.MappingSpace, _ usermem.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)

Types

type AttachOpts

type AttachOpts struct {
	Execute  bool
	Readonly bool
	Remap    bool
}

AttachOpts describes various flags passed to shmat(2).

type ID

type ID int32

ID represents the opaque handle for a shm segment. Analogous to an fd.

type Key

type Key int32

Key represents a shm segment key. Analogous to a file name.

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 ID) *Shm

FindByID looks up a segment given an ID.

func (*Registry) FindOrCreate

func (r *Registry) FindOrCreate(ctx context.Context, pid int32, key 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).

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) 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 {
	// AtomicRefCount tracks the number of references to this segment from
	// maps. A segment always holds a reference to itself, until it's marked for
	// destruction.
	refs.AtomicRefCount

	// ID is the kernel identifier for this segment. Immutable.
	ID ID
	// contains filtered or unexported fields
}

Shm represents a single shared memory segment.

Shm segment 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 shmctl(SHM_RMID).

Shm implements memmap.Mappable and memmap.MappingIdentity.

+stateify savable

func (*Shm) AddMapping

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

AddMapping implements memmap.Mappable.AddMapping.

func (*Shm) ConfigureAttach

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

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

ConfigureAttach returns with a ref on s on success. The caller should drop this once the map is installed. This reference prevents s from being destroyed before the returned configuration is used.

func (*Shm) CopyMapping

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

CopyMapping implements memmap.Mappable.CopyMapping.

func (*Shm) DecRef

func (s *Shm) DecRef()

DecRef overrides refs.RefCount.DecRef with a destructor.

Precondition: Caller must not hold s.mu.

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) 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) MappedName

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

MappedName implements memmap.MappingIdentity.MappedName.

func (*Shm) MarkDestroyed

func (s *Shm) MarkDestroyed()

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) RemoveMapping

func (s *Shm) RemoveMapping(ctx context.Context, _ memmap.MappingSpace, _ usermem.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 usermem.AccessType) ([]memmap.Translation, error)

Translate implements memmap.Mappable.Translate.