Commit | Line | Data |
---|---|---|
d7e09d03 PT |
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.sun.com/software/products/lustre/docs/GPLv2.pdf | |
19 | * | |
20 | * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, | |
21 | * CA 95054 USA or visit www.sun.com if you need additional information or | |
22 | * have any questions. | |
23 | * | |
24 | * GPL HEADER END | |
25 | */ | |
26 | /* | |
27 | * Copyright (c) 2003, 2010, Oracle and/or its affiliates. All rights reserved. | |
28 | * Use is subject to license terms. | |
29 | */ | |
30 | /* | |
31 | * This file is part of Lustre, http://www.lustre.org/ | |
32 | * Lustre is a trademark of Sun Microsystems, Inc. | |
33 | */ | |
34 | ||
35 | #ifndef __LNET_API_H__ | |
36 | #define __LNET_API_H__ | |
37 | ||
38 | /** \defgroup lnet LNet | |
39 | * | |
40 | * The Lustre Networking subsystem. | |
41 | * | |
42 | * LNet is an asynchronous message-passing API, which provides an unreliable | |
43 | * connectionless service that can't guarantee any order. It supports OFA IB, | |
44 | * TCP/IP, and Cray Portals, and routes between heterogeneous networks. | |
45 | * | |
46 | * LNet can run both in OS kernel space and in userspace as a library. | |
47 | * @{ | |
48 | */ | |
49 | ||
9fdaf8c0 | 50 | #include "../lnet/types.h" |
d7e09d03 PT |
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 LNetInit(void); | |
56 | void LNetFini(void); | |
57 | ||
58 | int LNetNIInit(lnet_pid_t requested_pid); | |
59 | int LNetNIFini(void); | |
60 | /** @} lnet_init_fini */ | |
61 | ||
62 | /** \defgroup lnet_addr LNet addressing and basic types | |
63 | * | |
64 | * Addressing scheme and basic data types of LNet. | |
65 | * | |
66 | * The LNet API is memory-oriented, so LNet must be able to address not only | |
67 | * end-points but also memory region within a process address space. | |
68 | * An ::lnet_nid_t addresses an end-point. An ::lnet_pid_t identifies a process | |
69 | * in a node. A portal represents an opening in the address space of a | |
70 | * process. Match bits is criteria to identify a region of memory inside a | |
71 | * portal, and offset specifies an offset within the memory region. | |
72 | * | |
73 | * LNet creates a table of portals for each process during initialization. | |
74 | * This table has MAX_PORTALS entries and its size can't be dynamically | |
75 | * changed. A portal stays empty until the owning process starts to add | |
76 | * memory regions to it. A portal is sometimes called an index because | |
77 | * it's an entry in the portals table of a process. | |
78 | * | |
79 | * \see LNetMEAttach | |
80 | * @{ */ | |
81 | int LNetGetId(unsigned int index, lnet_process_id_t *id); | |
82 | int LNetDist(lnet_nid_t nid, lnet_nid_t *srcnid, __u32 *order); | |
83 | void LNetSnprintHandle(char *str, int str_len, lnet_handle_any_t handle); | |
84 | ||
85 | /** @} lnet_addr */ | |
86 | ||
87 | ||
88 | /** \defgroup lnet_me Match entries | |
89 | * | |
90 | * A match entry (abbreviated as ME) describes a set of criteria to accept | |
91 | * incoming requests. | |
92 | * | |
93 | * A portal is essentially a match list plus a set of attributes. A match | |
94 | * list is a chain of MEs. Each ME includes a pointer to a memory descriptor | |
95 | * and a set of match criteria. The match criteria can be used to reject | |
96 | * incoming requests based on process ID or the match bits provided in the | |
97 | * request. MEs can be dynamically inserted into a match list by LNetMEAttach() | |
98 | * and LNetMEInsert(), and removed from its list by LNetMEUnlink(). | |
99 | * @{ */ | |
100 | int LNetMEAttach(unsigned int portal, | |
101 | lnet_process_id_t match_id_in, | |
102 | __u64 match_bits_in, | |
103 | __u64 ignore_bits_in, | |
104 | lnet_unlink_t unlink_in, | |
105 | lnet_ins_pos_t pos_in, | |
106 | lnet_handle_me_t *handle_out); | |
107 | ||
108 | int LNetMEInsert(lnet_handle_me_t current_in, | |
109 | lnet_process_id_t match_id_in, | |
110 | __u64 match_bits_in, | |
111 | __u64 ignore_bits_in, | |
112 | lnet_unlink_t unlink_in, | |
113 | lnet_ins_pos_t position_in, | |
114 | lnet_handle_me_t *handle_out); | |
115 | ||
116 | int LNetMEUnlink(lnet_handle_me_t current_in); | |
117 | /** @} lnet_me */ | |
118 | ||
119 | /** \defgroup lnet_md Memory descriptors | |
120 | * | |
121 | * A memory descriptor contains information about a region of a user's | |
122 | * memory (either in kernel or user space) and optionally points to an | |
123 | * event queue where information about the operations performed on the | |
124 | * memory descriptor are recorded. Memory descriptor is abbreviated as | |
125 | * MD and can be used interchangeably with the memory region it describes. | |
126 | * | |
127 | * The LNet API provides two operations to create MDs: LNetMDAttach() | |
128 | * and LNetMDBind(); one operation to unlink and release the resources | |
129 | * associated with a MD: LNetMDUnlink(). | |
130 | * @{ */ | |
131 | int LNetMDAttach(lnet_handle_me_t current_in, | |
132 | lnet_md_t md_in, | |
133 | lnet_unlink_t unlink_in, | |
134 | lnet_handle_md_t *handle_out); | |
135 | ||
136 | int LNetMDBind(lnet_md_t md_in, | |
137 | lnet_unlink_t unlink_in, | |
138 | lnet_handle_md_t *handle_out); | |
139 | ||
140 | int LNetMDUnlink(lnet_handle_md_t md_in); | |
141 | /** @} lnet_md */ | |
142 | ||
143 | /** \defgroup lnet_eq Events and event queues | |
144 | * | |
145 | * Event queues (abbreviated as EQ) are used to log operations performed on | |
146 | * local MDs. In particular, they signal the completion of a data transmission | |
147 | * into or out of a MD. They can also be used to hold acknowledgments for | |
148 | * completed PUT operations and indicate when a MD has been unlinked. Multiple | |
149 | * MDs can share a single EQ. An EQ may have an optional event handler | |
150 | * associated with it. If an event handler exists, it will be run for each | |
151 | * event that is deposited into the EQ. | |
152 | * | |
153 | * In addition to the lnet_handle_eq_t, the LNet API defines two types | |
154 | * associated with events: The ::lnet_event_kind_t defines the kinds of events | |
155 | * that can be stored in an EQ. The lnet_event_t defines a structure that | |
156 | * holds the information about with an event. | |
157 | * | |
158 | * There are five functions for dealing with EQs: LNetEQAlloc() is used to | |
159 | * create an EQ and allocate the resources needed, while LNetEQFree() | |
160 | * releases these resources and free the EQ. LNetEQGet() retrieves the next | |
161 | * event from an EQ, and LNetEQWait() can be used to block a process until | |
162 | * an EQ has at least one event. LNetEQPoll() can be used to test or wait | |
163 | * on multiple EQs. | |
164 | * @{ */ | |
165 | int LNetEQAlloc(unsigned int count_in, | |
166 | lnet_eq_handler_t handler, | |
167 | lnet_handle_eq_t *handle_out); | |
168 | ||
169 | int LNetEQFree(lnet_handle_eq_t eventq_in); | |
170 | ||
171 | int LNetEQGet(lnet_handle_eq_t eventq_in, | |
172 | lnet_event_t *event_out); | |
173 | ||
174 | ||
175 | int LNetEQWait(lnet_handle_eq_t eventq_in, | |
176 | lnet_event_t *event_out); | |
177 | ||
178 | int LNetEQPoll(lnet_handle_eq_t *eventqs_in, | |
179 | int neq_in, | |
180 | int timeout_ms, | |
181 | lnet_event_t *event_out, | |
182 | int *which_eq_out); | |
183 | /** @} lnet_eq */ | |
184 | ||
185 | /** \defgroup lnet_data Data movement operations | |
186 | * | |
187 | * The LNet API provides two data movement operations: LNetPut() | |
188 | * and LNetGet(). | |
189 | * @{ */ | |
190 | int LNetPut(lnet_nid_t self, | |
191 | lnet_handle_md_t md_in, | |
192 | lnet_ack_req_t ack_req_in, | |
193 | lnet_process_id_t target_in, | |
194 | unsigned int portal_in, | |
195 | __u64 match_bits_in, | |
196 | unsigned int offset_in, | |
197 | __u64 hdr_data_in); | |
198 | ||
199 | int LNetGet(lnet_nid_t self, | |
200 | lnet_handle_md_t md_in, | |
201 | lnet_process_id_t target_in, | |
202 | unsigned int portal_in, | |
203 | __u64 match_bits_in, | |
204 | unsigned int offset_in); | |
205 | /** @} lnet_data */ | |
206 | ||
207 | ||
208 | /** \defgroup lnet_misc Miscellaneous operations. | |
209 | * Miscellaneous operations. | |
210 | * @{ */ | |
211 | ||
212 | int LNetSetLazyPortal(int portal); | |
213 | int LNetClearLazyPortal(int portal); | |
214 | int LNetCtl(unsigned int cmd, void *arg); | |
215 | int LNetSetAsync(lnet_process_id_t id, int nasync); | |
216 | ||
217 | /** @} lnet_misc */ | |
218 | ||
219 | /** @} lnet */ | |
220 | #endif |