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  */
  31
  32 #ifndef __UAPI_LNET_TYPES_H__
  33 #define __UAPI_LNET_TYPES_H__
  34
  35 #include <linux/string.h>
  36 #include <asm/byteorder.h>
  37
  38 /** \addtogroup lnet
  39  * @{ */
  40
  41 #include <linux/lnet/lnet-idl.h>
  42
  43 /** \addtogroup lnet_addr
  44  * @{ */
  45
  46 #define LNET_VERSION            "0.7.0"
  47
  48 /** Portal reserved for LNet's own use.
  49  * \see lustre/include/lustre/lustre_idl.h for Lustre portal assignments.
  50  */
  51 #define LNET_RESERVED_PORTAL      0
  52
  53 /** wildcard NID that matches any end-point address */
  54 #define LNET_NID_ANY      ((lnet_nid_t) -1)
  55 /** wildcard PID that matches any lnet_pid_t */
  56 #define LNET_PID_ANY      ((lnet_pid_t) -1)
  57
  58 static inline int LNET_NID_IS_ANY(const struct lnet_nid *nid)
  59 {
  60         /* A NULL pointer can be used to mean "ANY" */
  61         return !nid || nid->nid_type == 0xFF;
  62 }
  63
  64 #define LNET_ANY_NID ((struct lnet_nid)                 \
  65                       {0xFF, 0xFF, ~0, {~0, ~0, ~0, ~0} })
  66
  67 #define LNET_PID_RESERVED 0xf0000000 /* reserved bits in PID */
  68 #define LNET_PID_USERFLAG 0x80000000 /* set in userspace peers */
  69 #define LNET_PID_LUSTRE 12345
  70
  71 /* how an LNET NID encodes net:address */
  72 /** extract the address part of an lnet_nid_t */
  73
  74 static inline __u32 LNET_NIDADDR(lnet_nid_t nid)
  75 {
  76         return nid & 0xffffffff;
  77 }
  78
  79 static inline __u32 LNET_NIDNET(lnet_nid_t nid)
  80 {
  81         return (nid >> 32) & 0xffffffff;
  82 }
  83
  84 static inline lnet_nid_t LNET_MKNID(__u32 net, __u32 addr)
  85 {
  86         return (((__u64)net) << 32) | addr;
  87 }
  88
  89 static inline __u32 LNET_NETNUM(__u32 net)
  90 {
  91         return net & 0xffff;
  92 }
  93
  94 static inline __u32 LNET_NETTYP(__u32 net)
  95 {
  96         return (net >> 16) & 0xff;
  97 }
  98
  99 static inline __u32 LNET_MKNET(__u32 type, __u32 num)
 100 {
 101         return (type << 16) | num;
 102 }
 103
 104 /** The lolnd NID (i.e. myself) */
 105 #define LNET_NID_LO_0 LNET_MKNID(LNET_MKNET(LOLND, 0), 0)
 106
 107 #define LNET_NET_ANY LNET_NIDNET(LNET_NID_ANY)
 108
 109 static inline int nid_is_nid4(const struct lnet_nid *nid)
 110 {
 111         return NID_ADDR_BYTES(nid) == 4;
 112 }
 113
 114 /* LOLND may not be defined yet, so we cannot use an inline */
 115 #define nid_is_lo0(__nid)                                               \
 116         ((__nid)->nid_type == LOLND &&                                  \
 117          nid_is_nid4(__nid) &&                                          \
 118          (__nid)->nid_num == 0 &&                                       \
 119          (__nid)->nid_addr[0] == 0)
 120
 121 static inline __u32 LNET_NID_NET(const struct lnet_nid *nid)
 122 {
 123         return LNET_MKNET(nid->nid_type, __be16_to_cpu(nid->nid_num));
 124 }
 125
 126 static inline void lnet_nid4_to_nid(lnet_nid_t nid4, struct lnet_nid *nid)
 127 {
 128         if (nid4 == LNET_NID_ANY) {
 129                 /* equal to setting to LNET_ANY_NID */
 130                 memset(nid, 0xff, sizeof(*nid));
 131                 return;
 132         }
 133
 134         nid->nid_size = 0;
 135         nid->nid_type = LNET_NETTYP(LNET_NIDNET(nid4));
 136         nid->nid_num = __cpu_to_be16(LNET_NETNUM(LNET_NIDNET(nid4)));
 137         nid->nid_addr[0] = __cpu_to_be32(LNET_NIDADDR(nid4));
 138         nid->nid_addr[1] = nid->nid_addr[2] = nid->nid_addr[3] = 0;
 139 }
 140
 141 static inline lnet_nid_t lnet_nid_to_nid4(const struct lnet_nid *nid)
 142 {
 143         if (LNET_NID_IS_ANY(nid))
 144                 return LNET_NID_ANY;
 145
 146         return LNET_MKNID(LNET_NID_NET(nid), __be32_to_cpu(nid->nid_addr[0]));
 147 }
 148
 149 static inline int nid_same(const struct lnet_nid *n1,
 150                             const struct lnet_nid *n2)
 151 {
 152         return n1->nid_size == n2->nid_size &&
 153                 n1->nid_type == n2->nid_type &&
 154                 n1->nid_num == n2->nid_num &&
 155                 n1->nid_addr[0] == n2->nid_addr[0] &&
 156                 n1->nid_addr[1] == n2->nid_addr[1] &&
 157                 n1->nid_addr[2] == n2->nid_addr[2] &&
 158                 n1->nid_addr[3] == n2->nid_addr[3];
 159 }
 160
 161 /* This can be used when we need to hash a nid */
 162 static inline unsigned long nidhash(lnet_nid_t nid)
 163 {
 164         unsigned long hash = 0;
 165
 166         hash ^= LNET_NIDNET(nid);
 167         hash ^= LNET_NIDADDR(nid);
 168         return hash;
 169 }
 170
 171 struct lnet_counters_health {
 172         __u32   lch_rst_alloc;
 173         __u32   lch_resend_count;
 174         __u32   lch_response_timeout_count;
 175         __u32   lch_local_interrupt_count;
 176         __u32   lch_local_dropped_count;
 177         __u32   lch_local_aborted_count;
 178         __u32   lch_local_no_route_count;
 179         __u32   lch_local_timeout_count;
 180         __u32   lch_local_error_count;
 181         __u32   lch_remote_dropped_count;
 182         __u32   lch_remote_error_count;
 183         __u32   lch_remote_timeout_count;
 184         __u32   lch_network_timeout_count;
 185 };
 186
 187 struct lnet_counters {
 188         struct lnet_counters_common lct_common;
 189         struct lnet_counters_health lct_health;
 190 };
 191
 192 /*
 193  * This is a hard-coded limit on the number of interfaces supported by
 194  * the interface bonding implemented by the ksocknal LND. It must be
 195  * defined here because it is used in LNet data structures that are
 196  * common to all LNDs.
 197  */
 198 #define LNET_INTERFACES_NUM     16
 199
 200 /* The minimum number of interfaces per node supported by LNet. */
 201 #define LNET_INTERFACES_MIN     16
 202 /* The default - arbitrary - value of the lnet_max_interfaces tunable. */
 203 #define LNET_INTERFACES_MAX_DEFAULT     200
 204
 205 /**
 206  * Objects maintained by the LNet are accessed through handles. Handle types
 207  * have names of the form lnet_handle_xx, where xx is one of the two letter
 208  * object type codes ('md' for memory descriptor, and
 209  * 'me' for match entry). Each type of object is given a unique handle type
 210  * to enhance type checking.
 211  */
 212 #define LNET_WIRE_HANDLE_COOKIE_NONE   (~0ULL)
 213
 214 struct lnet_handle_md {
 215         __u64   cookie;
 216 };
 217
 218 /**
 219  * Invalidate md handle \a h.
 220  */
 221 static inline void LNetInvalidateMDHandle(struct lnet_handle_md *h)
 222 {
 223         h->cookie = LNET_WIRE_HANDLE_COOKIE_NONE;
 224 }
 225
 226 /**
 227  * Check whether handler \a h is invalid.
 228  *
 229  * \return 1 if handle is invalid, 0 if valid.
 230  */
 231 static inline int LNetMDHandleIsInvalid(struct lnet_handle_md h)
 232 {
 233         return (LNET_WIRE_HANDLE_COOKIE_NONE == h.cookie);
 234 }
 235
 236 /**
 237  * Global process ID.
 238  */
 239 struct lnet_process_id {
 240         /** node id */
 241         lnet_nid_t nid;
 242         /** process id */
 243         lnet_pid_t pid;
 244 };
 245 /** @} lnet_addr */
 246
 247 /** \addtogroup lnet_me
 248  * @{ */
 249
 250 /**
 251  * Specifies whether the match entry or memory descriptor should be unlinked
 252  * automatically (LNET_UNLINK) or not (LNET_RETAIN).
 253  */
 254 enum lnet_unlink {
 255         LNET_RETAIN = 0,
 256         LNET_UNLINK
 257 };
 258
 259 /**
 260  * Values of the type enum lnet_ins_pos are used to control where a new match
 261  * entry is inserted. The value LNET_INS_BEFORE is used to insert the new
 262  * entry before the current entry or before the head of the list. The value
 263  * LNET_INS_AFTER is used to insert the new entry after the current entry
 264  * or after the last item in the list.
 265  */
 266 enum lnet_ins_pos {
 267         /** insert ME before current position or head of the list */
 268         LNET_INS_BEFORE,
 269         /** insert ME after current position or tail of the list */
 270         LNET_INS_AFTER,
 271         /** attach ME at tail of local CPU partition ME list */
 272         LNET_INS_LOCAL
 273 };
 274
 275 /** @} lnet_me */
 276
 277 /** \addtogroup lnet_md
 278  * @{ */
 279
 280 /**
 281  * Event queue handler function type.
 282  *
 283  * The EQ handler runs for each event that is deposited into the EQ. The
 284  * handler is supplied with a pointer to the event that triggered the
 285  * handler invocation.
 286  *
 287  * The handler must not block, must be reentrant, and must not call any LNet
 288  * API functions. It should return as quickly as possible.
 289  */
 290 struct lnet_event;
 291 typedef void (*lnet_handler_t)(struct lnet_event *event);
 292
 293 /**
 294  * Defines the visible parts of a memory descriptor. Values of this type
 295  * are used to initialize memory descriptors.
 296  */
 297 struct lnet_md {
 298         /**
 299          * Specify the memory region associated with the memory descriptor.
 300          * If the options field has:
 301          * - LNET_MD_KIOV bit set: The start field points to the starting
 302          * address of an array of struct bio_vec and the length field specifies
 303          * the number of entries in the array. The length can't be bigger
 304          * than LNET_MAX_IOV. The struct bio_vec is used to describe page-based
 305          * fragments that are not necessarily mapped in virtal memory.
 306          * - Otherwise: The memory region is contiguous. The start field
 307          * specifies the starting address for the memory region and the
 308          * length field specifies its length.
 309          *
 310          * When the memory region is fragmented, all fragments but the first
 311          * one must start on page boundary, and all but the last must end on
 312          * page boundary.
 313          */
 314         void            *start;
 315         unsigned int     length;
 316         /**
 317          * Specifies the maximum number of operations that can be performed
 318          * on the memory descriptor. An operation is any action that could
 319          * possibly generate an event. In the usual case, the threshold value
 320          * is decremented for each operation on the MD. When the threshold
 321          * drops to zero, the MD becomes inactive and does not respond to
 322          * operations. A threshold value of LNET_MD_THRESH_INF indicates that
 323          * there is no bound on the number of operations that may be applied
 324          * to a MD.
 325          */
 326         int              threshold;
 327         /**
 328          * Specifies the largest incoming request that the memory descriptor
 329          * should respond to. When the unused portion of a MD (length -
 330          * local offset) falls below this value, the MD becomes inactive and
 331          * does not respond to further operations. This value is only used
 332          * if the LNET_MD_MAX_SIZE option is set.
 333          */
 334         int              max_size;
 335         /**
 336          * Specifies the behavior of the memory descriptor. A bitwise OR
 337          * of the following values can be used:
 338          * - LNET_MD_OP_PUT: The LNet PUT operation is allowed on this MD.
 339          * - LNET_MD_OP_GET: The LNet GET operation is allowed on this MD.
 340          * - LNET_MD_MANAGE_REMOTE: The offset used in accessing the memory
 341          *   region is provided by the incoming request. By default, the
 342          *   offset is maintained locally. When maintained locally, the
 343          *   offset is incremented by the length of the request so that
 344          *   the next operation (PUT or GET) will access the next part of
 345          *   the memory region. Note that only one offset variable exists
 346          *   per memory descriptor. If both PUT and GET operations are
 347          *   performed on a memory descriptor, the offset is updated each time.
 348          * - LNET_MD_TRUNCATE: The length provided in the incoming request can
 349          *   be reduced to match the memory available in the region (determined
 350          *   by subtracting the offset from the length of the memory region).
 351          *   By default, if the length in the incoming operation is greater
 352          *   than the amount of memory available, the operation is rejected.
 353          * - LNET_MD_ACK_DISABLE: An acknowledgment should not be sent for
 354          *   incoming PUT operations, even if requested. By default,
 355          *   acknowledgments are sent for PUT operations that request an
 356          *   acknowledgment. Acknowledgments are never sent for GET operations.
 357          *   The data sent in the REPLY serves as an implicit acknowledgment.
 358          * - LNET_MD_KIOV: The start and length fields specify an array of
 359          *   struct bio_vec.
 360          * - LNET_MD_MAX_SIZE: The max_size field is valid.
 361          * - LNET_MD_BULK_HANDLE: The bulk_handle field is valid.
 362          * - LNET_MD_TRACK_RESPONSE: Enable response tracking on this MD
 363          *   regardless of the value of the lnet_response_tracking param.
 364          * - LNET_MD_NO_TRACK_RESPONSE: Disable response tracking on this MD
 365          *   regardless of the value of the lnet_response_tracking param.
 366          *
 367          * Note:
 368          * - LNET_MD_KIOV allows for a scatter/gather capability for memory
 369          *   descriptors.
 370          * - When LNET_MD_MAX_SIZE is set, the total length of the memory
 371          *   region (i.e. sum of all fragment lengths) must not be less than
 372          *   \a max_size.
 373          */
 374         unsigned int     options;
 375         /**
 376          * A user-specified value that is associated with the memory
 377          * descriptor. The value does not need to be a pointer, but must fit
 378          * in the space used by a pointer. This value is recorded in events
 379          * associated with operations on this MD.
 380          */
 381         void            *user_ptr;
 382         /**
 383          * The event handler used to log the operations performed on
 384          * the memory region. If this argument is NULL operations
 385          * performed on this memory descriptor are not logged.
 386          */
 387         lnet_handler_t  handler;
 388         /**
 389          * The bulk MD handle which was registered to describe the buffers
 390          * either to be used to transfer data to the peer or receive data
 391          * from the peer. This allows LNet to properly determine the NUMA
 392          * node on which the memory was allocated and use that to select the
 393          * nearest local network interface. This value is only used
 394          * if the LNET_MD_BULK_HANDLE option is set.
 395          */
 396         struct lnet_handle_md bulk_handle;
 397 };
 398
 399 /* Max Transfer Unit (minimum supported everywhere).
 400  * CAVEAT EMPTOR, with multinet (i.e. routers forwarding between networks)
 401  * these limits are system wide and not interface-local. */
 402 #define LNET_MTU_BITS   20
 403 #define LNET_MTU        (1 << LNET_MTU_BITS)
 404
 405 /**
 406  * Options for the MD structure. See struct lnet_md::options.
 407  */
 408 #define LNET_MD_OP_PUT               (1 << 0)
 409 /** See struct lnet_md::options. */
 410 #define LNET_MD_OP_GET               (1 << 1)
 411 /** See struct lnet_md::options. */
 412 #define LNET_MD_MANAGE_REMOTE        (1 << 2)
 413 /* unused                            (1 << 3) */
 414 /** See struct lnet_md::options. */
 415 #define LNET_MD_TRUNCATE             (1 << 4)
 416 /** See struct lnet_md::options. */
 417 #define LNET_MD_ACK_DISABLE          (1 << 5)
 418 /** See struct lnet_md::options. */
 419 /* deprecated #define LNET_MD_IOVEC  (1 << 6) */
 420 /** See struct lnet_md::options. */
 421 #define LNET_MD_MAX_SIZE             (1 << 7)
 422 /** See struct lnet_md::options. */
 423 #define LNET_MD_KIOV                 (1 << 8)
 424 /** See struct lnet_md::options. */
 425 #define LNET_MD_BULK_HANDLE          (1 << 9)
 426 /** See struct lnet_md::options. */
 427 #define LNET_MD_TRACK_RESPONSE       (1 << 10)
 428 /** See struct lnet_md::options. */
 429 #define LNET_MD_NO_TRACK_RESPONSE    (1 << 11)
 430
 431 /** Infinite threshold on MD operations. See struct lnet_md::threshold */
 432 #define LNET_MD_THRESH_INF       (-1)
 433
 434 /** @} lnet_md */
 435
 436 /** \addtogroup lnet_eq
 437  * @{ */
 438
 439 /**
 440  * Six types of events can be logged in an event queue.
 441  */
 442 enum lnet_event_kind {
 443         /** An incoming GET operation has completed on the MD. */
 444         LNET_EVENT_GET          = 1,
 445         /**
 446          * An incoming PUT operation has completed on the MD. The
 447          * underlying layers will not alter the memory (on behalf of this
 448          * operation) once this event has been logged.
 449          */
 450         LNET_EVENT_PUT,
 451         /**
 452          * A REPLY operation has completed. This event is logged after the
 453          * data (if any) from the REPLY has been written into the MD.
 454          */
 455         LNET_EVENT_REPLY,
 456         /** An acknowledgment has been received. */
 457         LNET_EVENT_ACK,
 458         /**
 459          * An outgoing send (PUT or GET) operation has completed. This event
 460          * is logged after the entire buffer has been sent and it is safe for
 461          * the caller to reuse the buffer.
 462          *
 463          * Note:
 464          * - The LNET_EVENT_SEND doesn't guarantee message delivery. It can
 465          *   happen even when the message has not yet been put out on wire.
 466          * - It's unsafe to assume that in an outgoing GET operation
 467          *   the LNET_EVENT_SEND event would happen before the
 468          *   LNET_EVENT_REPLY event. The same holds for LNET_EVENT_SEND and
 469          *   LNET_EVENT_ACK events in an outgoing PUT operation.
 470          */
 471         LNET_EVENT_SEND,
 472         /**
 473          * A MD has been unlinked. Note that LNetMDUnlink() does not
 474          * necessarily trigger an LNET_EVENT_UNLINK event.
 475          * \see LNetMDUnlink
 476          */
 477         LNET_EVENT_UNLINK,
 478 };
 479
 480 #define LNET_SEQ_GT(a, b)       (((signed long)((a) - (b))) > 0)
 481
 482 /**
 483  * Information about an event on a MD.
 484  */
 485 struct lnet_event {
 486         /** The identifier (nid, pid) of the target. */
 487         struct lnet_process_id   target;
 488         /** The identifier (nid, pid) of the initiator. */
 489         struct lnet_process_id   initiator;
 490         /** The source NID on the initiator. */
 491         struct lnet_process_id   source;
 492         /**
 493          * The NID of the immediate sender. If the request has been forwarded
 494          * by routers, this is the NID of the last hop; otherwise it's the
 495          * same as the source.
 496          */
 497         lnet_nid_t          sender;
 498         /** Indicates the type of the event. */
 499         enum lnet_event_kind    type;
 500         /** The portal table index specified in the request */
 501         unsigned int        pt_index;
 502         /** A copy of the match bits specified in the request. */
 503         __u64               match_bits;
 504         /** The length (in bytes) specified in the request. */
 505         unsigned int        rlength;
 506         /**
 507          * The length (in bytes) of the data that was manipulated by the
 508          * operation. For truncated operations, the manipulated length will be
 509          * the number of bytes specified by the MD (possibly with an offset,
 510          * see struct lnet_md). For all other operations, the manipulated length
 511          * will be the length of the requested operation, i.e. rlength.
 512          */
 513         unsigned int        mlength;
 514         /**
 515          * The handle to the MD associated with the event. The handle may be
 516          * invalid if the MD has been unlinked.
 517          */
 518         struct lnet_handle_md   md_handle;
 519         /**
 520          * A snapshot of relevant state of the MD immediately after the event
 521          * has been processed.
 522          */
 523         void                    *md_start;
 524         void                    *md_user_ptr;
 525         unsigned int            md_options;
 526         /**
 527          * 64 bits of out-of-band user data. Only valid for LNET_EVENT_PUT.
 528          * \see LNetPut
 529          */
 530         __u64               hdr_data;
 531         /**
 532          * The message type, to ensure a handler for LNET_EVENT_SEND can
 533          * distinguish between LNET_MSG_GET and LNET_MSG_PUT.
 534          */
 535         __u32               msg_type;
 536         /**
 537          * Indicates the completion status of the operation. It's 0 for
 538          * successful operations, otherwise it's an error code.
 539          */
 540         int                 status;
 541         /**
 542          * Indicates whether the MD has been unlinked. Note that:
 543          * - An event with unlinked set is the last event on the MD.
 544          * - This field is also set for an explicit LNET_EVENT_UNLINK event.
 545          * \see LNetMDUnlink
 546          */
 547         int                 unlinked;
 548         /**
 549          * The displacement (in bytes) into the memory region that the
 550          * operation used. The offset can be determined by the operation for
 551          * a remote managed MD or by the local MD.
 552          * \see struct lnet_md::options
 553          */
 554         unsigned int        offset;
 555         /**
 556          * The sequence number for this event. Sequence numbers are unique
 557          * to each event.
 558          */
 559         volatile unsigned long sequence;
 560 };
 561
 562 /** \addtogroup lnet_data
 563  * @{ */
 564
 565 /**
 566  * Specify whether an acknowledgment should be sent by target when the PUT
 567  * operation completes (i.e., when the data has been written to a MD of the
 568  * target process).
 569  *
 570  * \see struct lnet_md::options for the discussion on LNET_MD_ACK_DISABLE
 571  * by which acknowledgments can be disabled for a MD.
 572  */
 573 enum lnet_ack_req {
 574         /** Request an acknowledgment */
 575         LNET_ACK_REQ,
 576         /** Request that no acknowledgment should be generated. */
 577         LNET_NOACK_REQ
 578 };
 579
 580 /**
 581  * UDSP action types. There are two available actions:
 582  *      1. PRIORITY - set priority of matching LNet constructs
 583  *      2. PREFERRED LIST - set preferred list of matching LNet constructs
 584  */
 585 enum lnet_udsp_action_type {
 586         EN_LNET_UDSP_ACTION_NONE = 0,
 587         /** assign a priority to matching constructs */
 588         EN_LNET_UDSP_ACTION_PRIORITY = 1,
 589         /** assign a preferred list of NIDs to matching constructs */
 590         EN_LNET_UDSP_ACTION_PREFERRED_LIST = 2,
 591 };
 592
 593 /** @} lnet_data */
 594
 595 /** @} lnet */
 596 #endif