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