#include <optional>
#include <sys/mman.h>
#include <linux/mman.h>
#include <cosmos/BitMask.hxx>
#include <cosmos/fs/FileDescriptor.hxx>

Classes
class	cosmos::mem::MapFlags
	Flags used in MapSettings. More...

struct	cosmos::mem::MapSettings
	Collection of settings used in cosmos::mem::map(). More...

Macros
#define	PROT_SAO 0x10

Typedefs
using	cosmos::mem::AccessFlags = BitMask<AccessFlag>
	A mask of memory page access settings.

using	cosmos::mem::ProtectFlags = BitMask<ProtectFlag>
	A mask of extra settings used in mem::protect().

using	cosmos::mem::RemapFlags = BitMask<RemapFlag>

using	cosmos::mem::SyncFlags = BitMask<SyncFlag>

using	cosmos::mem::LockFlags = BitMask<LockFlag>

using	cosmos::mem::LockAllFlags = BitMask<LockAllFlag>

Enumerations
enum class	cosmos::mem::MapType : int { SHARED = MAP_SHARED , SHARED_VALIDATE = MAP_SHARED_VALIDATE , PRIVATE = MAP_PRIVATE }
	The basic type of a memory mapping to be created. More...

enum class	cosmos::mem::AccessFlag : int { EXEC = PROT_EXEC , READ = PROT_READ , WRITE = PROT_WRITE , NONE = PROT_NONE , SEM = PROT_SEM , SAO = PROT_SAO }
	Different memory page access permissions. More...

enum class	cosmos::mem::MapFlag : int { ANONYMOUS = MAP_ANONYMOUS , FIXED = MAP_FIXED , FIXED_NOREPLACE = MAP_FIXED_NOREPLACE , GROWSDOWN = MAP_GROWSDOWN , HUGETLB = MAP_HUGETLB , LOCKED = MAP_LOCKED , NONBLOCK = MAP_NONBLOCK , NORESERVE = MAP_NORESERVE , POPULATE = MAP_POPULATE , STACK = MAP_STACK , SYNC = MAP_SYNC , UNINITIALIZED = MAP_UNINITIALIZED }
	Flags that influence properties of memory mappings. More...

enum class	cosmos::mem::ProtectFlag : int { GROWSUP = PROT_GROWSUP , GROWSDOWN = PROT_GROWSDOWN }
	Extra flags used with mem::protect(). More...

enum class	cosmos::mem::RemapFlag : int { MAYMOVE = MREMAP_MAYMOVE , FIXED = MREMAP_FIXED , DONTUNMAP = MREMAP_DONTUNMAP }
	Flags used with cosmos::mem::remap(). More...

enum class	cosmos::mem::SyncFlag : int { ASYNC = MS_ASYNC , SYNC = MS_SYNC , INVALIDATE = MS_INVALIDATE }
	Flags used with cosmos::mem::sync(). More...

enum class	cosmos::mem::LockFlag : unsigned int { LOCK_ON_FAULT = MLOCK_ONFAULT }
	Flags used with cosmos::mem::lock(). More...

enum class	cosmos::mem::LockAllFlag : int { CURRENT = MCL_CURRENT , FUTURE = MCL_FUTURE , ONFAULT = MCL_ONFAULT }
	Flags passed to cosmos::mem::lockall(). More...

Functions
void *	cosmos::mem::map (const size_t length, const MapSettings &settings)
	Request a memory mapping of the given length using the provided settings.

void	cosmos::mem::unmap (void *addr, const size_t length)
	Unmap an existing mapping at the given address and of the given length.

void	cosmos::mem::protect (void *addr, const size_t length, const AccessFlags flags, const ProtectFlags extra={})
	Change memory protection settings of an existing mapping.

void *	cosmos::mem::remap (void old_addr, const size_t old_size, const size_t new_size, const RemapFlags flags={}, std::optional< void > new_addr={})
	Expand or shrink an existing memory mapping.

void	cosmos::mem::sync (void *addr, const size_t length, const SyncFlags flags=SyncFlags{SyncFlag::SYNC})
	Synchronize changes in a memory mapping with the file backing it.

