1 // SPDX-License-Identifier: GPL-2.0
3 /* Copyright (c) 2003, 2010, Oracle and/or its affiliates. All rights reserved.
4 * Use is subject to license terms.
6 * Copyright (c) 2016, 2017, Intel Corporation.
9 /* This file is part of Lustre, http://www.lustre.org/ */
11 #ifndef __LNET_API_H__
12 #define __LNET_API_H__
14 /** \defgroup lnet LNet
16 * The Lustre Networking subsystem.
18 * LNet is an asynchronous message-passing API, which provides an unreliable
19 * connectionless service that can't guarantee any order. It supports OFA IB,
20 * TCP/IP, and Cray Portals, and routes between heterogeneous networks.
25 # error This include is only for kernel use.
28 #include <uapi/linux/lnet/lnet-types.h>
30 /** \defgroup lnet_init_fini Initialization and cleanup
31 * The LNet must be properly initialized before any LNet calls can be made.
33 int LNetNIInit(lnet_pid_t requested_pid);
35 /** @} lnet_init_fini */
37 /** \defgroup lnet_addr LNet addressing and basic types
39 * Addressing scheme and basic data types of LNet.
41 * The LNet API is memory-oriented, so LNet must be able to address not only
42 * end-points but also memory region within a process address space.
43 * An ::lnet_nid_t addresses an end-point. An ::lnet_pid_t identifies a process
44 * in a node. A portal represents an opening in the address space of a
45 * process. Match bits is criteria to identify a region of memory inside a
46 * portal, and offset specifies an offset within the memory region.
48 * LNet creates a table of portals for each process during initialization.
49 * This table has MAX_PORTALS entries and its size can't be dynamically
50 * changed. A portal stays empty until the owning process starts to add
51 * memory regions to it. A portal is sometimes called an index because
52 * it's an entry in the portals table of a process.
56 int LNetGetId(unsigned int index, struct lnet_processid *id, bool large_nids);
57 int LNetDist(struct lnet_nid *nid, struct lnet_nid *srcnid, __u32 *order);
58 void LNetPrimaryNID(struct lnet_nid *nid);
59 bool LNetIsPeerLocal(struct lnet_nid *nid);
60 bool LNetPeerDiscovered(struct lnet_nid *nid);
65 /** \defgroup lnet_me Match entries
67 * A match entry (abbreviated as ME) describes a set of criteria to accept
70 * A portal is essentially a match list plus a set of attributes. A match
71 * list is a chain of MEs. Each ME includes a pointer to a memory descriptor
72 * and a set of match criteria. The match criteria can be used to reject
73 * incoming requests based on process ID or the match bits provided in the
74 * request. MEs can be dynamically inserted into a match list by LNetMEAttach(),
75 * and must then be attached to an MD with LNetMDAttach().
78 LNetMEAttach(unsigned int portal,
79 struct lnet_processid *match_id_in,
82 enum lnet_unlink unlink_in,
83 enum lnet_ins_pos pos_in);
86 /** \defgroup lnet_md Memory descriptors
88 * A memory descriptor contains information about a region of a user's
89 * memory (either in kernel or user space) and optionally points to an
90 * event queue where information about the operations performed on the
91 * memory descriptor are recorded. Memory descriptor is abbreviated as
92 * MD and can be used interchangeably with the memory region it describes.
94 * The LNet API provides two operations to create MDs: LNetMDAttach()
95 * and LNetMDBind(); one operation to unlink and release the resources
96 * associated with a MD: LNetMDUnlink().
98 int LNetMDAttach(struct lnet_me *current_in,
99 const struct lnet_md *md_in,
100 enum lnet_unlink unlink_in,
101 struct lnet_handle_md *md_handle_out);
103 int LNetMDBind(const struct lnet_md *md_in,
104 enum lnet_unlink unlink_in,
105 struct lnet_handle_md *md_handle_out);
107 int __LNetMDUnlink(struct lnet_handle_md md_in, bool discard);
108 #define LNetMDUnlink(handle) __LNetMDUnlink(handle, false)
110 bool lnet_assert_handler_unused(lnet_handler_t handler, bool assert);
113 /** \defgroup lnet_data Data movement operations
115 * The LNet API provides two data movement operations: LNetPut()
118 int LNetPut(struct lnet_nid *self,
119 struct lnet_handle_md md_in,
120 enum lnet_ack_req ack_req_in,
121 struct lnet_processid *target_in,
122 unsigned int portal_in,
124 unsigned int offset_in,
127 int LNetGet(struct lnet_nid *self,
128 struct lnet_handle_md md_in,
129 struct lnet_processid *target_in,
130 unsigned int portal_in,
132 unsigned int offset_in,
137 /** \defgroup lnet_misc Miscellaneous operations.
138 * Miscellaneous operations.
141 int LNetSetLazyPortal(int portal);
142 int LNetClearLazyPortal(int portal);
143 int LNetCtl(unsigned int cmd, void *arg);
144 void LNetDebugPeer(struct lnet_processid *id);
145 int LNetGetPeerDiscoveryStatus(void);
146 int LNetAddPeer(struct lnet_nid *nids, u32 num_nids);