'\" te
.\"  Copyright (c) 1996, Sun Microsystems, Inc.  All Rights Reserved
.\" 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.
.\" 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.
.\" 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]
.TH CSX_REQUESTCONFIGURATION 9F "Jul 19, 1996"
.SH NAME
csx_RequestConfiguration \- configure the PC Card and socket
.SH SYNOPSIS
.LP
.nf
#include <sys/pccard.h>



\fBint32_t\fR \fBcsx_RequestConfiguration\fR(\fBclient_handle_t\fR \fIch\fR, \fBconfig_req_t *\fR\fIcr\fR);
.fi

.SH INTERFACE LEVEL
.sp
.LP
Solaris \fBDDI\fR Specific (Solaris \fBDDI\fR)
.SH PARAMETERS
.sp
.ne 2
.na
\fB\fIch\fR\fR
.ad
.RS 6n
Client handle returned from \fBcsx_RegisterClient\fR(9F).
.RE

.sp
.ne 2
.na
\fB\fIcr\fR\fR
.ad
.RS 6n
Pointer to a \fBconfig_req_t\fR structure.
.RE

.SH DESCRIPTION
.sp
.LP
This function configures the \fBPC\fR Card and socket. It must be used by
clients that require \fBI/O\fR or \fBIRQ\fR resources for their \fBPC\fR Card.
.sp
.LP
\fBcsx_RequestIO\fR(9F) and \fBcsx_RequestIRQ\fR(9F) must be used before
calling this function to specify the \fBI/O\fR and \fBIRQ\fR requirements for
the \fBPC\fR Card and socket if necessary. \fBcsx_RequestConfiguration()\fR
establishes the configuration in the socket adapter and \fBPC\fR Card, and it
programs the Base and Limit registers of multi-function \fBPC\fR Cards if these
registers exist. The values programmed into these registers depend on the
\fBIO\fR requirements of this configuration.
.SH STRUCTURE MEMBERS
.sp
.LP
The structure members of \fBconfig_req_t\fR are:
.sp
.in +2
.nf
uint32_t     Socket;          /* socket number */
uint32_t     Attributes;      /* configuration attributes */
uint32_t     Vcc;             /* Vcc value */
uint32_t     Vpp1;            /* Vpp1 value */
uint32_t     Vpp2;            /* Vpp2 value */
uint32_t     IntType;         /* socket interface type - mem or IO */
uint32_t     ConfigBase;      /* offset from start of AM space */
uint32_t     Status;          /* value to write to STATUS register */
uint32_t     Pin;             /* value to write to PRR */
uint32_t     Copy;            /* value to write to COPY register */
uint32_t     ConfigIndex;     /* value to write to COR */
uint32_t     Present;         /* which config registers present */
uint32_t     ExtendedStatus;  /* value to write to EXSTAT register */
.fi
.in -2

.sp
.LP
The fields are defined as follows:
.sp
.ne 2
.na
\fB\fBSocket\fR\fR
.ad
.sp .6
.RS 4n
Not used in Solaris, but for portability with other Card Services
implementations, it should be set to the logical socket number.
.RE

.sp
.ne 2
.na
\fB\fBAttributes\fR\fR
.ad
.sp .6
.RS 4n
This field is bit-mapped. It indicates whether the client wishes the \fBIRQ\fR
resources to be enabled and whether Card Services should ignore the \fBVS\fR
bits on the socket interface. The following bits are defined:
.sp
.ne 2
.na
\fB\fBCONF_ENABLE_IRQ_STEERING\fR\fR
.ad
.sp .6
.RS 4n
Enable IRQ Steering. Set to connect the \fBPC\fR Card \fBIREQ\fR line to a
system interrupt previously selected by a call to \fBcsx_RequestIRQ\fR(9F). If
\fBCONF_ENABLE_IRQ_STEERING\fR is set, once \fBcsx_RequestConfiguration()\fR
has successfully returned, the client may start receiving \fBIRQ\fR callbacks
at the \fBIRQ\fR callback handler established in the call to
\fBcsx_RequestIRQ\fR(9F).
.RE

