fi_atomic - Man Page

Atomic functions may operate on one of the following identified data types. A given atomic function may support any datatype, subject to provider implementation constraints.

FI_INT8

Signed 8-bit integer.

FI_UINT8

Unsigned 8-bit integer.

FI_INT16

Signed 16-bit integer.

FI_UINT16

Unsigned 16-bit integer.

FI_INT32

Signed 32-bit integer.

FI_UINT32

Unsigned 32-bit integer.

FI_INT64

Signed 64-bit integer.

FI_UINT64

Unsigned 64-bit integer.

FI_INT128

Signed 128-bit integer.

FI_UINT128

Unsigned 128-bit integer.

FI_FLOAT

A single-precision floating point value (IEEE 754).

FI_DOUBLE

A double-precision floating point value (IEEE 754).

FI_FLOAT_COMPLEX

An ordered pair of single-precision floating point values (IEEE 754), with the first value representing the real portion of a complex number and the second representing the imaginary portion.

FI_DOUBLE_COMPLEX

An ordered pair of double-precision floating point values (IEEE 754), with the first value representing the real portion of a complex number and the second representing the imaginary portion.

FI_LONG_DOUBLE

A double-extended precision floating point value (IEEE 754). Note that the size of a long double and number of bits used for precision is compiler, platform, and/or provider specific. Developers that use long double should ensure that libfabric is built using a long double format that is compatible with their application, and that format is supported by the provider. The mechanism used for this validation is currently beyond the scope of the libfabric API.

FI_LONG_DOUBLE_COMPLEX

An ordered pair of double-extended precision floating point values (IEEE 754), with the first value representing the real portion of a complex number and the second representing the imaginary portion.

The following atomic operations are defined. An atomic operation often acts against a target value in the remote memory buffer and source value provided with the atomic function. It may also carry source data to replace the target value in compare and swap operations. A conceptual description of each operation is provided.

FI_MIN

Minimum

if (buf[i] < addr[i])
    addr[i] = buf[i]

FI_MAX

Maximum

if (buf[i] > addr[i])
    addr[i] = buf[i]

FI_SUM

Sum

addr[i] = addr[i] + buf[i]

FI_PROD

Product

addr[i] = addr[i] * buf[i]

FI_LOR

Logical OR

addr[i] = (addr[i] || buf[i])

FI_LAND

Logical AND

addr[i] = (addr[i] && buf[i])

FI_BOR

Bitwise OR

addr[i] = addr[i] | buf[i]

FI_BAND

Bitwise AND

addr[i] = addr[i] & buf[i]

FI_LXOR

Logical exclusive-OR (XOR)

addr[i] = ((addr[i] && !buf[i]) || (!addr[i] && buf[i]))

FI_BXOR

Bitwise exclusive-OR (XOR)

addr[i] = addr[i] ^ buf[i]

FI_ATOMIC_READ

Read data atomically

result[i] = addr[i]

FI_ATOMIC_WRITE

Write data atomically

addr[i] = buf[i]

FI_CSWAP

Compare values and if equal swap with data

if (compare[i] == addr[i])
    addr[i] = buf[i]

FI_CSWAP_NE

Compare values and if not equal swap with data

if (compare[i] != addr[i])
    addr[i] = buf[i]

FI_CSWAP_LE

Compare values and if less than or equal swap with data

if (compare[i] <= addr[i])
    addr[i] = buf[i]

FI_CSWAP_LT

Compare values and if less than swap with data

if (compare[i] < addr[i])
    addr[i] = buf[i]

FI_CSWAP_GE

Compare values and if greater than or equal swap with data

if (compare[i] >= addr[i])
    addr[i] = buf[i]

FI_CSWAP_GT

Compare values and if greater than swap with data

if (compare[i] > addr[i])
    addr[i] = buf[i]

FI_MSWAP

Swap masked bits with data

addr[i] = (buf[i] & compare[i]) | (addr[i] & ~compare[i])

The base atomic functions – fi_atomic, fi_atomicv, fi_atomicmsg – are used to transmit data to a remote node, where the specified atomic operation is performed against the target data. The result of a base atomic function is stored at the remote memory region. The main difference between atomic functions are the number and type of parameters that they accept as input. Otherwise, they perform the same general function.

The call fi_atomic transfers the data contained in the user-specified data buffer to a remote node. For connectionless endpoints, the destination endpoint is specified through the dest_addr parameter. Unless the endpoint has been configured differently, the data buffer passed into fi_atomic must not be touched by the application until the fi_atomic call completes asynchronously. The target buffer of a base atomic operation must allow for remote read an/or write access, as appropriate.

The fi_atomicv call adds support for a scatter-gather list to fi_atomic. The fi_atomicv transfers the set of data buffers referenced by the ioc parameter to the remote node for processing.

The fi_inject_atomic call is an optimized version of fi_atomic. The fi_inject_atomic function behaves as if the FI_INJECT transfer flag were set, and FI_COMPLETION were not. That is, the data buffer is available for reuse immediately on returning from from fi_inject_atomic, and no completion event will be generated for this atomic. The completion event will be suppressed even if the endpoint has not been configured with FI_SELECTIVE_COMPLETION. See the flags discussion below for more details. The requested message size that can be used with fi_inject_atomic is limited by inject_size.

The fi_atomicmsg call supports atomic functions over both connected and connectionless endpoints, with the ability to control the atomic operation per call through the use of flags. The fi_atomicmsg function takes a struct fi_msg_atomic as input.

