usr/src/man/man3rsm/rsm_memseg_import_get.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_GET 3RSM "Jun 8, 2001"
   7 .SH NAME
   8 rsm_memseg_import_get, rsm_memseg_import_get8, rsm_memseg_import_get16,
   9 rsm_memseg_import_get32, rsm_memseg_import_get64 \- read from a segment
  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_get\fR(\fBrsm_memseg_import_handle_t\fR \fIim_memseg\fR,
  17      \fBoff_t\fR \fIoffset\fR, \fBvoid *\fR\fIdest_addr\fR, \fBsize_t\fR \fIlength\fR);
  18 .fi
  19
  20 .LP
  21 .nf
  22 \fBint\fR \fBrsm_memseg_import_get8\fR(\fBrsm_memseg_import_handle_t\fR \fIim_memseg\fR,
  23      \fBoff_t\fR \fIoffset\fR, \fBuint8_t *\fR\fIdatap\fR, \fBulong_t\fR \fIrep_cnt\fR);
  24 .fi
  25
  26 .LP
  27 .nf
  28 \fBint\fR \fBrsm_memseg_import_get16\fR(\fBrsm_memseg_import_handle_t\fR \fIim_memseg\fR,
  29      \fBoff_t\fR \fIoffset\fR, \fBuint16_t *\fR\fIdatap\fR, \fBulong_t\fR \fIrep_cnt\fR);
  30 .fi
  31
  32 .LP
  33 .nf
  34 \fBint\fR \fBrsm_memseg_import_get32\fR(\fBrsm_memseg_import_handle_t\fR \fIim_memseg\fR,
  35      \fBoff_t\fR \fIoffset\fR, \fBuint32_t *\fR\fIdatap\fR, \fBulong_t\fR \fIrep_cnt\fR);
  36 .fi
  37
  38 .LP
  39 .nf
  40 \fBint\fR \fBrsm_memseg_import_get64\fR(\fBrsm_memseg_import_handle_t\fR \fIim_memseg\fR,
  41      \fBoff_t\fR \fIoffset\fR, \fBuint64_t *\fR\fIdatap\fR, \fBulong_t\fR \fIrep_cnt\fR);
  42 .fi
  43
  44 .SH DESCRIPTION
  45 .sp
  46 .LP
  47 When using interconnects that allow memory mapping (see
  48 \fBrsm_memseg_import_map\fR(3RSM)), standard CPU memory operations may be used
  49 for accessing memory of a segment. If a mapping is not provided, then
  50 explicitly calling these functions facilitates reading from a segment.
  51 Depending on the attributes of the extension library of the specific
  52 interconnect, these functions may involve performing an implicit mapping before
  53 performing the data transfer. Applications can be made interconnect-independent
  54 with respect to segment reads by using these functions. The data access error
  55 detection is performed through the use of barriers (see
  56 \fBrsm_memseg_import_open_barrier\fR(3RSM)). The default barrier operation mode
  57 is \fBRSM_BARRIER_MODE_IMPLICIT\fR, meaning that around every get operation
  58 open and close barrier are performed automatically. Alternatively, explicit
  59 error handling may be set up for these functions (see
  60 \fBrsm_memseg_import_set_mode\fR(3RSM)). In either case the barrier should be
  61 initialized prior to using these  functions using
  62 \fBrsm_memseg_import_init_barrier\fR(3RSM).
  63 .sp
  64 .LP
  65 The \fBrsm_memseg_import_get()\fR function copies \fIlength\fR bytes from the
  66 imported segment \fIim_memseg\fR beginning at location \fIoffset\fR from the
  67 start of the segment to a local memory buffer pointed to by \fIdest_addr\fR.
  68 .sp
  69 .LP
  70 The \fBrsm_memseg_import_get8()\fR function copies \fIrep_cnt\fR number of
  71 8-bit quantities from successive locations starting from \fIoffset\fR in the
  72 imported segment to successive local memory locations pointed to by
  73 \fIdatap\fR.
  74 .sp
  75 .LP
  76 The \fBrsm_memseg_import_get16()\fR functions copies \fIrep_cnt\fR number of
  77 16-bit quantities from successive locations starting from \fIoffset\fR in the
  78 imported segment to successive local memory locations pointed to by
  79 \fIdatap\fR. The offset must be aligned at half-word address boundary.
  80 .sp
  81 .LP
  82 The \fBrsm_memseg_import_get32()\fR function copies \fIrep_cnt\fR number of
  83 32-bit quantities from successive locations starting from \fIoffset\fR in the
  84 imported segment to successive local memory locations pointed to by
  85 \fIdatap\fR. The offset must be aligned at word address boundary.
  86 .sp
  87 .LP
  88 The \fBrsm_memseg_import_get64()\fR function copies \fIrep_cnt\fR number of
  89 -bit quantities from successive locations starting from \fIoffset\fR in the
  90 imported segment to successive local memory locations pointed to by
  91 \fIdatap\fR. The offset must be aligned at double-word address boundary.
  92 .sp
  93 .LP
  94 The data transfer functions that transfer small quantities of data (that is,
  95 8-, 16-, 32-, and 64-bit quantities) perform byte swapping prior to the data
  96 transfer, in the event that the source and destination have incompatible endian
  97 characteristics.
  98 .SH RETURN VALUES
  99 .sp
 100 .LP
 101 Upon successful completion, these functions return 0. Otherwise, an error value
 102 is returned to indicate the error.
 103 .SH ERRORS
 104 .sp
 105 .LP
 106 These functions can return the following errors:
 107 .sp
 108 .ne 2
 109 .na
 110 \fB\fBRSMERR_BAD_SEG_HNDL\fR \fR
 111 .ad
 112 .sp .6
 113 .RS 4n
 114 Invalid segment handle.
 115 .RE
 116
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fBRSMERR_BAD_ADDR\fR \fR
 121 .ad
 122 .sp .6
 123 .RS 4n
 124 Bad address.
 125 .RE
 126
 127 .sp
 128 .ne 2
 129 .na
 130 \fB\fBRSMERR_BAD_MEM_ALIGNMENT\fR \fR
 131 .ad
 132 .sp .6
 133 .RS 4n
 134 Invalid memory alignment for pointer.
 135 .RE
 136
 137 .sp
 138 .ne 2
 139 .na
 140 \fB\fBRSMERR_BAD_OFFSET\fR \fR
 141 .ad
 142 .sp .6
 143 .RS 4n
 144 Invalid offset.
 145 .RE
 146
 147 .sp
 148 .ne 2
 149 .na
 150 \fB\fBRSMERR_BAD_LENGTH\fR \fR
 151 .ad
 152 .sp .6
 153 .RS 4n
 154 Invalid length.
 155 .RE
 156
 157 .sp
 158 .ne 2
 159 .na
 160 \fB\fBRSMERR_PERM_DENIED\fR \fR
 161 .ad
 162 .sp .6
 163 .RS 4n
 164 Permission denied.
 165 .RE
 166
 167 .sp
 168 .ne 2
 169 .na
 170 \fB\fBRSMERR_INSUFFICIENT_RESOURCES\fR \fR
 171 .ad
 172 .sp .6
 173 .RS 4n
 174 Insufficient resources.
 175 .RE
 176
 177 .sp
 178 .ne 2
 179 .na
 180 \fB\fBRSMERR_BARRIER_UNINITIALIZED\fR \fR
 181 .ad
 182 .sp .6
 183 .RS 4n
 184 Barrier not initialized.
 185 .RE
 186
 187 .sp
 188 .ne 2
 189 .na
 190 \fB\fBRSMERR_BARRIER_FAILURE\fR \fR
 191 .ad
 192 .sp .6
 193 .RS 4n
 194 I/O completion error.
 195 .RE
 196
 197 .sp
 198 .ne 2
 199 .na
 200 \fB\fBRSMERR_CONN_ABORTED\fR \fR
 201 .ad
 202 .sp .6
 203 .RS 4n
 204 Connection aborted.
 205 .RE
 206
 207 .SH ATTRIBUTES
 208 .sp
 209 .LP
 210 See \fBattributes\fR(5) for descriptions of the following attributes:
 211 .sp
 212
 213 .sp
 214 .TS
 215 box;
 216 c | c
 217 l | l .
 218 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 219 _
 220 Interface Stability     Evolving
 221 _
 222 MT-Level        MT-Safe
 223 .TE
 224
 225 .SH SEE ALSO
 226 .sp
 227 .LP
 228 \fBrsm_memseg_import_init_barrier\fR(3RSM),
 229 \fBrsm_memseg_import_open_barrier\fR(3RSM),
 230 \fBrsm_memseg_import_set_mode\fR(3RSM), \fBattributes\fR(5)