contrib/ofed/management/opensm/include/opensm/osm_sa_mad_ctrl.h

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