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

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