void	cosmos::mem::lock (void *addr, const size_t length, const LockFlags flags={})
	Lock pages in memory, preventing memory from being paged to the swap area.

void	cosmos::mem::unlock (void *addr, const size_t length)
	Unlock previously locked pages.

void	cosmos::mem::lock_all (const LockAllFlags flags)
	Locks all current and/or future pages in memory.

void	cosmos::mem::unlock_all ()
	Unlock all current process memory pages..

Detailed Description

This header contains memory mapping related functionality.

Definition in file mman.hxx.

Macro Definition Documentation

◆ PROT_SAO

#define PROT_SAO 0x10

Definition at line 34 of file mman.hxx.

Typedef Documentation

◆ AccessFlags

using cosmos::mem::AccessFlags = BitMask<AccessFlag>

A mask of memory page access settings.

Definition at line 48 of file mman.hxx.

◆ LockAllFlags

using cosmos::mem::LockAllFlags = BitMask<LockAllFlag>

Definition at line 373 of file mman.hxx.

◆ LockFlags

using cosmos::mem::LockFlags = BitMask<LockFlag>

Definition at line 317 of file mman.hxx.

◆ ProtectFlags

using cosmos::mem::ProtectFlags = BitMask<ProtectFlag>

A mask of extra settings used in mem::protect().

Definition at line 188 of file mman.hxx.

◆ RemapFlags

using cosmos::mem::RemapFlags = BitMask<RemapFlag>

Definition at line 222 of file mman.hxx.

◆ SyncFlags

using cosmos::mem::SyncFlags = BitMask<SyncFlag>

Definition at line 287 of file mman.hxx.

Enumeration Type Documentation

◆ AccessFlag

enum class cosmos::mem::AccessFlag : int

strong

Different memory page access permissions.

