fi_shm(7)

NAME

fi_shm - The SHM Fabric Provider

OVERVIEW

The SHM provider is a complete provider that can be used on Linux systems supporting shared memory and process_vm_readv/process_vm_writev calls. The provider is intended to provide high-performance communication between processes on the same system.

SUPPORTED FEATURES

This release contains an initial implementation of the SHM provider that offers the following support:

Endpoint types
    The provider supports only endpoint type FI_EP_RDM.

Endpoint capabilities
    Endpoints cna support any combinations of the following data transfer capabilities: FI_MSG, FI_TAGGED, FI_RMA, amd FI_ATOMICS. These capabilities can be further defined by FI_SEND, FI_RECV, FI_READ, FI_WRITE, FI_REMOTE_READ, and FI_REMOTE_WRITE to limit the direction of operations.

Modes
    The provider does not require the use of any mode bits.

Progress
    The SHM provider supports FI_PROGRESS_MANUAL. Receive side data buffers are not modified outside of completion processing routines. The provider processes messages using three different methods, based on the size of the message. For messages smaller than 4096 bytes, tx completions are generated immediately after the send. For larger messages, tx completions are not generated until the receiving side has processed the message.

Address Format
    The SHM provider uses the address format FI_ADDR_STR, which follows the general format pattern "[prefix]://[addr]". The application can provide addresses through the node or hints parameter. As long as the address is in a valid FI_ADDR_STR format (contains "://"), the address will be used as is. If the application input is incorrectly formatted or no input was provided, the SHM provider will resolve it according to the following SHM provider standards:

(flags & FI_SOURCE) ? src_addr : dest_addr = - if (node && service) : "fi_ns://node:service" - if (service) : "fi_ns://service" - if (node && !service) : "fi_shm://node" - if (!node && !service) : "fi_shm://PID"

!(flags & FI_SOURCE) - src_addr = "fi_shm://PID"

In other words, if the application provides a source and/or destination address in an acceptable FI_ADDR_STR format (contains "://"), the call to util_getinfo will successfully fill in src_addr and dest_addr with the provided input. If the input is not in an ADDR_STR format, the shared memory provider will then create a proper FI_ADDR_STR address with either the "fi_ns://" (node/service format) or "fi_shm://" (shm format) prefixes signaling whether the addr is a "unique" address and does or does not need an extra endpoint name identifier appended in order to make it unique. For the shared memory provider, we assume that the service (with or without a node) is enough to make it unique, but a node alone is not sufficient. If only a node is provided, the "fi_shm://" prefix is used to signify that it is not a unique address. If no node or service are provided (and in the case of setting the src address without FI_SOURCE and no hints), the process ID will be used as a default address. On endpoint creation, if the src_addr has the "fi_shm://" prefix, the provider will append ":[uid]:[dom_idx]:[ep_idx]" as a unique endpoint name (essentially, in place of a service). In the case of the "fi_ns://" prefix (or any other prefix if one was provided by the application), no supplemental information is required to make it unique and it will remain with only the application-defined address. Note that the actual endpoint name will not include the FI_ADDR_STR "*://" prefix since it cannot be included in any shared memory region names. The provider will strip off the prefix before setting the endpoint name. As a result, the addresses "fi_prefix1://my_node:my_service" and "fi_prefix2://my_node:my_service" would result in endpoints and regions of the same name. The application can also override the endpoint name after creating an endpoint using setname() without any address format restrictions.

Msg flags The provider currently only supports the FI_REMOTE_CQ_DATA msg flag.

MR registration mode The provider implements FI_MR_VIRT_ADDR memory mode.

Atomic operations The provider supports all combinations of datatype and operations as long as the message is less than 4096 bytes (or 2048 for compare operations).

LIMITATIONS

The SHM provider has hard-coded maximums for supported queue sizes and data transfers. These values are reflected in the related fabric attribute structures

EPs must be bound to both RX and TX CQs.

No support for counters.

RUNTIME PARAMETERS

The shm provider checks for the following environment variables:

FI_SHM_SAR_THRESHOLD
    Maximum message size to use segmentation protocol before switching to mmap (only valid when CMA is not available). Default: SIZE_MAX (18446744073709551615)

FI_SHM_TX_SIZE
    Maximum number of outstanding tx operations. Default 1024

FI_SHM_RX_SIZE
    Maximum number of outstanding rx operations. Default 1024

SEE ALSO

fabric(7), fi_provider(7), fi_getinfo(3)

AUTHORS
OpenFabrics.