lnet/include/uapi/linux/lnet/lnet-types.h

   1 /*
   2  * GPL HEADER START
   3  *
   4  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   5  *
   6  * This program is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License version 2 only,
   8  * as published by the Free Software Foundation.
   9  *
  10  * This program is distributed in the hope that it will be useful, but
  11  * WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * General Public License version 2 for more details (a copy is included
  14  * in the LICENSE file that accompanied this code).
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * version 2 along with this program; If not, see
  18  * http://www.gnu.org/licenses/gpl-2.0.html
  19  *
  20  * GPL HEADER END
  21  */
  22 /*
  23  * Copyright (c) 2003, 2010, Oracle and/or its affiliates. All rights reserved.
  24  * Use is subject to license terms.
  25  *
  26  * Copyright (c) 2012, 2017, Intel Corporation.
  27  */
  28 /*
  29  * This file is part of Lustre, http://www.lustre.org/
  30  * Lustre is a trademark of Sun Microsystems, Inc.
  31  */
  32
  33 #ifndef __UAPI_LNET_TYPES_H__
  34 #define __UAPI_LNET_TYPES_H__
  35
  36 /** \addtogroup lnet
  37  * @{ */
  38
  39 #include <linux/types.h>
  40 /** \addtogroup lnet_addr
  41  * @{ */
  42
  43 #define LNET_VERSION            "0.7.0"
  44
  45 /** Portal reserved for LNet's own use.
  46  * \see lustre/include/lustre/lustre_idl.h for Lustre portal assignments.
  47  */
  48 #define LNET_RESERVED_PORTAL      0
  49
  50 /**
  51  * Address of an end-point in an LNet network.
  52  *
  53  * A node can have multiple end-points and hence multiple addresses.
  54  * An LNet network can be a simple network (e.g. tcp0) or a network of
  55  * LNet networks connected by LNet routers. Therefore an end-point address
  56  * has two parts: network ID, and address within a network.
  57  *
  58  * \see LNET_NIDNET, LNET_NIDADDR, and LNET_MKNID.
  59  */
  60 typedef __u64 lnet_nid_t;
  61
  62 /**
  63  * ID of a process in a node. Shortened as PID to distinguish from
  64  * lnet_process_id, the global process ID.
  65  */
  66 typedef __u32 lnet_pid_t;
  67
  68 /** wildcard NID that matches any end-point address */
  69 #define LNET_NID_ANY      ((lnet_nid_t) -1)
  70 /** wildcard PID that matches any lnet_pid_t */
  71 #define LNET_PID_ANY      ((lnet_pid_t) -1)
  72
  73 #define LNET_PID_RESERVED 0xf0000000 /* reserved bits in PID */
  74 #define LNET_PID_USERFLAG 0x80000000 /* set in userspace peers */
  75 #define LNET_PID_LUSTRE 12345
  76
  77 /* how an LNET NID encodes net:address */
  78 /** extract the address part of an lnet_nid_t */
  79
  80 static inline __u32 LNET_NIDADDR(lnet_nid_t nid)
  81 {
  82         return nid & 0xffffffff;
  83 }
  84
  85 static inline __u32 LNET_NIDNET(lnet_nid_t nid)
  86 {
  87         return (nid >> 32) & 0xffffffff;
  88 }
  89
  90 static inline lnet_nid_t LNET_MKNID(__u32 net, __u32 addr)
  91 {
  92         return (((__u64)net) << 32) | addr;
  93 }
  94
  95 static inline __u32 LNET_NETNUM(__u32 net)
  96 {
  97         return net & 0xffff;
  98 }
  99
 100 static inline __u32 LNET_NETTYP(__u32 net)
 101 {
 102         return (net >> 16) & 0xffff;
 103 }
 104
 105 static inline __u32 LNET_MKNET(__u32 type, __u32 num)
 106 {
 107         return (type << 16) | num;
 108 }
 109
 110 /** The lolnd NID (i.e. myself) */
 111 #define LNET_NID_LO_0 LNET_MKNID(LNET_MKNET(LOLND, 0), 0)
 112
 113 #define LNET_NET_ANY LNET_NIDNET(LNET_NID_ANY)
 114
 115 #define WIRE_ATTR       __attribute__((packed))
 116
 117 /* Packed version of struct lnet_process_id to transfer via network */
 118 struct lnet_process_id_packed {
 119         lnet_nid_t nid;
 120         lnet_pid_t pid; /* node id / process id */
 121 } WIRE_ATTR;
 122
 123 /* The wire handle's interface cookie only matches one network interface in
 124  * one epoch (i.e. new cookie when the interface restarts or the node
 125  * reboots).  The object cookie only matches one object on that interface
 126  * during that object's lifetime (i.e. no cookie re-use). */
 127 struct lnet_handle_wire {
 128         __u64 wh_interface_cookie;
 129         __u64 wh_object_cookie;
 130 } WIRE_ATTR;
 131
 132 enum lnet_msg_type {
 133         LNET_MSG_ACK = 0,
 134         LNET_MSG_PUT,
 135         LNET_MSG_GET,
 136         LNET_MSG_REPLY,
 137         LNET_MSG_HELLO,
 138 };
 139
 140 /* The variant fields of the portals message header are aligned on an 8
 141  * byte boundary in the message header.  Note that all types used in these
 142  * wire structs MUST be fixed size and the smaller types are placed at the
 143  * end. */
 144 struct lnet_ack {
 145         struct lnet_handle_wire dst_wmd;
 146         __u64                   match_bits;
 147         __u32                   mlength;
 148 } WIRE_ATTR;
 149
 150 struct lnet_put {
 151         struct lnet_handle_wire ack_wmd;
 152         __u64                   match_bits;
 153         __u64                   hdr_data;
 154         __u32                   ptl_index;
 155         __u32                   offset;
 156 } WIRE_ATTR;
 157
 158 struct lnet_get {
 159         struct lnet_handle_wire return_wmd;
 160         __u64                   match_bits;
 161         __u32                   ptl_index;
 162         __u32                   src_offset;
 163         __u32                   sink_length;
 164 } WIRE_ATTR;
 165
 166 struct lnet_reply {
 167         struct lnet_handle_wire dst_wmd;
 168 } WIRE_ATTR;
 169
 170 struct lnet_hello {
 171         __u64                   incarnation;
 172         __u32                   type;
 173 } WIRE_ATTR;
 174
 175 struct lnet_hdr {
 176         lnet_nid_t      dest_nid;
 177         lnet_nid_t      src_nid;
 178         lnet_pid_t      dest_pid;
 179         lnet_pid_t      src_pid;
 180         __u32           type;           /* enum lnet_msg_type */
 181         __u32           payload_length; /* payload data to follow */
 182         /*<------__u64 aligned------->*/
 183         union {
 184                 struct lnet_ack         ack;
 185                 struct lnet_put         put;
 186                 struct lnet_get         get;
 187                 struct lnet_reply       reply;
 188                 struct lnet_hello       hello;
 189         } msg;
 190 } WIRE_ATTR;
 191
 192 /* A HELLO message contains a magic number and protocol version
 193  * code in the header's dest_nid, the peer's NID in the src_nid, and
 194  * LNET_MSG_HELLO in the type field.  All other common fields are zero
 195  * (including payload_size; i.e. no payload).
 196  * This is for use by byte-stream LNDs (e.g. TCP/IP) to check the peer is
 197  * running the same protocol and to find out its NID. These LNDs should
 198  * exchange HELLO messages when a connection is first established.  Individual
 199  * LNDs can put whatever else they fancy in lnet_hdr::msg.
 200  */
 201 struct lnet_magicversion {
 202         __u32   magic;          /* LNET_PROTO_TCP_MAGIC */
 203         __u16   version_major;  /* increment on incompatible change */
 204         __u16   version_minor;  /* increment on compatible change */
 205 } WIRE_ATTR;
 206
 207 /* PROTO MAGIC for LNDs */
 208 #define LNET_PROTO_IB_MAGIC             0x0be91b91
 209 #define LNET_PROTO_GNI_MAGIC            0xb00fbabe /* ask Kim */
 210 #define LNET_PROTO_TCP_MAGIC            0xeebc0ded
 211 #define LNET_PROTO_ACCEPTOR_MAGIC       0xacce7100
 212 #define LNET_PROTO_PING_MAGIC           0x70696E67 /* 'ping' */
 213
 214 /* Placeholder for a future "unified" protocol across all LNDs */
 215 /* Current LNDs that receive a request with this magic will respond
 216  * with a "stub" reply using their current protocol */
 217 #define LNET_PROTO_MAGIC                0x45726963 /* ! */
 218
 219 #define LNET_PROTO_TCP_VERSION_MAJOR    1
 220 #define LNET_PROTO_TCP_VERSION_MINOR    0
 221
 222 /* Acceptor connection request */
 223 struct lnet_acceptor_connreq {
 224         __u32   acr_magic;      /* PTL_ACCEPTOR_PROTO_MAGIC */
 225         __u32   acr_version;    /* protocol version */
 226         __u64   acr_nid;        /* target NID */
 227 } WIRE_ATTR;
 228
 229 #define LNET_PROTO_ACCEPTOR_VERSION     1
 230
 231 struct lnet_counters_common {
 232         __u32   lcc_msgs_alloc;
 233         __u32   lcc_msgs_max;
 234         __u32   lcc_errors;
 235         __u32   lcc_send_count;
 236         __u32   lcc_recv_count;
 237         __u32   lcc_route_count;
 238         __u32   lcc_drop_count;
 239         __u64   lcc_send_length;
 240         __u64   lcc_recv_length;
 241         __u64   lcc_route_length;
 242         __u64   lcc_drop_length;
 243 } WIRE_ATTR;
 244
 245 struct lnet_counters_health {
 246         __u32   lch_rst_alloc;
 247         __u32   lch_resend_count;
 248         __u32   lch_response_timeout_count;
 249         __u32   lch_local_interrupt_count;
 250         __u32   lch_local_dropped_count;
 251         __u32   lch_local_aborted_count;
 252         __u32   lch_local_no_route_count;
 253         __u32   lch_local_timeout_count;
 254         __u32   lch_local_error_count;
 255         __u32   lch_remote_dropped_count;
 256         __u32   lch_remote_error_count;
 257         __u32   lch_remote_timeout_count;
 258         __u32   lch_network_timeout_count;
 259 };
 260
 261 struct lnet_counters {
 262         struct lnet_counters_common lct_common;
 263         struct lnet_counters_health lct_health;
 264 };
 265
 266 #define LNET_NI_STATUS_UP       0x15aac0de
 267 #define LNET_NI_STATUS_DOWN     0xdeadface
 268 #define LNET_NI_STATUS_INVALID  0x00000000
 269
 270 struct lnet_ni_status {
 271         lnet_nid_t ns_nid;
 272         __u32      ns_status;
 273         __u32      ns_unused;
 274 } WIRE_ATTR;
 275
 276 /*
 277  * NB: value of these features equal to LNET_PROTO_PING_VERSION_x
 278  * of old LNet, so there shouldn't be any compatibility issue
 279  */
 280 #define LNET_PING_FEAT_INVAL            (0)             /* no feature */
 281 #define LNET_PING_FEAT_BASE             (1 << 0)        /* just a ping */
 282 #define LNET_PING_FEAT_NI_STATUS        (1 << 1)        /* return NI status */
 283 #define LNET_PING_FEAT_RTE_DISABLED     (1 << 2)        /* Routing enabled */
 284 #define LNET_PING_FEAT_MULTI_RAIL       (1 << 3)        /* Multi-Rail aware */
 285 #define LNET_PING_FEAT_DISCOVERY        (1 << 4)        /* Supports Discovery */
 286
 287 /*
 288  * All ping feature bits fit to hit the wire.
 289  * In lnet_assert_wire_constants() this is compared against its open-coded
 290  * value, and in lnet_ping_target_update() it is used to verify that no
 291  * unknown bits have been set.
 292  * New feature bits can be added, just be aware that this does change the
 293  * over-the-wire protocol.
 294  */
 295 #define LNET_PING_FEAT_BITS             (LNET_PING_FEAT_BASE | \
 296                                          LNET_PING_FEAT_NI_STATUS | \
 297                                          LNET_PING_FEAT_RTE_DISABLED | \
 298                                          LNET_PING_FEAT_MULTI_RAIL | \
 299                                          LNET_PING_FEAT_DISCOVERY)
 300
 301 struct lnet_ping_info {
 302         __u32                   pi_magic;
 303         __u32                   pi_features;
 304         lnet_pid_t              pi_pid;
 305         __u32                   pi_nnis;
 306         struct lnet_ni_status   pi_ni[0];
 307 } WIRE_ATTR;
 308
 309 #define LNET_PING_INFO_SIZE(NNIDS) \
 310         offsetof(struct lnet_ping_info, pi_ni[NNIDS])
 311 #define LNET_PING_INFO_LONI(PINFO)      ((PINFO)->pi_ni[0].ns_nid)
 312 #define LNET_PING_INFO_SEQNO(PINFO)     ((PINFO)->pi_ni[0].ns_status)
 313
 314 /*
 315  * This is a hard-coded limit on the number of interfaces supported by
 316  * the interface bonding implemented by the ksocknal LND. It must be
 317  * defined here because it is used in LNet data structures that are
 318  * common to all LNDs.
 319  */
 320 #define LNET_INTERFACES_NUM     16
 321
 322 /* The minimum number of interfaces per node supported by LNet. */
 323 #define LNET_INTERFACES_MIN     16
 324 /* The default - arbitrary - value of the lnet_max_interfaces tunable. */
 325 #define LNET_INTERFACES_MAX_DEFAULT     200
 326
 327 /**
 328  * Objects maintained by the LNet are accessed through handles. Handle types
 329  * have names of the form lnet_handle_xx, where xx is one of the two letter
 330  * object type codes ('md' for memory descriptor, and
 331  * 'me' for match entry). Each type of object is given a unique handle type
 332  * to enhance type checking.
 333  */
 334 #define LNET_WIRE_HANDLE_COOKIE_NONE   (-1)
 335
 336 struct lnet_handle_md {
 337         __u64   cookie;
 338 };
 339
 340 /**
 341  * Invalidate md handle \a h.
 342  */
 343 static inline void LNetInvalidateMDHandle(struct lnet_handle_md *h)
 344 {
 345         h->cookie = LNET_WIRE_HANDLE_COOKIE_NONE;
 346 }
 347
 348 /**
 349  * Check whether handler \a h is invalid.
 350  *
 351  * \return 1 if handle is invalid, 0 if valid.
 352  */
 353 static inline int LNetMDHandleIsInvalid(struct lnet_handle_md h)
 354 {
 355         return (LNET_WIRE_HANDLE_COOKIE_NONE == h.cookie);
 356 }
 357
 358 /**
 359  * Global process ID.
 360  */
 361 struct lnet_process_id {
 362         /** node id */
 363         lnet_nid_t nid;
 364         /** process id */
 365         lnet_pid_t pid;
 366 };
 367 /** @} lnet_addr */
 368
 369 /** \addtogroup lnet_me
 370  * @{ */
 371
 372 /**
 373  * Specifies whether the match entry or memory descriptor should be unlinked
 374  * automatically (LNET_UNLINK) or not (LNET_RETAIN).
 375  */
 376 enum lnet_unlink {
 377         LNET_RETAIN = 0,
 378         LNET_UNLINK
 379 };
 380
 381 /**
 382  * Values of the type enum lnet_ins_pos are used to control where a new match
 383  * entry is inserted. The value LNET_INS_BEFORE is used to insert the new
 384  * entry before the current entry or before the head of the list. The value
 385  * LNET_INS_AFTER is used to insert the new entry after the current entry
 386  * or after the last item in the list.
 387  */
 388 enum lnet_ins_pos {
 389         /** insert ME before current position or head of the list */
 390         LNET_INS_BEFORE,
 391         /** insert ME after current position or tail of the list */
 392         LNET_INS_AFTER,
 393         /** attach ME at tail of local CPU partition ME list */
 394         LNET_INS_LOCAL
 395 };
 396
 397 /** @} lnet_me */
 398
 399 /** \addtogroup lnet_md
 400  * @{ */
 401
 402 /**
 403  * Event queue handler function type.
 404  *
 405  * The EQ handler runs for each event that is deposited into the EQ. The
 406  * handler is supplied with a pointer to the event that triggered the
 407  * handler invocation.
 408  *
 409  * The handler must not block, must be reentrant, and must not call any LNet
 410  * API functions. It should return as quickly as possible.
 411  */
 412 struct lnet_event;
 413 typedef void (*lnet_handler_t)(struct lnet_event *event);
 414
 415 /**
 416  * Defines the visible parts of a memory descriptor. Values of this type
 417  * are used to initialize memory descriptors.
 418  */
 419 struct lnet_md {
 420         /**
 421          * Specify the memory region associated with the memory descriptor.
 422          * If the options field has:
 423          * - LNET_MD_KIOV bit set: The start field points to the starting
 424          * address of an array of struct bio_vec and the length field specifies
 425          * the number of entries in the array. The length can't be bigger
 426          * than LNET_MAX_IOV. The struct bio_vec is used to describe page-based
 427          * fragments that are not necessarily mapped in virtal memory.
 428          * - Otherwise: The memory region is contiguous. The start field
 429          * specifies the starting address for the memory region and the
 430          * length field specifies its length.
 431          *
 432          * When the memory region is fragmented, all fragments but the first
 433          * one must start on page boundary, and all but the last must end on
 434          * page boundary.
 435          */
 436         void            *start;
 437         unsigned int     length;
 438         /**
 439          * Specifies the maximum number of operations that can be performed
 440          * on the memory descriptor. An operation is any action that could
 441          * possibly generate an event. In the usual case, the threshold value
 442          * is decremented for each operation on the MD. When the threshold
 443          * drops to zero, the MD becomes inactive and does not respond to
 444          * operations. A threshold value of LNET_MD_THRESH_INF indicates that
 445          * there is no bound on the number of operations that may be applied
 446          * to a MD.
 447          */
 448         int              threshold;
 449         /**
 450          * Specifies the largest incoming request that the memory descriptor
 451          * should respond to. When the unused portion of a MD (length -
 452          * local offset) falls below this value, the MD becomes inactive and
 453          * does not respond to further operations. This value is only used
 454          * if the LNET_MD_MAX_SIZE option is set.
 455          */
 456         int              max_size;
 457         /**
 458          * Specifies the behavior of the memory descriptor. A bitwise OR
 459          * of the following values can be used:
 460          * - LNET_MD_OP_PUT: The LNet PUT operation is allowed on this MD.
 461          * - LNET_MD_OP_GET: The LNet GET operation is allowed on this MD.
 462          * - LNET_MD_MANAGE_REMOTE: The offset used in accessing the memory
 463          *   region is provided by the incoming request. By default, the
 464          *   offset is maintained locally. When maintained locally, the
 465          *   offset is incremented by the length of the request so that
 466          *   the next operation (PUT or GET) will access the next part of
 467          *   the memory region. Note that only one offset variable exists
 468          *   per memory descriptor. If both PUT and GET operations are
 469          *   performed on a memory descriptor, the offset is updated each time.
 470          * - LNET_MD_TRUNCATE: The length provided in the incoming request can
 471          *   be reduced to match the memory available in the region (determined
 472          *   by subtracting the offset from the length of the memory region).
 473          *   By default, if the length in the incoming operation is greater
 474          *   than the amount of memory available, the operation is rejected.
 475          * - LNET_MD_ACK_DISABLE: An acknowledgment should not be sent for
 476          *   incoming PUT operations, even if requested. By default,
 477          *   acknowledgments are sent for PUT operations that request an
 478          *   acknowledgment. Acknowledgments are never sent for GET operations.
 479          *   The data sent in the REPLY serves as an implicit acknowledgment.
 480          * - LNET_MD_KIOV: The start and length fields specify an array of
 481          *   struct bio_vec.
 482          * - LNET_MD_MAX_SIZE: The max_size field is valid.
 483          * - LNET_MD_BULK_HANDLE: The bulk_handle field is valid.
 484          * - LNET_MD_TRACK_RESPONSE: Enable response tracking on this MD
 485          *   regardless of the value of the lnet_response_tracking param.
 486          * - LNET_MD_NO_TRACK_RESPONSE: Disable response tracking on this MD
 487          *   regardless of the value of the lnet_response_tracking param.
 488          *
 489          * Note:
 490          * - LNET_MD_KIOV allows for a scatter/gather capability for memory
 491          *   descriptors.
 492          * - When LNET_MD_MAX_SIZE is set, the total length of the memory
 493          *   region (i.e. sum of all fragment lengths) must not be less than
 494          *   \a max_size.
 495          */
 496         unsigned int     options;
 497         /**
 498          * A user-specified value that is associated with the memory
 499          * descriptor. The value does not need to be a pointer, but must fit
 500          * in the space used by a pointer. This value is recorded in events
 501          * associated with operations on this MD.
 502          */
 503         void            *user_ptr;
 504         /**
 505          * The event handler used to log the operations performed on
 506          * the memory region. If this argument is NULL operations
 507          * performed on this memory descriptor are not logged.
 508          */
 509         lnet_handler_t  handler;
 510         /**
 511          * The bulk MD handle which was registered to describe the buffers
 512          * either to be used to transfer data to the peer or receive data
 513          * from the peer. This allows LNet to properly determine the NUMA
 514          * node on which the memory was allocated and use that to select the
 515          * nearest local network interface. This value is only used
 516          * if the LNET_MD_BULK_HANDLE option is set.
 517          */
 518         struct lnet_handle_md bulk_handle;
 519 };
 520
 521 /* Max Transfer Unit (minimum supported everywhere).
 522  * CAVEAT EMPTOR, with multinet (i.e. routers forwarding between networks)
 523  * these limits are system wide and not interface-local. */
 524 #define LNET_MTU_BITS   20
 525 #define LNET_MTU        (1 << LNET_MTU_BITS)
 526
 527 /**
 528  * Options for the MD structure. See struct lnet_md::options.
 529  */
 530 #define LNET_MD_OP_PUT               (1 << 0)
 531 /** See struct lnet_md::options. */
 532 #define LNET_MD_OP_GET               (1 << 1)
 533 /** See struct lnet_md::options. */
 534 #define LNET_MD_MANAGE_REMOTE        (1 << 2)
 535 /* unused                            (1 << 3) */
 536 /** See struct lnet_md::options. */
 537 #define LNET_MD_TRUNCATE             (1 << 4)
 538 /** See struct lnet_md::options. */
 539 #define LNET_MD_ACK_DISABLE          (1 << 5)
 540 /** See struct lnet_md::options. */
 541 /* deprecated #define LNET_MD_IOVEC  (1 << 6) */
 542 /** See struct lnet_md::options. */
 543 #define LNET_MD_MAX_SIZE             (1 << 7)
 544 /** See struct lnet_md::options. */
 545 #define LNET_MD_KIOV                 (1 << 8)
 546 /** See struct lnet_md::options. */
 547 #define LNET_MD_BULK_HANDLE          (1 << 9)
 548 /** See struct lnet_md::options. */
 549 #define LNET_MD_TRACK_RESPONSE       (1 << 10)
 550 /** See struct lnet_md::options. */
 551 #define LNET_MD_NO_TRACK_RESPONSE    (1 << 11)
 552
 553 /* For compatibility with Cray Portals */
 554 #define LNET_MD_PHYS                         0
 555
 556 /** Infinite threshold on MD operations. See struct lnet_md::threshold */
 557 #define LNET_MD_THRESH_INF       (-1)
 558
 559 /** @} lnet_md */
 560
 561 /** \addtogroup lnet_eq
 562  * @{ */
 563
 564 /**
 565  * Six types of events can be logged in an event queue.
 566  */
 567 enum lnet_event_kind {
 568         /** An incoming GET operation has completed on the MD. */
 569         LNET_EVENT_GET          = 1,
 570         /**
 571          * An incoming PUT operation has completed on the MD. The
 572          * underlying layers will not alter the memory (on behalf of this
 573          * operation) once this event has been logged.
 574          */
 575         LNET_EVENT_PUT,
 576         /**
 577          * A REPLY operation has completed. This event is logged after the
 578          * data (if any) from the REPLY has been written into the MD.
 579          */
 580         LNET_EVENT_REPLY,
 581         /** An acknowledgment has been received. */
 582         LNET_EVENT_ACK,
 583         /**
 584          * An outgoing send (PUT or GET) operation has completed. This event
 585          * is logged after the entire buffer has been sent and it is safe for
 586          * the caller to reuse the buffer.
 587          *
 588          * Note:
 589          * - The LNET_EVENT_SEND doesn't guarantee message delivery. It can
 590          *   happen even when the message has not yet been put out on wire.
 591          * - It's unsafe to assume that in an outgoing GET operation
 592          *   the LNET_EVENT_SEND event would happen before the
 593          *   LNET_EVENT_REPLY event. The same holds for LNET_EVENT_SEND and
 594          *   LNET_EVENT_ACK events in an outgoing PUT operation.
 595          */
 596         LNET_EVENT_SEND,
 597         /**
 598          * A MD has been unlinked. Note that LNetMDUnlink() does not
 599          * necessarily trigger an LNET_EVENT_UNLINK event.
 600          * \see LNetMDUnlink
 601          */
 602         LNET_EVENT_UNLINK,
 603 };
 604
 605 #define LNET_SEQ_GT(a, b)       (((signed long)((a) - (b))) > 0)
 606
 607 /**
 608  * Information about an event on a MD.
 609  */
 610 struct lnet_event {
 611         /** The identifier (nid, pid) of the target. */
 612         struct lnet_process_id   target;
 613         /** The identifier (nid, pid) of the initiator. */
 614         struct lnet_process_id   initiator;
 615         /** The source NID on the initiator. */
 616         struct lnet_process_id   source;
 617         /**
 618          * The NID of the immediate sender. If the request has been forwarded
 619          * by routers, this is the NID of the last hop; otherwise it's the
 620          * same as the source.
 621          */
 622         lnet_nid_t          sender;
 623         /** Indicates the type of the event. */
 624         enum lnet_event_kind    type;
 625         /** The portal table index specified in the request */
 626         unsigned int        pt_index;
 627         /** A copy of the match bits specified in the request. */
 628         __u64               match_bits;
 629         /** The length (in bytes) specified in the request. */
 630         unsigned int        rlength;
 631         /**
 632          * The length (in bytes) of the data that was manipulated by the
 633          * operation. For truncated operations, the manipulated length will be
 634          * the number of bytes specified by the MD (possibly with an offset,
 635          * see struct lnet_md). For all other operations, the manipulated length
 636          * will be the length of the requested operation, i.e. rlength.
 637          */
 638         unsigned int        mlength;
 639         /**
 640          * The handle to the MD associated with the event. The handle may be
 641          * invalid if the MD has been unlinked.
 642          */
 643         struct lnet_handle_md   md_handle;
 644         /**
 645          * A snapshot of relevant state of the MD immediately after the event
 646          * has been processed.
 647          */
 648         void                    *md_start;
 649         void                    *md_user_ptr;
 650         unsigned int            md_options;
 651         /**
 652          * 64 bits of out-of-band user data. Only valid for LNET_EVENT_PUT.
 653          * \see LNetPut
 654          */
 655         __u64               hdr_data;
 656         /**
 657          * The message type, to ensure a handler for LNET_EVENT_SEND can
 658          * distinguish between LNET_MSG_GET and LNET_MSG_PUT.
 659          */
 660         __u32               msg_type;
 661         /**
 662          * Indicates the completion status of the operation. It's 0 for
 663          * successful operations, otherwise it's an error code.
 664          */
 665         int                 status;
 666         /**
 667          * Indicates whether the MD has been unlinked. Note that:
 668          * - An event with unlinked set is the last event on the MD.
 669          * - This field is also set for an explicit LNET_EVENT_UNLINK event.
 670          * \see LNetMDUnlink
 671          */
 672         int                 unlinked;
 673         /**
 674          * The displacement (in bytes) into the memory region that the
 675          * operation used. The offset can be determined by the operation for
 676          * a remote managed MD or by the local MD.
 677          * \see struct lnet_md::options
 678          */
 679         unsigned int        offset;
 680         /**
 681          * The sequence number for this event. Sequence numbers are unique
 682          * to each event.
 683          */
 684         volatile unsigned long sequence;
 685 };
 686
 687 /** \addtogroup lnet_data
 688  * @{ */
 689
 690 /**
 691  * Specify whether an acknowledgment should be sent by target when the PUT
 692  * operation completes (i.e., when the data has been written to a MD of the
 693  * target process).
 694  *
 695  * \see struct lnet_md::options for the discussion on LNET_MD_ACK_DISABLE
 696  * by which acknowledgments can be disabled for a MD.
 697  */
 698 enum lnet_ack_req {
 699         /** Request an acknowledgment */
 700         LNET_ACK_REQ,
 701         /** Request that no acknowledgment should be generated. */
 702         LNET_NOACK_REQ
 703 };
 704 /** @} lnet_data */
 705
 706 /** @} lnet */
 707 #endif