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