ODP SHARED MEMORY

API Description

Shared memory blocks.

Data Structures
struct	odp_shm_info_t
	Shared memory block info. More...
struct	odp_shm_segment_info_t
	SHM memory segment info. More...
struct	odp_shm_capability_t
	Shared memory capabilities. More...

Macros
#define	ODP_SHM_INVALID   ((odp_shm_t)0)
	Invalid shared memory block.
#define	ODP_SHM_NAME_LEN   32
	Maximum shared memory block name length, including the null character.
#define	ODP_SHM_IOVA_INVALID   ((uint64_t)-1)
	Invalid IOVA address.
#define	ODP_SHM_PA_INVALID   ODP_SHM_IOVA_INVALID
	Invalid physical address.
#define	ODP_SHM_PROC   0x2
	Share with external processes.
#define	ODP_SHM_SINGLE_VA   0x4
	Single virtual address. More...
#define	ODP_SHM_EXPORT   0x08
	Export memory. More...
#define	ODP_SHM_HP   0x10
	Use huge pages. More...
#define	ODP_SHM_HW_ACCESS   0x20
	Share memory with HW accelerators. More...
#define	ODP_SHM_NO_HP   0x40
	Don't use huge pages. More...

Typedefs
typedef _odp_abi_shm_t *	odp_shm_t
	ODP shared memory block.
typedef struct odp_shm_info_t	odp_shm_info_t
	Shared memory block info.
typedef struct odp_shm_segment_info_t	odp_shm_segment_info_t
	SHM memory segment info.
typedef struct odp_shm_capability_t	odp_shm_capability_t
	Shared memory capabilities.

Functions
int	odp_shm_capability (odp_shm_capability_t *capa)
	Query shared memory capabilities. More...
odp_shm_t	odp_shm_reserve (const char *name, uint64_t size, uint64_t align, uint32_t flags)
	Reserve a contiguous block of shared memory. More...
int	odp_shm_free (odp_shm_t shm)
	Free a contiguous block of shared memory. More...
odp_shm_t	odp_shm_lookup (const char *name)
	Lookup for a block of shared memory. More...
odp_shm_t	odp_shm_import (const char *remote_name, odp_instance_t odp_inst, const char *local_name)
	Import a block of shared memory, exported by another ODP instance. More...
void *	odp_shm_addr (odp_shm_t shm)
	Shared memory block address. More...
int	odp_shm_info (odp_shm_t shm, odp_shm_info_t *info)
	Shared memory block info. More...
int	odp_shm_segment_info (odp_shm_t shm, uint32_t index, uint32_t num, odp_shm_segment_info_t info[])
	SHM block segmentation information. More...
void	odp_shm_print_all (void)
	Print all shared memory blocks.
void	odp_shm_print (odp_shm_t shm)
	Print shared memory block info. More...
uint64_t	odp_shm_to_u64 (odp_shm_t shm)
	Get printable value for an odp_shm_t. More...

Macro Definition Documentation

ODP_SHM_SINGLE_VA

#define ODP_SHM_SINGLE_VA   0x4

Single virtual address.

When set, this flag guarantees that all ODP threads sharing this memory block will see the block at the same address - regardless of ODP thread type (e.g. pthread vs. process (or fork process time)).

Examples

odp_sysinfo.c, and odp_timer_accuracy.c.

Definition at line 63 of file api/spec/shared_memory.h.

ODP_SHM_EXPORT

#define ODP_SHM_EXPORT   0x08

Export memory.

When set, the memory block becomes visible to other ODP instances through odp_shm_import().

Examples

odp_sysinfo.c.

Definition at line 71 of file api/spec/shared_memory.h.

ODP_SHM_HP

#define ODP_SHM_HP   0x10

Use huge pages.

When set, this flag guarantees that the memory reserved by odp_shm_reserve() is allocated from huge pages. The reserve call will return failure if enough huge page memory is not available.

Examples

odp_sysinfo.c.

Definition at line 80 of file api/spec/shared_memory.h.

ODP_SHM_HW_ACCESS

#define ODP_SHM_HW_ACCESS   0x20

Share memory with HW accelerators.

When set, this flag guarantees that the reserved memory is accessible by both CPUs and HW accelerators of the device. This may require e.g. that the odp_shm_reserve() call configures the memory to be accessible through an Input-Output Memory Management Unit (IOMMU).

Examples

odp_sysinfo.c.

