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.