Enumerator
EXEC	allow execute access
READ	allow read access
WRITE	allow write access
NONE	no access is allowed at all; this is not actually a bit position, but simply a zero value.
SEM	the memory can be used for atomic operations (used with futexes, doesn't currently do anything on any architecture)
SAO	the memory should have strong access ordering (a PowerPC architecture feature)

Definition at line 38 of file mman.hxx.

                      : int {
        EXEC  = PROT_EXEC,  
        READ  = PROT_READ,  
        WRITE = PROT_WRITE, 
        NONE  = PROT_NONE,  
        SEM   = PROT_SEM,   
        SAO   = PROT_SAO,   
};

◆ LockAllFlag

enum class cosmos::mem::LockAllFlag : int

strong

Flags passed to cosmos::mem::lockall().

Enumerator
CURRENT	lock all currently loaded pages in memory.
FUTURE	lock all pages loaded in the future in memory.
ONFAULT	lock all current/future pages, but don't pre-fault them.

Definition at line 367 of file mman.hxx.

                       : int {
        CURRENT = MCL_CURRENT, 
        FUTURE  = MCL_FUTURE,  
        ONFAULT = MCL_ONFAULT, 
};

◆ LockFlag

enum class cosmos::mem::LockFlag : unsigned int

strong

Flags used with cosmos::mem::lock().

Enumerator
LOCK_ON_FAULT	lock all pages that are already resident, the rest will be locked after a page fault occurs.

Definition at line 313 of file mman.hxx.

                    : unsigned int {
        LOCK_ON_FAULT = MLOCK_ONFAULT, 
};

◆ MapFlag

enum class cosmos::mem::MapFlag : int

strong

Flags that influence properties of memory mappings.

Enumerator
ANONYMOUS	Create a mapping that is not backed by a file, contents are initialized to zero. The offset should be zero and the file descriptor invalid.
FIXED	Map memory exactly at the given hint address, replacing already existing mappings at the address.
FIXED_NOREPLACE	Like FIXED but don't replace existing mappings, fail with EEXISTS instead.
GROWSDOWN	Create a mapping suitable for stacks, including automatic growing via a guard page.
HUGETLB	Allocate the mapping using hugetlb page sizes, see also MapFlags::setTLBPageSize().
LOCKED	Mark the memory to be locked similar to mem::lock(), but no major faults will be prevented.
NONBLOCK	Used in conjunction with POPULATE, currently causes POPULATE to do nothing though.
NORESERVE	Do not reserve swap space for this mapping. Writes may fail with SIGSEGV if no physical memory is available.
POPULATE	Pre-fault page tables for a mapping. This is reduce blocking on page faults later; failure to populate the mapping does not cause an error of mmap(), though.
STACK	Allocate the mapping at an address suitable for a thread stack (currently has no effect on Linux).
SYNC	Synchronous writes for files supporting DAX (direct memory access). Using this flag only works in combination with MapType::SHARED_VALIDATE, otherwise it is ignored. For supported files, if suitable CPU instructions are used for writing to memory, it is guaranteed that the state of the memory is also found on the underlying persistent device.
UNINITIALIZED	Don't clear anonymous pages. Only possible if CONFIG_MMAP_ALLOW_UNITIALIZED is set in the kernel

Definition at line 51 of file mman.hxx.

                   : int {
#ifdef MAP_32BIT // this is not defined on non-x86 architectures?
 
        INTO_32BIT      = MAP_32BIT,
#endif
 
        ANONYMOUS       = MAP_ANONYMOUS,
        FIXED           = MAP_FIXED,
        FIXED_NOREPLACE = MAP_FIXED_NOREPLACE,
        GROWSDOWN       = MAP_GROWSDOWN,
        HUGETLB         = MAP_HUGETLB,
        LOCKED          = MAP_LOCKED,
        NONBLOCK        = MAP_NONBLOCK,
 
        NORESERVE       = MAP_NORESERVE,
 
        POPULATE        = MAP_POPULATE,
        STACK           = MAP_STACK,
 
        SYNC            = MAP_SYNC,
 
        UNINITIALIZED   = MAP_UNINITIALIZED,
};

◆ MapType

enum class cosmos::mem::MapType : int

strong

The basic type of a memory mapping to be created.

Enumerator
SHARED	Creates a shared memory mapping that can be shared with other processes.
SHARED_VALIDATE	Same as SHARED but the MapFlags will be validated for unknown flags.
PRIVATE	A private copy-on-write mapping that isn't shared with other processes.

Definition at line 23 of file mman.hxx.

                   : int {
        SHARED          = MAP_SHARED,
        SHARED_VALIDATE = MAP_SHARED_VALIDATE,
        PRIVATE         = MAP_PRIVATE
};

◆ ProtectFlag

enum class cosmos::mem::ProtectFlag : int

strong

Extra flags used with mem::protect().

Enumerator
GROWSUP	Apply protection settings up to the end of mapping that grows upwards.
GROWSDOWN	Apply protection settings down to the beginning of mapping that grows downwards.

Definition at line 182 of file mman.hxx.

                       : int {
        GROWSUP   = PROT_GROWSUP,   
        GROWSDOWN = PROT_GROWSDOWN, 
};

◆ RemapFlag

enum class cosmos::mem::RemapFlag : int

strong

Flags used with cosmos::mem::remap().

Enumerator
MAYMOVE	allow to move the mapping to a new starting address.
FIXED	request the mapping to be placed at a fixed supplied address, similar to MapFlag::FIXED; this requires the MAYMOVE flag to be set as well.
DONTUNMAP	used only together with MAYMOVE; keep the original mapping available for special memory algorithms like `realloc()` or garbage collection.

Definition at line 216 of file mman.hxx.

                     : int {
        MAYMOVE   = MREMAP_MAYMOVE,   
        FIXED     = MREMAP_FIXED,     
        DONTUNMAP = MREMAP_DONTUNMAP, 
};

◆ SyncFlag

enum class cosmos::mem::SyncFlag : int

strong

Flags used with cosmos::mem::sync().

At least one of ASYNC or SYNC, but not both, must be present when passing flags to sync().

Enumerator
ASYNC	schedule the operation but return immediately.
SYNC	perform the operation and block until completed.
INVALIDATE	invalidate other mappings of the same file, allowing them to be updated with the changed data.

Definition at line 281 of file mman.hxx.

                    : int {
        ASYNC      = MS_ASYNC, 
        SYNC       = MS_SYNC,  
        INVALIDATE = MS_INVALIDATE 
};

Function Documentation

◆ lock()

COSMOS_API void cosmos::mem::lock	(	void *	addr,
		const size_t	length,
		const LockFlags	flags = {} )

Lock pages in memory, preventing memory from being paged to the swap area.

The given address range will be pre-faulted upon return (unless LockFlag::LOCK_ON_FAULT is set in flags) and will be prevented from being swapped out. The main applications for this feature are real-time requirements or security considerations (preventing sensitive data from ending up on disk).

Memory locks do not stack, i.e. calling lock() multiple times doesn't change the state, a single unlock() will remove the lock.

Memory locks are not maintained across process forks or execve().

Note: Linux automatically rounds addr down to the nearest page size.

On error an ApiError is thrown with one of the following Errno values:

Errno::AGAIN: Some or all of the pages in the address range could not be locked.
Errno::INVALID_ARG:
- addr + length resulted in an overflow.
- invalid flags have been encountered.
Errno::NO_MEMORY:
- Some of the pages in the address range are not mapped in the process.
- The lock operation would result in exceeding the maximum number of distinct mappings in the process.
- The RLIMIT_MEMLOCK soft limit would be exceeded for non-privileged processes.
Errno::PERMISSION: the caller is not privileged to lock pages (CAP_IPC_LOCK).

Definition at line 53 of file mman.cxx.

                                                                  {
        if (::mlock2(addr, length, flags.raw()) != 0) {
                cosmos_throw (ApiError("mlock2()"));
        }
}

◆ lock_all()

COSMOS_API void cosmos::mem::lock_all ( const LockAllFlags flags )

Locks all current and/or future pages in memory.

Depending on the settings in flags this call locks all currently loaded memory pages in memory, as well as mappings possibly created in the future. The locking logic is the same as described in cosmos::mem::lock().

On error an ApiError with one of the following Errno values is thrown:

Errno::INVALID_ARG: bad flags encountered, or LockAllFlag::ONFAULT was specified without any of the other flags.

Definition at line 65 of file mman.cxx.

                                        {
        if (::mlockall(flags.raw()) != 0) {
                cosmos_throw (ApiError("mlockall()"));
        }
}

◆ map()

COSMOS_API void * cosmos::mem::map	(	const size_t	length,
		const MapSettings &	settings )

Request a memory mapping of the given length using the provided settings.

On error an ApiError is thrown with one of the following Errno values:

Errno::ACCESS: the settings.fd is not a regular file, or the OpenMode of the file does not match (lacking read or write permission, depending on settings.type and settings.access.
Errno::AGAIN: the file has been locked, or too much memory has been locked.
Errno::BAD_FD: settings.fd is not a valid file descriptor and settings.flags does not contain MapFlag::ANONYMOUS.
Errno::EXISTS: MapFlag::FIXED_NOREPLACE was set, but the requested memory range already is mapped.
Errno::INVALID_ARG:
- settings.offset, settings.addr or length are offending.
- settings.type is invalid (shouldn't happen if a proper MapType constant is used)
- length is zero.
Errno::NO_DEVICE: the underlying file system of settings.fd does not support memory mapping.
Errno::NO_MEMORY:
- lack of memory
- the process's maximum number of page settings would have been exceeded.
- the process's RLIMIT_DATA would have been exceeded
- settings.addr exceeds the virtual address space of the CPU.
Errno::OVERFLOW: On 32-bit architectures combined with large file extension (64 bit off_t), the resulting number of pages would exceed what an unsigned long can hold.
Errno::PERMISSION:
- settings.access has AccessFlag::EXEC set, but the file to be mapped resides on a filesystem mounted no-exec.
- The operation was prevent by a file seal, see FileDescriptor::addSeals().
- MapFlag::HUGETLB is set, but the caller is not privileged to do so (CAP_IPC_LOCK capability, not a member of sysctl_hugetlb_shm_group).

Definition at line 9 of file mman.cxx.

                                                            {
        // type is non-bitmask value that is added to the actual system call flags.
        // for type safety we use two separate types in the API.
        const auto flags = settings.flags.raw() | to_integral(settings.type);
 
        auto addr = ::mmap(
                        settings.addr, length, settings.access.raw(),
                        flags, to_integral(settings.fd.raw()), settings.offset);
 
        if (addr == MAP_FAILED) {
                cosmos_throw (ApiError("mmap()"));
        }
 
        return addr;
}

◆ protect()

COSMOS_API void cosmos::mem::protect	(	void *	addr,
		const size_t	length,
		const AccessFlags	flags,
		const ProtectFlags	extra = {} )

Change memory protection settings of an existing mapping.

Failure to change the memory protection causes an ApiError to be thrown, with one of the following Errno values:

Errno::ACCESS: The specified access is not possible for the given mapping. A situation for this can be when write access is requested, but the underlying file has OpenMode::READ_ONLY.
Errno::INVALID_ARG:
- addr is not a valid pointer or not page aligned
- extra has both ProtectFlag::GROWSUP and ProtectFlag::GROWSDOWN set.
- Bad flags encountered.
- AccessFlag::SAO was requested, but the hardware does not support it (only on PowerPC).
Errno::NO_MEMORY:
- internal kernel data structures could not be allocated.
- the given address range is in valid or not mapped in the process.
- changing the protection of part of larger mapping would result in exceeding the limit of distinct memory mappings allowed for the process.

Definition at line 77 of file mman.cxx.

                                                                                                 {
 
        const auto raw_flags = flags.raw() | extra.raw();
 
        if (::mprotect(addr, length, raw_flags) != 0) {
                cosmos_throw (ApiError("mprotect()"));
        }
}

◆ remap()

COSMOS_API void * cosmos::mem::remap	(	void *	old_addr,
		const size_t	old_size,
		const size_t	new_size,
		const RemapFlags	flags = {},
		std::optional< void * >	new_addr = {} )

Expand or shrink an existing memory mapping.

old_addr needs to be page aligned. If old_size is zero, and old_addr refers to a memory mapping of MapType::SHARED, then this call will create a new mapping of the same pages. new_addr behaves similar as the addr argument in mem::map(), depending on the RemapFlag::FIXED flag.

If it is not possible to change the size of the mapping, then an error is thrown, except if RemapFlag::MAYMOVE is specified, in which case a new address may be returned for the mapping.

Resizing or moving a mapping that is currently locked will cause the new mapping also to be locked.

Failure to change the mapping will cause an ApiError to be thrown with one of the following Errno values:

Errno::AGAIN: The memory mapping is locked, and the changed introduced by the call would have exceeded the RLIMIT_MEMLOCK resource limit.
Errno::FAULT: The range of the [old_addr, old_addr + old_size] is not consisting of all valid addresses for the calling process. This can also happen if all addresses are valid, but mixed types of memory mappings are found in this range.
Errno::INVALID_ARG:
- old_addr is not page aligned.
- bad flags have been specified.
- new_size was zero.
- new_size or new_addr are invalid.
- the range [new_addr, new_addr + new_size] overlap with the range of [old_addr, old_addr + old_size].
- RemapFlag::FIXED or RemapFlag::DONTUNMAP was specified in flags without RemapFlag::MAYMOVE being set as well.
- RemapFlag::DONTUNMAP was specified in flags, but one or more pages in the old range are not private-anonymous.
- RemapFlag::DONTUNMAP was specified in flags, but new_size is not equal to old_size.
- old_size is zero, but old_addr does not refer to a mapping of MapType::SHARED.
- old_size is zero, but RemapFlag::MAYMOVE is not set in flags.
Errno::NO_MEMORY:
- There is not enough virtual memory available to extend the mapping.
- The mapping cannot be extended at the given address and RemapFlag::MAYMOVE is not set in flags.
- RemapFlag::DONTUNMAP is set in flags, which would cause a new mapping to be created that would exceed the available virtual memory, or the maximum number of allowed mappings.

Definition at line 37 of file mman.cxx.

                                                                                                                               {
        if (flags[RemapFlag::FIXED] && !new_addr) {
                cosmos_throw (UsageError("missing new_addr argument along with FIXED"));
        } else if (!flags[RemapFlag::FIXED] && new_addr) {
                cosmos_throw (UsageError("unexpected new_addr argument without FIXED"));
        }
 
        auto ret = ::mremap(old_addr, old_size, new_size, flags.raw(), new_addr ? *new_addr : MAP_FAILED);
 
        if (ret == MAP_FAILED) {
                cosmos_throw (ApiError("mremap()"));
        }
 
        return ret;
}

◆ sync()

COSMOS_API void cosmos::mem::sync	(	void *	addr,
		const size_t	length,
		const SyncFlags	flags = SyncFlags{SyncFlag::SYNC} )

Synchronize changes in a memory mapping with the file backing it.

When writing changes to a memory mapping, then it is undefined when these changes will actually be written back to the file backing the mapping. Only after unmapping, the changes are guaranteed to be written back.

Using this call, changes can be written back explicitly.

On error an ApiError with one of the following Errno values is thrown:

Errno::BUSY: SyncFlag::INVALIDATE is set in flags, but a memory lock exists for the specified address range.
Errno::INVALID_ARG: addr is not on a page boundary, or bad values have been found in flags, or both SyncFlag::SYNC and SyncFlag::ASYNC have been encountered.
Errno::NO_MEMORY: The indicated memory range, or a part of it, is not mapped.

Definition at line 31 of file mman.cxx.

                                                                  {
        if (::msync(addr, length, flags.raw()) != 0) {
                cosmos_throw (ApiError("msync()"));
        }
}

◆ unlock()

COSMOS_API void cosmos::mem::unlock	(	void *	addr,
		const size_t	length )

Unlock previously locked pages.

After successful return from this call the affected address range can be swapped out by the kernel again.

On error an ApiError is thrown with one of the following Errno values:

Errno::INVALID_ARG, Errno::AGAIN, Errno::NO_MEMORY or Errno::PERMISSION, as documented in cosmos::mem::lock().

Definition at line 59 of file mman.cxx.

                                             {
        if (::munlock(addr, length) != 0) {
                cosmos_throw (ApiError("munlock()"));
        }
}

◆ unlock_all()

COSMOS_API void cosmos::mem::unlock_all ( )

Unlock all current process memory pages..

This is the inverse operation of lockall(), remove memory locking from all currently loaded pages.

Definition at line 71 of file mman.cxx.

                  {
        if (::munlockall() != 0) {
                cosmos_throw (ApiError("munlockall()"));
        }
}

◆ unmap()

COSMOS_API void cosmos::mem::unmap	(	void *	addr,
		const size_t	length )

Unmap an existing mapping at the given address and of the given length.

As with mapping memory, unmapping memory can also cause an ApiError to be thrown, with one of the following Errno values:

Errno::INVALID_ARG: addr or length are offending
Errno::NO_MEMORY: unmapping part of a larger mapping would cause the number of individual mappings for the process to be exceeded.

Definition at line 25 of file mman.cxx.

                                            {
        if (::munmap(addr, length) != 0) {
                cosmos_throw (ApiError("munmap()"));
        }
}

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ PROT_SAO

Typedef Documentation

◆ AccessFlags

◆ LockAllFlags

◆ LockFlags

◆ ProtectFlags

◆ RemapFlags

◆ SyncFlags

Enumeration Type Documentation

◆ AccessFlag

◆ LockAllFlag

◆ LockFlag

◆ MapFlag

◆ MapType

◆ ProtectFlag

◆ RemapFlag

◆ SyncFlag

Function Documentation

◆ lock()

◆ lock_all()

◆ map()

◆ protect()

◆ remap()

◆ sync()

◆ unlock()

◆ unlock_all()

◆ unmap()