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