Definition at line 90 of file api/spec/shared_memory.h.

ODP_SHM_NO_HP

#define ODP_SHM_NO_HP   0x40

Don't use huge pages.

When set, this flag guarantees that the memory reserved by odp_shm_reserve() is not allocated from huge pages. This flag must not be combined with ODP_SHM_HP.

Examples

odp_sysinfo.c.

Definition at line 99 of file api/spec/shared_memory.h.

Function Documentation

odp_shm_capability()

int odp_shm_capability

(

odp_shm_capability_t *

capa

)

Query shared memory capabilities.

Outputs shared memory capabilities on success.

Parameters

[out]

capa

Pointer to capability structure for output

Return values

0	on success
<0	on failure

Examples

odp_dma_perf.c, odp_mem_perf.c, odp_pool_latency.c, and odp_sysinfo.c.

odp_shm_reserve()

odp_shm_t odp_shm_reserve	(	const char *	name,
		uint64_t	size,
		uint64_t	align,
		uint32_t	flags
	)

Reserve a contiguous block of shared memory.

Reserve a contiguous block of shared memory that fulfills size, alignment and shareability (ODP_SHM_* flags) requirements. By default (without flags), the memory block can be shared between all threads of the ODP instance. Memory address (odp_shm_addr()) shareability depends on application memory model and ODP_SHM_SINGLE_VA flag usage.

Name is optional and does not need to be unique. However, if the block will be searched with odp_shm_lookup() or odp_shm_import(), a unique name is needed for correct match.

Parameters

name	Name of the block or NULL. Maximum string length is ODP_SHM_NAME_LEN, including the null character.
size	Block size in bytes
align	Block alignment in bytes
flags	Shared memory parameter flags (ODP_SHM_*). Default value is 0.

Returns

Handle of the reserved block

Return values

ODP_SHM_INVALID

on failure

See also

odp_mem_model_t

Examples

ipsec_api/odp_ipsec.c, ipsec_crypto/odp_ipsec.c, odp_atomic_perf.c, odp_bench_buffer.c, odp_bench_misc.c, odp_bench_packet.c, odp_bench_pktio_sp.c, odp_bench_timer.c, odp_classifier.c, odp_cpu_bench.c, odp_debug.c, odp_dma_perf.c, odp_dmafwd.c, odp_icache_perf.c, odp_ipfragreass.c, odp_ipsecfwd.c, odp_l2fwd.c, odp_l2fwd_simple.c, odp_l3fwd.c, odp_lock_perf.c, odp_mem_perf.c, odp_packet_gen.c, odp_pktio.c, odp_pktio_ordered.c, odp_pktio_perf.c, odp_pool_latency.c, odp_pool_perf.c, odp_queue_perf.c, odp_random.c, odp_sched_latency.c, odp_sched_perf.c, odp_sched_pktio.c, odp_simple_pipeline.c, odp_stash_perf.c, odp_stress.c, odp_switch.c, odp_timer_accuracy.c, and odp_timer_perf.c.

odp_shm_free()

int odp_shm_free

(

odp_shm_t

shm

)

Free a contiguous block of shared memory.

Frees a previously reserved block of shared memory. Freeing memory that is in use will result in UNDEFINED behavior

Parameters

shm	Block handle

Return values

0	on success
<0	on failure

Examples

ipsec_api/odp_ipsec.c, ipsec_crypto/odp_ipsec.c, odp_atomic_perf.c, odp_bench_buffer.c, odp_bench_misc.c, odp_bench_packet.c, odp_bench_pktio_sp.c, odp_bench_timer.c, odp_classifier.c, odp_cpu_bench.c, odp_debug.c, odp_dma_perf.c, odp_dmafwd.c, odp_icache_perf.c, odp_ipfragreass.c, odp_ipsecfwd.c, odp_l2fwd.c, odp_l2fwd_simple.c, odp_l3fwd.c, odp_lock_perf.c, odp_mem_perf.c, odp_packet_gen.c, odp_pktio.c, odp_pktio_ordered.c, odp_pktio_perf.c, odp_pool_latency.c, odp_pool_perf.c, odp_queue_perf.c, odp_random.c, odp_sched_latency.c, odp_sched_perf.c, odp_sched_pktio.c, odp_simple_pipeline.c, odp_stash_perf.c, odp_stress.c, odp_switch.c, odp_timer_accuracy.c, and odp_timer_perf.c.

odp_shm_lookup()

