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.
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:
12 * Redistribution and use in source and binary forms, with or
13 * without modification, are permitted provided that the following
16 * - Redistributions of source code must retain the above
17 * copyright notice, this list of conditions and the following
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.
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
38 * Declaration of osm_vl15_t.
39 * This object represents an IBA subnet.
40 * This object is part of the OpenSM family of objects.
43 #ifndef _OSM_VL15INTF_H_
44 #define _OSM_VL15INTF_H_
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>
58 # define BEGIN_C_DECLS extern "C" {
59 # define END_C_DECLS }
60 #else /* !__cplusplus */
61 # define BEGIN_C_DECLS
63 #endif /* __cplusplus */
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.
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
80 * The VL15 object is thread safe.
82 * This object should be treated as opaque and should
83 * be manipulated only through the provided functions.
89 /****d* OpenSM: SM/osm_vl15_state_t
94 * Enumerates the possible states of SM object.
98 typedef enum _osm_vl15_state {
99 OSM_VL15_STATE_INIT = 0,
104 /****s* OpenSM: VL15/osm_vl15_t
111 * This object should be treated as opaque and should
112 * be manipulated only through the provided functions.
116 typedef struct osm_vl15 {
117 osm_thread_state_t thread_state;
118 osm_vl15_state_t state;
119 uint32_t max_wire_smps;
125 osm_vendor_t *p_vend;
127 osm_stats_t *p_stats;
132 * Tracks the thread state of the poller thread.
135 * Tracks the state of the VL15 interface itself.
138 * Maximum number of VL15 MADs allowed on the wire at one time.
141 * Event on which the poller sleeps.
144 * First-in First-out queue for outbound VL15 MADs for which
145 * a response is expected, aka the "response fifo"
148 * First-in First-out queue for outbound VL15 MADs for which
149 * no response is expected, aka the "unicast fifo".
152 * Worker thread pool that services the fifo to transmit VL15 MADs
155 * Spinlock guarding the FIFO.
158 * Pointer to the vendor transport object.
161 * Pointer to the log object.
164 * Pointer to the OpenSM statistics block.
170 /****f* OpenSM: VL15/osm_vl15_construct
175 * This function constructs an VL15 object.
179 void osm_vl15_construct(IN osm_vl15_t * const p_vl15);
183 * [in] Pointer to a VL15 object to construct.
186 * This function does not return a value.
189 * Allows calling osm_vl15_destroy.
191 * Calling osm_vl15_construct is a prerequisite to calling any other
192 * method except osm_vl15_init.
195 * VL15 object, osm_vl15_init, osm_vl15_destroy
198 /****f* OpenSM: VL15/osm_vl15_destroy
203 * The osm_vl15_destroy function destroys the object, releasing
209 osm_vl15_destroy(IN osm_vl15_t * const p_vl15, IN struct osm_mad_pool *p_pool);
213 * [in] Pointer to a VL15 object to destroy.
216 * [in] The pointer to the mad pool to return outstanding mads to
219 * This function does not return a value.
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
228 * VL15 object, osm_vl15_construct, osm_vl15_init
233 Rate specifies the minimum number of microseconds between transmissions
236 /****f* OpenSM: VL15/osm_vl15_init
241 * The osm_vl15_init function initializes a VL15 object for use.
246 osm_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);
254 * [in] Pointer to an osm_vl15_t object to initialize.
257 * [in] Pointer to the vendor transport object.
260 * [in] Pointer to the log object.
263 * [in] Pointer to the OpenSM stastics block.
266 * [in] Maximum number of MADs allowed on the wire at one time.
269 * IB_SUCCESS if the VL15 object was initialized successfully.
272 * Allows calling other VL15 methods.
275 * VL15 object, osm_vl15_construct, osm_vl15_destroy
278 /****f* OpenSM: VL15/osm_vl15_post
283 * Posts a MAD to the VL15 interface for transmission.
287 void osm_vl15_post(IN osm_vl15_t * const p_vl15, IN osm_madw_t * const p_madw);
291 * [in] Pointer to an osm_vl15_t object.
294 * [in] Pointer to a MAD wrapper structure containing the MAD.
297 * This function does not return a value.
300 * The osm_vl15_construct or osm_vl15_init must be called before using
304 * VL15 object, osm_vl15_construct, osm_vl15_init
307 /****f* OpenSM: VL15/osm_vl15_poll
312 * Causes the VL15 Interface to consider sending another QP0 MAD.
316 void osm_vl15_poll(IN osm_vl15_t * const p_vl);
320 * [in] Pointer to an osm_vl15_t object.
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
333 * VL15 object, osm_vl15_construct, osm_vl15_init
336 /****f* OpenSM: VL15/osm_vl15_shutdown
341 * Cleanup all outstanding MADs on both fifo's.
342 * This is required to return all outstanding MAD resources.
347 osm_vl15_shutdown(IN osm_vl15_t * const p_vl,
348 IN osm_mad_pool_t * const p_mad_pool);
352 * [in] Pointer to an osm_vl15_t object.
355 * [in] The MAD pool owning the mads.
363 * VL15 object, osm_vl15_construct, osm_vl15_init
367 #endif /* _OSM_VL15INTF_H_ */