L4Re Operating System Framework
Interface and Usage Documentation
Loading...
Searching...
No Matches
Shared Memory Library

L4SHM provides a shared memory infrastructure that establishes a shared memory area between multiple parties and uses a fast notification mechanism. More...

+ Collaboration diagram for Shared Memory Library:

Modules

 Chunks
 
 Signals
 

Functions

long l4shmc_create (char const *shmc_name)
 Create a shared memory area.
 
long l4shmc_attach (char const *shmc_name, l4shmc_area_t *shmarea)
 Attach to a shared memory area.
 
long l4shmc_get_client_nr (l4shmc_area_t const *shmarea)
 Determine the client number of the shared memory region.
 
long l4shmc_mark_client_initialized (l4shmc_area_t *shmarea)
 Mark this shared memory client as 'initialized'.
 
long l4shmc_get_initialized_clients (l4shmc_area_t *shmarea, l4_umword_t *bitmask)
 Fetch the _clients_init_done bitmask of the shared memory area.
 
long l4shmc_connect_chunk_signal (l4shmc_chunk_t *chunk, l4shmc_signal_t *signal)
 Connect a signal with a chunk.
 
long l4shmc_area_size (l4shmc_area_t const *shmarea)
 Get size of shared memory area.
 
long l4shmc_area_size_free (l4shmc_area_t const *shmarea)
 Get free size of shared memory area.
 
long l4shmc_area_overhead (void)
 Get memory overhead per area that is not available for chunks.
 
long l4shmc_chunk_overhead (void)
 Get memory overhead required in addition to the chunk capacity for adding one chunk.
 

Detailed Description

L4SHM provides a shared memory infrastructure that establishes a shared memory area between multiple parties and uses a fast notification mechanism.

A shared memory area consists of chunks and signals. A chunk is a defined chunk of memory within the memory area with a maximum size. A chunk is filled (written) by a producer and read by a consumer. When a producer has finished writing to the chunk it signals a data ready notification to the consumer.

A consumer attaches to a chunk and waits for the producer to fill the chunk. After reading out the chunk it marks the chunk free again.

A shared memory area can have multiple chunks.

The interface is divided in three roles.

A signal can be connected with a chunk or can be used independently (e.g. for multiple chunks).

Function Documentation

◆ l4shmc_area_overhead()

long l4shmc_area_overhead ( void  )

Get memory overhead per area that is not available for chunks.

Returns
Size of the overhead in bytes.

◆ l4shmc_area_size()

long l4shmc_area_size ( l4shmc_area_t const *  shmarea)

Get size of shared memory area.

Parameters
shmareaShared memory area.
Return values
>0Size of the shared memory area.
<0Error.

◆ l4shmc_area_size_free()

long l4shmc_area_size_free ( l4shmc_area_t const *  shmarea)

Get free size of shared memory area.

To get the max size to pass to l4shmc_add_chunk, subtract l4shmc_chunk_overhead().

Parameters
shmareaShared memory area.
Returns
Size of the shared memory area.

◆ l4shmc_attach()

long l4shmc_attach ( char const *  shmc_name,
l4shmc_area_t *  shmarea 
)

Attach to a shared memory area.

Parameters
shmc_nameName of the shared memory area.
[out]shmareaPointer to shared memory area descriptor to be filled with information for the shared memory area.

On success, the data in 'shmarea' contains a client number which can be used to mutual agree about client initialization:

Return values
0Success.
<0Error.
Examples
examples/libs/shmc/prodcons.c.

◆ l4shmc_chunk_overhead()

long l4shmc_chunk_overhead ( void  )

Get memory overhead required in addition to the chunk capacity for adding one chunk.

Returns
Size of the overhead in bytes.

◆ l4shmc_connect_chunk_signal()

long l4shmc_connect_chunk_signal ( l4shmc_chunk_t *  chunk,
l4shmc_signal_t *  signal 
)

Connect a signal with a chunk.

Parameters
chunkChunk to attach the signal to.
signalSignal to attach.
Return values
0Success.
<0Error.
Examples
examples/libs/shmc/prodcons.c.

◆ l4shmc_create()

long l4shmc_create ( char const *  shmc_name)

Create a shared memory area.

Parameters
shmc_nameName of the shared memory area.
Return values
0Success.
-L4_ENOMEMThe requested size is too big.
-L4_ENOENTNo valid capability with the name of the shared memory area found.
<0Errors from l4re_rm_attach or l4re_ns_register_obj_srv.
Examples
examples/libs/shmc/prodcons.c.

◆ l4shmc_get_client_nr()

long l4shmc_get_client_nr ( l4shmc_area_t const *  shmarea)

Determine the client number of the shared memory region.

Parameters
shmareaThe shared memory area.
Returns
client number.

◆ l4shmc_get_initialized_clients()

long l4shmc_get_initialized_clients ( l4shmc_area_t *  shmarea,
l4_umword_t bitmask 
)

Fetch the _clients_init_done bitmask of the shared memory area.

Parameters
shmareaThe shared memory area.
[out]bitmaskThe bitmask describing which clients are initialized.
Return values
0Success.
<0Error.
See also
l4shmc_mark_client_initialized(), l4shmc_get_client_nr()
Examples
examples/libs/shmc/prodcons.c.

◆ l4shmc_mark_client_initialized()

long l4shmc_mark_client_initialized ( l4shmc_area_t *  shmarea)

Mark this shared memory client as 'initialized'.

The corresponding bit is set in the _clients_init_done bitmask. The bitmask can be fetched with l4shmc_get_initialized_clients().

Parameters
shmareaThe shared memory area.
Return values
0Success.
<0Error.
Examples
examples/libs/shmc/prodcons.c.