odp_shm_t odp_shm_lookup

(

const char *

name

)

Lookup for a block of shared memory.

Parameters

name	Name of the block

Returns

A handle to the block if it is found by name

Return values

ODP_SHM_INVALID

on failure

Examples

ipsec_api/odp_ipsec.c, ipsec_crypto/odp_ipsec.c, odp_l3fwd.c, odp_pktio_perf.c, and odp_sched_latency.c.

odp_shm_import()

odp_shm_t odp_shm_import	(	const char *	remote_name,
		odp_instance_t	odp_inst,
		const char *	local_name
	)

Import a block of shared memory, exported by another ODP instance.

This call creates a new handle for accessing a shared memory block created (with ODP_SHM_EXPORT flag) by another ODP instance. An instance may have only a single handle to the same block. Application must not access the block after freeing the handle. When an imported handle is freed, only the calling instance is affected. The exported block may be freed only after all other instances have stopped accessing the block.

Parameters

remote_name	Name of the block, in the remote ODP instance
odp_inst	Remote ODP instance, as returned by odp_init_global()
local_name	Name given to the block, in the local ODP instance May be NULL, if the application doesn't need a name (for a lookup). Maximum string length is ODP_SHM_NAME_LEN, including the null character.

Returns

A handle to access a block exported by another ODP instance.

Return values

ODP_SHM_INVALID

on failure

odp_shm_addr()

void* odp_shm_addr

(

odp_shm_t

shm

)

Shared memory block address.

Parameters

shm	Block handle

Returns

Memory block address

Return values

NULL	on failure

Examples

ipsec_api/odp_ipsec.c, ipsec_crypto/odp_ipsec.c, odp_atomic_perf.c, odp_bench_buffer.c, odp_bench_misc.c, odp_bench_packet.c, odp_bench_pktio_sp.c, odp_bench_timer.c, odp_classifier.c, odp_cpu_bench.c, odp_dma_perf.c, odp_dmafwd.c, odp_icache_perf.c, odp_ipfragreass.c, odp_ipsecfwd.c, odp_l2fwd.c, odp_l2fwd_simple.c, odp_l3fwd.c, odp_lock_perf.c, odp_mem_perf.c, odp_packet_gen.c, odp_pktio.c, odp_pktio_ordered.c, odp_pktio_perf.c, odp_pool_latency.c, odp_pool_perf.c, odp_queue_perf.c, odp_random.c, odp_sched_latency.c, odp_sched_perf.c, odp_sched_pktio.c, odp_simple_pipeline.c, odp_stash_perf.c, odp_stress.c, odp_switch.c, odp_timer_accuracy.c, and odp_timer_perf.c.

odp_shm_info()

int odp_shm_info	(	odp_shm_t	shm,
		odp_shm_info_t *	info
	)

Shared memory block info.

Get information about the specified shared memory block.

Parameters

	shm	Block handle
[out]	info	Block info pointer for output

Return values

0	on success
<0	on failure

odp_shm_segment_info()

int odp_shm_segment_info	(	odp_shm_t	shm,
		uint32_t	index,
		uint32_t	num,
		odp_shm_segment_info_t	info[]
	)

SHM block segmentation information.

Retrieve information about each memory segment of an SHM block. SHM info call outputs the number of memory segments (odp_shm_info_t::num_seg). A single segment info call may be used to request information for all the segments, or for a subset of those. Use 'index' and 'num' parameters to specify the segments. Segment indexing starts from zero and continues to odp_shm_info_t.num_seg - 1. Segment infos are written in virtual memory address order and without address overlaps. Segment info array must have at least 'num' elements.

Parameters

	shm	SHM block handle
	index	Index of the first segment to retrieve information
	num	Number of segments to retrieve information
[out]	info	Segment info array for output

Return values

0	on success
<0	on failure

odp_shm_print()

void odp_shm_print

(

odp_shm_t

shm

)

Print shared memory block info.

Print implementation defined information about the specified shared memory block to the ODP log. The information is intended to be used for debugging.

Parameters

shm	Block handle

Examples

odp_debug.c.

odp_shm_to_u64()

uint64_t odp_shm_to_u64

(

odp_shm_t

shm

)

Get printable value for an odp_shm_t.

This routine is intended to be used for diagnostic purposes to enable applications to generate a printable value that represents an odp_shm_t handle.

Parameters

shm	Block handle

Returns

uint64_t value that can be used to print this handle