contrib/ofed/management/opensm/include/opensm/osm_sm_mad_ctrl.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  *      Declaration of osm_sm_mad_ctrl_t.
  39  *      This object represents a controller that receives the IBA NodeInfo
  40  *      attribute from a node.
  41  *      This object is part of the OpenSM family of objects.
  42  */
  43
  44 #ifndef _OSM_SM_MAD_CTRL_H_
  45 #define _OSM_SM_MAD_CTRL_H_
  46
  47 #include <complib/cl_passivelock.h>
  48 #include <complib/cl_dispatcher.h>
  49 #include <opensm/osm_base.h>
  50 #include <opensm/osm_stats.h>
  51 #include <opensm/osm_madw.h>
  52 #include <opensm/osm_mad_pool.h>
  53 #include <opensm/osm_subnet.h>
  54 #include <opensm/osm_log.h>
  55 #include <opensm/osm_vl15intf.h>
  56
  57 #ifdef __cplusplus
  58 #  define BEGIN_C_DECLS extern "C" {
  59 #  define END_C_DECLS   }
  60 #else                           /* !__cplusplus */
  61 #  define BEGIN_C_DECLS
  62 #  define END_C_DECLS
  63 #endif                          /* __cplusplus */
  64
  65 BEGIN_C_DECLS
  66 /****h* OpenSM/SM MAD Controller
  67 * NAME
  68 *       SM MAD Controller
  69 *
  70 * DESCRIPTION
  71 *       The SM MAD Controller object encapsulates
  72 *       the information needed to receive MADs from the transport layer.
  73 *
  74 *       The SM MAD Controller object is thread safe.
  75 *
  76 *       This object should be treated as opaque and should be
  77 *       manipulated only through the provided functions.
  78 *
  79 * AUTHOR
  80 *       Steve King, Intel
  81 *
  82 *********/
  83 /****s* OpenSM: SM MAD Controller/osm_sm_mad_ctrl_t
  84 * NAME
  85 *       osm_sm_mad_ctrl_t
  86 *
  87 * DESCRIPTION
  88 *       SM MAD Controller structure.
  89 *
  90 *       This object should be treated as opaque and should
  91 *       be manipulated only through the provided functions.
  92 *
  93 * SYNOPSIS
  94 */
  95 typedef struct osm_sm_mad_ctrl {
  96         osm_log_t *p_log;
  97         osm_subn_t *p_subn;
  98         osm_mad_pool_t *p_mad_pool;
  99         osm_vl15_t *p_vl15;
 100         osm_vendor_t *p_vendor;
 101         osm_bind_handle_t h_bind;
 102         cl_plock_t *p_lock;
 103         cl_dispatcher_t *p_disp;
 104         cl_disp_reg_handle_t h_disp;
 105         osm_stats_t *p_stats;
 106 } osm_sm_mad_ctrl_t;
 107 /*
 108 * FIELDS
 109 *       p_log
 110 *               Pointer to the log object.
 111 *
 112 *       p_subn
 113 *               Pointer to the subnet object.
 114 *
 115 *       p_mad_pool
 116 *               Pointer to the MAD pool.
 117 *
 118 *       p_vendor
 119 *               Pointer to the vendor specific interfaces object.
 120 *
 121 *       h_bind
 122 *               Bind handle returned by the transport layer.
 123 *
 124 *       p_lock
 125 *               Pointer to the serializing lock.
 126 *
 127 *       p_disp
 128 *               Pointer to the Dispatcher.
 129 *
 130 *       h_disp
 131 *               Handle returned from dispatcher registration.
 132 *
 133 *       p_stats
 134 *               Pointer to the OpenSM statistics block.
 135 *
 136 * SEE ALSO
 137 *       SM MAD Controller object
 138 *       SM MADr object
 139 *********/
 140
 141 /****f* OpenSM: SM MAD Controller/osm_sm_mad_ctrl_construct
 142 * NAME
 143 *       osm_sm_mad_ctrl_construct
 144 *
 145 * DESCRIPTION
 146 *       This function constructs a SM MAD Controller object.
 147 *
 148 * SYNOPSIS
 149 */
 150 void osm_sm_mad_ctrl_construct(IN osm_sm_mad_ctrl_t * const p_ctrl);
 151 /*
 152 * PARAMETERS
 153 *       p_ctrl
 154 *               [in] Pointer to a SM MAD Controller
 155 *               object to construct.
 156 *
 157 * RETURN VALUE
 158 *       This function does not return a value.
 159 *
 160 * NOTES
 161 *       Allows calling osm_sm_mad_ctrl_init, and osm_sm_mad_ctrl_destroy.
 162 *
 163 *       Calling osm_sm_mad_ctrl_construct is a prerequisite to calling any other
 164 *       method except osm_sm_mad_ctrl_init.
 165 *
 166 * SEE ALSO
 167 *       SM MAD Controller object, osm_sm_mad_ctrl_init,
 168 *       osm_sm_mad_ctrl_destroy
 169 *********/
 170
 171 /****f* OpenSM: SM MAD Controller/osm_sm_mad_ctrl_destroy
 172 * NAME
 173 *       osm_sm_mad_ctrl_destroy
 174 *
 175 * DESCRIPTION
 176 *       The osm_sm_mad_ctrl_destroy function destroys the object, releasing
 177 *       all resources.
 178 *
 179 * SYNOPSIS
 180 */
 181 void osm_sm_mad_ctrl_destroy(IN osm_sm_mad_ctrl_t * const p_ctrl);
 182 /*
 183 * PARAMETERS
 184 *       p_ctrl
 185 *               [in] Pointer to the object to destroy.
 186 *
 187 * RETURN VALUE
 188 *       This function does not return a value.
 189 *
 190 * NOTES
 191 *       Performs any necessary cleanup of the specified
 192 *       SM MAD Controller object.
 193 *       Further operations should not be attempted on the destroyed object.
 194 *       This function should only be called after a call to
 195 *       osm_sm_mad_ctrl_construct or osm_sm_mad_ctrl_init.
 196 *
 197 * SEE ALSO
 198 *       SM MAD Controller object, osm_sm_mad_ctrl_construct,
 199 *       osm_sm_mad_ctrl_init
 200 *********/
 201
 202 /****f* OpenSM: SM MAD Controller/osm_sm_mad_ctrl_init
 203 * NAME
 204 *       osm_sm_mad_ctrl_init
 205 *
 206 * DESCRIPTION
 207 *       The osm_sm_mad_ctrl_init function initializes a
 208 *       SM MAD Controller object for use.
 209 *
 210 * SYNOPSIS
 211 */
 212 ib_api_status_t
 213 osm_sm_mad_ctrl_init(IN osm_sm_mad_ctrl_t * const p_ctrl,
 214                      IN osm_subn_t * const p_subn,
 215                      IN osm_mad_pool_t * const p_mad_pool,
 216                      IN osm_vl15_t * const p_vl15,
 217                      IN osm_vendor_t * const p_vendor,
 218                      IN osm_log_t * const p_log,
 219                      IN osm_stats_t * const p_stats,
 220                      IN cl_plock_t * const p_lock,
 221                      IN cl_dispatcher_t * const p_disp);
 222 /*
 223 * PARAMETERS
 224 *       p_ctrl
 225 *               [in] Pointer to an osm_sm_mad_ctrl_t object to initialize.
 226 *
 227 *       p_mad_pool
 228 *               [in] Pointer to the MAD pool.
 229 *
 230 *       p_vl15
 231 *               [in] Pointer to the VL15 interface object.
 232 *
 233 *       p_vendor
 234 *               [in] Pointer to the vendor specific interfaces object.
 235 *
 236 *       p_log
 237 *               [in] Pointer to the log object.
 238 *
 239 *       p_stats
 240 *               [in] Pointer to the OpenSM stastics block.
 241 *
 242 *       p_lock
 243 *               [in] Pointer to the OpenSM serializing lock.
 244 *
 245 *       p_disp
 246 *               [in] Pointer to the OpenSM central Dispatcher.
 247 *
 248 * RETURN VALUES
 249 *       IB_SUCCESS if the SM MAD Controller object was initialized
 250 *       successfully.
 251 *
 252 * NOTES
 253 *       Allows calling other SM MAD Controller methods.
 254 *
 255 * SEE ALSO
 256 *       SM MAD Controller object, osm_sm_mad_ctrl_construct,
 257 *       osm_sm_mad_ctrl_destroy
 258 *********/
 259
 260 /****f* OpenSM: SM/osm_sm_mad_ctrl_bind
 261 * NAME
 262 *       osm_sm_mad_ctrl_bind
 263 *
 264 * DESCRIPTION
 265 *       Binds the SM MAD Controller object to a port guid.
 266 *
 267 * SYNOPSIS
 268 */
 269 ib_api_status_t
 270 osm_sm_mad_ctrl_bind(IN osm_sm_mad_ctrl_t * const p_ctrl,
 271                      IN const ib_net64_t port_guid);
 272 /*
 273 * PARAMETERS
 274 *       p_ctrl
 275 *               [in] Pointer to an osm_sm_mad_ctrl_t object to initialize.
 276 *
 277 *       port_guid
 278 *               [in] Local port GUID with which to bind.
 279 *
 280 *
 281 * RETURN VALUES
 282 *       None
 283 *
 284 * NOTES
 285 *       A given SM MAD Controller object can only be bound to one
 286 *       port at a time.
 287 *
 288 * SEE ALSO
 289 *********/
 290
 291 /****f* OpenSM: SM/osm_sm_mad_ctrl_get_bind_handle
 292 * NAME
 293 *       osm_sm_mad_ctrl_get_bind_handle
 294 *
 295 * DESCRIPTION
 296 *       Returns the bind handle.
 297 *
 298 * SYNOPSIS
 299 */
 300 static inline osm_bind_handle_t
 301 osm_sm_mad_ctrl_get_bind_handle(IN const osm_sm_mad_ctrl_t * const p_ctrl)
 302 {
 303         return (p_ctrl->h_bind);
 304 }
 305
 306 /*
 307 * PARAMETERS
 308 *       p_ctrl
 309 *               [in] Pointer to an osm_sm_mad_ctrl_t object.
 310 *
 311 * RETURN VALUES
 312 *       Returns the bind handle, which may be OSM_BIND_INVALID_HANDLE
 313 *       if no port has been bound.
 314 *
 315 * NOTES
 316 *       A given SM MAD Controller object can only be bound to one
 317 *       port at a time.
 318 *
 319 * SEE ALSO
 320 *********/
 321
 322 END_C_DECLS
 323 #endif                          /* _OSM_SM_MAD_CTRL_H_ */