usr/src/man/man3dat/dat_ep_modify.3dat

   1 '\" te
   2 .\" This manual page is derived from the DAT/uDAPL 1.2 specification.
   3 .\" Portions Copyright (c) 2007, Sun Microsystems, Inc. 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 DAT_EP_MODIFY 3DAT "Jul 16, 2004"
   8 .SH NAME
   9 dat_ep_modify \- change parameters of an Endpoint
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ]
  14 #include <\fBdat/udat.h\fR>
  15
  16 DAT_RETURN
  17     dat_ep_modify (
  18     IN    DAT_EP_HANDLE        ep_handle,
  19     IN    DAT_EP_PARAM_MASK    ep_param_mask,
  20     IN    DAT_EP_PARAM         *ep_param
  21     )
  22 .fi
  23
  24 .SH PARAMETERS
  25 .sp
  26 .ne 2
  27 .na
  28 \fB\fIep_handle\fR\fR
  29 .ad
  30 .RS 17n
  31 Handle for an instance of the Endpoint.
  32 .RE
  33
  34 .sp
  35 .ne 2
  36 .na
  37 \fB\fIep_param_mask\fR\fR
  38 .ad
  39 .RS 17n
  40 Mask for Endpoint parameters.
  41 .RE
  42
  43 .sp
  44 .ne 2
  45 .na
  46 \fB\fIep_param\fR\fR
  47 .ad
  48 .RS 17n
  49 Pointer to the Consumer-allocated structure that contains Consumer-requested
  50 Endpoint parameters.
  51 .RE
  52
  53 .SH DESCRIPTION
  54 .sp
  55 .LP
  56 The \fBdat_ep_modify()\fR function provides the Consumer a way to change
  57 parameters of an Endpoint.
  58 .sp
  59 .LP
  60 The \fIep_param_mask\fR parameter allows Consumers to specify which parameters
  61 to modify. Providers modify values for \fIep_param_mask\fR requested parameters
  62 only.
  63 .sp
  64 .LP
  65 Not all the parameters of the Endpoint can be modified. Some can be modified
  66 only when the Endpoint is in a specific state. The following list specifies
  67 which parameters can be modified and when they can be modified.
  68 .sp
  69 .ne 2
  70 .na
  71 \fBInterface Adapter\fR
  72 .ad
  73 .sp .6
  74 .RS 4n
  75 Cannot be modified.
  76 .sp
  77 Endpoint belongs to an open instance of IA and that association cannot be
  78 changed.
  79 .RE
  80
  81 .sp
  82 .ne 2
  83 .na
  84 \fBEndpoint State\fR
  85 .ad
  86 .sp .6
  87 .RS 4n
  88 Cannot be modified.
  89 .sp
  90 State of Endpoint cannot be changed by a \fBdat_ep_modify()\fR operation.
  91 .RE
  92
  93 .sp
  94 .ne 2
  95 .na
  96 \fBLocal IA Address\fR
  97 .ad
  98 .sp .6
  99 .RS 4n
 100 Cannot be modified.
 101 .sp
 102 Local IA Address cannot be changed by a \fBdat_ep_modify()\fR operation.
 103 .RE
 104
 105 .sp
 106 .ne 2
 107 .na
 108 \fBLocal Port Qualifier\fR
 109 .ad
 110 .sp .6
 111 .RS 4n
 112 Cannot be modified.
 113 .sp
 114 Local port qualifier cannot be changed by a \fBdat_ep_modify()\fR operation.
 115 .RE
 116
 117 .sp
 118 .ne 2
 119 .na
 120 \fBRemote IA Address\fR
 121 .ad
 122 .sp .6
 123 .RS 4n
 124 Cannot be modified.
 125 .sp
 126 Remote IA Address cannot be changed by a \fBdat_ep_modify()\fR operation.
 127 .RE
 128
 129 .sp
 130 .ne 2
 131 .na
 132 \fBRemote Port Qualifier\fR
 133 .ad
 134 .sp .6
 135 .RS 4n
 136 Cannot be modified.
 137 .sp
 138 Remote port qualifier cannot be changed by a \fBdat_ep_modify()\fR operation
 139 .RE
 140
 141 .sp
 142 .ne 2
 143 .na
 144 \fBProtection Zone\fR
 145 .ad
 146 .sp .6
 147 .RS 4n
 148 Can be modified when in Quiescent, Unconnected, and Tentative Connection
 149 Pending states.
 150 .sp
 151 Protection Zone can be changed only when the Endpoint is in quiescent state.
 152 The only Endpoint states that isare quiescent isare
 153 \fBDAT_EP_STATE_UNCONNECTED\fR and
 154 \fBDAT_EP_STATE_TENTATIVE_CONNECTION_PENDING\fR. Consumers should be aware that
 155 any Receive DTOs currently posted to the Endpoint that do not match the new
 156 Protection Zone fail with a \fBDAT_PROTECTION_VIOLATION\fR return.
 157 .RE
 158
 159 .sp
 160 .ne 2
 161 .na
 162 \fBIn DTO Event Dispatcher\fR
 163 .ad
 164 .sp .6
 165 .RS 4n
 166 Can be modified when in Unconnected, Reserved, Passive Connection Request
 167 Pending, and Tentative Connection Pending states.
 168 .sp
 169 Event Dispatcher for incoming DTOs (Receive) can be changed only prior to a
 170 request for a connection for an Active side or prior to accepting a Connection
 171 Request for a Passive side.
 172 .RE
 173
 174 .sp
 175 .ne 2
 176 .na
 177 \fBOut DTO Event Dispatcher\fR
 178 .ad
 179 .sp .6
 180 .RS 4n
 181 Can be modified when in Unconnected, Reserved, Passive Connection Pending, and
 182 Tentative Connection Pending states.
 183 .sp
 184 Event Dispatcher for outgoing DTOs (Send, RDMA Read, and RDMA Write) can be
 185 changed only prior to a request for a connection for an Active side or prior to
 186 accepting a Connection Request for a Passive side.
 187 .RE
 188
 189 .sp
 190 .ne 2
 191 .na
 192 \fBConnection Event Dispatcher\fR
 193 .ad
 194 .sp .6
 195 .RS 4n
 196 Can be modified when in Unconnected, Reserved, Passive Connection Pending, and
 197 Tentative Connection Pending states.
 198 .sp
 199 Event Dispatcher for the Endpoint Connection events can be changed only prior
 200 to a request for a connection for an Active side or accepting a Connection
 201 Request for a Passive side.
 202 .RE
 203
 204 .sp
 205 .ne 2
 206 .na
 207 \fBService Type\fR
 208 .ad
 209 .sp .6
 210 .RS 4n
 211 Can be modified when in Unconnected, Reserved, Passive Connection Pending, and
 212 Tentative Connection Pending states.
 213 .sp
 214 Service Type can be changed only prior to a request for a connection for an
 215 Active side or accepting a Connection Request for a Passive side.
 216 .RE
 217
 218 .sp
 219 .ne 2
 220 .na
 221 \fBMaximum Message Size\fR
 222 .ad
 223 .sp .6
 224 .RS 4n
 225 Can be modified when in Unconnected, Reserved, Passive Connection Request
 226 Pending, and Tentative Connection Pending states.
 227 .sp
 228 Maximum Message Size can be changed only prior to a request for a connection
 229 for an Active side or accepting a Connection Request for a Passive side.
 230 .RE
 231
 232 .sp
 233 .ne 2
 234 .na
 235 \fBMaximum RDMA Size\fR
 236 .ad
 237 .sp .6
 238 .RS 4n
 239 Can be modified when in Unconnected, Reserved, Passive Connection Pending, and
 240 Tentative Connection Pending states.
 241 .sp
 242 Maximum RDMA Size can be changed only prior to a request for a connection for
 243 an Active side or accepting a Connection Request for a Passive side.
 244 .RE
 245
 246 .sp
 247 .ne 2
 248 .na
 249 \fBQuality of Service\fR
 250 .ad
 251 .sp .6
 252 .RS 4n
 253 Can be modified when in Unconnected, Reserved, Passive Connection Pending, and
 254 Tentative Connection Pending states.
 255 .sp
 256 QoS can be changed only prior to a request for a connection for an Active side
 257 or accepting a Connection Request for a Passive side.
 258 .RE
 259
 260 .sp
 261 .ne 2
 262 .na
 263 \fBRecv Completion Flags\fR
 264 .ad
 265 .sp .6
 266 .RS 4n
 267 Can be modified when in Unconnected, Reserved, Passive Connection Pending, and
 268 Tentative Connection Pending states.
 269 .sp
 270 Recv Completion Flags specifies what DTO flags the Endpoint should support for
 271 Receive DTO operations. The value can be
 272 \fBDAT_COMPLETION_NOTIFICATION_SUPPRESS_FLAG\fR,
 273 \fBDAT_COMPLETION_SOLICITED_WAIT_FLAG\fR, or
 274 \fBDAT_COMPLETION_EVD_THRESHOLD_FLAG\fR. Recv posting does not support
 275 \fBDAT_COMPLETION_SUPPRESS_FLAG\fR or \fBDAT_COMPLETION_BARRIER_FENCE_FLAG\fR
 276 dat_completion_flags values that are only applicable to Request postings. Recv
 277 Completion Flags can be changed only prior to a request for a connection for an
 278 Active side or accepting a Connection Request for a Passive side, but before
 279 posting of any Recvs.
 280 .RE
 281
 282 .sp
 283 .ne 2
 284 .na
 285 \fBRequest Completion Flags\fR
 286 .ad
 287 .sp .6
 288 .RS 4n
 289 Can be modified when in Unconnected, Reserved, Passive Connection Request
 290 Pending, and Tentative Connection Pending states.
 291 .sp
 292 Request Completion Flags specifies what DTO flags the Endpoint should support
 293 for Send, RDMA Read, RDMA Write, and RMR Bind operations. The value can be:
 294 \fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR or
 295 \fBDAT_COMPLETION_EVD_THRESHOLD_FLAG\fR. Request postings always support
 296 \fBDAT_COMPLETION_SUPPRESS_FLAG\fR, \fBDAT_COMPLETION_SOLICITED_WAIT_FLAG\fR,
 297 or \fBDAT_COMPLETION_BARRIER_FENCE_FLAG\fR completion_flags values. Request
 298 Completion Flags can be changed only prior to a request for a connection for an
 299 Active side or accepting a Connection Request for a Passive side.
 300 .RE
 301
 302 .sp
 303 .ne 2
 304 .na
 305 \fBMaximum Recv DTO\fR
 306 .ad
 307 .sp .6
 308 .RS 4n
 309 Can be modified when in Unconnected, Reserved, Passive Connection Pending, and
 310 Tentative Connection Pending states.
 311 .sp
 312 Maximum Recv DTO specifies the maximum number of outstanding Consumer-submitted
 313 Receive DTOs that a Consumer expects at any time at the Endpoint. Maximum Recv
 314 DTO can be changed only prior to a request for a connection for an Active side
 315 or accepting a Connection Request for a Passive side.
 316 .RE
 317
 318 .sp
 319 .ne 2
 320 .na
 321 \fBMaximum Request DTO\fR
 322 .ad
 323 .sp .6
 324 .RS 4n
 325 Can be modified when in Unconnected, Reserved, Passive Connection Pending, and
 326 Tentative Connection Pending states.
 327 .sp
 328 Maximum Request DTO specifies the maximum number of outstanding
 329 Consumer-submitted send and RDMA DTOs and RMR Binds that a Consumer expects at
 330 any time at the Endpoint. Maximum Out DTO can be changed only prior to a
 331 request for a connection for an Active side or accepting a Connection Request
 332 for a Passive side.
 333 .RE
 334
 335 .sp
 336 .ne 2
 337 .na
 338 \fBMaximum Recv IOV\fR
 339 .ad
 340 .sp .6
 341 .RS 4n
 342 Can be modified when in Unconnected, Reserved, Passive Connection Pending, and
 343 Tentative Connection Pending states.
 344 .sp
 345 Maximum Recv IOV specifies the maximum number of elements in IOV that a
 346 Consumer specifies for posting a Receive DTO for the Endpoint. Maximum Recv IOV
 347 can be changed only prior to a request for a connection for an Active side or
 348 accepting a Connection Request for a Passive side.
 349 .RE
 350
 351 .sp
 352 .ne 2
 353 .na
 354 \fBMaximum Request IOV\fR
 355 .ad
 356 .sp .6
 357 .RS 4n
 358 Can be modified when in Unconnected, Reserved, Passive Connection Pending, and
 359 Tentative Connection Pending states.
 360 .sp
 361 Maximum Request IOV specifies the maximum number of elements in IOV that a
 362 Consumer specifies for posting a Send, RDMA Read, or RDMA Write DTO for the
 363 Endpoint. Maximum Request IOV can be changed only prior to a request for a
 364 connection for an Active side or accepting a Connection Request for a Passive
 365 side.
 366 .RE
 367
 368 .sp
 369 .ne 2
 370 .na
 371 \fBMaximum outstanding RDMA Read as target\fR
 372 .ad
 373 .sp .6
 374 .RS 4n
 375 Can be modified when in Unconnected, Reserved, Passive Connection Pending, and
 376 Tentative Connection Pending states.
 377 .sp
 378 Maximum number of outstanding RDMA Reads for which the Endpoint is the target.
 379 .RE
 380
 381 .sp
 382 .ne 2
 383 .na
 384 \fBMaximum outstanding RDMA Read as originator\fR
 385 .ad
 386 .sp .6
 387 .RS 4n
 388 Can be modified when in Unconnected, Reserved, Passive Connection Pending, and
 389 Tentative Connection Pending states.
 390 .sp
 391 Maximum number of outstanding RDMA Reads for which the Endpoint is the
 392 originator.
 393 .RE
 394
 395 .sp
 396 .ne 2
 397 .na
 398 \fBNum transport-specific attributes\fR
 399 .ad
 400 .sp .6
 401 .RS 4n
 402 Can be modified when in Quiescent (unconnected) state.
 403 .sp
 404 Number of transport-specific attributes to be modified.
 405 .RE
 406
 407 .sp
 408 .ne 2
 409 .na
 410 \fBTransport-specific endpoint attributes\fR
 411 .ad
 412 .sp .6
 413 .RS 4n
 414 Can be modified when in Quiescent (unconnected) state.
 415 .sp
 416 Transport-specific attributes can be modified only in the transport-defined
 417 Endpoint state. The only guaranteed safe state in which to modify
 418 transport-specific Endpoint attributes is the quiescent state
 419 \fBDAT_EP_STATE_UNCONNECTED\fR.
 420 .RE
 421
 422 .sp
 423 .ne 2
 424 .na
 425 \fBNum provider-specific attributes\fR
 426 .ad
 427 .sp .6
 428 .RS 4n
 429 Can be modified when in Quiescent (unconnected) state.
 430 .sp
 431  Number of Provider-specific attributes to be modified.
 432 .RE
 433
 434 .sp
 435 .ne 2
 436 .na
 437 \fBProvider-specific endpoint attributes\fR
 438 .ad
 439 .sp .6
 440 .RS 4n
 441 Can be modified when in Quiescent (unconnected) state.
 442 .sp
 443 Provider-specific attributes can be modified only in the Provider-defined
 444 Endpoint state. The only guaranteed safe state in which to modify
 445 Provider-specific Endpoint attributes is the quiescent state
 446 \fBDAT_EP_STATE_UNCONNECTED\fR.
 447 .RE
 448
 449 .SH RETURN VALUES
 450 .sp
 451 .ne 2
 452 .na
 453 \fB\fBDAT_SUCCESS\fR\fR
 454 .ad
 455 .RS 25n
 456 The operation was successful.
 457 .RE
 458
 459 .sp
 460 .ne 2
 461 .na
 462 \fB\fBDAT_INVALID_HANDLE\fR\fR
 463 .ad
 464 .RS 25n
 465 The \fIep_handle\fR parameter is invalid.
 466 .RE
 467
 468 .sp
 469 .ne 2
 470 .na
 471 \fB\fBDAT_INVALID_PARAMETER\fR\fR
 472 .ad
 473 .RS 25n
 474 The \fIep_param_mask\fR parameter is invalid, or one of the requested Endpoint
 475 parameters or attributes was invalid, not supported, or cannot be modified.
 476 .RE
 477
 478 .sp
 479 .ne 2
 480 .na
 481 \fB\fBDAT_INVALID_STATE\fR\fR
 482 .ad
 483 .RS 25n
 484 Parameter in an invalid state. The Endpoint was not in the state that allows
 485 one of the parameters or attributes to be modified.
 486 .RE
 487
 488 .SH ATTRIBUTES
 489 .sp
 490 .LP
 491 See \fBattributes\fR(5) for descriptions of the following attributes:
 492 .sp
 493
 494 .sp
 495 .TS
 496 box;
 497 c | c
 498 l | l .
 499 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 500 _
 501 Interface Stability     Standard: uDAPL, 1.1, 1.2
 502 _
 503 MT-Level        Unsafe
 504 .TE
 505
 506 .SH SEE ALSO
 507 .sp
 508 .LP
 509 \fBlibdat\fR(3LIB), \fBattributes\fR(5)