Sun Microsystems, Inc.
spacerspacer
spacer   www.sun.com docs.sun.com | | |  
spacer
black dot
   
A   B   C   D   E   F   G   H   I   J   K   L   M   N   O   P   Q   R   S   T   U   V   W   X   Y   Z
    
 
Remote Shared Memory Library Functionsrsm_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 [flags...] 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 thersm_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 StabilityEvolving
MT-LevelMT-Safe

SEE ALSO

 

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


SunOS 5.9Go To TopLast Changed 12 Nov 2001

 
      
      
Copyright 2002 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.