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