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_REQUESTIO 9F "Jul 19, 1996"
   7 .SH NAME
   8 csx_RequestIO, csx_ReleaseIO \- request or release I/O resources for the client
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/pccard.h>
  13 
  14 
  15 
  16 \fBint32_t\fR \fBcsx_RequestIO\fR(\fBclient_handle_t\fR \fIch\fR, \fBio_req_t *\fR\fIir\fR);
  17 .fi
  18 
  19 .LP
  20 .nf
  21 \fBint32_t\fR \fBcsx_ReleaseIO\fR(\fBclient_handle_t\fR \fIch\fR, \fBio_req_t *\fR\fIir\fR);
  22 .fi
  23 
  24 .SH INTERFACE LEVEL
  25 .sp
  26 .LP
  27 Solaris \fBDDI \fRSpecific (Solaris \fBDDI\fR)
  28 .SH PARAMETERS
  29 .sp
  30 .ne 2
  31 .na
  32 \fB\fIch\fR\fR
  33 .ad
  34 .RS 6n
  35 Client handle returned from \fBcsx_RegisterClient\fR(9F).
  36 .RE
  37 
  38 .sp
  39 .ne 2
  40 .na
  41 \fB\fIir\fR\fR
  42 .ad
  43 .RS 6n
  44 Pointer to an \fBio_req_t\fR structure.
  45 .RE
  46 
  47 .SH DESCRIPTION
  48 .sp
  49 .LP
  50 The functions \fBcsx_RequestIO()\fR and \fBcsx_ReleaseIO()\fR request or
  51 release, respectively, \fBI/O\fR resources for the client.
  52 .sp
  53 .LP
  54 If a client requires \fBI/O\fR resources, \fBcsx_RequestIO()\fR must be called
  55 to request \fBI/O\fR resources from Card Services; then
  56 \fBcsx_RequestConfiguration\fR(9F) must be used to establish the configuration.
  57 \fBcsx_RequestIO()\fR can be called multiple times until a successful set of
  58 \fBI/O\fR resources is found. \fBcsx_RequestConfiguration\fR(9F) only uses the
  59 last configuration specified.
  60 .sp
  61 .LP
  62 \fBcsx_RequestIO()\fR fails if it has already been called without a
  63 corresponding \fBcsx_ReleaseIO()\fR.
  64 .sp
  65 .LP
  66 \fBcsx_ReleaseIO()\fR releases previously requested \fBI/O\fR resources. The
  67 Card Services window resource list is adjusted by this function. Depending on
  68 the adapter hardware, the \fBI/O\fR window might also be disabled.
  69 .SH STRUCTURE MEMBERS
  70 .sp
  71 .LP
  72 The structure members of \fBio_req_t\fR are:
  73 .sp
  74 .in +2
  75 .nf
  76 uint32_t      Socket;            /* socket number*/
  77 
  78 uint32_t      Baseport1.base;    /* IO range base port address */
  79 acc_handle_t  Baseport1.handle;  /* IO range base address
  80                                   /*   or port num */
  81 uint32_t      NumPorts1;         /* first IO range number contiguous
  82                                   /*   ports */
  83 uint32_t      Attributes1;       /* first IO range attributes */
  84 
  85 uint32_t      Baseport2.base;    /* IO range base port address */
  86 acc_handle_t  Baseport2.handle;  /* IO range base address or port num */
  87 uint32_t      NumPorts2;         /* second IO range number contiguous
  88                                   /*   ports */
  89 uint32_t      Attributes2;       /* second IO range attributes */
  90 
  91 uint32_t      IOAddrLines;       /* number of IO address lines decoded */
  92 .fi
  93 .in -2
  94 
  95 .sp
  96 .LP
  97 The fields are defined as follows:
  98 .sp
  99 .ne 2
 100 .na
 101 \fB\fBSocket\fR\fR
 102 .ad
 103 .RS 20n
 104 Not used in Solaris, but for portability with other Card Services
 105 implementations, it should be set to the logical socket number.
 106 .RE
 107 
 108 .sp
 109 .ne 2
 110 .na
 111 \fB\fBBasePort1.base\fR\fR
 112 .ad
 113 .br
 114 .na
 115 \fB\fBBasePort1.handle\fR\fR
 116 .ad
 117 .br
 118 .na
 119 \fB\fBBasePort2.base\fR\fR
 120 .ad
 121 .br
 122 .na
 123 \fB\fBBasePort2.handle\fR\fR
 124 .ad
 125 .RS 20n
 126 Two \fBI/O\fR address ranges can be requested by \fBcsx_RequestIO()\fR. Each
 127 \fBI/O\fR address range is specified by the \fBBasePort\fR, \fBNumPorts\fR, and
 128 \fBAttributes\fR fields. If only a single \fBI/O\fR range is being requested,
 129 the \fBNumPorts2\fR field must be reset to \fB0\fR.
 130 .sp
 131 When calling \fBcsx_RequestIO()\fR, the \fBBasePort.base\fR field specifies the
 132 first port address requested. Upon successful return from
 133 \fBcsx_RequestIO()\fR, the \fBBasePort.handle\fR field contains an access
 134 handle, corresponding to the first byte of the allocated \fBI/O\fR window,
 135 which the client must use when accessing the \fBPC\fR Card's \fBI/O\fR space
 136 via the common access functions. A client \fImust not\fR make any assumptions
 137 as to the format of the returned \fBBasePort.handle\fR field value.
 138 .sp
 139 If the \fBBasePort.base\fR field is set to \fB0\fR, Card Services returns an
 140 \fBI/O\fR resource based on the available \fBI/O\fR resources and the number of
 141 contiguous ports requested. When \fBBasePort.base\fR is \fB0\fR, Card Services
 142 aligns the returned resource in the host system's \fBI/O\fR address space on a
 143 boundary that is a multiple of the number of contiguous ports requested,
 144 rounded up to the nearest power of two. For example, if a client requests two
 145 \fBI/O\fR ports, the resource returned will be a multiple of two. If a client
 146 requests five contiguous \fBI/O\fR ports, the resource returned will be a
 147 multiple of eight.
 148 .sp
 149 If multiple ranges are being requested, at least one of the \fBBasePort.base\fR
 150 fields must be non-zero.
 151 .RE
 152 
 153 .sp
 154 .ne 2
 155 .na
 156 \fB\fBNumPorts\fR\fR
 157 .ad
 158 .RS 20n
 159 This field is the number of contiguous ports being requested.
 160 .RE
 161 
 162 .sp
 163 .ne 2
 164 .na
 165 \fB\fBAttributes\fR\fR
 166 .ad
 167 .RS 20n
 168 This field is bit-mapped. The following bits are defined:
 169 .sp
 170 .ne 2
 171 .na
 172 \fB\fBIO_DATA_WIDTH_8\fR\fR
 173 .ad
 174 .RS 27n
 175 \fBI/O\fR resource uses 8-bit data path.
 176 .RE
 177 
 178 .sp
 179 .ne 2
 180 .na
 181 \fB\fBIO_DATA_WIDTH_16\fR\fR
 182 .ad
 183 .RS 27n
 184 \fBI/O\fR resource uses 16-bit data path.
 185 .RE
 186 
 187 .sp
 188 .ne 2
 189 .na
 190 \fB\fBWIN_ACC_NEVER_SWAP\fR\fR
 191 .ad
 192 .RS 27n
 193 Host endian byte ordering.
 194 .RE
 195 
 196 .sp
 197 .ne 2
 198 .na
 199 \fB\fBWIN_ACC_BIG_ENDIAN\fR\fR
 200 .ad
 201 .RS 27n
 202 Big endian byte ordering
 203 .RE
 204 
 205 .sp
 206 .ne 2
 207 .na
 208 \fB\fBWIN_ACC_LITTLE_ENDIAN\fR\fR
 209 .ad
 210 .RS 27n
 211 Little endian byte ordering.
 212 .RE
 213 
 214 .sp
 215 .ne 2
 216 .na
 217 \fB\fBWIN_ACC_STRICT_ORDER\fR\fR
 218 .ad
 219 .RS 27n
 220 Program ordering references.
 221 .RE
 222 
 223 .sp
 224 .ne 2
 225 .na
 226 \fB\fBWIN_ACC_UNORDERED_OK\fR\fR
 227 .ad
 228 .RS 27n
 229 May re-order references.
 230 .RE
 231 
 232 .sp
 233 .ne 2
 234 .na
 235 \fB\fBWIN_ACC_MERGING_OK\fR\fR
 236 .ad
 237 .RS 27n
 238 Merge stores to consecutive locations.
 239 .RE
 240 
 241 .sp
 242 .ne 2
 243 .na
 244 \fB\fBWIN_ACC_LOADCACHING_OK\fR\fR
 245 .ad
 246 .RS 27n
 247 May cache load operations.
 248 .RE
 249 
 250 .sp
 251 .ne 2
 252 .na
 253 \fB\fBWIN_ACC_STORECACHING_OK\fR\fR
 254 .ad
 255 .RS 27n
 256 May cache store operations.
 257 .RE
 258 
 259 For some combinations of host system busses and adapter hardware, the width of
 260 an \fBI/O\fR resource can not be set via \fBRequestIO()\fR; on those systems,
 261 the host bus cycle access type determines the \fBI/O\fR resource data path
 262 width on a per-cycle basis.
 263 .sp
 264 \fBWIN_ACC_BIG_ENDIAN\fR and \fBWIN_ACC_LITTLE\fR \fBENDIAN\fR describe the
 265 endian characteristics of the device as big endian or little endian,
 266 respectively. Even though most of the devices will have the same endian
 267 characteristics as their busses, there are examples of devices with an
 268 \fBI/O\fR processor that has opposite endian characteristics of the busses.
 269 When \fBWIN_ACC_BIG_ENDIAN\fR or \fBWIN_ACC_LITTLE\fR \fBENDIAN\fR is set, byte
 270 swapping will automatically be performed by the system if the host machine and
 271 the device data formats have opposite endian characteristics. The
 272 implementation may take advantage of hardware platform byte swapping
 273 capabilities.
 274 .sp
 275 When \fBWIN_ACC_NEVER_SWAP\fR is specified, byte swapping will not be invoked
 276 in the data access functions. The ability to specify the order in which the
 277 \fBCPU\fR will reference data is provided by the following \fBAttributes\fR
 278 bits. Only one of the following bits may be specified:
 279 .sp
 280 .ne 2
 281 .na
 282 \fB\fBWIN_ACC_STRICT_ORDER\fR\fR
 283 .ad
 284 .sp .6
 285 .RS 4n
 286 The data references must be issued by a \fBCPU\fR in program order. Strict
 287 ordering is the default behavior.
 288 .RE
 289 
 290 .sp
 291 .ne 2
 292 .na
 293 \fB\fBWIN_ACC_UNORDERED_OK\fR\fR
 294 .ad
 295 .sp .6
 296 .RS 4n
 297 The \fBCPU\fR may re-order the data references. This includes all kinds of
 298 re-ordering (that is, a load followed by a store may be replaced by a store
 299 followed by a load).
 300 .RE
 301 
 302 .sp
 303 .ne 2
 304 .na
 305 \fB\fBWIN_ACC_MERGING_OK\fR\fR
 306 .ad
 307 .sp .6
 308 .RS 4n
 309 The \fBCPU\fR may merge individual stores to consecutive locations. For
 310 example, the \fBCPU\fR may turn two consecutive byte stores into one halfword
 311 store. It may also batch individual loads. For example, the \fBCPU\fR may turn
 312 two consecutive byte loads into one halfword load. \fBIO_MERGING_OK_ACC\fR also
 313 implies re-ordering.
 314 .RE
 315 
 316 .sp
 317 .ne 2
 318 .na
 319 \fB\fBWIN_ACC_LOADCACHING_OK\fR\fR
 320 .ad
 321 .sp .6
 322 .RS 4n
 323 The \fBCPU\fR may cache the data it fetches and reuse it until another store
 324 occurs. The default behavior is to fetch new data on every load.
 325 \fBWIN_ACC_LOADCACHING_OK\fR also implies merging and re-ordering.
 326 .RE
 327 
 328 .sp
 329 .ne 2
 330 .na
 331 \fB\fBWIN_ACC_STORECACHING_OK\fR\fR
 332 .ad
 333 .sp .6
 334 .RS 4n
 335 The \fBCPU\fR may keep the data in the cache and push it to the device (perhaps
 336 with other data) at a later time. The default behavior is to push the data
 337 right away. \fBWIN_ACC_STORECACHING_OK\fR also implies load caching, merging,
 338 and re-ordering.
 339 .RE
 340 
 341 These values are advisory, not mandatory. For example, data can be ordered
 342 without being merged or cached, even though a driver requests unordered, merged
 343 and cached together. All other bits in the \fBAttributes\fR field must be set
 344 to \fB0\fR.
 345 .RE
 346 
 347 .sp
 348 .ne 2
 349 .na
 350 \fB\fBIOAddrLines\fR\fR
 351 .ad
 352 .RS 20n
 353 This field is the number of \fBI/O\fR address lines decoded by the \fBPC\fR
 354 Card in the specified socket.
 355 .RE
 356 
 357 .sp
 358 .LP
 359 On some systems, multiple calls to \fBcsx_RequestIO()\fR with different
 360 \fBBasePort\fR, \fBNumPorts\fR, and/or \fBIOAddrLines\fR values will have to be
 361 made to find an acceptable combination of parameters that can be used by Card
 362 Services to allocate \fBI/O\fR resources for the client. (See \fBNOTES\fR).
 363 .SH RETURN VALUES
 364 .sp
 365 .ne 2
 366 .na
 367 \fB\fBCS_SUCCESS\fR\fR
 368 .ad
 369 .RS 27n
 370 Successful operation.
 371 .RE
 372 
 373 .sp
 374 .ne 2
 375 .na
 376 \fB\fBCS_BAD_ATTRIBUTE\fR\fR
 377 .ad
 378 .RS 27n
 379 Invalid \fBAttributes\fR specified.
 380 .RE
 381 
 382 .sp
 383 .ne 2
 384 .na
 385 \fB\fBCS_BAD_BASE\fR\fR
 386 .ad
 387 .RS 27n
 388 \fBBasePort\fR value is invalid.
 389 .RE
 390 
 391 .sp
 392 .ne 2
 393 .na
 394 \fB\fBCS_BAD_HANDLE\fR\fR
 395 .ad
 396 .RS 27n
 397 Client handle is invalid.
 398 .RE
 399 
 400 .sp
 401 .ne 2
 402 .na
 403 \fB\fBCS_CONFIGURATION_LOCKED\fR\fR
 404 .ad
 405 .RS 27n
 406 \fBcsx_RequestConfiguration\fR(9F) has already been done.
 407 .RE
 408 
 409 .sp
 410 .ne 2
 411 .na
 412 \fB\fBCS_IN_USE\fR\fR
 413 .ad
 414 .RS 27n
 415 \fBcsx_RequestIO()\fR has already been done without a corresponding
 416 \fBcsx_ReleaseIO()\fR.
 417 .RE
 418 
 419 .sp
 420 .ne 2
 421 .na
 422 \fB\fBCS_NO_CARD\fR\fR
 423 .ad
 424 .RS 27n
 425 No \fBPC\fR Card in socket.
 426 .RE
 427 
 428 .sp
 429 .ne 2
 430 .na
 431 \fB\fBCS_BAD_WINDOW\fR\fR
 432 .ad
 433 .RS 27n
 434 Unable to allocate \fBI/O\fR resources.
 435 .RE
 436 
 437 .sp
 438 .ne 2
 439 .na
 440 \fB\fBCS_OUT_OF_RESOURCE\fR\fR
 441 .ad
 442 .RS 27n
 443 Unable to allocate \fBI/O\fR resources.
 444 .RE
 445 
 446 .sp
 447 .ne 2
 448 .na
 449 \fB\fBCS_UNSUPPORTED_FUNCTION\fR\fR
 450 .ad
 451 .RS 27n
 452 No \fBPCMCIA\fR hardware installed.
 453 .RE
 454 
 455 .SH CONTEXT
 456 .sp
 457 .LP
 458 These functions may be called from user or kernel context.
 459 .SH SEE ALSO
 460 .sp
 461 .LP
 462 \fBcsx_RegisterClient\fR(9F), \fBcsx_RequestConfiguration\fR(9F)
 463 .sp
 464 .LP
 465 \fIPC Card 95 Standard\fR, PCMCIA/JEIDA
 466 .SH NOTES
 467 .sp
 468 .LP
 469 It is important for clients to try to use the minimum amount of \fBI/O\fR
 470 resources necessary. One way to do this is for the client to parse the
 471 \fBCIS\fR of the \fBPC\fR Card and call \fBcsx_RequestIO()\fR first with any
 472 \fBIOAddrLines\fR values that are \fB0\fR or that specify a minimum number of
 473 address lines necessary to decode the \fBI/O\fR space on the \fBPC\fR Card.
 474 Also, if no convenient minimum number of address lines can be used to decode
 475 the \fBI/O\fR space on the \fBPC\fR Card, it is important to try to avoid
 476 system conflicts with well-known architectural hardware features.