.sp
.ne 2
.na
\fB\fBCONF_VSOVERRIDE\fR\fR
.ad
.sp .6
.RS 4n
Override VS pins. After card insertion and prior to the first successful
\fBcsx_RequestConfiguration()\fR, the voltage levels applied to the card shall
be those indicated by the card's physical key and/or the VS[2:1] voltage sense
pins. For Low Voltage capable host systems (hosts which are capable of \fBVS\fR
pin decoding), if a client desires to apply a voltage not indicated by the
\fBVS\fR pin decoding, then \fBCONF_VSOVERRIDE\fR must be set in the
\fBAttributes\fR field; otherwise, \fBCS_BAD_VCC\fR shall be returned.
.RE

.RE

.sp
.ne 2
.na
\fB\fBVcc, Vpp1, Vpp2\fR\fR
.ad
.sp .6
.RS 4n
These fields all represent voltages expressed in tenths of a volt. Values from
zero (\fB0\fR) to \fB25.5\fR volts may be set. To be valid, the exact voltage
must be available from the system.  \fBPC\fR Cards indicate multiple \fBVcc\fR
voltage capability in their \fBCIS\fR via the \fBCISTPL_CFTABLE_ENTRY\fR tuple.
After card insertion, Card Services processes the \fBCIS\fR, and when multiple
\fBVcc\fR voltage capability is indicated, Card Services will allow the client
to apply \fBVcc\fR voltage levels which are contrary to the \fBVS\fR pin
decoding without requiring the client to set \fBCONF_VSOVERRIDE.\fR
.RE

.sp
.ne 2
.na
\fB\fBIntType\fR\fR
.ad
.sp .6
.RS 4n
This field is bit-mapped. It indicates how the socket should be configured. The
following bits are defined:
.sp
.ne 2
.na
\fB\fBSOCKET_INTERFACE_MEMORY\fR\fR
.ad
.sp .6
.RS 4n
Memory only interface.
.RE

.sp
.ne 2
.na
\fB\fBSOCKET_INTERFACE_MEMORY_AND_IO\fR\fR
.ad
.sp .6
.RS 4n
Memory and I/O interface.
.RE

.RE

.sp
.ne 2
.na
\fB\fBConfigBase\fR\fR
.ad
.sp .6
.RS 4n
This field is the offset in bytes from the beginning of attribute memory of the
configuration registers.
.RE

.sp
.ne 2
.na
\fB\fBPresent\fR\fR
.ad
.sp .6
.RS 4n
This field identifies which of the configuration registers are present. If
present, the corresponding bit is set. This field is bit-mapped as follows:
.sp
.ne 2
.na
\fB\fBCONFIG_OPTION_REG_PRESENT\fR\fR
.ad
.RS 30n
Configuration Option Register (COR) present
.RE

.sp
.ne 2
.na
\fB\fBCONFIG_STATUS_REG_PRESENT\fR\fR
.ad
.RS 30n
Configuration Status Register (CCSR) present
.RE

.sp
.ne 2
.na
\fB\fBCONFIG_PINREPL_REG_PRESENT\fR\fR
.ad
.RS 30n
Pin Replacement Register (PRR) present
.RE

.sp
.ne 2
.na
\fB\fBCONFIG_COPY_REG_PRESENT\fR\fR
.ad
.RS 30n
Socket and Copy Register (SCR) present
.RE

.sp
.ne 2
.na
\fB\fBCONFIG_ESR_REG_PRESENT\fR\fR
.ad
.RS 30n
Extended Status Register (ESR) present
.RE

.RE

.sp
.ne 2
.na
\fB\fBStatus, Pin, Copy, ExtendedStatus\fR\fR
.ad
.sp .6
.RS 4n
These fields represent the initial values that should be written to those
registers if they are present, as indicated by the \fBPresent\fR field.
.sp
The \fBPin\fR field is also used to inform Card Services which pins in the
\fBPC\fR Card's \fBPRR\fR (Pin Replacement Register) are valid. Only those bits
which are set are considered valid. This affects how status is returned by the
\fBcsx_GetStatus\fR(9F) function. If a particular signal is valid in the
\fBPRR\fR, both the \fImask\fR (\fBSTATUS\fR) bit and the \fIchange\fR
(\fBEVENT\fR) bit must be set in the \fBPin\fR field. The following \fBPRR\fR
bit definitions are provided for client use:
.sp
.ne 2
.na
\fB\fBPRR_WP_STATUS\fR\fR
.ad
.RS 20n
\fBWRITE PROTECT\fR mask
.RE

