1 '\" te
   2 .\"  Copyright (c) 2002, 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_REGISTERCLIENT 9F "Jul 19, 1996"
   7 .SH NAME
   8 csx_RegisterClient \- register a client
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/pccard.h>
  13 
  14 
  15 
  16 \fBint32_t\fR \fBcsx_RegisterClient\fR(\fBclient_handle_t *\fR\fIch\fR, \fBclient_reg_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 Pointer to a \fBclient_handle_t\fR structure.
  31 .RE
  32 
  33 .sp
  34 .ne 2
  35 .na
  36 \fB\fImc\fR\fR
  37 .ad
  38 .RS 6n
  39 Pointer to a \fBclient_reg_t\fR structure.
  40 .RE
  41 
  42 .SH DESCRIPTION
  43 .sp
  44 .LP
  45 This function registers a client with Card Services and returns a unique client
  46 handle for the client. The client handle must be passed to
  47 \fBcsx_DeregisterClient\fR(9F) when the client terminates.
  48 .SH STRUCTURE MEMBERS
  49 .sp
  50 .LP
  51 The structure members of \fBclient_reg_t\fR are:
  52 .sp
  53 .in +2
  54 .nf
  55  uint32_t                 Attributes;
  56   uint32_t                 EventMask;
  57   event_callback_args_t    event_callback_args;
  58   uint32_t                 Version;             /* CS version to expect */
  59   csfunction_t             *event_handler;
  60   ddi_iblock_cookie_t      *iblk_cookie;        /* event iblk cookie */
  61   ddi_idevice_cookie_t     *idev_cookie;        /* event idev cookie */
  62   dev_info_t               *dip;                /* client's dip */
  63   char                     driver_name[MODMAXNAMELEN];
  64 .fi
  65 .in -2
  66 
  67 .sp
  68 .LP
  69 The fields are defined as follows:
  70 .sp
  71 .ne 2
  72 .na
  73 \fB\fBAttributes\fR\fR
  74 .ad
  75 .RS 23n
  76 This field is bit-mapped and defined as follows:
  77 .sp
  78 .ne 2
  79 .na
  80 \fB\fBINFO_MEM_CLIENT\fR\fR
  81 .ad
  82 .sp .6
  83 .RS 4n
  84 Memory client device driver.
  85 .RE
  86 
  87 .sp
  88 .ne 2
  89 .na
  90 \fB\fBINFO_MTD_CLIENT\fR\fR
  91 .ad
  92 .sp .6
  93 .RS 4n
  94 Memory Technology Driver client.
  95 .RE
  96 
  97 .sp
  98 .ne 2
  99 .na
 100 \fB\fBINFO_IO_CLIENT\fR\fR
 101 .ad
 102 .sp .6
 103 .RS 4n
 104 \fBIO\fR client device driver.
 105 .RE
 106 
 107 .sp
 108 .ne 2
 109 .na
 110 \fB\fBINFO_CARD_SHARE\fR\fR
 111 .ad
 112 .sp .6
 113 .RS 4n
 114 Generate artificial \fBCS_EVENT_CARD_INSERTION\fR and
 115 \fBCS_EVENT_REGISTRATION_COMPLETE\fR events.
 116 .RE
 117 
 118 .sp
 119 .ne 2
 120 .na
 121 \fB\fBINFO_CARD_EXCL\fR\fR
 122 .ad
 123 .sp .6
 124 .RS 4n
 125 Generate artificial \fBCS_EVENT_CARD_INSERTION\fR and
 126 \fBCS_EVENT_REGISTRATION_COMPLETE\fR events.
 127 .sp
 128 .ne 2
 129 .na
 130 \fB\fBINFO_MEM_CLIENT\fR\fR
 131 .ad
 132 .br
 133 .na
 134 \fB\fBINFO_MTD_CLIENT\fR\fR
 135 .ad
 136 .br
 137 .na
 138 \fB\fBINFO_IO_CLIENT\fR\fR
 139 .ad
 140 .sp .6
 141 .RS 4n
 142 These bits are mutually exclusive (that is, only one bit may be set), but one
 143 of the bits must be set.
 144 .RE
 145 
 146 .sp
 147 .ne 2
 148 .na
 149 \fB\fBINFO_CARD_SHARE\fR\fR
 150 .ad
 151 .br
 152 .na
 153 \fB\fBINFO_CARD_EXCL\fR\fR
 154 .ad
 155 .sp .6
 156 .RS 4n
 157 If either of these bits is set, the client will receive a
 158 \fBCS_EVENT_REGISTRATION_COMPLETE\fR event when Card Services has completed its
 159 internal client registration processing and after a sucessful call to
 160 \fBcsx_RequestSocketMask\fR(9F).
 161 .sp
 162 Also, if either of these bits is set, and if a card of the type that the client
 163 can control is currently inserted in the socket (and after a successful call to
 164 \fBcsx_RequestSocketMask\fR(9F)), the client will receive an artificial
 165 \fBCS_EVENT_CARD_INSERTION\fR event.
 166 .RE
 167 
 168 .RE
 169 
 170 .RE
 171 
 172 .sp
 173 .ne 2
 174 .na
 175 \fB\fBEvent\fR \fBMask\fR\fR
 176 .ad
 177 .RS 23n
 178 This field is bit-mapped and specifies the client's global event mask. Card
 179 Services performs event notification based on this field. See
 180 \fBcsx_event_handler\fR(9E) for valid event definitions and for additional
 181 information about handling events.
 182 .RE
 183 
 184 .sp
 185 .ne 2
 186 .na
 187 \fB\fBevent_callback_args\fR\fR
 188 .ad
 189 .RS 23n
 190 The \fBevent_callback_args_t\fR structure members are:
 191 .sp
 192 .in +2
 193 .nf
 194     void     *client_data;
 195 .fi
 196 .in -2
 197 
 198 The \fBclient_data\fR field may be used to provide data available to the event
 199 handler (see \fBcsx_event_handler\fR(9E)). Typically, this is the client
 200 driver's soft state pointer.
 201 .RE
 202 
 203 .sp
 204 .ne 2
 205 .na
 206 \fB\fBVersion\fR\fR
 207 .ad
 208 .RS 23n
 209 This field contains the specific Card Services version number that the client
 210 expects to use. Typically, the client will use the \fBCS_VERSION\fR macro to
 211 specify to Card Services which version of Card Services the client expects.
 212 .RE
 213 
 214 .sp
 215 .ne 2
 216 .na
 217 \fB\fBevent_handler\fR\fR
 218 .ad
 219 .RS 23n
 220 The client event callback handler entry point is passed in the
 221 \fBevent_handler\fR field.
 222 .RE
 223 
 224 .sp
 225 .ne 2
 226 .na
 227 \fB\fBiblk_cookie\fR\fR
 228 .ad
 229 .br
 230 .na
 231 \fB\fBidev_cookie\fR\fR
 232 .ad
 233 .RS 23n
 234 These fields must be used by the client to set up mutexes that are used in the
 235 client's event callback handler when handling high priority events.
 236 .RE
 237 
 238 .sp
 239 .ne 2
 240 .na
 241 \fB\fBdip\fR\fR
 242 .ad
 243 .RS 23n
 244 The client must set this field with a pointer to the client's dip.
 245 .RE
 246 
 247 .sp
 248 .ne 2
 249 .na
 250 \fB\fBdriver_name\fR\fR
 251 .ad
 252 .RS 23n
 253 The client must copy a driver-unique name into this member. This name must be
 254 identical across all instances of the driver.
 255 .RE
 256 
 257 .SH RETURN VALUES
 258 .sp
 259 .ne 2
 260 .na
 261 \fB\fBCS_SUCCESS\fR\fR
 262 .ad
 263 .RS 27n
 264 Successful operation.
 265 .RE
 266 
 267 .sp
 268 .ne 2
 269 .na
 270 \fB\fBCS_BAD_ATTRIBUTE\fR\fR
 271 .ad
 272 .RS 27n
 273 No client type or more than one client type specified.
 274 .RE
 275 
 276 .sp
 277 .ne 2
 278 .na
 279 \fB\fBCS_OUT_OF_RESOURCE\fR\fR
 280 .ad
 281 .RS 27n
 282 Card Services is unable to register client.
 283 .RE
 284 
 285 .sp
 286 .ne 2
 287 .na
 288 \fB\fBCS_BAD_VERSION\fR\fR
 289 .ad
 290 .RS 27n
 291 Card Services version is incompatible with client.
 292 .RE
 293 
 294 .sp
 295 .ne 2
 296 .na
 297 \fB\fBCS_BAD_HANDLE\fR\fR
 298 .ad
 299 .RS 27n
 300 Client has already registered for this socket.
 301 .RE
 302 
 303 .sp
 304 .ne 2
 305 .na
 306 \fB\fBCS_UNSUPPORTED_FUNCTION\fR\fR
 307 .ad
 308 .RS 27n
 309 No \fBPCMCIA\fR hardware installed.
 310 .RE
 311 
 312 .SH CONTEXT
 313 .sp
 314 .LP
 315 This function may be called from user or kernel context.
 316 .SH SEE ALSO
 317 .sp
 318 .LP
 319 \fBcsx_DeregisterClient\fR(9F), \fBcsx_RequestSocketMask\fR(9F)
 320 .sp
 321 .LP
 322 \fIPC Card 95 Standard\fR, PCMCIA/JEIDA