1 '\" te
   2 .\"  Copyright (c) 1996, 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 CSX_DUPHANDLE 9F "Jul 19, 1996"
   7 .SH NAME
   8 csx_DupHandle \- duplicate access handle
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/pccard.h>
  13 
  14 
  15 
  16 \fBint32_t\fR \fBcsx_DupHandle\fR(\fBacc_handle_t\fR \fIhandle1\fR, \fBacc_handle_t *\fR\fIhandle2\fR,
  17      \fBuint32_t\fR \fIflags\fR);
  18 .fi
  19 
  20 .SH INTERFACE LEVEL
  21 .sp
  22 .LP
  23 Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR
  24 .SH PARAMETERS
  25 .sp
  26 .ne 2
  27 .na
  28 \fB\fIhandle1\fR \fR
  29 .ad
  30 .RS 12n
  31 The access handle returned from \fBcsx_RequestIO\fR(9F) or
  32 \fBcsx_RequestWindow\fR(9F) that is to be duplicated.
  33 .RE
  34 
  35 .sp
  36 .ne 2
  37 .na
  38 \fB\fIhandle2\fR \fR
  39 .ad
  40 .RS 12n
  41 A pointer to the newly-created duplicated data access handle.
  42 .RE
  43 
  44 .sp
  45 .ne 2
  46 .na
  47 \fB\fIflags\fR \fR
  48 .ad
  49 .RS 12n
  50 The access attributes that will be applied to the new handle.
  51 .RE
  52 
  53 .SH DESCRIPTION
  54 .sp
  55 .LP
  56 This function duplicates the handle, \fIhandle1\fR, into a new handle,
  57 \fIhandle2\fR, that has the access attributes specified in the \fIflags\fR
  58 argument. Both the original handle and the new handle are active and can be
  59 used with the common access functions.
  60 .sp
  61 .LP
  62 Both handles must be explicitly freed when they are no longer necessary.
  63 .sp
  64 .LP
  65 The \fIflags\fR argument is bit-mapped. The following bits are defined:
  66 .sp
  67 .in +2
  68 .nf
  69 WIN_ACC_NEVER_SWAP       Host endian byte ordering
  70 WIN_ACC_BIG_ENDIAN       Big endian byte ordering
  71 WIN_ACC_LITTLE_ENDIAN    Little endian byte ordering
  72 WIN_ACC_STRICT_ORDER     Program ordering references
  73 WIN_ACC_UNORDERED_OK     May re-order references
  74 WIN_ACC_MERGING_OK       Merge stores to consecutive locations
  75 WIN_ACC_LOADCACHING_OK   May cache load operations
  76 WIN_ACC_STORECACHING_OK  May cache store operations
  77 .fi
  78 .in -2
  79 
  80 .sp
  81 .LP
  82 \fBWIN_ACC_BIG_ENDIAN\fR and \fBWIN_ACC_LITTLE_ENDIAN\fR describe the endian
  83 characteristics of the device as big endian or little endian, respectively.
  84 Even though most of the devices will have the same endian characteristics as
  85 their busses, there are examples of devices with an \fBI/O \fRprocessor that
  86 has opposite endian characteristics of the busses. When
  87 \fBWIN_ACC_BIG_ENDIAN\fR or \fBWIN_ACC_LITTLE_ENDIAN\fR is  set, byte swapping
  88 will automatically be performed by the system if the host machine and the
  89 device data formats have opposite endian characteristics. The implementation
  90 may take advantage of hardware platform byte swapping capabilities.  When
  91 \fBWIN_ACC_NEVER_SWAP\fR is specified, byte swapping will not be invoked in the
  92 data access functions. The ability to specify the order in which the \fBCPU
  93 \fRwill reference data is provided by the following \fIflags\fR bits. Only one
  94 of the following bits may be specified:
  95 .sp
  96 .ne 2
  97 .na
  98 \fB\fBWIN_ACC_STRICT_ORDER\fR \fR
  99 .ad
 100 .RS 28n
 101 The data references must be issued by a \fBCPU \fRin program order. Strict
 102 ordering is the default behavior.
 103 .RE
 104 
 105 .sp
 106 .ne 2
 107 .na
 108 \fB\fBWIN_ACC_UNORDERED_OK\fR \fR
 109 .ad
 110 .RS 28n
 111 The \fBCPU \fRmay re-order the data  references. This includes all kinds of
 112 re-ordering (that is, a load followed by a store may be replaced by a store
 113 followed by a load).
 114 .RE
 115 
 116 .sp
 117 .ne 2
 118 .na
 119 \fB\fBWIN_ACC_MERGING_OK\fR \fR
 120 .ad
 121 .RS 28n
 122 The \fBCPU \fRmay merge individual stores to consecutive locations. For
 123 example, the \fBCPU \fRmay turn two consecutive byte stores into one halfword
 124 store. It may also batch individual loads. For example, the \fBCPU \fRmay turn
 125 two consecutive byte loads into one halfword load. Setting this bit also
 126 implies re-ordering.
 127 .RE
 128 
 129 .sp
 130 .ne 2
 131 .na
 132 \fB\fBWIN_ACC_LOADCACHING_OK\fR \fR
 133 .ad
 134 .RS 28n
 135 The \fBCPU \fRmay cache the data it fetches and reuse it until another store
 136 occurs. The default behavior is to fetch new data on every load. Setting this
 137 bit also implies merging and re-ordering.
 138 .RE
 139 
 140 .sp
 141 .ne 2
 142 .na
 143 \fB\fBWIN_ACC_STORECACHING_OK\fR \fR
 144 .ad
 145 .RS 28n
 146 The \fBCPU \fRmay keep the data in the cache and push it to the device (perhaps
 147 with other data) at a later time. The  default behavior is to push the data
 148 right away. Setting this bit also implies load caching, merging, and
 149 re-ordering.
 150 .RE
 151 
 152 .sp
 153 .LP
 154 These values are advisory, not mandatory. For example, data can be ordered
 155 without being merged or cached, even though a driver requests unordered, merged
 156 and cached together.
 157 .SH RETURN VALUES
 158 .sp
 159 .ne 2
 160 .na
 161 \fB\fBCS_SUCCESS\fR \fR
 162 .ad
 163 .RS 28n
 164 Successful operation.
 165 .RE
 166 
 167 .sp
 168 .ne 2
 169 .na
 170 \fB\fBCS_FAILURE\fR \fR
 171 .ad
 172 .RS 28n
 173 Error in \fIflags\fR argument or handle could not be duplicated for some
 174 reason.
 175 .RE
 176 
 177 .sp
 178 .ne 2
 179 .na
 180 \fB\fBCS_UNSUPPORTED_FUNCTION\fR \fR
 181 .ad
 182 .RS 28n
 183 No \fBPCMCIA \fRhardware installed.
 184 .RE
 185 
 186 .SH CONTEXT
 187 .sp
 188 .LP
 189 This function may be called from user or kernel context.
 190 .SH SEE ALSO
 191 .sp
 192 .LP
 193 \fBcsx_Get8\fR(9F), \fBcsx_GetMappedAddr\fR(9F), \fBcsx_Put8\fR(9F),
 194 \fBcsx_RepGet8\fR(9F), \fBcsx_RepPut8\fR(9F), \fBcsx_RequestIO\fR(9F),
 195 \fBcsx_RequestWindow\fR(9F)
 196 .sp
 197 .LP
 198 \fIPC Card 95 Standard, PCMCIA/JEIDA\fR