1 '\" te 2 .\" Copyright (c) 1999, 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_REQUESTWINDOW 9F "Jul 19, 1996" 7 .SH NAME 8 csx_RequestWindow, csx_ReleaseWindow \- request or release window resources 9 .SH SYNOPSIS 10 .LP 11 .nf 12 #include <sys/pccard.h> 13 14 15 16 \fBint32_t\fR \fBcsx_RequestWindow\fR(\fBclient_handle_t\fR \fIch\fR, \fBwindow_handle_t *\fR\fIwh\fR, 17 \fBwin_req_t *\fR\fIwr\fR); 18 .fi 19 20 .LP 21 .nf 22 \fBint32_t\fR \fBcsx_ReleaseWindow\fR(\fBwindow_handle_t\fR \fIwh\fR); 23 .fi 24 25 .SH INTERFACE LEVEL 26 .sp 27 .LP 28 Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR 29 .SH PARAMETERS 30 .sp 31 .ne 2 32 .na 33 \fB\fIch\fR\fR 34 .ad 35 .RS 6n 36 Client handle returned from \fBcsx_RegisterClient\fR(9F). 37 .RE 38 39 .sp 40 .ne 2 41 .na 42 \fB\fIwh\fR\fR 43 .ad 44 .RS 6n 45 Pointer to a \fBwindow_handle_t\fR structure. 46 .RE 47 48 .sp 49 .ne 2 50 .na 51 \fB\fIwr\fR\fR 52 .ad 53 .RS 6n 54 Pointer to a \fBwin_req_t\fR structure. 55 .RE 56 57 .SH DESCRIPTION 58 .sp 59 .LP 60 The function \fBcsx_RequestWindow()\fR requests a block of system address space 61 be assigned to a \fBPC \fRCard in a socket. 62 .sp 63 .LP 64 The function \fBcsx_ReleaseWindow()\fR releases window resources which were 65 obtained by a call to \fBcsx_RequestWindow()\fR. No adapter or socket hardware 66 is modified by this function. 67 .sp 68 .LP 69 The \fBcsx_MapMemPage\fR(9F) and \fBcsx_ModifyWindow\fR(9F) functions use the 70 window handle returned by \fBcsx_RequestWindow()\fR. This window handle must be 71 freed by calling \fBcsx_ReleaseWindow()\fR when the client is done using this 72 window. 73 .sp 74 .LP 75 The \fBPC\fR Card Attribute or Common Memory offset for this window is set by 76 \fBcsx_MapMemPage\fR(9F). 77 .SH STRUCTURE MEMBERS 78 .sp 79 .LP 80 The structure members of \fBwin_req_t\fR are: 81 .sp 82 .in +2 83 .nf 84 uint32_t Socket; /* socket number */ 85 uint32_t Attributes; /* window flags */ 86 uint32_t Base.base; /* requested window */ 87 /* base address */ 88 acc_handle_t Base.handle; /* returned handle for 89 /* base of window */ 90 uint32_t Size; /* window size requested */ 91 /* or granted */ 92 uint32_t win_params.AccessSpeed; /* window access speed */ 93 uint32_t win_params.IOAddrLines; /* IO address lines decoded */ 94 uint32_t ReqOffset; /* required window offest */ 95 .fi 96 .in -2 97 98 .sp 99 .LP 100 The fields are defined as follows: 101 .sp 102 .ne 2 103 .na 104 \fB\fBSocket\fR\fR 105 .ad 106 .RS 26n 107 Not used in Solaris, but for portability with other Card Services 108 implementations, it should be set to the logical socket number. 109 .RE 110 111 .sp 112 .ne 2 113 .na 114 \fB\fBAttributes\fR\fR 115 .ad 116 .RS 26n 117 This field is bit-mapped and is defined as follows: 118 .sp 119 .ne 2 120 .na 121 \fB\fBWIN_MEMORY_TYPE_IO\fR\fR 122 .ad 123 .sp .6 124 .RS 4n 125 Points to I/O space. 126 .RE 127 128 .sp 129 .ne 2 130 .na 131 \fB\fBWIN_MEMORY_TYPE_CM\fR\fR 132 .ad 133 .sp .6 134 .RS 4n 135 Points to common memory space. 136 .RE 137 138 .sp 139 .ne 2 140 .na 141 \fB\fBWIN_MEMORY_TYPE_AM\fR\fR 142 .ad 143 .sp .6 144 .RS 4n 145 These bits select which type of window is being requested. One of these bits 146 must be set. 147 .RE 148 149 .sp 150 .ne 2 151 .na 152 \fB\fBWIN_ENABLE\fR\fR 153 .ad 154 .sp .6 155 .RS 4n 156 The client must set this bit to enable the window. 157 .RE 158 159 .sp 160 .ne 2 161 .na 162 \fB\fBWIN_ACC_BIG_ENDIAN\fR\fR 163 .ad 164 .sp .6 165 .RS 4n 166 Describes device as big-endian. 167 .RE 168 169 .sp 170 .ne 2 171 .na 172 \fB\fBWIN_ACC_LITTLE_ENDIAN\fR\fR 173 .ad 174 .sp .6 175 .RS 4n 176 These bits describe the endian characteristics of the device as big endian or 177 little endian, respectively. Even though most of the devices will have the same 178 endian characteristics as their busses, there are examples of devices with an 179 \fBI/O \fRprocessor that has opposite endian characteristics of the busses. 180 When either of these bits are set, byte swapping will automatically be 181 performed by the system if the host machine and the device data formats have 182 opposite endian characteristics. The implementation may take advantage of 183 hardware platform byte swapping capabilities. 184 .RE 185 186 .sp 187 .ne 2 188 .na 189 \fB\fBWIN_ACC_NEVER_SWAP\fR\fR 190 .ad 191 .sp .6 192 .RS 4n 193 When this is specified, byte swapping will not be invoked in the data access 194 functions. 195 .RE 196 197 The ability to specify the order in which the \fBCPU\fR will reference data is 198 provided by the following \fBAttributes\fR bits, only one of which may be 199 specified: 200 .sp 201 .ne 2 202 .na 203 \fB\fBWIN_ACC_STRICT_ORDER\fR\fR 204 .ad 205 .sp .6 206 .RS 4n 207 The data references must be issued by a \fBCPU \fR in program order. Strict 208 ordering is the default behavior. 209 .RE 210 211 .sp 212 .ne 2 213 .na 214 \fB\fBWIN_ACC_UNORDERED_OK\fR\fR 215 .ad 216 .sp .6 217 .RS 4n 218 The \fBCPU\fR may re-order the data references. This includes all kinds of 219 re-ordering (that is, a load followed by a store may be replaced by a store 220 followed by a load). 221 .RE 222 223 .sp 224 .ne 2 225 .na 226 \fB\fBWIN_ACC_MERGING_OK\fR\fR 227 .ad 228 .sp .6 229 .RS 4n 230 The \fBCPU \fRmay merge individual stores to consecutive locations. For 231 example, the \fBCPU \fRmay turn two consecutive byte stores into one halfword 232 store. It may also batch individual loads. For example, the \fBCPU \fRmay turn 233 two consecutive byte loads into one halfword load. This bit also implies 234 re-ordering. 235 .RE 236 237 .sp 238 .ne 2 239 .na 240 \fB\fBWIN_ACC_LOADCACHING_OK\fR\fR 241 .ad 242 .sp .6 243 .RS 4n 244 The \fBCPU \fRmay cache the data it fetches and reuse it until another store 245 occurs. The default behavior is to fetch new data on every load. This bit also 246 implies merging and re-ordering. 247 .RE 248 249 .sp 250 .ne 2 251 .na 252 \fB\fBWIN_ACC_STORECACHING_OK\fR\fR 253 .ad 254 .sp .6 255 .RS 4n 256 The \fBCPU \fRmay keep the data in the cache and push it to the device (perhaps 257 with other data) at a later time. The default behavior is to push the data 258 right away. This bit also implies load caching, merging, and re-ordering. 259 .RE 260 261 These values are advisory, not mandatory. For example, data can be ordered 262 without being merged or cached, even though a driver requests unordered, merged 263 and cached together. 264 .sp 265 All other bits in the \fBAttributes\fR field must be set to \fB0\fR. 266 .sp 267 On successful return from \fBcsx_RequestWindow()\fR, \fBWIN_OFFSET_SIZE\fR is 268 set in the \fBAttributes\fR field when the client must specify card offsets to 269 \fBcsx_MapMemPage\fR(9F) that are a multiple of the window size. 270 .RE 271 272 .sp 273 .ne 2 274 .na 275 \fB\fBBase.base\fR\fR 276 .ad 277 .RS 26n 278 This field must be set to \fB0\fR on calling \fBcsx_RequestWindow()\fR. 279 .RE 280 281 .sp 282 .ne 2 283 .na 284 \fB\fBBase.handle\fR\fR 285 .ad 286 .RS 26n 287 On successful return from \fBcsx_RequestWindow()\fR, the \fBBase.handle\fR 288 field contains an access handle corresponding to the first byte of the 289 allocated memory window which the client must use when accessing the \fBPC 290 \fRCard's memory space via the common access functions. A client must \fBnot\fR 291 make any assumptions as to the format of the returned \fBBase.handle\fR field 292 value. 293 .RE 294 295 .sp 296 .ne 2 297 .na 298 \fB\fBSize\fR\fR 299 .ad 300 .RS 26n 301 On calling \fBcsx_RequestWindow()\fR, the \fBSize\fR field is the size in bytes 302 of the memory window requested. \fBSize\fR may be zero to indicate that Card 303 Services should provide the smallest sized window available. On successful 304 return from \fBcsx_RequestWindow()\fR, the \fBSize\fR field contains the actual 305 size of the window allocated. 306 .RE 307 308 .sp 309 .ne 2 310 .na 311 \fB\fBwin_params.AccessSpeed\fR\fR 312 .ad 313 .RS 26n 314 This field specifies the access speed of the window if the client is requesting 315 a memory window. The \fBAccessSpeed\fR field bit definitions use the format of 316 the extended speed byte of the Device \fBID \fRtuple. If the mantissa is 317 \fB0\fR (noted as reserved in the \fBPC Card 95 Standard\fR), the lower bits 318 are a binary code representing a speed from the following table: 319 .RE 320 321 .sp 322 323 .sp 324 .TS 325 box; 326 l | l 327 l | l . 328 \fBCode\fR \fBSpeed\fR 329 _ 330 0 (Reserved - do not use). 331 _ 332 1 250 nsec 333 _ 334 2 200 nsec 335 _ 336 3 150 nsec 337 _ 338 4 100 nse 339 _ 340 5-7 (Reserved\(emdo not use.) 341 .TE 342 343 .sp 344 .LP 345 To request a window that supports the \fBWAIT\fR signal, \fBOR-in\fR the 346 \fBWIN_USE_WAIT\fR bit to the \fBAccessSpeed\fR value before calling this 347 function. 348 .sp 349 .LP 350 It is recommended that clients use the \fBcsx_ConvertSpeed\fR(9F) function to 351 generate the appropriate \fBAccessSpeed\fR values rather than manually 352 perturbing the \fBAccessSpeed\fR field. 353 .sp 354 .ne 2 355 .na 356 \fB\fBwin_params.IOAddrLines\fR\fR 357 .ad 358 .RS 26n 359 If the client is requesting an \fBI/O \fRwindow, the \fBIOAddrLines\fR field is 360 the number of \fBI/O \fRaddress lines decoded by the \fBPC \fRCard in the 361 specified socket. Access to the \fBI/O \fRwindow is not enabled until 362 \fBcsx_RequestConfiguration\fR(9F) has been invoked successfully. 363 .RE 364 365 .sp 366 .ne 2 367 .na 368 \fB\fBReqOffset\fR\fR 369 .ad 370 .RS 26n 371 This field is a Solaris-specific extension that can be used by clients to 372 generate optimum window offsets passed to \fBcsx_MapMemPage\fR(9F). 373 .RE 374 375 .SH RETURN VALUES 376 .sp 377 .ne 2 378 .na 379 \fB\fBCS_SUCCESS\fR\fR 380 .ad 381 .RS 27n 382 Successful operation. 383 .RE 384 385 .sp 386 .ne 2 387 .na 388 \fB\fBCS_BAD_ATTRIBUTE\fR\fR 389 .ad 390 .RS 27n 391 \fBAttributes\fR are invalid. 392 .RE 393 394 .sp 395 .ne 2 396 .na 397 \fB\fBCS_BAD_SPEED\fR\fR 398 .ad 399 .RS 27n 400 Speed is invalid. 401 .RE 402 403 .sp 404 .ne 2 405 .na 406 \fB\fBCS_BAD_HANDLE\fR\fR 407 .ad 408 .RS 27n 409 Client handle is invalid. 410 .RE 411 412 .sp 413 .ne 2 414 .na 415 \fB\fBCS_BAD_SIZE\fR\fR 416 .ad 417 .RS 27n 418 Window size is invalid. 419 .RE 420 421 .sp 422 .ne 2 423 .na 424 \fB\fBCS_NO_CARD\fR\fR 425 .ad 426 .RS 27n 427 No \fBPC \fRCard in socket. 428 .RE 429 430 .sp 431 .ne 2 432 .na 433 \fB\fBCS_OUT_OF_RESOURCE\fR\fR 434 .ad 435 .RS 27n 436 Unable to allocate window. 437 .RE 438 439 .sp 440 .ne 2 441 .na 442 \fB\fBCS_UNSUPPORTED_FUNCTION\fR\fR 443 .ad 444 .RS 27n 445 No \fBPCMCIA \fRhardware installed. 446 .RE 447 448 .SH CONTEXT 449 .sp 450 .LP 451 These functions may be called from user or kernel context. 452 .SH SEE ALSO 453 .sp 454 .LP 455 \fBcsx_ConvertSpeed\fR(9F), \fBcsx_MapMemPage\fR(9F), 456 \fBcsx_ModifyWindow\fR(9F), \fBcsx_RegisterClient\fR(9F), 457 \fBcsx_RequestConfiguration\fR(9F) 458 .sp 459 .LP 460 \fIPC\fR \fICard\fR \fI95\fR \fIStandard,\fR PCMCIA/JEIDA