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:

Topics
	Chunks
	Signals

Functions
L4_BEGIN_DECLS 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.

• The master role, responsible for setting up a shared memory area.
• A producer, generating data into a chunk
• A consumer, receiving data.

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.

References L4_CV.

l4shmc_area_size()

long l4shmc_area_size

(

l4shmc_area_t const *

shmarea

)

Get size of shared memory area.

Parameters

shmarea

Shared memory area.

Return values

>0	Size of the shared memory area.
<0	Error.

References L4_CV.

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

shmarea

Shared memory area.

Returns

Size of the shared memory area.

References L4_CV.

l4shmc_attach()

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

Attach to a shared memory area.

Parameters

	shmc_name	Name of the shared memory area.
[out]	shmarea	Pointer 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:

• l4shmc_get_client_nr() returns the client number stored in 'shmarea'. The first attached client will get 0 and this number is increased for each attached client.
• l4shmc_mark_client_initialized() tells other clients that this client has finished its initialization.
• l4shmc_get_initialized_clients() returns the bitmap of initialized clients attached to this shared memory.

Return values

0	Success.
<0	Error.

Examples

examples/libs/shmc/prodcons.c.

References L4_CV.

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.

References L4_END_DECLS.

l4shmc_connect_chunk_signal()

long l4shmc_connect_chunk_signal	(	l4shmc_chunk_t *	chunk,
		l4shmc_signal_t *	signal )

Connect a signal with a chunk.

Parameters

chunk	Chunk to attach the signal to.
signal	Signal to attach.

Return values

0	Success.
<0	Error.

Examples

examples/libs/shmc/prodcons.c.

References L4_CV, and L4_INLINE.

l4shmc_create()

L4_BEGIN_DECLS long l4shmc_create

(

char const *

shmc_name

)

Create a shared memory area.

Parameters

shmc_name

Name of the shared memory area.

Return values

0	Success.
-L4_ENOMEM	The requested size is too big.
-L4_ENOENT	No valid capability with the name of the shared memory area found.
<0	Errors from l4re_rm_attach or l4re_ns_register_obj_srv.

Examples

examples/libs/shmc/prodcons.c.

References L4_CV.

l4shmc_get_client_nr()

long l4shmc_get_client_nr

(

l4shmc_area_t const *

shmarea

)

Determine the client number of the shared memory region.

Parameters

shmarea

The shared memory area.

Returns

client number.

References L4_CV.

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

	shmarea	The shared memory area.
[out]	bitmask	The bitmask describing which clients are initialized.

Return values

0	Success.
<0	Error.

See also

l4shmc_mark_client_initialized(), l4shmc_get_client_nr()

Examples

examples/libs/shmc/prodcons.c.

References L4_CV.

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

shmarea

The shared memory area.

Return values

0	Success.
<0	Error.

Examples

examples/libs/shmc/prodcons.c.

References L4_CV.