contrib/ofed/management/opensm/include/vendor/osm_vendor_mtl_transaction_mgr.h

   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  *      Definition of interface for the MTL Vendor
  39  *         This object is part of the OpenSM family of objects.
  40  */
  41
  42 #ifndef _OSM_TRANSACTION_MGR_H_
  43 #define _OSM_TRANSACTION_MGR_H_
  44
  45   /*
  46      #include <vapi_types.h>
  47      #include <evapi.h>
  48    */
  49
  50 #include <iba/ib_types.h>
  51 #include <iba/ib_al.h>
  52 #include <complib/cl_qlist.h>
  53 #include <complib/cl_qmap.h>
  54 #include <complib/cl_timer.h>
  55 #include <complib/cl_thread.h>
  56 #include <complib/cl_types_osd.h>
  57 #include <complib/cl_spinlock.h>
  58 #include <opensm/osm_base.h>
  59 #include <opensm/osm_log.h>
  60 #include <opensm/osm_madw.h>
  61 #ifdef OSM_VENDOR_INTF_MTL
  62 #include <ib_mgt.h>
  63 #include <opensm/osm_mtl_bind.h>
  64 #endif
  65
  66 #ifdef __cplusplus
  67 #  define BEGIN_C_DECLS extern "C" {
  68 #  define END_C_DECLS   }
  69 #else                           /* !__cplusplus */
  70 #  define BEGIN_C_DECLS
  71 #  define END_C_DECLS
  72 #endif                          /* __cplusplus */
  73
  74 BEGIN_C_DECLS
  75 /****s* OpenSM: Transaction Manager/osm_madw_req_t
  76 * NAME
  77 *  osm_madw_req_t
  78 *
  79 * DESCRIPTION
  80 *  The structure defining each object in the transaction_mgr.
  81 *  For every request mad sent, we will save such an object for it.
  82 *
  83 * SYNOPSIS
  84 */
  85 typedef struct _osm_madw_req {
  86         cl_list_item_t list_item;
  87         cl_map_item_t map_item;
  88         osm_madw_t *p_madw;
  89         uint64_t waking_time;
  90         uint8_t retry_cnt;
  91         osm_bind_handle_t *p_bind;
  92 } osm_madw_req_t;
  93
  94 /*
  95 * FIELDS
  96 *  list_item
  97 *     List item for qlist linkage. Must be first element!!
  98 *
  99 *  map_item
 100 *     Map item for qmap linkage.
 101 *
 102 *  p_madw
 103 *     pointer to mad wrapper that is expecting to get a response.
 104 *
 105 *  waking_time
 106 *     Time stamp (in microseconds) when the p_madw needs to wake up.
 107 *     This value is
 108 *      cl_get_time_stamp() + timeout  during the sending of the mad.
 109 *      where timeout should be given in microseconds.
 110 *
 111 *  retry_cnt
 112 *     The number of outstanding retries to be called.
 113 *********/
 114
 115 /****s* OpenSM: Transaction Manager/osm_transaction_mgr_t
 116 * NAME
 117 *  osm_transaction_mgr_t
 118 *
 119 * DESCRIPTION
 120 *  This structure defines the transaction manager.
 121 *  It holds a qlist and a qmap, a lock on the transaction manager, and
 122 *  a timer used for the list.
 123 *  The manager is responsible for keeping track of every request mad that was
 124 *  sent. It is used for finding mads according to their transaction id, and for
 125 *  acting as an event wheel - reporting as error each packet was supposed to get
 126 *  a response and didn't get one by the timeout time expected.
 127 *
 128 *  Both the list and the map hold the osm_madw_req_t objects - one for every madw.
 129 *
 130 *  Managing of the list:
 131 *  The timer wakes on the timeout of the first madw. If the waking_time is greater than
 132 *  the current time - then the mad received a response. If not - the mad didn't get
 133 *  its response.
 134 *
 135 * SYNOPSIS
 136 */
 137 typedef struct _osm_transaction_mgr {
 138         cl_qmap_t *madw_by_tid_map_p;
 139         cl_qlist_t *madw_reqs_list_p;
 140         cl_spinlock_t transaction_mgr_lock;
 141         cl_timer_t madw_list_timer;
 142 } osm_transaction_mgr_t;
 143
 144 /*
 145 * FIELDS
 146 *  madw_by_tid_map_p
 147 *     A qmap with key = transaction id. and value of osm_madw_req_t.
 148 *
 149 *  madw_reqs_list_p
 150 *     A qlist of all the madw with their waking time.
 151 *
 152 *  transaction_mgr_lock
 153 *     Lock used on the transaction manager - make sure changes on it are serial.
 154 *
 155 *  madw_list_timer
 156 *     Timer on the list.
 157 *********/
 158
 159 /****f* OpenSM: Transaction Manager/osm_transaction_mgr_init
 160 * NAME
 161 *       osm_transaction_mgr_init
 162 *
 163 * DESCRIPTION
 164 *       Initialize the transaction manager.
 165 *  Will update the p_transaction_mgr in the vendor object with
 166 *  the new Transaction Manager created.*
 167 *
 168 * SYNOPSIS
 169 */
 170 void osm_transaction_mgr_init(IN osm_vendor_t * const p_vend);
 171
 172 /*
 173 * PARAMETERS
 174 *       p_vend
 175 *               [in] Pointer to a Osm Vendor object.
 176 *
 177 *********/
 178
 179 /****f* OpenSM: Transaction Manager/osm_transaction_mgr_destroy
 180 * NAME
 181 *       osm_transaction_mgr_destroy
 182 *
 183 * DESCRIPTION
 184 *       Destroy the transaction manager.
 185 *  Will de-allocate all memory allocated by the Transaction
 186 *  Manager up to now.
 187 *
 188 * SYNOPSIS
 189 */
 190 void osm_transaction_mgr_destroy(IN osm_vendor_t * const p_vend);
 191
 192 /*
 193 * PARAMETERS
 194 *       p_vend
 195 *               [in] Pointer to a Osm Vendor object.
 196 *
 197 *********/
 198
 199 /****f* OpenSM: Transaction Manager/osm_transaction_mgr_insert_madw
 200 * NAME
 201 *       osm_transaction_mgr_insert_madw
 202 *
 203 * DESCRIPTION
 204 *       Insert a new madw to the manager. The madw is added with a waking_time,
 205 *  Which is equal to the current_time + timeout. This is the maximum time
 206 *  that the madw can leave without being handled (e.g - get a response).
 207 *  If there are no madw saved in the manager - start the timer for vendor
 208 *  timeout period.
 209 *
 210 * SYNOPSIS
 211 */
 212 ib_api_status_t
 213 osm_transaction_mgr_insert_madw(IN osm_bind_handle_t * p_bind,
 214                                 IN osm_madw_t * p_madw);
 215 /*
 216 * PARAMETERS
 217 *       p_vend
 218 *               [in] Pointer to a mtl bind object.
 219 *
 220 *  p_madw
 221 *     [in] Pointer to the Mad Wrapper to be added.
 222 *
 223 *********/
 224
 225 /****f* OpenSM: Transaction Manager/osm_transaction_mgr_erase_madw
 226 * NAME
 227 *       osm_transaction_mgr_erase_madw
 228 *
 229 * DESCRIPTION
 230 *       Erase a madw object from the manager.
 231 *  The removal is done using the transaction id of the mad - using
 232 *  it the madw_p is allocated (in the qmap) and removed from the
 233 *  qmap and qlist.
 234 *
 235 * SYNOPSIS
 236 */
 237 ib_api_status_t
 238 osm_transaction_mgr_erase_madw(IN osm_vendor_t * const p_vend,
 239                                IN ib_mad_t * p_mad);
 240 /*
 241 * PARAMETERS
 242 *       p_vend
 243 *               [in] Pointer to a Osm Vendor object.
 244 *
 245 *  p_mad
 246 *      [in] Pointer to the Mad to be removed.
 247 *
 248 *********/
 249
 250 /****f* OpenSM: Transaction Manager/osm_transaction_mgr_get_madw_for_tid
 251 * NAME
 252 *       osm_transaction_mgr_get_madw_for_tid
 253 *
 254 * DESCRIPTION
 255 *       Return the mad wrapper, given the p_mad (and in it the transaction id)
 256 *
 257 * SYNOPSIS
 258 */
 259 ib_api_status_t
 260 osm_transaction_mgr_get_madw_for_tid(IN osm_vendor_t * const p_vend,
 261                                      IN ib_mad_t * const p_mad,
 262                                      OUT osm_madw_t ** req_madw_p);
 263 /*
 264 * PARAMETERS
 265 *       p_vend
 266 *               [in] Pointer to a Osm Vendor object.
 267 *
 268 *  p_mad
 269 *      [in] Pointer to the Mad to be located.
 270 *
 271 * req_madw_p
 272 *      [out] Pointer to the mad Wrapper to be found.
 273 *
 274 *********/
 275
 276 /****f* OpenSM: Transaction Manager/osm_transaction_mgr_callback
 277 * NAME
 278 *       osm_transaction_mgr_callback
 279 *
 280 * DESCRIPTION
 281 *       This callback is called on timeout of the timer.
 282 *  It checks the time of the head madw in the qlist, and compares it to
 283 *  the current time.
 284 *  Will send an error callback if the time of the madw is less than the
 285 *  current time - this means that the madw wasn't removed in the timeout
 286 *  it was supposed to be handled.
 287 *
 288 * SYNOPSIS
 289 */
 290 void osm_transaction_mgr_callback(IN void *context);
 291 /*
 292 * PARAMETERS
 293 *       context
 294 *               [in] void* context
 295 *
 296 *********/
 297
 298 END_C_DECLS
 299 #endif                          /* _OSM_TRANSACTION_MGR_H_ */