From 1ab6d59863c17bd62a76517d434092f68d4ff8f3 Mon Sep 17 00:00:00 2001 From: Gedare Bloom Date: Fri, 28 Jul 2017 14:45:01 -0400 Subject: [PATCH] memory_management: update mmap, munmap, shm_open, shm_unlink Close #2859. --- posix-users/memory_managment.rst | 149 +++++++++++++++++++++++++++++-- 1 file changed, 140 insertions(+), 9 deletions(-) diff --git a/posix-users/memory_managment.rst b/posix-users/memory_managment.rst index 631ba45..ec3e60c 100644 --- a/posix-users/memory_managment.rst +++ b/posix-users/memory_managment.rst @@ -167,7 +167,13 @@ mmap - Map Process Addresses to a Memory Object .. code-block:: c - int mmap( + void *mmap( + void *addr, + size_t len, + int prot, + int flags, + int fildes, + off_t off ); **STATUS CODES:** @@ -175,13 +181,65 @@ mmap - Map Process Addresses to a Memory Object .. list-table:: :class: rtems-table - * - ``E`` - - The + * - ``EBADF`` + - The fildes argument is not a valid open file descriptor. + * - ``EINVAL`` + - The value of len is zero. + * - ``EINVAL`` + - The value of flags is invalid (neither MAP_PRIVATE nor MAP_SHARED is set). + * - ``EINVAL`` + - The addr argument (if MAP_FIXED was specified) or off is not a multiple of + the page size as returned by sysconf(), or is considered invalid by the + implementation. + * - ``ENODEV`` + - The fildes argument refers to a file whose type is not supported by mmap. + * - ``ENOMEM`` + - MAP_FIXED was specified, and the range [addr,addr+len) exceeds that + allowed for the address space of a process; or, if MAP_FIXED was not + specified and there is insufficient room in the address space to effect + the mapping. + * - ``ENOTSUP`` + - MAP_FIXED or MAP_PRIVATE was specified in the flags argument and the + implementation does not support this functionality. + * - ``ENOTSUP`` + - The implementation does not support the combination of accesses requested + in the prot argument. + * - ``ENXIO`` + - Addresses in the range [off,off+len) are invalid for the object specified + by fildes. + * - ``ENXIO`` + - MAP_FIXED was specified in flags and the combination of addr, len, and off + is invalid for the object specified by fildes. + * - ``EOVERFLOW`` + - The file is a regular file and the value of off plus len exceeds the + offset maximum established in the open file description associated with + fildes. **DESCRIPTION:** +``mmap`` establishes a mapping between an address ``pa`` for ``len`` bytes to +the memory object represented by the file descriptor ``fildes`` at offset +``off`` for ``len`` bytes. The value of ``pa`` is an implementation-defined +function of the parameter addr and the values of ``flags``. A successful +``mmap()`` call shall return ``pa`` as its result. An unsuccessful call returns +``MAP_FAILED`` and sets ``errno`` accordingly. + **NOTES:** +RTEMS is a single address space operating system without privilege separation +between the kernel and user space. Therefore, the implementation of ``mmap`` +has a number of implementation-specific issues to be aware of: + * Read, write and execute permissions are allowed because the memory in RTEMS + does not normally have protections but we cannot hide access to memory. + Thus, the use of ``PROT_NONE`` for the ``prot`` argument is not supported. + Similarly, there is no restriction of write access, so ``PROT_WRITE`` must + be in the ``prot`` argument. + * Anonymous mappings must have ``fildes`` set to -1 and ``off`` set to 0. + Shared mappings are not supported with Anonymous mappings. + * ``MAP_FIXED`` is not supported for shared memory objects with ``MAP_SHARED``. + * Support for shared mappings is dependent on the underlying object's + filesystem implementation of an ``mmap_h`` file operation handler. + .. _munmap: munmap - Unmap Previously Mapped Addresses @@ -194,6 +252,8 @@ munmap - Unmap Previously Mapped Addresses .. code-block:: c int munmap( + void *addr, + size_t len ); **STATUS CODES:** @@ -201,11 +261,22 @@ munmap - Unmap Previously Mapped Addresses .. list-table:: :class: rtems-table - * - ``E`` - - The + * - ``EINVAL`` + - Addresses in the range [addr,addr+len) are outside the valid range for the + address space. + * - ``EINVAL`` + - The len argument is 0. **DESCRIPTION:** +The ``munmap()`` function shall remove any mappings for those entire pages +containing any part of the address space of the process starting at ``addr`` +and continuing for ``len`` bytes. If there are no mappings in the specified +address range, then ``munmap()`` has no effect. + +Upon successful completion, ``munmap()`` shall return 0; otherwise, it shall +return -1 and set ``errno`` to indicate the error. + **NOTES:** .. _mprotect: @@ -272,6 +343,9 @@ shm_open - Open a Shared Memory Object .. code-block:: c int shm_open( + const char *name, + int oflag, + mode_t mode ); **STATUS CODES:** @@ -279,13 +353,49 @@ shm_open - Open a Shared Memory Object .. list-table:: :class: rtems-table - * - ``E`` - - The + * - ``EACCES`` + - The shared memory object exists and the permissions specified by oflag are + denied, or the shared memory object does not exist and permission to + create the shared memory object is denied, or O_TRUNC is specified and + write permission is denied. + * - ``EEXIST`` + - O_CREAT and O_EXCL are set and the named shared memory object already + exists. + * - ``EINVAL`` + - The ``shm_open()`` operation is not supported for the given name. + * - ``EMFILE`` + - All file descriptors available to the process are currently open. + * - ``ENFILE`` + - Too many shared memory objects are currently open in the system. + * - ``ENOENT`` + - O_CREAT is not set and the named shared memory object does not exist. + * - ``ENOSPC`` + - There is insufficient space for the creation of the new shared memory + object. + * - ``ENAMETOOLONG`` + - The length of the name argument exceeds ``_POSIX_PATH_MAX``. + **DESCRIPTION:** +The ``shm_open()`` function shall establish a connection between a shared +memory object and a file descriptor. It shall create an open file description +that refers to the shared memory object and a file descriptor that refers to +that open file description. The ``name`` argument points to a string naming a +shared memory object. + +If successful, ``shm_open()`` shall return a file descriptor for the shared +memory object. Upon successful completion, the ``shm_open()`` function shall +return a non-negative integer representing the file descriptor. Otherwise, it +shall return -1 and set ``errno`` to indicate the error. + **NOTES:** +An application can set the ``_POSIX_Shm_Object_operations`` to control the +behavior of shared memory objects when accessed via the file descriptor. + +The ``name`` must be valid for an RTEMS SuperCore Object. + .. _shm_unlink: shm_unlink - Remove a Shared Memory Object @@ -298,6 +408,7 @@ shm_unlink - Remove a Shared Memory Object .. code-block:: c int shm_unlink( + const char *name ); **STATUS CODES:** @@ -305,9 +416,29 @@ shm_unlink - Remove a Shared Memory Object .. list-table:: :class: rtems-table - * - ``E`` - - The + * - ``ENOENT`` + - The named shared memory object does not exist. + * - ``ENAMETOOLONG`` + - The length of the name argument exceeds ``_POSIX_PATH_MAX``. **DESCRIPTION:** +The ``shm_unlink()`` function shall remove the name of the shared memory object +named by the string pointed to by ``name``. + +If one or more references to the shared memory object exist when the object is +unlinked, the name shall be removed before ``shm_unlink()`` returns, but the +removal of the memory object contents shall be postponed until all open and map +references to the shared memory object have been removed. + +Even if the object continues to exist after the last ``shm_unlink()``, reuse of +the name shall subsequently cause ``shm_open()`` to behave as if no shared +memory object of this name exists. + +Upon successful completion, a value of zero shall be returned. Otherwise, a +value of -1 shall be returned and errno set to indicate the error. If -1 is +returned, the named shared memory object shall not be changed by this function +call. + **NOTES:** +