Whamcloud - gitweb
f00d84f78f95a318b4066a2ead3744687e0f4a20
[fs/lustre-release.git] / 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