Shared Memory Support

Prerequisites

These features must be enabled before shared memory support can be provided:

  • CONFIG_ARCH_ADDRENV=y - Support for per-task address environment using a MMU.

  • CONFIG_BUILD_KERNEL=y - Support for protected kernel-/user-space memory regions must be provided by the MMU.

  • CONFIG_GRAN=y - The granule allocation is the allocation underlying all paged allocations.

  • CONFIG_MM_PGALLOC=y - Enables the physical page allocator

  • CONFIG_MM_PGSIZE - Determines the size of one page that can be mapped by the MMU.

And then finally:

  • CONFIG_MM_SHM=y - Enables shared memory support

  • CONFIG_ARCH_SHM_VBASE - The virtual address of the beginning of the shared memory region.

  • CONFIG_ARCH_SHM_MAXREGIONS - The maximum number of regions that can allocated for the shared memory space. This hard-coded value permits static allocation of the shared memory data structures and serves no other purpose. Default is 1.

  • CONFIG_ARCH_SHM_NPAGES - The maximum number of pages that can allocated for the shared memory region. Default is 1.

The size of the virtual shared memory address space is then determined by the product of the maximum number of regions, the maximum number of pages per region, and the configured size of each page.

Concepts

Each process has a task group structure, struct task_group_s, that holds information common to all threads in the group. If CONFIG_MM_SHM=y, then this includes data structures for the per-process shared memory virtual page allocator.

A memory region is accessed using:

int shmget(key_t key, size_t size, int shmflg);

by a lookup using internal shared memory data sets with key as the lookup match value. On success, shmget returns the shared memory identifier for the match – in this implementation that identifier is simply the table index of the match.

If the memory region does not exist, it may also be created by shmget (if the IPC_CREAT bit is set in the shmflag). When a shared memory region is created, the following things happen:

  • A new entry is set aside in the internal data set. The key value is assigned to the entry and the table index is the new shared memory identifier.

  • The requested size is rounded up to rounded up to full pages, each of size CONFIG_MM_PGSIZE.

  • A set of physical pages are allocated and the physical address of these pages is retained in the internal data set.

Now the key maps to and shared memory identifier (the table index) and the table index provides access to the list of physical pages making up the shared memory region.

NOTE: An improved implementation my perform a “lazy” back up of the physical memory, i.e., do not allocate the physical memory until the memory is required, for example, when a page fault occurs when a application tries to allocate the memory.

A shared memory region is destroyed via:

int shmctl(int shmid, int cmd, struct shmid_ds *buf);

In order for a process to make use of the memory region, it must be “attached” the process using:

FAR void *shmat(int shmid, FAR const void *shmaddr, int shmflg);

shmat() returns the virtual address where the shared memory can be found in the user process. Attaching the shared memory region involves the following steps:

  • Use the shmid as a table index to look up the mapping in the shared memory internal data structures.

  • Allocate a virtual address spaces of the same size as the physical address space using the per-process virtual shared memory virtual page allocator that can be found in the calling process’s task group structure.

  • Use platform specific interfaces to mapy the physical memory to the selected virtual address space, and

  • Return the allocated virtual base address to the caller.

The memory region can be detached from the user process using:

int shmdt(FAR const void *shmaddr);

Relevant header files

  • include/sys/shm.h - Shared memory interface declarations

  • include/sys/ipc.h - Provides additional definitions used by the shared memory interfaces

  • include/nuttx/addrenv.h - Defines the virtual address space of the process.

  • include/nuttx/pgalloc.h - Page allocator interfaces

  • mm/shm/shm.h - Internal shared memory definitions. This includes the

    definitions of the internal shared memory data structures.