Whamcloud - gitweb
LU-13005 lnet: eq: discard struct lnet_handle_eq
[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  * Lustre is a trademark of Sun Microsystems, Inc.
31  */
32
33 #ifndef __LNET_API_H__
34 #define __LNET_API_H__
35
36 /** \defgroup lnet LNet
37  *
38  * The Lustre Networking subsystem.
39  *
40  * LNet is an asynchronous message-passing API, which provides an unreliable
41  * connectionless service that can't guarantee any order. It supports OFA IB,
42  * TCP/IP, and Cray Portals, and routes between heterogeneous networks.
43  * @{
44  */
45
46 #ifndef __KERNEL__
47 # error This include is only for kernel use.
48 #endif
49
50 #include <uapi/linux/lnet/lnet-types.h>
51
52 /** \defgroup lnet_init_fini Initialization and cleanup
53  * The LNet must be properly initialized before any LNet calls can be made.
54  * @{ */
55 int LNetNIInit(lnet_pid_t requested_pid);
56 int LNetNIFini(void);
57 /** @} lnet_init_fini */
58
59 /** \defgroup lnet_addr LNet addressing and basic types
60  *
61  * Addressing scheme and basic data types of LNet.
62  *
63  * The LNet API is memory-oriented, so LNet must be able to address not only
64  * end-points but also memory region within a process address space.
65  * An ::lnet_nid_t addresses an end-point. An ::lnet_pid_t identifies a process
66  * in a node. A portal represents an opening in the address space of a
67  * process. Match bits is criteria to identify a region of memory inside a
68  * portal, and offset specifies an offset within the memory region.
69  *
70  * LNet creates a table of portals for each process during initialization.
71  * This table has MAX_PORTALS entries and its size can't be dynamically
72  * changed. A portal stays empty until the owning process starts to add
73  * memory regions to it. A portal is sometimes called an index because
74  * it's an entry in the portals table of a process.
75  *
76  * \see LNetMEAttach
77  * @{ */
78 int LNetGetId(unsigned int index, struct lnet_process_id *id);
79 int LNetDist(lnet_nid_t nid, lnet_nid_t *srcnid, __u32 *order);
80 lnet_nid_t LNetPrimaryNID(lnet_nid_t nid);
81 bool LNetIsPeerLocal(lnet_nid_t nid);
82
83 /** @} lnet_addr */
84
85
86 /** \defgroup lnet_me Match entries
87  *
88  * A match entry (abbreviated as ME) describes a set of criteria to accept
89  * incoming requests.
90  *
91  * A portal is essentially a match list plus a set of attributes. A match
92  * list is a chain of MEs. Each ME includes a pointer to a memory descriptor
93  * and a set of match criteria. The match criteria can be used to reject
94  * incoming requests based on process ID or the match bits provided in the
95  * request. MEs can be dynamically inserted into a match list by LNetMEAttach()
96  * and removed from its list by LNetMEUnlink().
97  * @{ */
98 struct lnet_me *
99 LNetMEAttach(unsigned int portal,
100              struct lnet_process_id match_id_in,
101              __u64 match_bits_in,
102              __u64 ignore_bits_in,
103              enum lnet_unlink unlink_in,
104              enum lnet_ins_pos pos_in);
105
106 void LNetMEUnlink(struct lnet_me *current_in);
107 /** @} lnet_me */
108
109 /** \defgroup lnet_md Memory descriptors
110  *
111  * A memory descriptor contains information about a region of a user's
112  * memory (either in kernel or user space) and optionally points to an
113  * event queue where information about the operations performed on the
114  * memory descriptor are recorded. Memory descriptor is abbreviated as
115  * MD and can be used interchangeably with the memory region it describes.
116  *
117  * The LNet API provides two operations to create MDs: LNetMDAttach()
118  * and LNetMDBind(); one operation to unlink and release the resources
119  * associated with a MD: LNetMDUnlink().
120  * @{ */
121 int LNetMDAttach(struct lnet_me *current_in,
122                  struct lnet_md md_in,
123                  enum lnet_unlink unlink_in,
124                  struct lnet_handle_md *md_handle_out);
125
126 int LNetMDBind(struct lnet_md    md_in,
127                enum lnet_unlink unlink_in,
128                struct lnet_handle_md *md_handle_out);
129
130 int LNetMDUnlink(struct lnet_handle_md md_in);
131 /** @} lnet_md */
132
133 /** \defgroup lnet_eq Events and event queues
134  *
135  * Event queues (abbreviated as EQ) are used to log operations performed on
136  * local MDs. In particular, they signal the completion of a data transmission
137  * into or out of a MD. They can also be used to hold acknowledgments for
138  * completed PUT operations and indicate when a MD has been unlinked. Multiple
139  * MDs can share a single EQ. An EQ may have an optional event handler
140  * associated with it. If an event handler exists, it will be run for each
141  * event that is deposited into the EQ.
142  *
143  * In addition to the struct lnet_eq, the LNet API defines two types
144  * associated with events: The ::lnet_event_kind defines the kinds of events
145  * that can be stored in an EQ. The struct lnet_event defines a structure that
146  * holds the information about with an event.
147  *
148  * There are three functions for dealing with EQs: LNetEQAlloc() is used
149  * to create an EQ and allocate the resources needed, while LNetEQFree()
150  * releases these resources and free the EQ.  LNetEQPoll() can be used
151  * to test or wait on multiple EQs.
152  * @{ */
153 struct lnet_eq *
154 LNetEQAlloc(unsigned int count_in,
155             lnet_eq_handler_t handler);
156
157 int LNetEQFree(struct lnet_eq *eventq_in);
158
159 int LNetEQPoll(struct lnet_eq **eventqs_in,
160                int neq_in,
161                signed long timeout,
162                struct lnet_event *event_out,
163                int *which_eq_out);
164 /** @} lnet_eq */
165
166 /** \defgroup lnet_data Data movement operations
167  *
168  * The LNet API provides two data movement operations: LNetPut()
169  * and LNetGet().
170  * @{ */
171 int LNetPut(lnet_nid_t        self,
172             struct lnet_handle_md md_in,
173             enum lnet_ack_req   ack_req_in,
174             struct lnet_process_id target_in,
175             unsigned int      portal_in,
176             __u64             match_bits_in,
177             unsigned int      offset_in,
178             __u64             hdr_data_in);
179
180 int LNetGet(lnet_nid_t        self,
181             struct lnet_handle_md md_in,
182             struct lnet_process_id target_in,
183             unsigned int      portal_in,
184             __u64             match_bits_in,
185             unsigned int      offset_in,
186             bool              recovery);
187 /** @} lnet_data */
188
189
190 /** \defgroup lnet_misc Miscellaneous operations.
191  * Miscellaneous operations.
192  * @{ */
193
194 int LNetSetLazyPortal(int portal);
195 int LNetClearLazyPortal(int portal);
196 int LNetCtl(unsigned int cmd, void *arg);
197 void LNetDebugPeer(struct lnet_process_id id);
198 int LNetGetPeerDiscoveryStatus(void);
199
200 /** @} lnet_misc */
201
202 /** @} lnet */
203 #endif