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 *  Specification of the OpenSM transport API. This API is OpenSM's view
39 *  of the Infiniband transport.
40 */
41
42#ifndef _OSM_VENDOR_API_H_
43#define _OSM_VENDOR_API_H_
44
45#include <opensm/osm_madw.h>
46#include <opensm/osm_mad_pool.h>
47#include <vendor/osm_vendor.h>
48
49#ifdef __cplusplus
50#  define BEGIN_C_DECLS extern "C" {
51#  define END_C_DECLS   }
52#else				/* !__cplusplus */
53#  define BEGIN_C_DECLS
54#  define END_C_DECLS
55#endif				/* __cplusplus */
56
57BEGIN_C_DECLS
58/****s* OpenSM Vendor API/osm_vend_mad_recv_callback_t
59* NAME
60*  osm_vend_mad_recv_callback_t
61*
62* DESCRIPTION
63*  Function prototype for the vendor MAD receive callback.
64*  The vendor layer calls this function for MAD receives.
65*
66* SYNOPSIS
67*/
68typedef void (*osm_vend_mad_recv_callback_t) (IN osm_madw_t * p_madw,
69					      IN void *bind_context,
70					      IN osm_madw_t * p_req_madw);
71/*
72* PARAMETERS
73*  p_madw
74*     [in] The received MAD wrapper.
75*
76*  bind_context
77*     [in] User context supplied during the bind call.
78*
79*  p_req_madw
80*     [in] Pointer to the request mad wrapper that generated this response.
81*     If the inbound MAD is not a response, this field is NULL.
82*
83* RETURN VALUES
84*  None.
85*
86* NOTES
87*
88* SEE ALSO
89*********/
90
91/****s* OpenSM Vendor API/osm_vend_mad_send_err_callback_t
92* NAME
93*  osm_vend_mad_send_err_callback_t
94*
95* DESCRIPTION
96*  Function prototype for the vendor send failure callback.
97*  The vendor layer calls this function when MADs expecting
98*  a response are completed in error, most likely due to a
99*  timeout.
100*
101* SYNOPSIS
102*/
103typedef void (*osm_vend_mad_send_err_callback_t) (IN void *bind_context,
104						  IN osm_madw_t * p_madw);
105/*
106* PARAMETERS
107*  bind_context
108*     [in] User context supplied during the bind call.
109*
110*  p_madw
111*     [in] Pointer to the request mad that failed.
112*
113* RETURN VALUES
114*  None.
115*
116* NOTES
117*  The vendor layer does not call this function (or any other)
118*  for MADs that were not expecting a response.
119*
120* SEE ALSO
121*********/
122
123/****f* OpenSM Vendor API/osm_vendor_new
124* NAME
125*  osm_vendor_new
126*
127* DESCRIPTION
128*  Allocates and initializes a new osm_vendor_t object.
129*  OpenSM calls this function before any other in the vendor API.
130*  This object is passed as a parameter to all other vendor functions.
131*
132* SYNOPSIS
133*/
134osm_vendor_t *osm_vendor_new(IN osm_log_t * const p_log,
135			     IN const uint32_t timeout);
136/*
137* PARAMETERS
138*  p_log
139*     [in] Pointer to the log object to use.
140*
141*  timeout
142*     [in] transaction timeout
143*
144* RETURN VALUES
145*  Returns a pointer to the vendor object.
146*
147* NOTES
148*
149* SEE ALSO
150*********/
151
152/****s* OpenSM Vendor API/osm_vendor_delete
153* NAME
154*  osm_vendor_delete
155*
156* DESCRIPTION
157*  Dealocate the vendor object.
158*
159* SYNOPSIS
160*/
161void osm_vendor_delete(IN osm_vendor_t ** const pp_vend);
162/*
163* PARAMETERS
164*  pp_vend
165*     [in/out] pointer to pointer to vendor objcet to be deleted
166*
167* RETURN VALUES
168*  None
169*
170* NOTES
171*
172* SEE ALSO
173*********/
174
175/****f* OpenSM Vendor API/osm_vendor_get_ports
176* NAME
177*  osm_vendor_get_ports
178*
179* DESCRIPTION
180*  Returns an array of available port attribute structures.
181*
182* SYNOPSIS
183*/
184ib_api_status_t
185osm_vendor_get_all_port_attr(IN osm_vendor_t * const p_vend,
186			     IN ib_port_attr_t * const p_attr_array,
187			     IN uint32_t * const p_num_ports);
188/*
189* PARAMETERS
190*  p_vend
191*     [in] Pointer to the vendor object to initialize.
192*
193*  p_attr_array
194*     [in/out] Pointer to pre-allocated array of port attributes.
195*     If it is NULL - then the command only updates the p_num_ports,
196*     and return IB_INSUFFICIENT_MEMORY.
197*
198*  p_num_ports
199*     [in/out] Pointer to a variable to hold the total number of ports
200*     available on the local machine..
201*
202* RETURN VALUES
203*  IB_SUCCESS on success.
204*  IB_INSUFFICIENT_MEMORY if the attribute array was not large enough.
205*  The number of attributes needed is returned in num_guids.
206*
207* NOTES
208*
209* SEE ALSO
210*********/
211
212/****f* OpenSM Vendor API/osm_vendor_init
213* NAME
214*  osm_vendor_init
215*
216* DESCRIPTION
217*  The osm_vendor_init function initializes the vendor transport layer.
218*
219* SYNOPSIS
220*/
221ib_api_status_t
222osm_vendor_init(IN osm_vendor_t * const p_vend,
223		IN osm_log_t * const p_log, IN const uint32_t timeout);
224/*
225* PARAMETERS
226*  p_vend
227*     [in] Pointer to the vendor object to initialize.
228*
229*  p_log
230*     [in] Pointer to OpenSM's log object.  Vendor code may
231*     use the log object to send messages to OpenSM's log.
232*
233*  timeout
234*     [in] Transaction timeout value in milliseconds.
235*     A value of 0 disables timeouts.
236*
237* RETURN VALUE
238*
239* NOTES
240*
241* SEE ALSO
242*********/
243
244/****f* OpenSM Vendor API/osm_vendor_bind
245* NAME
246*   osm_vendor_bind
247*
248* DESCRIPTION
249*   The osm_vendor_bind function registers with the vendor transport layer
250*   per Mad Class per PortGuid for mad transport capability.
251*
252* SYNOPSIS
253*/
254osm_bind_handle_t
255osm_vendor_bind(IN osm_vendor_t * const p_vend,
256		IN osm_bind_info_t * const p_bind_info,
257		IN osm_mad_pool_t * const p_mad_pool,
258		IN osm_vend_mad_recv_callback_t mad_recv_callback,
259		IN osm_vend_mad_send_err_callback_t send_err_callback,
260		IN void *context);
261/*
262* PARAMETERS
263*  p_vend
264*    [in] pointer to the vendor object
265*
266*  p_osm_bind_info
267*    [in] pointer to a struct defining the type of bind to perform.
268*
269*  p_mad_pool
270*    [in] pointer to a mad wrappers pool to be used for allocating
271*    mad wrappers on send and receive.
272*
273*  mad_recv_callback
274*    [in] the callback function to be invoked on mad receive.
275*
276*  send_err_callback
277*    [in] the callback function to be invoked on mad transaction errors.
278*
279*  context
280*    [in] the context to be provided to the callbacks as bind_ctx.
281*
282* RETURN VALUE
283*  On success, a valid bind handle.
284*  OSM_BIND_INVALID_HANDLE otherwise.
285*
286* NOTES
287*
288* SEE ALSO
289*********/
290
291/****f* OpenSM Vendor API/osm_vendor_unbind
292* NAME
293*   osm_vendor_unbind
294*
295* DESCRIPTION
296*   Unbind the given bind handle (obtained by osm_vendor_bind).
297*
298* SYNOPSIS
299*/
300void osm_vendor_unbind(IN osm_bind_handle_t h_bind);
301/*
302* PARAMETERS
303*  h_bind
304*    [in] the bind handle to release.
305*
306* RETURN VALUE
307*    NONE.
308*
309* NOTES
310*
311* SEE ALSO
312*********/
313
314/****f* OpenSM Vendor API/osm_vendor_get
315* NAME
316*   osm_vendor_get
317*
318* DESCRIPTION
319*   Obtain a mad wrapper holding actual mad buffer to be sent via
320*   the transport.
321*
322* SYNOPSIS
323*/
324ib_mad_t *osm_vendor_get(IN osm_bind_handle_t h_bind,
325			 IN const uint32_t mad_size,
326			 IN osm_vend_wrap_t * const p_vend_wrap);
327/*
328* PARAMETERS
329*   h_bind
330*      [in] the bind handle obtained by calling osm_vendor_bind
331*
332*   mad_size
333*      [in] the actual mad size required
334*
335*   p_vend_wrap
336*      [out] the returned mad vendor wrapper
337*
338* RETURN VALUE
339*   IB_SUCCESS on succesful completion.
340*
341* NOTES
342*
343* SEE ALSO
344*********/
345
346/****f* OpenSM Vendor API/osm_vendor_send
347* NAME
348*   osm_vendor_send
349*
350* DESCRIPTION
351*
352* SYNOPSIS
353*/
354ib_api_status_t
355osm_vendor_send(IN osm_bind_handle_t h_bind,
356		IN osm_madw_t * const p_madw, IN boolean_t const resp_expected);
357/*
358* PARAMETERS
359*   h_bind
360*      [in] the bind handle obtained by calling osm_vendor_bind
361*
362*   p_madw
363*      [in] pointer to the Mad Wrapper structure for the MAD to be sent.
364*
365*   resp_expected
366*      [in] boolean value declaring the mad as a request (expecting a response).
367*
368* RETURN VALUE
369*   IB_SUCCESS on succesful completion.
370*
371* NOTES
372*   1. Only mads that expect a response are tracked for transaction competion.
373*   2. A mad that does not expect a response is being put back immediatly after
374*      being sent.
375*
376* SEE ALSO
377*********/
378
379/****f* OpenSM Vendor API/osm_vendor_put
380* NAME
381*   osm_vendor_put
382*
383* DESCRIPTION
384*   Return a mad vendor wrapper to the mad pool. It also means that the
385*   mad buffer is returned to the transport.
386*
387* SYNOPSIS
388*/
389void
390osm_vendor_put(IN osm_bind_handle_t h_bind,
391	       IN osm_vend_wrap_t * const p_vend_wrap);
392/*
393* PARAMETERS
394*   h_bind
395*      [in] the bind handle obtained by calling osm_vendor_bind
396*
397*   p_vend_wrap
398*      [in] pointer to the mad vendor wrapper to put back into the pool.
399*
400* RETURN VALUE
401*   None.
402*
403* NOTES
404*
405* SEE ALSO
406*********/
407
408/****i* OpenSM Vendor API/osm_vendor_local_lid_change
409* NAME
410*   osm_vendor_local_lid_change
411*
412* DESCRIPTION
413*  Notifies the vendor transport layer that the local address
414*  has changed.  This allows the vendor layer to perform housekeeping
415*  functions such as address vector updates.
416*
417* SYNOPSIS
418*/
419ib_api_status_t osm_vendor_local_lid_change(IN osm_bind_handle_t h_bind);
420/*
421* PARAMETERS
422*   h_bind
423*      [in] the bind handle obtained by calling osm_vendor_bind
424*
425* RETURN VALUE
426*
427* NOTES
428*
429* SEE ALSO
430*********/
431
432/****f* OpenSM Vendor API/osm_vendor_set_sm
433* NAME
434*   osm_vendor_set_sm
435*
436* DESCRIPTION
437*  Modifies the port info for the bound port to set the "IS_SM" bit
438*  according to the value given (TRUE or FALSE).
439*
440* SYNOPSIS
441*/
442void osm_vendor_set_sm(IN osm_bind_handle_t h_bind, IN boolean_t is_sm_val);
443/*
444* PARAMETERS
445*   h_bind
446*     [in] bind handle for this port.
447*
448*   is_sm_val
449*     [in] If TRUE - will set the is_sm to TRUE, if FALSE - will set the
450*          the is_sm to FALSE.
451*
452* RETURN VALUE
453*  None.
454*
455* NOTES
456*
457* SEE ALSO
458*********/
459
460/****f* OpenSM Vendor API/osm_vendor_set_debug
461* NAME
462*   osm_vendor_set_debug
463*
464* DESCRIPTION
465*  Modifies the vendor specific debug level.
466*
467* SYNOPSIS
468*/
469void osm_vendor_set_debug(IN osm_vendor_t * const p_vend, IN int32_t level);
470/*
471* PARAMETERS
472*   p_vend
473*     [in] vendor handle.
474*
475*   level
476*     [in] vendor specific debug level.
477*
478* RETURN VALUE
479*  None.
480*
481* NOTES
482*
483* SEE ALSO
484*********/
485
486END_C_DECLS
487#endif				/* _OSM_VENDOR_API_H_ */
488