usr/src/man/man9f/csx_RequestWindow.9f

   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