struct fi_msg_atomic {
    const struct fi_ioc *msg_iov; /* local scatter-gather array */
    void                **desc;   /* local access descriptors */
    size_t              iov_count;/* # elements in ioc */
    const void          *addr;    /* optional endpoint address */
    const struct fi_rma_ioc *rma_iov; /* remote SGL */
    size_t              rma_iov_count;/* # elements in remote SGL */
    enum fi_datatype    datatype; /* operand datatype */
    enum fi_op          op;       /* atomic operation */
    void                *context; /* user-defined context */
    uint64_t            data;     /* optional data */
};

struct fi_ioc {
    void        *addr;    /* local address */
    size_t      count;    /* # target operands */
};

struct fi_rma_ioc {
    uint64_t    addr;     /* target address */
    size_t      count;    /* # target operands */
    uint64_t    key;      /* access key */
};

The following list of atomic operations are usable with base atomic operations: FI_MIN, FI_MAX, FI_SUM, FI_PROD, FI_LOR, FI_LAND, FI_BOR, FI_BAND, FI_LXOR, FI_BXOR, and FI_ATOMIC_WRITE.

The fetch atomic functions – fi_fetch_atomic, fi_fetch_atomicv, and fi_fetch atomicmsg – behave similar to the equivalent base atomic function. The difference between the fetch and base atomic calls are the fetch atomic routines return the initial value that was stored at the target to the user. The initial value is read into the user provided result buffer. The target buffer of fetch-atomic operations must be enabled for remote read access.

The following list of atomic operations are usable with fetch atomic operations: FI_MIN, FI_MAX, FI_SUM, FI_PROD, FI_LOR, FI_LAND, FI_BOR, FI_BAND, FI_LXOR, FI_BXOR, FI_ATOMIC_READ, and FI_ATOMIC_WRITE.

For FI_ATOMIC_READ operations, the source buffer operand (e.g. fi_fetch_atomic buf parameter) is ignored and may be NULL. The results are written into the result buffer.

The compare atomic functions – fi_compare_atomic, fi_compare_atomicv, and fi_compare atomicmsg – are used for operations that require comparing the target data against a value before performing a swap operation. The compare atomic functions support: FI_CSWAP, FI_CSWAP_NE, FI_CSWAP_LE, FI_CSWAP_LT, FI_CSWAP_GE, FI_CSWAP_GT, and FI_MSWAP.

The atomic valid functions – fi_atomicvalid, fi_fetch_atomicvalid, and fi_compare_atomicvalid –indicate which operations the local provider supports. Needed operations not supported by the provider must be emulated by the application. Each valid call corresponds to a set of atomic functions. fi_atomicvalid checks whether a provider supports a specific base atomic operation for a given datatype and operation. fi_fetch_atomicvalid indicates if a provider supports a specific fetch-atomic operation for a given datatype and operation. And fi_compare_atomicvalid checks if a provider supports a specified compare-atomic operation for a given datatype and operation.

If an operation is supported, an atomic valid call will return 0, along with a count of atomic data units that a single function call will operate on.

The fi_query_atomic call acts as an enhanced atomic valid operation (see the atomic valid function definitions above). It is provided, in part, for future extensibility. The query operation reports which atomic operations are supported by the domain, for suitably configured endpoints.

The behavior of fi_query_atomic is adjusted based on the flags parameter. If flags is 0, then the operation reports the supported atomic attributes for base atomic operations, similar to fi_atomicvalid for endpoints. If flags has the FI_FETCH_ATOMIC bit set, the operation behaves similar to fi_fetch_atomicvalid. Similarly, the flag bit FI_COMPARE_ATOMIC results in query acting as fi_compare_atomicvalid. The FI_FETCH_ATOMIC and FI_COMPARE_ATOMIC bits may not both be set.

If the FI_TAGGED bit is set, the provider will indicate if it supports atomic operations to tagged receive buffers. The FI_TAGGED bit may be used by itself, or in conjunction with the FI_FETCH_ATOMIC and FI_COMPARE_ATOMIC flags.

The output of fi_query_atomic is struct fi_atomic_attr:

struct fi_atomic_attr {
    size_t count;
    size_t size;
};

The count attribute field is as defined for the atomic valid calls. The size field indicates the size in bytes of the atomic datatype. The size field is useful for datatypes that may differ in sizes based on the platform or compiler, such FI_LONG_DOUBLE.

Completed atomic operations are reported to the initiator of the request through an associated completion queue or counter. Any user provided context specified with the request will be returned as part of any completion event written to a CQ. See fi_cq for completion event details.

Any results returned to the initiator as part of an atomic operation will be available prior to a completion event being generated. This will be true even if the requested completion semantic provides a weaker guarantee. That is, atomic fetch operations have FI_DELIVERY_COMPLETE semantics. Completions generated for other types of atomic operations indicate that it is safe to re-use the source data buffers.

Any updates to data at the target of an atomic operation will be visible to agents (CPU processes, NICs, and other devices) on the target node prior to one of the following occurring. If the atomic operation generates a completion event or updates a completion counter at the target endpoint, the results will be available prior to the completion notification. After processing a completion for the atomic, if the initiator submits a transfer between the same endpoints that generates a completion at the target, the results will be available prior to the subsequent transfer’s event. Or, if a fenced data transfer from the initiator follows the atomic request, the results will be available prior to a completion at the target for the fenced transfer.

The correctness of atomic operations on a target memory region is guaranteed only when performed by a single actor for a given window of time. An actor is defined as a single libfabric domain on the target (identified by the domain name, and not an open instance of that domain), a coherent CPU complex, or other device (e.g. GPU) capable of performing atomic operations on the target memory. The results of atomic operations performed by multiple actors simultaneously are undefined. For example, issuing CPU based atomic operations to a target region concurrently being updated by NIC based atomics may leave the region’s data in an unknown state. The results of a first actor’s atomic operations must be visible to a second actor prior to the second actor issuing its own atomics.