1 '\" te
   2 .\"  Copyright (c) 2000, Sun Microsystems, Inc.
   3 .\"  All Rights Reserved
   4 .\" 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.
   5 .\" 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.
   6 .\" 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]
   7 .TH CSX_REQUESTIRQ 9F "Jul 19, 1996"
   8 .SH NAME
   9 csx_RequestIRQ, csx_ReleaseIRQ \- request or release IRQ resource
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/pccard.h>
  14 
  15 
  16 
  17 \fBint32_t\fR \fBcsx_RequestIRQ\fR(\fBclient_handle_t\fR \fIch\fR, \fBirq_req_t *\fR\fIir\fR);
  18 .fi
  19 
  20 .LP
  21 .nf
  22 \fBint32_t\fR \fBcsx_ReleaseIRQ\fR(\fBclient_handle_t\fR \fIch\fR, \fBirq_req_t *\fR\fIir\fR);
  23 .fi
  24 
  25 .SH INTERFACE LEVEL
  26 .sp
  27 .LP
  28 Solaris \fBDDI\fR Specific (Solaris \fBDDI\fR)
  29 .SH PARAMETERS
  30 .sp
  31 .ne 2
  32 .na
  33 \fB\fIch\fR \fR
  34 .ad
  35 .RS 7n
  36 Client handle returned from \fBcsx_RegisterClient\fR(9F).
  37 .RE
  38 
  39 .sp
  40 .ne 2
  41 .na
  42 \fB\fIir\fR \fR
  43 .ad
  44 .RS 7n
  45 Pointer to an \fBirq_req_t\fR structure.
  46 .RE
  47 
  48 .SH DESCRIPTION
  49 .sp
  50 .LP
  51 The function \fBcsx_RequestIRQ()\fR requests an \fBIRQ\fR resource and
  52 registers the client's \fBIRQ\fR handler with Card Services.
  53 .sp
  54 .LP
  55 If a client requires an \fBIRQ\fR,\fBcsx_RequestIRQ()\fR must be called to
  56 request an \fBIRQ\fR resource as well as to register the client's \fBIRQ\fR
  57 handler with Card Services. The client will not receive callbacks at the
  58 \fBIRQ\fR callback handler until \fBcsx_RequestConfiguration\fR(9F) or
  59 \fBcsx_ModifyConfiguration\fR(9F) has successfully returned when either of
  60 these functions are called with the \fBCONF_ENABLE_IRQ_STEERING\fR bit set.
  61 .sp
  62 .LP
  63 The function \fBcsx_ReleaseIRQ()\fR releases a previously requested \fBIRQ\fR
  64 resource.
  65 .sp
  66 .LP
  67 The Card Services \fBIRQ\fR resource list is adjusted by
  68 \fBcsx_ReleaseIRQ()\fR. Depending on the adapter hardware, the host bus
  69 \fBIRQ\fR connection might also be disabled. Client \fBIRQ\fR handlers always
  70 run above lock level and so should take care to perform only Solaris operations
  71 that are appropriate for an above-lock-level \fBIRQ\fR handler.
  72 .sp
  73 .LP
  74 \fBcsx_RequestIRQ()\fR fails if it has already been called without a
  75 corresponding \fBcsx_ReleaseIRQ()\fR.
  76 .SH STRUCTURE MEMBERS
  77 .sp
  78 .LP
  79 The structure members of \fBirq_req_t\fR are:
  80 .sp
  81 .in +2
  82 .nf
  83 uint32_t                Socket;          /* socket number */
  84 uint32_t                Attributes;      /* IRQ attribute flags */
  85 csfunction_t            *irq_handler;    /* IRQ handler */
  86 void                    *irq_handler_arg; /* IRQ handler argument */
  87 ddi_iblock_cookie_t     *iblk_cookie;    /* IRQ interrupt
  88                                          /*   block cookie */
  89 ddi_idevice_cookie_t    *idev_cookie;    /* IRQ interrupt device
  90                                          /*   cookie */
  91 .fi
  92 .in -2
  93 
  94 .sp
  95 .LP
  96 The fields are defined as follows:
  97 .sp
  98 .ne 2
  99 .na
 100 \fB\fBSocket\fR \fR
 101 .ad
 102 .RS 20n
 103 Not used in Solaris, but for portability with other Card Services
 104 implementations, it should be set to the logical socket number.
 105 .RE
 106 
 107 .sp
 108 .ne 2
 109 .na
 110 \fB\fBAttributes\fR \fR
 111 .ad
 112 .RS 20n
 113 This field is bit-mapped. It specifies details about the type of \fBIRQ\fR
 114 desired by the client. The following bits are defined:
 115 .sp
 116 .ne 2
 117 .na
 118 \fB\fBIRQ_TYPE_EXCLUSIVE\fR\fR
 119 .ad
 120 .RS 22n
 121 \fBIRQ\fR is exclusive to this socket. This bit must be set. It indicates that
 122 the system IRQ is dedicated to this PC Card.
 123 .RE
 124 
 125 .RE
 126 
 127 .sp
 128 .ne 2
 129 .na
 130 \fB\fBirq_handler\fR \fR
 131 .ad
 132 .RS 20n
 133 The client \fBIRQ\fR callback handler entry point is passed in the
 134 \fBirq_handler\fR field.
 135 .RE
 136 
 137 .sp
 138 .ne 2
 139 .na
 140 \fB\fBirq_handler_arg\fR \fR
 141 .ad
 142 .RS 20n
 143 The client can use the \fBirq_handler_arg\fR field to pass client-specific data
 144 to the client \fBIRQ\fR callback handler.
 145 .RE
 146 
 147 .sp
 148 .ne 2
 149 .na
 150 \fB\fBiblk_cookie\fR \fR
 151 .ad
 152 .br
 153 .na
 154 \fB\fBidev_cookie\fR \fR
 155 .ad
 156 .RS 20n
 157 These fields must be used by the client to set up mutexes that are used in the
 158 client's \fBIRQ\fR callback handler.
 159 .RE
 160 
 161 .sp
 162 .LP
 163 For a specific \fBcsx_ReleaseIRQ()\fR call, the values in the \fBirq_req_t\fR
 164 structure must be the same as those returned from the previous
 165 \fBcsx_RequestIRQ()\fR call; otherwise, \fBCS_BAD_ARGS\fR is returned and no
 166 changes are made to Card Services resources or the socket and adapter hardware.
 167 .SH RETURN VALUES
 168 .sp
 169 .ne 2
 170 .na
 171 \fB\fBCS_SUCCESS\fR \fR
 172 .ad
 173 .RS 28n
 174 Successful operation.
 175 .RE
 176 
 177 .sp
 178 .ne 2
 179 .na
 180 \fB\fBCS_BAD_ARGS\fR \fR
 181 .ad
 182 .RS 28n
 183 \fBIRQ\fR description does not match allocation.
 184 .RE
 185 
 186 .sp
 187 .ne 2
 188 .na
 189 \fB\fBCS_BAD_ATTRIBUTE\fR \fR
 190 .ad
 191 .RS 28n
 192 \fBIRQ_TYPE_EXCLUSIVE\fR not set, or an unsupported or reserved bit is set.
 193 .RE
 194 
 195 .sp
 196 .ne 2
 197 .na
 198 \fB\fBCS_BAD_HANDLE\fR \fR
 199 .ad
 200 .RS 28n
 201 Client handle is invalid or \fBcsx_RequestConfiguration\fR(9F) not done.
 202 .RE
 203 
 204 .sp
 205 .ne 2
 206 .na
 207 \fB\fBCS_BAD_IRQ\fR \fR
 208 .ad
 209 .RS 28n
 210 Unable to allocate \fBIRQ\fR resources.
 211 .RE
 212 
 213 .sp
 214 .ne 2
 215 .na
 216 \fB\fBCS_IN_USE\fR \fR
 217 .ad
 218 .RS 28n
 219 \fBcsx_RequestIRQ()\fR already done or a previous \fBcsx_RequestIRQ()\fR has
 220 not been done for a corresponding \fBcsx_ReleaseIRQ()\fR.
 221 .RE
 222 
 223 .sp
 224 .ne 2
 225 .na
 226 \fB\fBCS_CONFIGURATION_LOCKED\fR \fR
 227 .ad
 228 .RS 28n
 229 \fBcsx_RequestConfiguration\fR(9F) already done or
 230 \fBcsx_ReleaseConfiguration\fR(9F) has not been done.
 231 .RE
 232 
 233 .sp
 234 .ne 2
 235 .na
 236 \fB\fBCS_NO_CARD\fR \fR
 237 .ad
 238 .RS 28n
 239 No \fBPC\fR Card in socket.
 240 .RE
 241 
 242 .sp
 243 .ne 2
 244 .na
 245 \fB\fBCS_UNSUPPORTED_FUNCTION\fR \fR
 246 .ad
 247 .RS 28n
 248 No \fBPCMCIA\fR hardware installed.
 249 .RE
 250 
 251 .SH CONTEXT
 252 .sp
 253 .LP
 254 These functions may be called from user or kernel context.
 255 .SH SEE ALSO
 256 .sp
 257 .LP
 258 \fBcsx_ReleaseConfiguration\fR(9F), \fBcsx_RequestConfiguration\fR(9F)
 259 .sp
 260 .LP
 261 \fIPC Card Card 95 Standard\fR, PCMCIA/JEIDA