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_REQUESTCONFIGURATION 9F "Jul 19, 1996"
   7 .SH NAME
   8 csx_RequestConfiguration \- configure the PC Card and socket
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/pccard.h>
  13 
  14 
  15 
  16 \fBint32_t\fR \fBcsx_RequestConfiguration\fR(\fBclient_handle_t\fR \fIch\fR, \fBconfig_req_t *\fR\fIcr\fR);
  17 .fi
  18 
  19 .SH INTERFACE LEVEL
  20 .sp
  21 .LP
  22 Solaris \fBDDI\fR Specific (Solaris \fBDDI\fR)
  23 .SH PARAMETERS
  24 .sp
  25 .ne 2
  26 .na
  27 \fB\fIch\fR\fR
  28 .ad
  29 .RS 6n
  30 Client handle returned from \fBcsx_RegisterClient\fR(9F).
  31 .RE
  32 
  33 .sp
  34 .ne 2
  35 .na
  36 \fB\fIcr\fR\fR
  37 .ad
  38 .RS 6n
  39 Pointer to a \fBconfig_req_t\fR structure.
  40 .RE
  41 
  42 .SH DESCRIPTION
  43 .sp
  44 .LP
  45 This function configures the \fBPC\fR Card and socket. It must be used by
  46 clients that require \fBI/O\fR or \fBIRQ\fR resources for their \fBPC\fR Card.
  47 .sp
  48 .LP
  49 \fBcsx_RequestIO\fR(9F) and \fBcsx_RequestIRQ\fR(9F) must be used before
  50 calling this function to specify the \fBI/O\fR and \fBIRQ\fR requirements for
  51 the \fBPC\fR Card and socket if necessary. \fBcsx_RequestConfiguration()\fR
  52 establishes the configuration in the socket adapter and \fBPC\fR Card, and it
  53 programs the Base and Limit registers of multi-function \fBPC\fR Cards if these
  54 registers exist. The values programmed into these registers depend on the
  55 \fBIO\fR requirements of this configuration.
  56 .SH STRUCTURE MEMBERS
  57 .sp
  58 .LP
  59 The structure members of \fBconfig_req_t\fR are:
  60 .sp
  61 .in +2
  62 .nf
  63 uint32_t     Socket;          /* socket number */
  64 uint32_t     Attributes;      /* configuration attributes */
  65 uint32_t     Vcc;             /* Vcc value */
  66 uint32_t     Vpp1;            /* Vpp1 value */
  67 uint32_t     Vpp2;            /* Vpp2 value */
  68 uint32_t     IntType;         /* socket interface type - mem or IO */
  69 uint32_t     ConfigBase;      /* offset from start of AM space */
  70 uint32_t     Status;          /* value to write to STATUS register */
  71 uint32_t     Pin;             /* value to write to PRR */
  72 uint32_t     Copy;            /* value to write to COPY register */
  73 uint32_t     ConfigIndex;     /* value to write to COR */
  74 uint32_t     Present;         /* which config registers present */
  75 uint32_t     ExtendedStatus;  /* value to write to EXSTAT register */
  76 .fi
  77 .in -2
  78 
  79 .sp
  80 .LP
  81 The fields are defined as follows:
  82 .sp
  83 .ne 2
  84 .na
  85 \fB\fBSocket\fR\fR
  86 .ad
  87 .sp .6
  88 .RS 4n
  89 Not used in Solaris, but for portability with other Card Services
  90 implementations, it should be set to the logical socket number.
  91 .RE
  92 
  93 .sp
  94 .ne 2
  95 .na
  96 \fB\fBAttributes\fR\fR
  97 .ad
  98 .sp .6
  99 .RS 4n
 100 This field is bit-mapped. It indicates whether the client wishes the \fBIRQ\fR
 101 resources to be enabled and whether Card Services should ignore the \fBVS\fR
 102 bits on the socket interface. The following bits are defined:
 103 .sp
 104 .ne 2
 105 .na
 106 \fB\fBCONF_ENABLE_IRQ_STEERING\fR\fR
 107 .ad
 108 .sp .6
 109 .RS 4n
 110 Enable IRQ Steering. Set to connect the \fBPC\fR Card \fBIREQ\fR line to a
 111 system interrupt previously selected by a call to \fBcsx_RequestIRQ\fR(9F). If
 112 \fBCONF_ENABLE_IRQ_STEERING\fR is set, once \fBcsx_RequestConfiguration()\fR
 113 has successfully returned, the client may start receiving \fBIRQ\fR callbacks
 114 at the \fBIRQ\fR callback handler established in the call to
 115 \fBcsx_RequestIRQ\fR(9F).
 116 .RE
 117 
 118 .sp
 119 .ne 2
 120 .na
 121 \fB\fBCONF_VSOVERRIDE\fR\fR
 122 .ad
 123 .sp .6
 124 .RS 4n
 125 Override VS pins. After card insertion and prior to the first successful
 126 \fBcsx_RequestConfiguration()\fR, the voltage levels applied to the card shall
 127 be those indicated by the card's physical key and/or the VS[2:1] voltage sense
 128 pins. For Low Voltage capable host systems (hosts which are capable of \fBVS\fR
 129 pin decoding), if a client desires to apply a voltage not indicated by the
 130 \fBVS\fR pin decoding, then \fBCONF_VSOVERRIDE\fR must be set in the
 131 \fBAttributes\fR field; otherwise, \fBCS_BAD_VCC\fR shall be returned.
 132 .RE
 133 
 134 .RE
 135 
 136 .sp
 137 .ne 2
 138 .na
 139 \fB\fBVcc, Vpp1, Vpp2\fR\fR
 140 .ad
 141 .sp .6
 142 .RS 4n
 143 These fields all represent voltages expressed in tenths of a volt. Values from
 144 zero (\fB0\fR) to \fB25.5\fR volts may be set. To be valid, the exact voltage
 145 must be available from the system.  \fBPC\fR Cards indicate multiple \fBVcc\fR
 146 voltage capability in their \fBCIS\fR via the \fBCISTPL_CFTABLE_ENTRY\fR tuple.
 147 After card insertion, Card Services processes the \fBCIS\fR, and when multiple
 148 \fBVcc\fR voltage capability is indicated, Card Services will allow the client
 149 to apply \fBVcc\fR voltage levels which are contrary to the \fBVS\fR pin
 150 decoding without requiring the client to set \fBCONF_VSOVERRIDE.\fR
 151 .RE
 152 
 153 .sp
 154 .ne 2
 155 .na
 156 \fB\fBIntType\fR\fR
 157 .ad
 158 .sp .6
 159 .RS 4n
 160 This field is bit-mapped. It indicates how the socket should be configured. The
 161 following bits are defined:
 162 .sp
 163 .ne 2
 164 .na
 165 \fB\fBSOCKET_INTERFACE_MEMORY\fR\fR
 166 .ad
 167 .sp .6
 168 .RS 4n
 169 Memory only interface.
 170 .RE
 171 
 172 .sp
 173 .ne 2
 174 .na
 175 \fB\fBSOCKET_INTERFACE_MEMORY_AND_IO\fR\fR
 176 .ad
 177 .sp .6
 178 .RS 4n
 179 Memory and I/O interface.
 180 .RE
 181 
 182 .RE
 183 
 184 .sp
 185 .ne 2
 186 .na
 187 \fB\fBConfigBase\fR\fR
 188 .ad
 189 .sp .6
 190 .RS 4n
 191 This field is the offset in bytes from the beginning of attribute memory of the
 192 configuration registers.
 193 .RE
 194 
 195 .sp
 196 .ne 2
 197 .na
 198 \fB\fBPresent\fR\fR
 199 .ad
 200 .sp .6
 201 .RS 4n
 202 This field identifies which of the configuration registers are present. If
 203 present, the corresponding bit is set. This field is bit-mapped as follows:
 204 .sp
 205 .ne 2
 206 .na
 207 \fB\fBCONFIG_OPTION_REG_PRESENT\fR\fR
 208 .ad
 209 .RS 30n
 210 Configuration Option Register (COR) present
 211 .RE
 212 
 213 .sp
 214 .ne 2
 215 .na
 216 \fB\fBCONFIG_STATUS_REG_PRESENT\fR\fR
 217 .ad
 218 .RS 30n
 219 Configuration Status Register (CCSR) present
 220 .RE
 221 
 222 .sp
 223 .ne 2
 224 .na
 225 \fB\fBCONFIG_PINREPL_REG_PRESENT\fR\fR
 226 .ad
 227 .RS 30n
 228 Pin Replacement Register (PRR) present
 229 .RE
 230 
 231 .sp
 232 .ne 2
 233 .na
 234 \fB\fBCONFIG_COPY_REG_PRESENT\fR\fR
 235 .ad
 236 .RS 30n
 237 Socket and Copy Register (SCR) present
 238 .RE
 239 
 240 .sp
 241 .ne 2
 242 .na
 243 \fB\fBCONFIG_ESR_REG_PRESENT\fR\fR
 244 .ad
 245 .RS 30n
 246 Extended Status Register (ESR) present
 247 .RE
 248 
 249 .RE
 250 
 251 .sp
 252 .ne 2
 253 .na
 254 \fB\fBStatus, Pin, Copy, ExtendedStatus\fR\fR
 255 .ad
 256 .sp .6
 257 .RS 4n
 258 These fields represent the initial values that should be written to those
 259 registers if they are present, as indicated by the \fBPresent\fR field.
 260 .sp
 261 The \fBPin\fR field is also used to inform Card Services which pins in the
 262 \fBPC\fR Card's \fBPRR\fR (Pin Replacement Register) are valid. Only those bits
 263 which are set are considered valid. This affects how status is returned by the
 264 \fBcsx_GetStatus\fR(9F) function. If a particular signal is valid in the
 265 \fBPRR\fR, both the \fImask\fR (\fBSTATUS\fR) bit and the \fIchange\fR
 266 (\fBEVENT\fR) bit must be set in the \fBPin\fR field. The following \fBPRR\fR
 267 bit definitions are provided for client use:
 268 .sp
 269 .ne 2
 270 .na
 271 \fB\fBPRR_WP_STATUS\fR\fR
 272 .ad
 273 .RS 20n
 274 \fBWRITE PROTECT\fR mask
 275 .RE
 276 
 277 .sp
 278 .ne 2
 279 .na
 280 \fB\fBPRR_READY_STATUS\fR\fR
 281 .ad
 282 .RS 20n
 283 \fBREADY\fR mask
 284 .RE
 285 
 286 .sp
 287 .ne 2
 288 .na
 289 \fB\fBPRR_BVD2_STATUS\fR\fR
 290 .ad
 291 .RS 20n
 292 \fBBVD2\fR mask
 293 .RE
 294 
 295 .sp
 296 .ne 2
 297 .na
 298 \fB\fBPRR_BVD1_STATUS\fR\fR
 299 .ad
 300 .RS 20n
 301 \fBBVD1\fR mask
 302 .RE
 303 
 304 .sp
 305 .ne 2
 306 .na
 307 \fB\fBPRR_WP_EVENT\fR\fR
 308 .ad
 309 .RS 20n
 310 \fBWRITE PROTECT\fR changed
 311 .RE
 312 
 313 .sp
 314 .ne 2
 315 .na
 316 \fB\fBPRR_READY_EVENT\fR\fR
 317 .ad
 318 .RS 20n
 319 \fBREADY\fR changed
 320 .RE
 321 
 322 .sp
 323 .ne 2
 324 .na
 325 \fB\fBPRR_BVD2_EVENT\fR\fR
 326 .ad
 327 .RS 20n
 328 \fBBVD2\fR changed
 329 .RE
 330 
 331 .sp
 332 .ne 2
 333 .na
 334 \fB\fBPRR_BVD1_EVENT\fR\fR
 335 .ad
 336 .RS 20n
 337 \fBBVD1\fR changed
 338 .RE
 339 
 340 .RE
 341 
 342 .sp
 343 .ne 2
 344 .na
 345 \fB\fBConfigIndex\fR\fR
 346 .ad
 347 .sp .6
 348 .RS 4n
 349 This field is the value written to the \fBCOR\fR (Configuration Option
 350 Register) for the configuration index required by the \fBPC\fR Card. Only the
 351 least significant six bits of the \fBConfigIndex\fR field are significant; the
 352 upper two (2) bits are ignored. The interrupt type in the \fBCOR\fR is always
 353 set to \fIlevel\fR mode by Card Services.
 354 .RE
 355 
 356 .SH RETURN VALUES
 357 .sp
 358 .ne 2
 359 .na
 360 \fB\fBCS_SUCCESS\fR\fR
 361 .ad
 362 .RS 27n
 363 Successful operation.
 364 .RE
 365 
 366 .sp
 367 .ne 2
 368 .na
 369 \fB\fBCS_BAD_HANDLE\fR\fR
 370 .ad
 371 .RS 27n
 372 Client handle is invalid or \fBcsx_RequestConfiguration()\fR not done.
 373 .RE
 374 
 375 .sp
 376 .ne 2
 377 .na
 378 \fB\fBCS_BAD_SOCKET\fR\fR
 379 .ad
 380 .RS 27n
 381 Error in getting or setting socket hardware parameters.
 382 .RE
 383 
 384 .sp
 385 .ne 2
 386 .na
 387 \fB\fBCS_BAD_VCC\fR\fR
 388 .ad
 389 .RS 27n
 390 Requested \fBVcc\fR is not available on socket.
 391 .RE
 392 
 393 .sp
 394 .ne 2
 395 .na
 396 \fB\fBCS_BAD_VPP\fR\fR
 397 .ad
 398 .RS 27n
 399 Requested \fBVpp\fR is not available on socket.
 400 .RE
 401 
 402 .sp
 403 .ne 2
 404 .na
 405 \fB\fBCS_NO_CARD\fR\fR
 406 .ad
 407 .RS 27n
 408 No \fBPC\fR Card in socket.
 409 .RE
 410 
 411 .sp
 412 .ne 2
 413 .na
 414 \fB\fBCS_BAD_TYPE\fR\fR
 415 .ad
 416 .RS 27n
 417 \fBI/O\fR and memory interface not supported on socket.
 418 .RE
 419 
 420 .sp
 421 .ne 2
 422 .na
 423 \fB\fBCS_CONFIGURATION_LOCKED\fR\fR
 424 .ad
 425 .RS 27n
 426 \fBcsx_RequestConfiguration()\fR already done.
 427 .RE
 428 
 429 .sp
 430 .ne 2
 431 .na
 432 \fB\fBCS_UNSUPPORTED_FUNCTION\fR\fR
 433 .ad
 434 .RS 27n
 435 No \fBPCMCIA\fR hardware installed.
 436 .RE
 437 
 438 .SH CONTEXT
 439 .sp
 440 .LP
 441 This function may be called from user or kernel context.
 442 .SH SEE ALSO
 443 .sp
 444 .LP
 445 \fBcsx_AccessConfigurationRegister\fR(9F), \fBcsx_GetStatus\fR(9F),
 446 \fBcsx_RegisterClient\fR(9F), \fBcsx_ReleaseConfiguration\fR(9F),
 447 \fBcsx_RequestIO\fR(9F), \fBcsx_RequestIRQ\fR(9F)
 448 .sp
 449 .LP
 450 \fIPC Card 95 Standard\fR, PCMCIA/JEIDA