usr/src/man/man3rsm/rsm_create_localmemory_handle.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_CREATE_LOCALMEMORY_HANDLE 3RSM "Jun 8, 2001"
   7 .SH NAME
   8 rsm_create_localmemory_handle, rsm_free_localmemory_handle \- create or free
   9 local memory handle
  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_create_localmemory_handle\fR(
  17      \fBrsmapi_controller_handle_t\fR \fIhandle\fR,
  18      \fBrsm_localmemory_handle_t *\fR\fIl_handle\fR,
  19      \fBcaddr_t\fR \fIlocal_vaddr\fR, \fBsize_t\fR \fIlength\fR);
  20 .fi
  21
  22 .LP
  23 .nf
  24 \fBint\fR \fBrsm_free_localmemory_handle\fR(
  25      \fBrsmapi_controller_handle_t\fR \fIhandle\fR,
  26      \fBrsm_localmemory_handle_t\fR \fIl_handle\fR);
  27 .fi
  28
  29 .SH DESCRIPTION
  30 .sp
  31 .LP
  32 The  \fBrsm_create_localmemory_handle()\fR and
  33 \fBrsm_free_localmemory_handle()\fR functions are supporting functions for
  34 \fBrsm_memseg_import_putv\fR(3RSM) and \fBrsm_memseg_import_getv\fR(3RSM).
  35 .sp
  36 .LP
  37 The \fBrsm_create_localmemory_handle()\fR function creates a local memory
  38 handle to be used in the I/O vector component of a scatter-gather list of
  39 subsequent \fBrsm_memseg_import_putv()\fR and \fBrsm_memseg_import_getv()\fR
  40 calls. The \fIhandle\fR argument specifies the controller handle obtained from
  41 \fBrsm_get_controller\fR(3RSM). The \fIl_handle\fR argument is a pointer to the
  42 location for the function to return the local memory handle. The
  43 \fIlocal_vaddr\fR argument specifies the local virtual address; it should be
  44 aligned at a page boundary. The \fIlength\fR argument specifies the length of
  45 memory spanned by the handle.
  46 .sp
  47 .LP
  48 The \fBrsm_free_localmemory_handle()\fR function unlocks the memory range for
  49 the local handle specified by \fIl_handle\fR and releases the associated system
  50 resources. The \fIhandle\fR argument specifies the controller handle.  All
  51 handles created by a process are freed when the process exits, but the process
  52 should call \fBrsm_free_localmemory_handle()\fR as soon as possible to free the
  53 system resources.
  54 .SH RETURN VALUES
  55 .sp
  56 .LP
  57 Upon successful completion, these functions return 0. Otherwise, an error value
  58 is returned to indicate the error.
  59 .SH ERRORS
  60 .sp
  61 .LP
  62 The \fBrsm_create_localmemory_handle()\fR and
  63 \fBrsm_free_localmemory_handle()\fR functions can return the following errors:
  64 .sp
  65 .ne 2
  66 .na
  67 \fB\fBRSMERR_BAD_CTLR_HNDL\fR \fR
  68 .ad
  69 .RS 29n
  70 Invalid controller handle.
  71 .RE
  72
  73 .sp
  74 .ne 2
  75 .na
  76 \fB\fBRSMERR_BAD_LOCALMEM_HNDL\fR \fR
  77 .ad
  78 .RS 29n
  79 Invalid local memory handle.
  80 .RE
  81
  82 .sp
  83 .LP
  84 The  \fBrsm_create_localmemory_handle()\fR function can return the following
  85 errors:
  86 .sp
  87 .ne 2
  88 .na
  89 \fB\fBRSMERR_BAD_LENGTH\fR \fR
  90 .ad
  91 .RS 28n
  92 Invalid length.
  93 .RE
  94
  95 .sp
  96 .ne 2
  97 .na
  98 \fB\fBRSMERR_BAD_ADDRESS\fR \fR
  99 .ad
 100 .RS 28n
 101 Invalid address.
 102 .RE
 103
 104 .sp
 105 .ne 2
 106 .na
 107 \fB\fBRSMERR_INSUFFICIENT_MEM\fR \fR
 108 .ad
 109 .RS 28n
 110 Insufficient memory.
 111 .RE
 112
 113 .SH ATTRIBUTES
 114 .sp
 115 .LP
 116 See \fBattributes\fR(5) for descriptions of the following attributes:
 117 .sp
 118
 119 .sp
 120 .TS
 121 box;
 122 c | c
 123 l | l .
 124 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 125 _
 126 Interface Stability     Evolving
 127 _
 128 MT-Level        MT-Safe
 129 .TE
 130
 131 .SH SEE ALSO
 132 .sp
 133 .LP
 134 \fBrsm_memseg_import_putv\fR(3RSM), \fBattributes\fR(5)