.sp
.ne 2
.na
\fB\fBPRR_READY_STATUS\fR\fR
.ad
.RS 20n
\fBREADY\fR mask
.RE

.sp
.ne 2
.na
\fB\fBPRR_BVD2_STATUS\fR\fR
.ad
.RS 20n
\fBBVD2\fR mask
.RE

.sp
.ne 2
.na
\fB\fBPRR_BVD1_STATUS\fR\fR
.ad
.RS 20n
\fBBVD1\fR mask
.RE

.sp
.ne 2
.na
\fB\fBPRR_WP_EVENT\fR\fR
.ad
.RS 20n
\fBWRITE PROTECT\fR changed
.RE

.sp
.ne 2
.na
\fB\fBPRR_READY_EVENT\fR\fR
.ad
.RS 20n
\fBREADY\fR changed
.RE

.sp
.ne 2
.na
\fB\fBPRR_BVD2_EVENT\fR\fR
.ad
.RS 20n
\fBBVD2\fR changed
.RE

.sp
.ne 2
.na
\fB\fBPRR_BVD1_EVENT\fR\fR
.ad
.RS 20n
\fBBVD1\fR changed
.RE

.RE

.sp
.ne 2
.na
\fB\fBConfigIndex\fR\fR
.ad
.sp .6
.RS 4n
This field is the value written to the \fBCOR\fR (Configuration Option
Register) for the configuration index required by the \fBPC\fR Card. Only the
least significant six bits of the \fBConfigIndex\fR field are significant; the
upper two (2) bits are ignored. The interrupt type in the \fBCOR\fR is always
set to \fIlevel\fR mode by Card Services.
.RE

.SH RETURN VALUES
.sp
.ne 2
.na
\fB\fBCS_SUCCESS\fR\fR
.ad
.RS 27n
Successful operation.
.RE

.sp
.ne 2
.na
\fB\fBCS_BAD_HANDLE\fR\fR
.ad
.RS 27n
Client handle is invalid or \fBcsx_RequestConfiguration()\fR not done.
.RE

.sp
.ne 2
.na
\fB\fBCS_BAD_SOCKET\fR\fR
.ad
.RS 27n
Error in getting or setting socket hardware parameters.
.RE

.sp
.ne 2
.na
\fB\fBCS_BAD_VCC\fR\fR
.ad
.RS 27n
Requested \fBVcc\fR is not available on socket.
.RE

.sp
.ne 2
.na
\fB\fBCS_BAD_VPP\fR\fR
.ad
.RS 27n
Requested \fBVpp\fR is not available on socket.
.RE

.sp
.ne 2
.na
\fB\fBCS_NO_CARD\fR\fR
.ad
.RS 27n
No \fBPC\fR Card in socket.
.RE

.sp
.ne 2
.na
\fB\fBCS_BAD_TYPE\fR\fR
.ad
.RS 27n
\fBI/O\fR and memory interface not supported on socket.
.RE

.sp
.ne 2
.na
\fB\fBCS_CONFIGURATION_LOCKED\fR\fR
.ad
.RS 27n
\fBcsx_RequestConfiguration()\fR already done.
.RE

.sp
.ne 2
.na
\fB\fBCS_UNSUPPORTED_FUNCTION\fR\fR
.ad
.RS 27n
No \fBPCMCIA\fR hardware installed.
.RE

.SH CONTEXT
.sp
.LP
This function may be called from user or kernel context.
.SH SEE ALSO
.sp
.LP
\fBcsx_AccessConfigurationRegister\fR(9F), \fBcsx_GetStatus\fR(9F),
\fBcsx_RegisterClient\fR(9F), \fBcsx_ReleaseConfiguration\fR(9F),
\fBcsx_RequestIO\fR(9F), \fBcsx_RequestIRQ\fR(9F)
.sp
.LP
\fIPC Card 95 Standard\fR, PCMCIA/JEIDA