RSM_MEMSEG_IMPORT_PUTV(3RSM) Remote Shared Memory Library Functions
rsm_memseg_import_putv, rsm_memseg_import_getv - write to a segment
using a list of I/O requests
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);
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.
Upon successful completion, these functions return 0. Otherwise, an
error value is returned to indicate the error.
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.
See attributes(7) for descriptions of the following attributes:
+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Evolving |
+--------------------+-----------------+
|MT-Level | MT-Safe |
+--------------------+-----------------+
rsm_create_localmemory_handle(3RSM),
rsm_free_localmemory_handle(3RSM), attributes(7)
November 12, 2001 RSM_MEMSEG_IMPORT_PUTV(3RSM)
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(7) 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(7)
November 12, 2001 RSM_MEMSEG_IMPORT_PUTV(3RSM)