1/* 2 * Copyright (c) 2004, 2005 Voltaire, Inc. All rights reserved. 3 * Copyright (c) 2002-2005 Mellanox Technologies LTD. All rights reserved. 4 * Copyright (c) 1996-2003 Intel Corporation. All rights reserved. 5 * 6 * This software is available to you under a choice of one of two 7 * licenses. You may choose to be licensed under the terms of the GNU 8 * General Public License (GPL) Version 2, available from the file 9 * COPYING in the main directory of this source tree, or the 10 * OpenIB.org BSD license below: 11 * 12 * Redistribution and use in source and binary forms, with or 13 * without modification, are permitted provided that the following 14 * conditions are met: 15 * 16 * - Redistributions of source code must retain the above 17 * copyright notice, this list of conditions and the following 18 * disclaimer. 19 * 20 * - Redistributions in binary form must reproduce the above 21 * copyright notice, this list of conditions and the following 22 * disclaimer in the documentation and/or other materials 23 * provided with the distribution. 24 * 25 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 26 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 27 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 28 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS 29 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 30 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 31 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 32 * SOFTWARE. 33 * 34 */ 35 36/* 37 * Abstract: 38 * Declaration of osm_vl15_t. 39 * This object represents an IBA subnet. 40 * This object is part of the OpenSM family of objects. 41 */ 42 43#ifndef _OSM_VL15INTF_H_ 44#define _OSM_VL15INTF_H_ 45 46#include <iba/ib_types.h> 47#include <complib/cl_spinlock.h> 48#include <complib/cl_event.h> 49#include <complib/cl_thread.h> 50#include <complib/cl_qlist.h> 51#include <opensm/osm_stats.h> 52#include <opensm/osm_log.h> 53#include <opensm/osm_madw.h> 54#include <opensm/osm_mad_pool.h> 55#include <vendor/osm_vendor_api.h> 56 57#ifdef __cplusplus 58# define BEGIN_C_DECLS extern "C" { 59# define END_C_DECLS } 60#else /* !__cplusplus */ 61# define BEGIN_C_DECLS 62# define END_C_DECLS 63#endif /* __cplusplus */ 64 65BEGIN_C_DECLS 66/****h* OpenSM/VL15 67* NAME 68* VL15 69* 70* DESCRIPTION 71* The VL15 object encapsulates the information needed by the 72* OpenSM to instantiate the VL15 interface. The OpenSM allocates 73* one VL15 object per subnet. 74* 75* The VL15 object transmits MADs to the wire at a throttled rate, 76* so as to not overload the VL15 buffering of subnet components. 77* OpenSM modules may post VL15 MADs to the VL15 interface as fast 78* as possible. 79* 80* The VL15 object is thread safe. 81* 82* This object should be treated as opaque and should 83* be manipulated only through the provided functions. 84* 85* AUTHOR 86* Steve King, Intel 87* 88*********/ 89/****d* OpenSM: SM/osm_vl15_state_t 90* NAME 91* osm_vl15_state_t 92* 93* DESCRIPTION 94* Enumerates the possible states of SM object. 95* 96* SYNOPSIS 97*/ 98typedef enum _osm_vl15_state { 99 OSM_VL15_STATE_INIT = 0, 100 OSM_VL15_STATE_READY 101} osm_vl15_state_t; 102/***********/ 103 104/****s* OpenSM: VL15/osm_vl15_t 105* NAME 106* osm_vl15_t 107* 108* DESCRIPTION 109* VL15 structure. 110* 111* This object should be treated as opaque and should 112* be manipulated only through the provided functions. 113* 114* SYNOPSIS 115*/ 116typedef struct osm_vl15 { 117 osm_thread_state_t thread_state; 118 osm_vl15_state_t state; 119 uint32_t max_wire_smps; 120 cl_event_t signal; 121 cl_thread_t poller; 122 cl_qlist_t rfifo; 123 cl_qlist_t ufifo; 124 cl_spinlock_t lock; 125 osm_vendor_t *p_vend; 126 osm_log_t *p_log; 127 osm_stats_t *p_stats; 128} osm_vl15_t; 129/* 130* FIELDS 131* thread_state 132* Tracks the thread state of the poller thread. 133* 134* state 135* Tracks the state of the VL15 interface itself. 136* 137* max_wire_smps 138* Maximum number of VL15 MADs allowed on the wire at one time. 139* 140* signal 141* Event on which the poller sleeps. 142* 143* rfifo 144* First-in First-out queue for outbound VL15 MADs for which 145* a response is expected, aka the "response fifo" 146* 147* ufifo 148* First-in First-out queue for outbound VL15 MADs for which 149* no response is expected, aka the "unicast fifo". 150* 151* poller 152* Worker thread pool that services the fifo to transmit VL15 MADs 153* 154* lock 155* Spinlock guarding the FIFO. 156* 157* p_vend 158* Pointer to the vendor transport object. 159* 160* p_log 161* Pointer to the log object. 162* 163* p_stats 164* Pointer to the OpenSM statistics block. 165* 166* SEE ALSO 167* VL15 object 168*********/ 169 170/****f* OpenSM: VL15/osm_vl15_construct 171* NAME 172* osm_vl15_construct 173* 174* DESCRIPTION 175* This function constructs an VL15 object. 176* 177* SYNOPSIS 178*/ 179void osm_vl15_construct(IN osm_vl15_t * const p_vl15); 180/* 181* PARAMETERS 182* p_vl15 183* [in] Pointer to a VL15 object to construct. 184* 185* RETURN VALUE 186* This function does not return a value. 187* 188* NOTES 189* Allows calling osm_vl15_destroy. 190* 191* Calling osm_vl15_construct is a prerequisite to calling any other 192* method except osm_vl15_init. 193* 194* SEE ALSO 195* VL15 object, osm_vl15_init, osm_vl15_destroy 196*********/ 197 198/****f* OpenSM: VL15/osm_vl15_destroy 199* NAME 200* osm_vl15_destroy 201* 202* DESCRIPTION 203* The osm_vl15_destroy function destroys the object, releasing 204* all resources. 205* 206* SYNOPSIS 207*/ 208void 209osm_vl15_destroy(IN osm_vl15_t * const p_vl15, IN struct osm_mad_pool *p_pool); 210/* 211* PARAMETERS 212* p_vl15 213* [in] Pointer to a VL15 object to destroy. 214* 215* p_pool 216* [in] The pointer to the mad pool to return outstanding mads to 217* 218* RETURN VALUE 219* This function does not return a value. 220* 221* NOTES 222* Performs any necessary cleanup of the specified VL15 object. 223* Further operations should not be attempted on the destroyed object. 224* This function should only be called after a call to osm_vl15_construct or 225* osm_vl15_init. 226* 227* SEE ALSO 228* VL15 object, osm_vl15_construct, osm_vl15_init 229*********/ 230 231/* 232 Initialization. 233 Rate specifies the minimum number of microseconds between transmissions 234 on VL15. 235*/ 236/****f* OpenSM: VL15/osm_vl15_init 237* NAME 238* osm_vl15_init 239* 240* DESCRIPTION 241* The osm_vl15_init function initializes a VL15 object for use. 242* 243* SYNOPSIS 244*/ 245ib_api_status_t 246osm_vl15_init(IN osm_vl15_t * const p_vl15, 247 IN osm_vendor_t * const p_vend, 248 IN osm_log_t * const p_log, 249 IN osm_stats_t * const p_stats, 250 IN const int32_t max_wire_smps); 251/* 252* PARAMETERS 253* p_vl15 254* [in] Pointer to an osm_vl15_t object to initialize. 255* 256* p_vend 257* [in] Pointer to the vendor transport object. 258* 259* p_log 260* [in] Pointer to the log object. 261* 262* p_stats 263* [in] Pointer to the OpenSM stastics block. 264* 265* max_wire_smps 266* [in] Maximum number of MADs allowed on the wire at one time. 267* 268* RETURN VALUES 269* IB_SUCCESS if the VL15 object was initialized successfully. 270* 271* NOTES 272* Allows calling other VL15 methods. 273* 274* SEE ALSO 275* VL15 object, osm_vl15_construct, osm_vl15_destroy 276*********/ 277 278/****f* OpenSM: VL15/osm_vl15_post 279* NAME 280* osm_vl15_post 281* 282* DESCRIPTION 283* Posts a MAD to the VL15 interface for transmission. 284* 285* SYNOPSIS 286*/ 287void osm_vl15_post(IN osm_vl15_t * const p_vl15, IN osm_madw_t * const p_madw); 288/* 289* PARAMETERS 290* p_vl15 291* [in] Pointer to an osm_vl15_t object. 292* 293* p_madw 294* [in] Pointer to a MAD wrapper structure containing the MAD. 295* 296* RETURN VALUES 297* This function does not return a value. 298* 299* NOTES 300* The osm_vl15_construct or osm_vl15_init must be called before using 301* this function. 302* 303* SEE ALSO 304* VL15 object, osm_vl15_construct, osm_vl15_init 305*********/ 306 307/****f* OpenSM: VL15/osm_vl15_poll 308* NAME 309* osm_vl15_poll 310* 311* DESCRIPTION 312* Causes the VL15 Interface to consider sending another QP0 MAD. 313* 314* SYNOPSIS 315*/ 316void osm_vl15_poll(IN osm_vl15_t * const p_vl); 317/* 318* PARAMETERS 319* p_vl15 320* [in] Pointer to an osm_vl15_t object. 321* 322* RETURN VALUES 323* None. 324* 325* NOTES 326* This function signals the VL15 that it may be possible to send 327* a SMP. This function checks three criteria before sending a SMP: 328* 1) The VL15 worker is IDLE 329* 2) There are no QP0 SMPs currently outstanding 330* 3) There is something on the VL15 FIFO to send 331* 332* SEE ALSO 333* VL15 object, osm_vl15_construct, osm_vl15_init 334*********/ 335 336/****f* OpenSM: VL15/osm_vl15_shutdown 337* NAME 338* osm_vl15_shutdown 339* 340* DESCRIPTION 341* Cleanup all outstanding MADs on both fifo's. 342* This is required to return all outstanding MAD resources. 343* 344* SYNOPSIS 345*/ 346void 347osm_vl15_shutdown(IN osm_vl15_t * const p_vl, 348 IN osm_mad_pool_t * const p_mad_pool); 349/* 350* PARAMETERS 351* p_vl15 352* [in] Pointer to an osm_vl15_t object. 353* 354* p_mad_pool 355* [in] The MAD pool owning the mads. 356* 357* RETURN VALUES 358* None. 359* 360* NOTES 361* 362* SEE ALSO 363* VL15 object, osm_vl15_construct, osm_vl15_init 364*********/ 365 366END_C_DECLS 367#endif /* _OSM_VL15INTF_H_ */ 368