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 * Specification of the OpenSM transport API. This API is OpenSM's view
39 * of the Infiniband transport.
42 #ifndef _OSM_VENDOR_API_H_
43 #define _OSM_VENDOR_API_H_
45 #include <opensm/osm_madw.h>
46 #include <opensm/osm_mad_pool.h>
47 #include <vendor/osm_vendor.h>
50 # define BEGIN_C_DECLS extern "C" {
51 # define END_C_DECLS }
52 #else /* !__cplusplus */
53 # define BEGIN_C_DECLS
55 #endif /* __cplusplus */
58 /****s* OpenSM Vendor API/osm_vend_mad_recv_callback_t
60 * osm_vend_mad_recv_callback_t
63 * Function prototype for the vendor MAD receive callback.
64 * The vendor layer calls this function for MAD receives.
68 typedef 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);
74 * [in] The received MAD wrapper.
77 * [in] User context supplied during the bind call.
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.
91 /****s* OpenSM Vendor API/osm_vend_mad_send_err_callback_t
93 * osm_vend_mad_send_err_callback_t
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
103 typedef void (*osm_vend_mad_send_err_callback_t) (IN void *bind_context,
104 IN osm_madw_t * p_madw);
108 * [in] User context supplied during the bind call.
111 * [in] Pointer to the request mad that failed.
117 * The vendor layer does not call this function (or any other)
118 * for MADs that were not expecting a response.
123 /****f* OpenSM Vendor API/osm_vendor_new
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.
134 osm_vendor_t *osm_vendor_new(IN osm_log_t * const p_log,
135 IN const uint32_t timeout);
139 * [in] Pointer to the log object to use.
142 * [in] transaction timeout
145 * Returns a pointer to the vendor object.
152 /****s* OpenSM Vendor API/osm_vendor_delete
157 * Dealocate the vendor object.
161 void osm_vendor_delete(IN osm_vendor_t ** const pp_vend);
165 * [in/out] pointer to pointer to vendor objcet to be deleted
175 /****f* OpenSM Vendor API/osm_vendor_get_ports
177 * osm_vendor_get_ports
180 * Returns an array of available port attribute structures.
185 osm_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);
191 * [in] Pointer to the vendor object to initialize.
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.
199 * [in/out] Pointer to a variable to hold the total number of ports
200 * available on the local machine..
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.
212 /****f* OpenSM Vendor API/osm_vendor_init
217 * The osm_vendor_init function initializes the vendor transport layer.
222 osm_vendor_init(IN osm_vendor_t * const p_vend,
223 IN osm_log_t * const p_log, IN const uint32_t timeout);
227 * [in] Pointer to the vendor object to initialize.
230 * [in] Pointer to OpenSM's log object. Vendor code may
231 * use the log object to send messages to OpenSM's log.
234 * [in] Transaction timeout value in milliseconds.
235 * A value of 0 disables timeouts.
244 /****f* OpenSM Vendor API/osm_vendor_bind
249 * The osm_vendor_bind function registers with the vendor transport layer
250 * per Mad Class per PortGuid for mad transport capability.
255 osm_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,
264 * [in] pointer to the vendor object
267 * [in] pointer to a struct defining the type of bind to perform.
270 * [in] pointer to a mad wrappers pool to be used for allocating
271 * mad wrappers on send and receive.
274 * [in] the callback function to be invoked on mad receive.
277 * [in] the callback function to be invoked on mad transaction errors.
280 * [in] the context to be provided to the callbacks as bind_ctx.
283 * On success, a valid bind handle.
284 * OSM_BIND_INVALID_HANDLE otherwise.
291 /****f* OpenSM Vendor API/osm_vendor_unbind
296 * Unbind the given bind handle (obtained by osm_vendor_bind).
300 void osm_vendor_unbind(IN osm_bind_handle_t h_bind);
304 * [in] the bind handle to release.
314 /****f* OpenSM Vendor API/osm_vendor_get
319 * Obtain a mad wrapper holding actual mad buffer to be sent via
324 ib_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);
330 * [in] the bind handle obtained by calling osm_vendor_bind
333 * [in] the actual mad size required
336 * [out] the returned mad vendor wrapper
339 * IB_SUCCESS on succesful completion.
346 /****f* OpenSM Vendor API/osm_vendor_send
355 osm_vendor_send(IN osm_bind_handle_t h_bind,
356 IN osm_madw_t * const p_madw, IN boolean_t const resp_expected);
360 * [in] the bind handle obtained by calling osm_vendor_bind
363 * [in] pointer to the Mad Wrapper structure for the MAD to be sent.
366 * [in] boolean value declaring the mad as a request (expecting a response).
369 * IB_SUCCESS on succesful completion.
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
379 /****f* OpenSM Vendor API/osm_vendor_put
384 * Return a mad vendor wrapper to the mad pool. It also means that the
385 * mad buffer is returned to the transport.
390 osm_vendor_put(IN osm_bind_handle_t h_bind,
391 IN osm_vend_wrap_t * const p_vend_wrap);
395 * [in] the bind handle obtained by calling osm_vendor_bind
398 * [in] pointer to the mad vendor wrapper to put back into the pool.
408 /****i* OpenSM Vendor API/osm_vendor_local_lid_change
410 * osm_vendor_local_lid_change
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.
419 ib_api_status_t osm_vendor_local_lid_change(IN osm_bind_handle_t h_bind);
423 * [in] the bind handle obtained by calling osm_vendor_bind
432 /****f* OpenSM Vendor API/osm_vendor_set_sm
437 * Modifies the port info for the bound port to set the "IS_SM" bit
438 * according to the value given (TRUE or FALSE).
442 void osm_vendor_set_sm(IN osm_bind_handle_t h_bind, IN boolean_t is_sm_val);
446 * [in] bind handle for this port.
449 * [in] If TRUE - will set the is_sm to TRUE, if FALSE - will set the
450 * the is_sm to FALSE.
460 /****f* OpenSM Vendor API/osm_vendor_set_debug
462 * osm_vendor_set_debug
465 * Modifies the vendor specific debug level.
469 void osm_vendor_set_debug(IN osm_vendor_t * const p_vend, IN int32_t level);
473 * [in] vendor handle.
476 * [in] vendor specific debug level.
487 #endif /* _OSM_VENDOR_API_H_ */