Whamcloud - gitweb
8871124341ca7a1ad3c4556ef68ed2f10ffb55f9
[fs/lustre-release.git] / lnet / include / lnet / api.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) 2016, 2017, Intel Corporation.
27  */
28 /*
29  * This file is part of Lustre, http://www.lustre.org/
30  */
31
32 #ifndef __LNET_API_H__
33 #define __LNET_API_H__
34
35 /** \defgroup lnet LNet
36  *
37  * The Lustre Networking subsystem.
38  *
39  * LNet is an asynchronous message-passing API, which provides an unreliable
40  * connectionless service that can't guarantee any order. It supports OFA IB,
41  * TCP/IP, and Cray Portals, and routes between heterogeneous networks.
42  * @{
43  */
44
45 #ifndef __KERNEL__
46 # error This include is only for kernel use.
47 #endif
48
49 #include <uapi/linux/lnet/lnet-types.h>
50
51 /** \defgroup lnet_init_fini Initialization and cleanup
52  * The LNet must be properly initialized before any LNet calls can be made.
53  * @{ */
54 int LNetNIInit(lnet_pid_t requested_pid);
55 int LNetNIFini(void);
56 /** @} lnet_init_fini */
57
58 /** \defgroup lnet_addr LNet addressing and basic types
59  *
60  * Addressing scheme and basic data types of LNet.
61  *
62  * The LNet API is memory-oriented, so LNet must be able to address not only
63  * end-points but also memory region within a process address space.
64  * An ::lnet_nid_t addresses an end-point. An ::lnet_pid_t identifies a process
65  * in a node. A portal represents an opening in the address space of a
66  * process. Match bits is criteria to identify a region of memory inside a
67  * portal, and offset specifies an offset within the memory region.
68  *
69  * LNet creates a table of portals for each process during initialization.
70  * This table has MAX_PORTALS entries and its size can't be dynamically
71  * changed. A portal stays empty until the owning process starts to add
72  * memory regions to it. A portal is sometimes called an index because
73  * it's an entry in the portals table of a process.
74  *
75  * \see LNetMEAttach
76  * @{ */
77 int LNetGetId(unsigned int index, struct lnet_process_id *id);
78 int LNetDist(lnet_nid_t nid, lnet_nid_t *srcnid, __u32 *order);
79 lnet_nid_t LNetPrimaryNID(lnet_nid_t nid);
80 bool LNetIsPeerLocal(lnet_nid_t nid);
81
82 /** @} lnet_addr */
83
84
85 /** \defgroup lnet_me Match entries
86  *
87  * A match entry (abbreviated as ME) describes a set of criteria to accept
88  * incoming requests.
89  *
90  * A portal is essentially a match list plus a set of attributes. A match
91  * list is a chain of MEs. Each ME includes a pointer to a memory descriptor
92  * and a set of match criteria. The match criteria can be used to reject
93  * incoming requests based on process ID or the match bits provided in the
94  * request. MEs can be dynamically inserted into a match list by LNetMEAttach(),
95  * and must then be attached to an MD with LNetMDAttach().
96  * @{ */
97 struct lnet_me *
98 LNetMEAttach(unsigned int portal,
99              struct lnet_process_id match_id_in,
100              __u64 match_bits_in,
101              __u64 ignore_bits_in,
102              enum lnet_unlink unlink_in,
103              enum lnet_ins_pos pos_in);
104 /** @} lnet_me */
105
106 /** \defgroup lnet_md Memory descriptors
107  *
108  * A memory descriptor contains information about a region of a user's
109  * memory (either in kernel or user space) and optionally points to an
110  * event queue where information about the operations performed on the
111  * memory descriptor are recorded. Memory descriptor is abbreviated as
112  * MD and can be used interchangeably with the memory region it describes.
113  *
114  * The LNet API provides two operations to create MDs: LNetMDAttach()
115  * and LNetMDBind(); one operation to unlink and release the resources
116  * associated with a MD: LNetMDUnlink().
117  * @{ */
118 int LNetMDAttach(struct lnet_me *current_in,
119                  const struct lnet_md *md_in,
120                  enum lnet_unlink unlink_in,
121                  struct lnet_handle_md *md_handle_out);
122
123 int LNetMDBind(const struct lnet_md *md_in,
124                enum lnet_unlink unlink_in,
125                struct lnet_handle_md *md_handle_out);
126
127 int __LNetMDUnlink(struct lnet_handle_md md_in, bool discard);
128 #define LNetMDUnlink(handle) __LNetMDUnlink(handle, false)
129
130 void lnet_assert_handler_unused(lnet_handler_t handler);
131 /** @} lnet_md */
132
133 /** \defgroup lnet_data Data movement operations
134  *
135  * The LNet API provides two data movement operations: LNetPut()
136  * and LNetGet().
137  * @{ */
138 int LNetPut(lnet_nid_t        self,
139             struct lnet_handle_md md_in,
140             enum lnet_ack_req   ack_req_in,
141             struct lnet_process_id target_in,
142             unsigned int      portal_in,
143             __u64             match_bits_in,
144             unsigned int      offset_in,
145             __u64             hdr_data_in);
146
147 int LNetGet(lnet_nid_t        self,
148             struct lnet_handle_md md_in,
149             struct lnet_process_id target_in,
150             unsigned int      portal_in,
151             __u64             match_bits_in,
152             unsigned int      offset_in,
153             bool              recovery);
154 /** @} lnet_data */
155
156
157 /** \defgroup lnet_misc Miscellaneous operations.
158  * Miscellaneous operations.
159  * @{ */
160
161 int LNetSetLazyPortal(int portal);
162 int LNetClearLazyPortal(int portal);
163 int LNetCtl(unsigned int cmd, void *arg);
164 void LNetDebugPeer(struct lnet_process_id id);
165 int LNetGetPeerDiscoveryStatus(void);
166 int LNetAddPeer(lnet_nid_t *nids, __u32 num_nids);
167
168 /** @} lnet_misc */
169
170 /** @} lnet */
171 #endif