X-Git-Url: https://git.whamcloud.com/?a=blobdiff_plain;f=lnet%2Finclude%2Flnet%2Fapi.h;h=8871124341ca7a1ad3c4556ef68ed2f10ffb55f9;hb=9b0738c53c962f4269178e420d45565f9ec5bd09;hp=adbe2e28bf85bc312a1b1de5dfb7a13a0916f709;hpb=c43e26a94c069e25c8f01b435310ded31b029bee;p=fs%2Flustre-release.git diff --git a/lnet/include/lnet/api.h b/lnet/include/lnet/api.h index adbe2e2..8871124 100644 --- a/lnet/include/lnet/api.h +++ b/lnet/include/lnet/api.h @@ -1,110 +1,171 @@ -#ifndef __LNET_API_H__ -#define __LNET_API_H__ - -#include - -int LNetInit(void); -void LNetFini(void); - -int LNetNIInit(lnet_pid_t requested_pid); -int LNetNIFini(void); - -int LNetGetId(unsigned int index, lnet_process_id_t *id); -int LNetDist(lnet_nid_t nid, lnet_nid_t *srcnid, __u32 *order); -int LNetCtl(unsigned int cmd, void *arg); -void LNetSnprintHandle (char *str, int str_len, lnet_handle_any_t handle); - /* - * Portals + * GPL HEADER START + * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * 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). + * + * 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 */ -int LNetSetLazyPortal(int portal); -int LNetClearLazyPortal(int portal); - /* - * Match entries + * Copyright (c) 2003, 2010, Oracle and/or its affiliates. All rights reserved. + * Use is subject to license terms. + * + * Copyright (c) 2016, 2017, Intel Corporation. */ -int LNetMEAttach(unsigned int portal, - lnet_process_id_t match_id_in, - __u64 match_bits_in, - __u64 ignore_bits_in, - lnet_unlink_t unlink_in, - lnet_ins_pos_t pos_in, - lnet_handle_me_t *handle_out); - -int LNetMEInsert(lnet_handle_me_t current_in, - lnet_process_id_t match_id_in, - __u64 match_bits_in, - __u64 ignore_bits_in, - lnet_unlink_t unlink_in, - lnet_ins_pos_t position_in, - lnet_handle_me_t *handle_out); - -int LNetMEUnlink(lnet_handle_me_t current_in); - /* - * Memory descriptors + * This file is part of Lustre, http://www.lustre.org/ */ -int LNetMDAttach(lnet_handle_me_t current_in, - lnet_md_t md_in, - lnet_unlink_t unlink_in, - lnet_handle_md_t *handle_out); -int LNetMDBind(lnet_md_t md_in, - lnet_unlink_t unlink_in, - lnet_handle_md_t *handle_out); - -int LNetMDUnlink(lnet_handle_md_t md_in); +#ifndef __LNET_API_H__ +#define __LNET_API_H__ -/* - * 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. + * @{ */ -int LNetEQAlloc(unsigned int count_in, - lnet_eq_handler_t handler, - lnet_handle_eq_t *handle_out); - -int LNetEQFree(lnet_handle_eq_t eventq_in); - -int LNetEQGet(lnet_handle_eq_t eventq_in, - lnet_event_t *event_out); - -int LNetEQWait(lnet_handle_eq_t eventq_in, - lnet_event_t *event_out); +#ifndef __KERNEL__ +# error This include is only for kernel use. +#endif -int LNetEQPoll(lnet_handle_eq_t *eventqs_in, - int neq_in, - int timeout_ms, - lnet_event_t *event_out, - int *which_eq_out); +#include -/* - * Data movement - */ -int LNetPut(lnet_nid_t self, - lnet_handle_md_t md_in, - lnet_ack_req_t ack_req_in, - lnet_process_id_t target_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 */ + +/** \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 must then be attached to an MD with LNetMDAttach(). + * @{ */ +struct lnet_me * +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); +/** @} 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_me *current_in, + const struct lnet_md *md_in, + enum lnet_unlink unlink_in, + struct lnet_handle_md *md_handle_out); + +int LNetMDBind(const 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, bool discard); +#define LNetMDUnlink(handle) __LNetMDUnlink(handle, false) + +void lnet_assert_handler_unused(lnet_handler_t handler); +/** @} lnet_md */ + +/** \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); + __u64 match_bits_in, + unsigned int offset_in, + __u64 hdr_data_in); -int LNetGet(lnet_nid_t self, - lnet_handle_md_t md_in, - lnet_process_id_t target_in, - unsigned int portal_in, - __u64 match_bits_in, - unsigned int offset_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, + bool recovery); +/** @} lnet_data */ -int LNetSetAsync(lnet_process_id_t id, int nasync); +/** \defgroup lnet_misc Miscellaneous operations. + * Miscellaneous operations. + * @{ */ -#ifndef __KERNEL__ -/* Temporary workaround to allow uOSS and test programs force server - * mode in userspace. See comments near ln_server_mode_flag in - * lnet/lib-types.h */ +int LNetSetLazyPortal(int portal); +int LNetClearLazyPortal(int portal); +int LNetCtl(unsigned int cmd, void *arg); +void LNetDebugPeer(struct lnet_process_id id); +int LNetGetPeerDiscoveryStatus(void); +int LNetAddPeer(lnet_nid_t *nids, __u32 num_nids); -void lnet_server_mode(); -#endif +/** @} lnet_misc */ +/** @} lnet */ #endif