share/man/man3rsm/rsm_memseg_import_putv.3rsm

   1 '\" te
   2 .\"  Copyright (c) 2001 by Sun Microsystems, Inc.  All rights reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH RSM_MEMSEG_IMPORT_PUTV 3RSM "Nov 12, 2001"
   7 .SH NAME
   8 rsm_memseg_import_putv, rsm_memseg_import_getv \- write to a segment using a
   9 list of I/O requests
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 cc [ \fIflag\fR... ] \fIfile\fR... -lrsm [ \fIlibrary\fR... ]
  14 #include <rsmapi.h>
  15
  16 \fBint\fR \fBrsm_memseg_import_putv\fR(\fBrsm_scat_gath_t *\fR\fIsg_io\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBint\fR \fBrsm_memseg_import_getv\fR(\fBrsm_scat_gath_t *\fR\fIsg_io\fR);
  22 .fi
  23
  24 .SH DESCRIPTION
  25 .sp
  26 .LP
  27 The \fBrsm_memseg_import_putv()\fR and \fBrsm_memseg_import_getv()\fR functions
  28 provide for using a list of I/O requests rather than a single source and
  29 destination address as is done for the \fBrsm_memseg_import_put\fR(3RSM) and
  30 \fBrsm_memseg_import_get\fR(3RSM) functions.
  31 .sp
  32 .LP
  33 The I/O vector component of the scatter-gather list (\fIsg_io\fR), allows
  34 specifying local virtual addresses or local_memory_handles. When a local
  35 address range is used repeatedly, it is efficient to use a handle because
  36 allocated system resources (that is, locked down local memory) are maintained
  37 until the handle is freed. The supporting functions for handles are
  38 \fBrsm_create_localmemory_handle\fR(3RSM) and
  39 \fBrsm_free_localmemory_handle\fR(3RSM).
  40 .sp
  41 .LP
  42 Virtual addresses or handles may be gathered into the vector for writing to a
  43 single remote segment, or a read from a single remote segment may be scattered
  44 to the vector of virtual addresses or handles.
  45 .sp
  46 .LP
  47 Implicit mapping is supported for the scatter-gather type of access. The
  48 attributes of the extension library for the specific interconnect are used to
  49 determine whether mapping is necessary before any scatter-gather access. If
  50 mapping of the imported segment is a prerequisite for scatter-gather access and
  51 the mapping has not already been performed, an implicit mapping is performed
  52 for the imported segment. The I/O for the vector is then initiated.
  53 .sp
  54 .LP
  55 I/O for the entire vector is initiated before returning. The barrier mode
  56 attribute of the import segment determines if the I/O has completed before the
  57 function returns.  A barrier mode attribute setting of \fBIMPLICIT\fR
  58 guarantees that the transfer of data is completed in the order as entered in
  59 the I/O vector. An implicit barrier open and close surrounds each list entry.
  60 If an error is detected, I/O for the vector is terminated and the function
  61 returns immediately. The residual count indicates the number of entries for
  62 which the I/O either did not complete or was not initiated.
  63 .sp
  64 .LP
  65 The number of entries in the I/O vector component of the scatter-gather list is
  66 specified in the \fBio_request_count\fR field of the \fBrsm_scat_gath_t\fR
  67 pointed to by \fIsg_io\fR. The \fBio_request_count\fR is valid if greater than
  68 0 and less than or equal to \fBRSM_MAX_SGIOREQS\fR.  If \fBio_request_count\fR
  69 is not in the valid range, \fBrsm_memseg_import_putv()\fR and
  70 \fBrsm_memseg_import_getv()\fR returns \fBRSMERR_BAD_SGIO\fR.
  71 .sp
  72 .LP
  73 Optionally, the scatter-gather list allows support for an implicit signal post
  74 after the I/O for the entire vector has completed. This alleviates the need to
  75 do an explicit signal post after ever I/O transfer operation. The means of
  76 enabling the implicit signal post involves setting the \fBflags\fR field within
  77 the scatter-gather list to \fBRSM_IMPLICIT_SIGPOST\fR. The \fBflags\fR field
  78 may also be set to \fBRSM_SIG_POST_NO_ACCUMULATE\fR, which will be passed on to
  79 the signal post operation when \fBRSM_IMPLICIT_SIGPOST\fR is set.
  80 .SH RETURN VALUES
  81 .sp
  82 .LP
  83 Upon successful completion, these functions return 0. Otherwise, an error value
  84 is returned to indicate the error.
  85 .SH ERRORS
  86 .sp
  87 .LP
  88 The \fBrsm_memseg_import_putv()\fR and \fBrsm_memseg_import_getv()\fR functions
  89 can return the following errors:
  90 .sp
  91 .ne 2
  92 .na
  93 \fB\fBRSMERR_BAD_SGIO\fR \fR
  94 .ad
  95 .sp .6
  96 .RS 4n
  97 Invalid scatter-gather structure pointer.
  98 .RE
  99
 100 .sp
 101 .ne 2
 102 .na
 103 \fB\fBRSMERR_BAD_SEG_HNDL\fR \fR
 104 .ad
 105 .sp .6
 106 .RS 4n
 107 Invalid segment handle.
 108 .RE
 109
 110 .sp
 111 .ne 2
 112 .na
 113 \fB\fBRSMERR_BAD_CTLR_HNDL\fR \fR
 114 .ad
 115 .sp .6
 116 .RS 4n
 117 Invalid controller handle.
 118 .RE
 119
 120 .sp
 121 .ne 2
 122 .na
 123 \fB\fBRSMERR_BAD_OFFSET\fR \fR
 124 .ad
 125 .sp .6
 126 .RS 4n
 127 Invalid offset.
 128 .RE
 129
 130 .sp
 131 .ne 2
 132 .na
 133 \fB\fBRSMERR_BAD_LENGTH\fR \fR
 134 .ad
 135 .sp .6
 136 .RS 4n
 137 Invalid length.
 138 .RE
 139
 140 .sp
 141 .ne 2
 142 .na
 143 \fB\fBRSMERR_BAD_ADDR\fR \fR
 144 .ad
 145 .sp .6
 146 .RS 4n
 147 Bad address.
 148 .RE
 149
 150 .sp
 151 .ne 2
 152 .na
 153 \fB\fBRSMERR_INSUFFICIENT_RESOURCES\fR \fR
 154 .ad
 155 .sp .6
 156 .RS 4n
 157 Insufficient resources.
 158 .RE
 159
 160 .sp
 161 .ne 2
 162 .na
 163 \fB\fBRSMERR_INTERRUPTED\fR\fR
 164 .ad
 165 .sp .6
 166 .RS 4n
 167 The operation was interrupted by a signal.
 168 .RE
 169
 170 .sp
 171 .ne 2
 172 .na
 173 \fB\fBRSMERR_PERM_DENIED\fR \fR
 174 .ad
 175 .sp .6
 176 .RS 4n
 177 Permission denied.
 178 .RE
 179
 180 .sp
 181 .ne 2
 182 .na
 183 \fB\fBRSMERR_BARRIER_FAILURE\fR \fR
 184 .ad
 185 .sp .6
 186 .RS 4n
 187 I/O completion error.
 188 .RE
 189
 190 .sp
 191 .ne 2
 192 .na
 193 \fB\fBRSMERR_REMOTE_NODE_UNREACHABLE\fR \fR
 194 .ad
 195 .sp .6
 196 .RS 4n
 197 Remote node not reachable.
 198 .RE
 199
 200 .SH ATTRIBUTES
 201 .sp
 202 .LP
 203 See \fBattributes\fR(5) for descriptions of the following attributes:
 204 .sp
 205
 206 .sp
 207 .TS
 208 box;
 209 c | c
 210 l | l .
 211 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 212 _
 213 Interface Stability     Evolving
 214 _
 215 MT-Level        MT-Safe
 216 .TE
 217
 218 .SH SEE ALSO
 219 .sp
 220 .LP
 221 \fBrsm_create_localmemory_handle\fR(3RSM),
 222 \fBrsm_free_localmemory_handle\fR(3RSM), \fBattributes\fR(5)