X-Git-Url: https://git.whamcloud.com/?p=fs%2Flustre-release.git;a=blobdiff_plain;f=lnet%2Finclude%2Flnet%2Fapi.h;h=84c6bd0039632247d09a951560655f8f1cc0ea83;hp=69fa339b9759407bedf6097fbe4c3e93222b3715;hb=b0ab95d6133e783acacc6329c025d17fb282775e;hpb=090c677210ee2946d99c71412e4ff762bb300f4f diff --git a/lnet/include/lnet/api.h b/lnet/include/lnet/api.h index 69fa339..84c6bd0 100644 --- a/lnet/include/lnet/api.h +++ b/lnet/include/lnet/api.h @@ -1,163 +1,217 @@ -#ifndef P30_API_H -#define P30_API_H - -#include "build_check.h" - -#include - -#ifndef PTL_NO_WRAP -int PtlInit(int *); -void PtlFini(void); - -int PtlNIInit(ptl_interface_t interface, ptl_pt_index_t ptl_size_in, - ptl_ac_index_t acl_size_in, ptl_pid_t requested_pid, - ptl_handle_ni_t * interface_out); - -int PtlNIInitialized(ptl_interface_t); - -int PtlNIFini(ptl_handle_ni_t interface_in); - -#endif - -int PtlGetId(ptl_handle_ni_t ni_handle, ptl_process_id_t *id); - - -/* - * Network interfaces - */ - -int PtlNIStatus(ptl_handle_ni_t interface_in, ptl_sr_index_t register_in, - ptl_sr_value_t * status_out); - -int PtlNIDist(ptl_handle_ni_t interface_in, ptl_process_id_t process_in, - unsigned long *distance_out); - -#ifndef PTL_NO_WRAP -int PtlNIHandle(ptl_handle_any_t handle_in, ptl_handle_ni_t * interface_out); -#endif - - /* - * PtlNIDebug: + * GPL HEADER START * - * This is not an official Portals 3 API call. It is provided - * by the reference implementation to allow the maintainers an - * easy way to turn on and off debugging information in the - * library. Do not use it in code that is not intended for use - * with any version other than the portable reference library. - */ -unsigned int PtlNIDebug(ptl_handle_ni_t ni, unsigned int mask_in); - -/* - * PtlNIFailNid + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * - * Not an official Portals 3 API call. It provides a way of simulating - * communications failures to all (nid == PTL_NID_ANY), or specific peers - * (via multiple calls), either until further notice (threshold == -1), or - * for a specific number of messages. Passing a threshold of zero, "heals" - * the given peer. - */ -int PtlFailNid (ptl_handle_ni_t ni, ptl_nid_t nid, unsigned int threshold); - -/* - * PtlSnprintHandle: + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License version 2 only, + * as published by the Free Software Foundation. + * + * This program is distributed in the hope that it will be useful, but + * WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * General Public License version 2 for more details (a copy is included + * in the LICENSE file that accompanied this code). * - * This is not an official Portals 3 API call. It is provided - * so that an application can print an opaque handle. + * You should have received a copy of the GNU General Public License + * version 2 along with this program; If not, see + * http://www.gnu.org/licenses/gpl-2.0.html + * + * GPL HEADER END */ -void PtlSnprintHandle (char *str, int str_len, ptl_handle_any_t handle); - /* - * Match entries + * Copyright (c) 2003, 2010, Oracle and/or its affiliates. All rights reserved. + * Use is subject to license terms. + * + * Copyright (c) 2016, Intel Corporation. */ - -int PtlMEAttach(ptl_handle_ni_t interface_in, ptl_pt_index_t index_in, - ptl_process_id_t match_id_in, ptl_match_bits_t match_bits_in, - ptl_match_bits_t ignore_bits_in, ptl_unlink_t unlink_in, - ptl_ins_pos_t pos_in, ptl_handle_me_t * handle_out); - -int PtlMEInsert(ptl_handle_me_t current_in, ptl_process_id_t match_id_in, - ptl_match_bits_t match_bits_in, ptl_match_bits_t ignore_bits_in, - ptl_unlink_t unlink_in, ptl_ins_pos_t position_in, - ptl_handle_me_t * handle_out); - -int PtlMEUnlink(ptl_handle_me_t current_in); - -int PtlMEUnlinkList(ptl_handle_me_t current_in); - -int PtlTblDump(ptl_handle_ni_t ni, int index_in); -int PtlMEDump(ptl_handle_me_t current_in); - - - /* - * Memory descriptors + * This file is part of Lustre, http://www.lustre.org/ + * Lustre is a trademark of Sun Microsystems, Inc. */ -#ifndef PTL_NO_WRAP -int PtlMDAttach(ptl_handle_me_t current_in, ptl_md_t md_in, - ptl_unlink_t unlink_in, ptl_handle_md_t * handle_out); +#ifndef __LNET_API_H__ +#define __LNET_API_H__ -int PtlMDBind(ptl_handle_ni_t ni_in, ptl_md_t md_in, - ptl_unlink_t unlink_in, ptl_handle_md_t * handle_out); - -int PtlMDUnlink(ptl_handle_md_t md_in); - -int PtlMDUpdate(ptl_handle_md_t md_in, ptl_md_t * old_inout, - ptl_md_t * new_inout, ptl_handle_eq_t testq_in); - -#endif - -/* These should not be called by users */ -int PtlMDUpdate_internal(ptl_handle_md_t md_in, ptl_md_t * old_inout, - ptl_md_t * new_inout, ptl_handle_eq_t testq_in, - ptl_seq_t sequence_in); - - - - -/* - * Event queues +/** \defgroup lnet LNet + * + * The Lustre Networking subsystem. + * + * LNet is an asynchronous message-passing API, which provides an unreliable + * connectionless service that can't guarantee any order. It supports OFA IB, + * TCP/IP, and Cray Portals, and routes between heterogeneous networks. + * @{ */ -#ifndef PTL_NO_WRAP - -/* These should be called by users */ -int PtlEQAlloc(ptl_handle_ni_t ni_in, ptl_size_t count_in, - int (*callback) (ptl_event_t * event), - ptl_handle_eq_t * handle_out); -int PtlEQFree(ptl_handle_eq_t eventq_in); - -int PtlEQCount(ptl_handle_eq_t eventq_in, ptl_size_t * count_out); -int PtlEQGet(ptl_handle_eq_t eventq_in, ptl_event_t * event_out); - - -int PtlEQWait(ptl_handle_eq_t eventq_in, ptl_event_t * event_out); - -int PtlEQPoll(ptl_handle_eq_t *eventqs_in, int neq_in, int timeout, - ptl_event_t *event_out, int *which_out); +#ifndef __KERNEL__ +# error This include is only for kernel use. #endif -/* - * Access Control Table - */ -int PtlACEntry(ptl_handle_ni_t ni_in, ptl_ac_index_t index_in, - ptl_process_id_t match_id_in, ptl_pt_index_t portal_in); - - -/* - * Data movement - */ +#include -int PtlPut(ptl_handle_md_t md_in, ptl_ack_req_t ack_req_in, - ptl_process_id_t target_in, ptl_pt_index_t portal_in, - ptl_ac_index_t cookie_in, ptl_match_bits_t match_bits_in, - ptl_size_t offset_in, ptl_hdr_data_t hdr_data_in); +/** \defgroup lnet_init_fini Initialization and cleanup + * The LNet must be properly initialized before any LNet calls can be made. + * @{ */ +int LNetNIInit(lnet_pid_t requested_pid); +int LNetNIFini(void); +/** @} lnet_init_fini */ -int PtlGet(ptl_handle_md_t md_in, ptl_process_id_t target_in, - ptl_pt_index_t portal_in, ptl_ac_index_t cookie_in, - ptl_match_bits_t match_bits_in, ptl_size_t offset_in); +/** \defgroup lnet_addr LNet addressing and basic types + * + * Addressing scheme and basic data types of LNet. + * + * The LNet API is memory-oriented, so LNet must be able to address not only + * end-points but also memory region within a process address space. + * An ::lnet_nid_t addresses an end-point. An ::lnet_pid_t identifies a process + * in a node. A portal represents an opening in the address space of a + * process. Match bits is criteria to identify a region of memory inside a + * portal, and offset specifies an offset within the memory region. + * + * LNet creates a table of portals for each process during initialization. + * This table has MAX_PORTALS entries and its size can't be dynamically + * changed. A portal stays empty until the owning process starts to add + * memory regions to it. A portal is sometimes called an index because + * it's an entry in the portals table of a process. + * + * \see LNetMEAttach + * @{ */ +int LNetGetId(unsigned int index, struct lnet_process_id *id); +int LNetDist(lnet_nid_t nid, lnet_nid_t *srcnid, __u32 *order); +lnet_nid_t LNetPrimaryNID(lnet_nid_t nid); +bool LNetIsPeerLocal(lnet_nid_t nid); +/** @} lnet_addr */ +/** \defgroup lnet_me Match entries + * + * A match entry (abbreviated as ME) describes a set of criteria to accept + * incoming requests. + * + * A portal is essentially a match list plus a set of attributes. A match + * list is a chain of MEs. Each ME includes a pointer to a memory descriptor + * and a set of match criteria. The match criteria can be used to reject + * incoming requests based on process ID or the match bits provided in the + * request. MEs can be dynamically inserted into a match list by LNetMEAttach() + * and LNetMEInsert(), and removed from its list by LNetMEUnlink(). + * @{ */ +int LNetMEAttach(unsigned int portal, + struct lnet_process_id match_id_in, + __u64 match_bits_in, + __u64 ignore_bits_in, + enum lnet_unlink unlink_in, + enum lnet_ins_pos pos_in, + struct lnet_handle_me *handle_out); + +int LNetMEInsert(struct lnet_handle_me current_in, + struct lnet_process_id match_id_in, + __u64 match_bits_in, + __u64 ignore_bits_in, + enum lnet_unlink unlink_in, + enum lnet_ins_pos position_in, + struct lnet_handle_me *handle_out); + +int LNetMEUnlink(struct lnet_handle_me current_in); +/** @} lnet_me */ + +/** \defgroup lnet_md Memory descriptors + * + * A memory descriptor contains information about a region of a user's + * memory (either in kernel or user space) and optionally points to an + * event queue where information about the operations performed on the + * memory descriptor are recorded. Memory descriptor is abbreviated as + * MD and can be used interchangeably with the memory region it describes. + * + * The LNet API provides two operations to create MDs: LNetMDAttach() + * and LNetMDBind(); one operation to unlink and release the resources + * associated with a MD: LNetMDUnlink(). + * @{ */ +int LNetMDAttach(struct lnet_handle_me current_in, + struct lnet_md md_in, + enum lnet_unlink unlink_in, + struct lnet_handle_md *md_handle_out); + +int LNetMDBind(struct lnet_md md_in, + enum lnet_unlink unlink_in, + struct lnet_handle_md *md_handle_out); + +int LNetMDUnlink(struct lnet_handle_md md_in); +/** @} lnet_md */ + +/** \defgroup lnet_eq Events and event queues + * + * Event queues (abbreviated as EQ) are used to log operations performed on + * local MDs. In particular, they signal the completion of a data transmission + * into or out of a MD. They can also be used to hold acknowledgments for + * completed PUT operations and indicate when a MD has been unlinked. Multiple + * MDs can share a single EQ. An EQ may have an optional event handler + * associated with it. If an event handler exists, it will be run for each + * event that is deposited into the EQ. + * + * In addition to the struct lnet_handle_eq, the LNet API defines two types + * associated with events: The ::lnet_event_kind defines the kinds of events + * that can be stored in an EQ. The struct lnet_event defines a structure that + * holds the information about with an event. + * + * There are five functions for dealing with EQs: LNetEQAlloc() is used to + * create an EQ and allocate the resources needed, while LNetEQFree() + * releases these resources and free the EQ. LNetEQGet() retrieves the next + * event from an EQ, and LNetEQWait() can be used to block a process until + * an EQ has at least one event. LNetEQPoll() can be used to test or wait + * on multiple EQs. + * @{ */ +int LNetEQAlloc(unsigned int count_in, + lnet_eq_handler_t handler, + struct lnet_handle_eq *handle_out); + +int LNetEQFree(struct lnet_handle_eq eventq_in); + +int LNetEQGet(struct lnet_handle_eq eventq_in, + struct lnet_event *event_out); + +int LNetEQWait(struct lnet_handle_eq eventq_in, + struct lnet_event *event_out); + +int LNetEQPoll(struct lnet_handle_eq *eventqs_in, + int neq_in, + signed long timeout, + struct lnet_event *event_out, + int *which_eq_out); +/** @} lnet_eq */ + +/** \defgroup lnet_data Data movement operations + * + * The LNet API provides two data movement operations: LNetPut() + * and LNetGet(). + * @{ */ +int LNetPut(lnet_nid_t self, + struct lnet_handle_md md_in, + enum lnet_ack_req ack_req_in, + struct lnet_process_id target_in, + unsigned int portal_in, + __u64 match_bits_in, + unsigned int offset_in, + __u64 hdr_data_in); + +int LNetGet(lnet_nid_t self, + struct lnet_handle_md md_in, + struct lnet_process_id target_in, + unsigned int portal_in, + __u64 match_bits_in, + unsigned int offset_in); +/** @} lnet_data */ + + +/** \defgroup lnet_misc Miscellaneous operations. + * Miscellaneous operations. + * @{ */ + +int LNetSetLazyPortal(int portal); +int LNetClearLazyPortal(int portal); +int LNetCtl(unsigned int cmd, void *arg); +void LNetDebugPeer(struct lnet_process_id id); + +/** @} lnet_misc */ + +/** @} lnet */ #endif