1 /* 2 * Copyright (c) 2004-2009 Voltaire, Inc. All rights reserved. 3 * Copyright (c) 2002-2010 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 a VL15 interface object. 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 #include <opensm/osm_subnet.h> 57 58 #ifdef __cplusplus 59 # define BEGIN_C_DECLS extern "C" { 60 # define END_C_DECLS } 61 #else /* !__cplusplus */ 62 # define BEGIN_C_DECLS 63 # define END_C_DECLS 64 #endif /* __cplusplus */ 65 66 BEGIN_C_DECLS 67 /****h* OpenSM/VL15 68 * NAME 69 * VL15 70 * 71 * DESCRIPTION 72 * The VL15 object encapsulates the information needed by the 73 * OpenSM to instantiate the VL15 interface. The OpenSM allocates 74 * one VL15 object per subnet. 75 * 76 * The VL15 object transmits MADs to the wire at a throttled rate, 77 * so as to not overload the VL15 buffering of subnet components. 78 * OpenSM modules may post VL15 MADs to the VL15 interface as fast 79 * as possible. 80 * 81 * The VL15 object is thread safe. 82 * 83 * This object should be treated as opaque and should 84 * be manipulated only through the provided functions. 85 * 86 * AUTHOR 87 * Steve King, Intel 88 * 89 *********/ 90 /****d* OpenSM: SM/osm_vl15_state_t 91 * NAME 92 * osm_vl15_state_t 93 * 94 * DESCRIPTION 95 * Enumerates the possible states of SM object. 96 * 97 * SYNOPSIS 98 */ 99 typedef enum _osm_vl15_state { 100 OSM_VL15_STATE_INIT = 0, 101 OSM_VL15_STATE_READY 102 } osm_vl15_state_t; 103 /***********/ 104 105 /****s* OpenSM: VL15/osm_vl15_t 106 * NAME 107 * osm_vl15_t 108 * 109 * DESCRIPTION 110 * VL15 structure. 111 * 112 * This object should be treated as opaque and should 113 * be manipulated only through the provided functions. 114 * 115 * SYNOPSIS 116 */ 117 typedef struct osm_vl15 { 118 osm_thread_state_t thread_state; 119 osm_vl15_state_t state; 120 uint32_t max_wire_smps; 121 uint32_t max_wire_smps2; 122 uint32_t max_smps_timeout; 123 cl_event_t signal; 124 cl_thread_t poller; 125 cl_qlist_t rfifo; 126 cl_qlist_t ufifo; 127 cl_spinlock_t lock; 128 osm_vendor_t *p_vend; 129 osm_log_t *p_log; 130 osm_stats_t *p_stats; 131 osm_subn_t *p_subn; 132 } osm_vl15_t; 133 /* 134 * FIELDS 135 * thread_state 136 * Tracks the thread state of the poller thread. 137 * 138 * state 139 * Tracks the state of the VL15 interface itself. 140 * 141 * max_wire_smps 142 * Maximum number of VL15 MADs allowed on the wire at one time. 143 * 144 * max_wire_smps2 145 * Maximum number of timeout based SMPs allowed to be outstanding. 146 * 147 * max_smps_timeout 148 * Wait time in usec for timeout based SMPs. 149 * 150 * signal 151 * Event on which the poller sleeps. 152 * 153 * rfifo 154 * First-in First-out queue for outbound VL15 MADs for which 155 * a response is expected, aka the "response fifo" 156 * 157 * ufifo 158 * First-in First-out queue for outbound VL15 MADs for which 159 * no response is expected, aka the "unicast fifo". 160 * 161 * poller 162 * Worker thread pool that services the fifo to transmit VL15 MADs 163 * 164 * lock 165 * Spinlock guarding the FIFO. 166 * 167 * p_vend 168 * Pointer to the vendor transport object. 169 * 170 * p_log 171 * Pointer to the log object. 172 * 173 * p_stats 174 * Pointer to the OpenSM statistics block. 175 * 176 * p_subn 177 * Pointer to the OpenSM subnet object. 178 * 179 * SEE ALSO 180 * VL15 object 181 *********/ 182 183 /****f* OpenSM: VL15/osm_vl15_construct 184 * NAME 185 * osm_vl15_construct 186 * 187 * DESCRIPTION 188 * This function constructs an VL15 object. 189 * 190 * SYNOPSIS 191 */ 192 void osm_vl15_construct(IN osm_vl15_t * p_vl15); 193 /* 194 * PARAMETERS 195 * p_vl15 196 * [in] Pointer to a VL15 object to construct. 197 * 198 * RETURN VALUE 199 * This function does not return a value. 200 * 201 * NOTES 202 * Allows calling osm_vl15_destroy. 203 * 204 * Calling osm_vl15_construct is a prerequisite to calling any other 205 * method except osm_vl15_init. 206 * 207 * SEE ALSO 208 * VL15 object, osm_vl15_init, osm_vl15_destroy 209 *********/ 210 211 /****f* OpenSM: VL15/osm_vl15_destroy 212 * NAME 213 * osm_vl15_destroy 214 * 215 * DESCRIPTION 216 * The osm_vl15_destroy function destroys the object, releasing 217 * all resources. 218 * 219 * SYNOPSIS 220 */ 221 void osm_vl15_destroy(IN osm_vl15_t * p_vl15, IN struct osm_mad_pool *p_pool); 222 /* 223 * PARAMETERS 224 * p_vl15 225 * [in] Pointer to a VL15 object to destroy. 226 * 227 * p_pool 228 * [in] The pointer to the mad pool to return outstanding mads to 229 * 230 * RETURN VALUE 231 * This function does not return a value. 232 * 233 * NOTES 234 * Performs any necessary cleanup of the specified VL15 object. 235 * Further operations should not be attempted on the destroyed object. 236 * This function should only be called after a call to osm_vl15_construct or 237 * osm_vl15_init. 238 * 239 * SEE ALSO 240 * VL15 object, osm_vl15_construct, osm_vl15_init 241 *********/ 242 243 /* 244 Initialization. 245 Rate specifies the minimum number of microseconds between transmissions 246 on VL15. 247 */ 248 /****f* OpenSM: VL15/osm_vl15_init 249 * NAME 250 * osm_vl15_init 251 * 252 * DESCRIPTION 253 * The osm_vl15_init function initializes a VL15 object for use. 254 * 255 * SYNOPSIS 256 */ 257 ib_api_status_t osm_vl15_init(IN osm_vl15_t * p_vl15, IN osm_vendor_t * p_vend, 258 IN osm_log_t * p_log, IN osm_stats_t * p_stats, 259 IN osm_subn_t * p_subn, 260 IN int32_t max_wire_smps, 261 IN int32_t max_wire_smps2, 262 IN uint32_t max_smps_timeout); 263 /* 264 * PARAMETERS 265 * p_vl15 266 * [in] Pointer to an osm_vl15_t object to initialize. 267 * 268 * p_vend 269 * [in] Pointer to the vendor transport object. 270 * 271 * p_log 272 * [in] Pointer to the log object. 273 * 274 * p_stats 275 * [in] Pointer to the OpenSM statistics block. 276 * 277 * p_subn 278 * [in] Pointer to the OpenSM subnet object. 279 * 280 * max_wire_smps 281 * [in] Maximum number of SMPs allowed on the wire at one time. 282 * 283 * max_wire_smps2 284 * [in] Maximum number of timeout based SMPs allowed to be 285 * outstanding. 286 * 287 * max_smps_timeout 288 * [in] Wait time in usec for timeout based SMPs. 289 * 290 * 291 * RETURN VALUES 292 * IB_SUCCESS if the VL15 object was initialized successfully. 293 * 294 * NOTES 295 * Allows calling other VL15 methods. 296 * 297 * SEE ALSO 298 * VL15 object, osm_vl15_construct, osm_vl15_destroy 299 *********/ 300 301 /****f* OpenSM: VL15/osm_vl15_post 302 * NAME 303 * osm_vl15_post 304 * 305 * DESCRIPTION 306 * Posts a MAD to the VL15 interface for transmission. 307 * 308 * SYNOPSIS 309 */ 310 void osm_vl15_post(IN osm_vl15_t * p_vl15, IN osm_madw_t * p_madw); 311 /* 312 * PARAMETERS 313 * p_vl15 314 * [in] Pointer to an osm_vl15_t object. 315 * 316 * p_madw 317 * [in] Pointer to a MAD wrapper structure containing the MAD. 318 * 319 * RETURN VALUES 320 * This function does not return a value. 321 * 322 * NOTES 323 * The osm_vl15_construct or osm_vl15_init must be called before using 324 * this function. 325 * 326 * SEE ALSO 327 * VL15 object, osm_vl15_construct, osm_vl15_init 328 *********/ 329 330 /****f* OpenSM: VL15/osm_vl15_poll 331 * NAME 332 * osm_vl15_poll 333 * 334 * DESCRIPTION 335 * Causes the VL15 Interface to consider sending another QP0 MAD. 336 * 337 * SYNOPSIS 338 */ 339 void osm_vl15_poll(IN osm_vl15_t * p_vl); 340 /* 341 * PARAMETERS 342 * p_vl15 343 * [in] Pointer to an osm_vl15_t object. 344 * 345 * RETURN VALUES 346 * None. 347 * 348 * NOTES 349 * This function signals the VL15 that it may be possible to send 350 * a SMP. This function checks three criteria before sending a SMP: 351 * 1) The VL15 worker is IDLE 352 * 2) There are no QP0 SMPs currently outstanding 353 * 3) There is something on the VL15 FIFO to send 354 * 355 * SEE ALSO 356 * VL15 object, osm_vl15_construct, osm_vl15_init 357 *********/ 358 359 /****f* OpenSM: VL15/osm_vl15_shutdown 360 * NAME 361 * osm_vl15_shutdown 362 * 363 * DESCRIPTION 364 * Cleanup all outstanding MADs on both fifo's. 365 * This is required to return all outstanding MAD resources. 366 * 367 * SYNOPSIS 368 */ 369 void osm_vl15_shutdown(IN osm_vl15_t * p_vl, IN osm_mad_pool_t * p_mad_pool); 370 /* 371 * PARAMETERS 372 * p_vl15 373 * [in] Pointer to an osm_vl15_t object. 374 * 375 * p_mad_pool 376 * [in] The MAD pool owning the mads. 377 * 378 * RETURN VALUES 379 * None. 380 * 381 * NOTES 382 * 383 * SEE ALSO 384 * VL15 object, osm_vl15_construct, osm_vl15_init 385 *********/ 386 387 END_C_DECLS 388 #endif /* _OSM_VL15INTF_H_ */ 389