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.