RSM_MEMSEG_IMPORT_PUTV(3RSM) Remote Shared Memory Library Functions


NAME


rsm_memseg_import_putv, rsm_memseg_import_getv - write to a segment using
a list of I/O requests

SYNOPSIS


cc [ flag... ] file... -lrsm [ library... ]
#include <rsmapi.h>

int rsm_memseg_import_putv(rsm_scat_gath_t *sg_io);


int rsm_memseg_import_getv(rsm_scat_gath_t *sg_io);


DESCRIPTION


The rsm_memseg_import_putv() and rsm_memseg_import_getv() functions
provide for using a list of I/O requests rather than a single source and
destination address as is done for the rsm_memseg_import_put(3RSM) and
rsm_memseg_import_get(3RSM) functions.


The I/O vector component of the scatter-gather list (sg_io), allows
specifying local virtual addresses or local_memory_handles. When a local
address range is used repeatedly, it is efficient to use a handle because
allocated system resources (that is, locked down local memory) are
maintained until the handle is freed. The supporting functions for
handles are rsm_create_localmemory_handle(3RSM) and
rsm_free_localmemory_handle(3RSM).


Virtual addresses or handles may be gathered into the vector for writing
to a single remote segment, or a read from a single remote segment may be
scattered to the vector of virtual addresses or handles.


Implicit mapping is supported for the scatter-gather type of access. The
attributes of the extension library for the specific interconnect are
used to determine whether mapping is necessary before any scatter-gather
access. If mapping of the imported segment is a prerequisite for scatter-
gather access and the mapping has not already been performed, an implicit
mapping is performed for the imported segment. The I/O for the vector is
then initiated.


I/O for the entire vector is initiated before returning. The barrier mode
attribute of the import segment determines if the I/O has completed
before the function returns. A barrier mode attribute setting of
IMPLICIT guarantees that the transfer of data is completed in the order
as entered in the I/O vector. An implicit barrier open and close
surrounds each list entry. If an error is detected, I/O for the vector
is terminated and the function returns immediately. The residual count
indicates the number of entries for which the I/O either did not complete
or was not initiated.


The number of entries in the I/O vector component of the scatter-gather
list is specified in the io_request_count field of the rsm_scat_gath_t
pointed to by sg_io. The io_request_count is valid if greater than 0 and
less than or equal to RSM_MAX_SGIOREQS. If io_request_count is not in
the valid range, rsm_memseg_import_putv() and rsm_memseg_import_getv()
returns RSMERR_BAD_SGIO.


Optionally, the scatter-gather list allows support for an implicit signal
post after the I/O for the entire vector has completed. This alleviates
the need to do an explicit signal post after ever I/O transfer operation.
The means of enabling the implicit signal post involves setting the flags
field within the scatter-gather list to RSM_IMPLICIT_SIGPOST. The flags
field may also be set to RSM_SIG_POST_NO_ACCUMULATE, which will be passed
on to the signal post operation when RSM_IMPLICIT_SIGPOST is set.

RETURN VALUES


Upon successful completion, these functions return 0. Otherwise, an error
value is returned to indicate the error.

ERRORS


The rsm_memseg_import_putv() and rsm_memseg_import_getv() functions can
return the following errors:

RSMERR_BAD_SGIO

Invalid scatter-gather structure pointer.


RSMERR_BAD_SEG_HNDL

Invalid segment handle.


RSMERR_BAD_CTLR_HNDL

Invalid controller handle.


RSMERR_BAD_OFFSET

Invalid offset.


RSMERR_BAD_LENGTH

Invalid length.


RSMERR_BAD_ADDR

Bad address.


RSMERR_INSUFFICIENT_RESOURCES

Insufficient resources.


RSMERR_INTERRUPTED

The operation was interrupted by a signal.


RSMERR_PERM_DENIED

Permission denied.


RSMERR_BARRIER_FAILURE

I/O completion error.


RSMERR_REMOTE_NODE_UNREACHABLE

Remote node not reachable.


ATTRIBUTES


See attributes(5) for descriptions of the following attributes:


+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Evolving |
+--------------------+-----------------+
|MT-Level | MT-Safe |
+--------------------+-----------------+

SEE ALSO


rsm_create_localmemory_handle(3RSM), rsm_free_localmemory_handle(3RSM),
attributes(5)


November 12, 2001 RSM_MEMSEG_IMPORT_PUTV(3RSM)