1 DAT_IA_QUERY(3DAT)                   Direct Access Transport Library Functions
   2 
   3 
   4 
   5 NAME
   6        dat_ia_query - query an IA
   7 
   8 SYNOPSIS
   9        cc [ flag... ] file... -ldat [ library... ]
  10        #include <dat/udat.h>
  11 
  12        DAT_RETURN
  13            dat_ia_query (
  14            IN    DAT_IA_HANDLE           ia_handle,
  15            OUT   DAT_EVD_HANDLE          *async_evd_handle,
  16            IN    DAT_IA_ATTR_MASK        ia_attr_mask,
  17            OUT   DAT_IA_ATTR             *ia_attributes,
  18            IN    DAT_PROVIDER_ATTR_MASK  provider_attr_mask,
  19            OUT   DAT_PROVIDER_ATTR       *provider_attributes
  20            )
  21 
  22 
  23 PARAMETERS
  24        ia_handle
  25                               Handle for an open instance of an IA.
  26 
  27 
  28        async_evd_handle
  29                               Handle for an Event Dispatcher for asynchronous
  30                               events generated by the IA.
  31 
  32 
  33        ia_attr_mask
  34                               Mask for the ia_attributes.
  35 
  36 
  37        ia_attributes
  38                               Pointer to a Consumer-allocated structure that
  39                               the Provider fills with IA attributes.
  40 
  41 
  42        provider_attr_mask
  43                               Mask for the provider_attributes.
  44 
  45 
  46        provider_attributes
  47                               Pointer to a Consumer-allocated structure that
  48                               the Provider fills with Provider attributes.
  49 
  50 
  51 DESCRIPTION
  52        The dat_ia_query() functions provides the Consumer with the IA
  53        parameters, as well as the IA and Provider attributes. Consumers pass
  54        in pointers to Consumer-allocated structures for the IA and Provider
  55        attributes that the Provider fills.
  56 
  57 
  58        The ia_attr_mask and provider_attr_mask parameters allow the Consumer
  59        to specify which attributes to query. The Provider returns values for
  60        requested attributes. The Provider can also return values for any of
  61        the other attributes.
  62 
  63    Interface Adapter Attributes
  64        The IA attributes are common to all open instances of the IA. DAT
  65        defines a method to query the IA attributes but does not define a
  66        method to modify them.
  67 
  68 
  69        If IA is multiported, each port is presented to a Consumer as a
  70        separate IA.
  71 
  72        Adapter name:
  73 
  74            The name of the IA controlled by the Provider. The same as
  75            ia_name_ptr.
  76 
  77 
  78        Vendor name:
  79 
  80            Vendor if IA hardware.
  81 
  82 
  83        HW version major:
  84 
  85            Major version of IA hardware.
  86 
  87 
  88        HW version minor:
  89 
  90            Minor version of IA hardware.
  91 
  92 
  93        Firmware version major:
  94 
  95            Major version of IA firmware.
  96 
  97 
  98        Firmware version minor:
  99 
 100            Minor version of IA firmware.
 101 
 102 
 103        IA_address_ptr:
 104 
 105            An address of the interface Adapter.
 106 
 107 
 108        Max EPs:
 109 
 110            Maximum number of Endpoints that the IA can support. This covers
 111            all Endpoints in all states, including the ones used by the
 112            Providers, zero or more applications, and management.
 113 
 114 
 115        Max DTOs per EP:
 116 
 117            Maximum number of DTOs and RMR_binds that any Endpoint can support
 118            for a single direction. This means the maximum number of
 119            outstanding and in-progress Send, RDMA Read, RDMA Write DTOs, and
 120            RMR Binds at any one time for any Endpoint; and maximum number of
 121            outstanding and in-progress Receive DTOs at any one time for any
 122            Endpoint.
 123 
 124 
 125        Max incoming RDMA Reads per EP:
 126 
 127            Maximum number of RDMA Reads that can be outstanding per
 128            (connected) Endpoint with the IA as the target.
 129 
 130 
 131        Max outgoing RDMA Reads per EP:
 132 
 133            Maximum number of RDMA Reads that can be outstanding per
 134            (connected) Endpoint with the IA as the originator.
 135 
 136 
 137        Max EVDs:
 138 
 139            Maximum number of Event Dispatchers that an IA can support. An IA
 140            cannot support an Event Dispatcher directly, but indirectly by
 141            Transport-specific Objects, for example, Completion Queues for
 142            Infinibandtm and VI. The Event Dispatcher Objects can be shared
 143            among multiple Providers and similar Objects from other APIs, for
 144            example, Event Queues for uDAPL.
 145 
 146 
 147        Max EVD queue size:
 148 
 149            Maximum size of the EVD queue supported by an IA.
 150 
 151 
 152        Max IOV segments per DTO:
 153 
 154            Maximum entries in an IOV list that an IA supports. Notice that
 155            this number cannot be explicit but must be implicit to transport-
 156            specific Object entries.  For example, for IB, it is the maximum
 157            number of scatter/gather entries per Work Request, and for VI it is
 158            the maximum number of data segments per VI Descriptor.
 159 
 160 
 161        Max LMRs:
 162 
 163            Maximum number of Local Memory Regions IA supports among all
 164            Providers and applications of this IA.
 165 
 166 
 167        Max LMR block size:
 168 
 169            Maximum contiguous block that can be registered by the IA.
 170 
 171 
 172        Mac LMR VA:
 173 
 174            Highest valid virtual address within the context of an LMR.
 175            Frequently, IAs on 32-bit architectures support only 32-bit local
 176            virtual addresses.
 177 
 178 
 179        Max PZs:
 180 
 181            Maximum number of Protection Zones that the IA supports.
 182 
 183 
 184        Max MTU size:
 185 
 186            Maximum message size supported by the IA
 187 
 188 
 189        Max RDMA size:
 190 
 191            Maximum RDMA size supported by the IA
 192 
 193 
 194        Max RMRs:
 195 
 196            Maximum number of RMRs an IA supports among all Providers and
 197            applications of this IA.
 198 
 199 
 200        Max RMR target address:
 201 
 202            Highest valid target address with the context of a local RMR.
 203            Frequently, IAs on 32-bit architectures support only 32-bit local
 204            virtual addresses.
 205 
 206 
 207        Num transport attributes:
 208 
 209            Number of transport-specific attributes.
 210 
 211 
 212        Transport-specific attributes:
 213 
 214            Array of transport-specific attributes. Each entry has the format
 215            of DAT_NAMED_ATTR, which is a structure with two elements. The
 216            first element is the name of the attribute. The second element is
 217            the value of the attribute as a string.
 218 
 219 
 220        Num vendor attributes:
 221 
 222            Number of vendor-specific attributes.
 223 
 224 
 225        Vendor-specific attributes:
 226 
 227            Array of vendor-specific attributes. Each entry has the format of
 228            DAT_NAMED_ATTR, which is a structure with two elements. The first
 229            element is the name of the attribute. The second element is the
 230            value of the attribute as a string.
 231 
 232 
 233    DAPL Provider Attributes
 234        The provider attributes are specific to the open instance of the IA.
 235        DAT defines a method to query Provider attributes but does not define a
 236        method to modify them.
 237 
 238        Provider name:
 239 
 240            Name of the Provider vendor.
 241 
 242 
 243        Provider version major:
 244 
 245            Major Version of uDAPL Provider.
 246 
 247 
 248        Provider version minor:
 249 
 250            Minor Version of uDAPL Provider.
 251 
 252 
 253        DAPL API version major:
 254 
 255            Major Version of uDAPL API supported.
 256 
 257 
 258        DAPL API version minor:
 259 
 260            Minor Version of uDAPL API supported.
 261 
 262 
 263        LMR memory types supported:
 264 
 265            Memory types that LMR Create supports for memory registration. This
 266            value is a union of LMR Memory Types DAT_MEM_TYPE_VIRTUAL,
 267            DAT_MEM_TYPE_LMR, and DAT_MEM_TYPE_SHARED_VIRTUAL that the Provider
 268            supports. All Providers must support the following Memory Types:
 269            DAT_MEM_TYPE_VIRTUAL, DAT_MEM_TYPE_LMR, and
 270            DAT_MEM_TYPE_SHARED_VIRTUAL.
 271 
 272 
 273        IOV ownership:
 274 
 275            An enumeration flag that specifies the ownership of the local
 276            buffer description (IOV list) after post DTO returns. The three
 277            values are as follows:
 278 
 279                o      DAT_IOV_CONSUMER indicates that the Consumer has the
 280                       ownership of the local buffer description after a post
 281                       returns.
 282 
 283                o      DAT_IOV_PROVIDER_NOMOD indicates that the Provider still
 284                       has ownership of the local buffer description of the DTO
 285                       when the post DTO returns, but the Provider does not
 286                       modify the buffer description.
 287 
 288                o      DAT_IOV_PROVIDER_MOD indicates that the Provider still
 289                       has ownership of the local buffer description of the DTO
 290                       when the post DTO returns and can modify the buffer
 291                       description.
 292            In any case, the Consumer obtains ownership of the local buffer
 293            description after the DTO transfer is completed and the Consumer is
 294            notified through a DTO completion event.
 295 
 296 
 297        QOS supported:
 298 
 299            The union of the connection QOS supported by the Provider.
 300 
 301 
 302        Completion flags supported:
 303 
 304            The following values for the completion flag DAT_COMPLETION_FLAGS
 305            are supported by the Provider: DAT_COMPLETION_SUPPRESS_FLAG,
 306            DAT_COMPLETION_UNSIGNALLED_FLAG,
 307            DAT_COMPLETION_SOLICITED_WAIT_FLAG, and
 308            DAT_COMPLETION_BARRIER_FENCE_FLAG.
 309 
 310 
 311        Thread safety:
 312 
 313            Provider Library thread safe or not. The Provider Library is not
 314            required to be thread safe.
 315 
 316 
 317        Max private data size:
 318 
 319            Maximum size of private data the Provider supports. This value is
 320            at least 64 bytes.
 321 
 322 
 323        Multipathing support:
 324 
 325            Capability of the Provider to support Multipathing for connection
 326            establishment.
 327 
 328 
 329        EP creator for PSP:
 330 
 331            Indicator for who can create an Endpoint for a Connection Request.
 332            For the Consumer it is DAT_PSP_CREATES_EP_NEVER. For the Provider
 333            it is DAT_PSP_CREATES_EP_ALWAYS. For both it is
 334            DAT_PSP_CREATES_EP_IFASKED. This attribute is used for Public
 335            Service Point creation.
 336 
 337 
 338        PZ support:
 339 
 340            Indicator of what kind of protection the Provider's PZ provides.
 341 
 342 
 343        Optimal Buffer Alignment:
 344 
 345            Local and remote DTO buffer alignment for optimal performance on
 346            the Platform.  The DAT_OPTIMAL_ALIGNMENT must be divisible by this
 347            attribute value. The maximum allowed value is
 348            DAT_OPTIMAL_ALIGNMENT, or 256.
 349 
 350 
 351        EVD stream merging support:
 352 
 353            A 2D binary matrix where each row and column represent an event
 354            stream type.  Each binary entry is 1 if the event streams of its
 355            row and column can be fed to the same EVD, and 0 otherwise.
 356 
 357            More than two different event stream types can feed the same EVD if
 358            for each pair of the event stream types the entry is 1.
 359 
 360            The Provider should support merging of all event stream types.
 361 
 362            The Consumer should check this attribute before requesting an EVD
 363            that merges multiple event stream types.
 364 
 365 
 366        Num provider attributes:
 367 
 368            Number of Provider-specific attributes.
 369 
 370 
 371        Provider-specific attributes:
 372 
 373            Array of Provider-specific attributes. Each entry has the format of
 374            DAT_NAMED_ATTR, which is a structure with two elements. The first
 375            element is the name of the attribute. The second element is the
 376            value of the attribute as a string.
 377 
 378 
 379 RETURN VALUES
 380        DAT_SUCCESS
 381                                 The operation was successful.
 382 
 383 
 384        DAT_INVALID_PARAMETER
 385                                 Invalid parameter;
 386 
 387 
 388        DAT_INVALID_HANDLE
 389                                 Invalid DAT handle; ia_handle is invalid.
 390 
 391 
 392 ATTRIBUTES
 393        See attributes(5) for descriptions of the following attributes:
 394 
 395 
 396 
 397 
 398        +--------------------+---------------------------+
 399        |  ATTRIBUTE TYPE    |      ATTRIBUTE VALUE      |
 400        +--------------------+---------------------------+
 401        |Interface Stability | Standard: uDAPL, 1.1, 1.2 |
 402        +--------------------+---------------------------+
 403        |MT-Level            | Safe                      |
 404        +--------------------+---------------------------+
 405 
 406 SEE ALSO
 407        libdat(3LIB), attributes(5)
 408 
 409 
 410 
 411                                  July 16, 2004              DAT_IA_QUERY(3DAT)