4 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
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.
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).
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
23 * Copyright (c) 2003, 2010, Oracle and/or its affiliates. All rights reserved.
24 * Use is subject to license terms.
26 * Copyright (c) 2016, 2017, Intel Corporation.
29 * This file is part of Lustre, http://www.lustre.org/
30 * Lustre is a trademark of Sun Microsystems, Inc.
33 #ifndef __LNET_API_H__
34 #define __LNET_API_H__
36 /** \defgroup lnet LNet
38 * The Lustre Networking subsystem.
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.
47 # error This include is only for kernel use.
50 #include <uapi/linux/lnet/lnet-types.h>
52 /** \defgroup lnet_init_fini Initialization and cleanup
53 * The LNet must be properly initialized before any LNet calls can be made.
55 int LNetNIInit(lnet_pid_t requested_pid);
57 /** @} lnet_init_fini */
59 /** \defgroup lnet_addr LNet addressing and basic types
61 * Addressing scheme and basic data types of LNet.
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.
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.
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);
86 /** \defgroup lnet_me Match entries
88 * A match entry (abbreviated as ME) describes a set of criteria to accept
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().
99 LNetMEAttach(unsigned int portal,
100 struct lnet_process_id match_id_in,
102 __u64 ignore_bits_in,
103 enum lnet_unlink unlink_in,
104 enum lnet_ins_pos pos_in);
106 void LNetMEUnlink(struct lnet_me *current_in);
109 /** \defgroup lnet_md Memory descriptors
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.
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().
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);
126 int LNetMDBind(struct lnet_md md_in,
127 enum lnet_unlink unlink_in,
128 struct lnet_handle_md *md_handle_out);
130 int LNetMDUnlink(struct lnet_handle_md md_in);
133 /** \defgroup lnet_eq Events and event queues
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.
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.
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.
154 LNetEQAlloc(unsigned int count_in,
155 lnet_eq_handler_t handler);
157 int LNetEQFree(struct lnet_eq *eventq_in);
159 int LNetEQPoll(struct lnet_eq **eventqs_in,
162 struct lnet_event *event_out,
166 /** \defgroup lnet_data Data movement operations
168 * The LNet API provides two data movement operations: LNetPut()
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,
177 unsigned int offset_in,
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,
185 unsigned int offset_in,
190 /** \defgroup lnet_misc Miscellaneous operations.
191 * Miscellaneous operations.
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);