contrib/ofed/management/opensm/include/opensm/osm_sa.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_t.
  39  *      This object represents an IBA subnet.
  40  *      This object is part of the OpenSM family of objects.
  41  */
  42
  43 #ifndef _OSM_SA_H_
  44 #define _OSM_SA_H_
  45
  46 #include <iba/ib_types.h>
  47 #include <complib/cl_passivelock.h>
  48 #include <complib/cl_event.h>
  49 #include <complib/cl_thread.h>
  50 #include <complib/cl_timer.h>
  51 #include <complib/cl_dispatcher.h>
  52 #include <opensm/osm_stats.h>
  53 #include <opensm/osm_subnet.h>
  54 #include <vendor/osm_vendor_api.h>
  55 #include <opensm/osm_mad_pool.h>
  56 #include <opensm/osm_log.h>
  57 #include <opensm/osm_sa_mad_ctrl.h>
  58 #include <opensm/osm_sm.h>
  59 #include <opensm/osm_multicast.h>
  60
  61 #ifdef __cplusplus
  62 #  define BEGIN_C_DECLS extern "C" {
  63 #  define END_C_DECLS   }
  64 #else                           /* !__cplusplus */
  65 #  define BEGIN_C_DECLS
  66 #  define END_C_DECLS
  67 #endif                          /* __cplusplus */
  68
  69 BEGIN_C_DECLS
  70 /****h* OpenSM/SA
  71 * NAME
  72 *       SA
  73 *
  74 * DESCRIPTION
  75 *       The SA object encapsulates the information needed by the
  76 *       OpenSM to instantiate a subnet administrator.  The OpenSM allocates
  77 *       one SA object per subnet manager.
  78 *
  79 *       The SA object is thread safe.
  80 *
  81 *       This object should be treated as opaque and should
  82 *       be manipulated only through the provided functions.
  83 *
  84 * AUTHOR
  85 *       Ranjit Pandit, Intel
  86 *       Anil Keshavamurthy, Intel
  87 *
  88 *********/
  89 /****d* OpenSM: SA/osm_sa_state_t
  90 * NAME
  91 *       osm_sa_state_t
  92 *
  93 * DESCRIPTION
  94 *       Enumerates the possible states of SA object.
  95 *
  96 * SYNOPSIS
  97 */
  98 typedef enum _osm_sa_state {
  99         OSM_SA_STATE_INIT = 0,
 100         OSM_SA_STATE_READY
 101 } osm_sa_state_t;
 102 /***********/
 103
 104 /****s* OpenSM: SM/osm_sa_t
 105 * NAME
 106 *       osm_sa_t
 107 *
 108 * DESCRIPTION
 109 *       Subnet Administration structure.
 110 *
 111 *       This object should be treated as opaque and should
 112 *       be manipulated only through the provided functions.
 113 *
 114 * SYNOPSIS
 115 */
 116 typedef struct osm_sa {
 117         osm_sa_state_t state;
 118         osm_sm_t *sm;
 119         osm_subn_t *p_subn;
 120         osm_vendor_t *p_vendor;
 121         osm_log_t *p_log;
 122         osm_mad_pool_t *p_mad_pool;
 123         cl_dispatcher_t *p_disp;
 124         cl_plock_t *p_lock;
 125         atomic32_t sa_trans_id;
 126         osm_sa_mad_ctrl_t mad_ctrl;
 127         cl_timer_t sr_timer;
 128         cl_disp_reg_handle_t cpi_disp_h;
 129         cl_disp_reg_handle_t nr_disp_h;
 130         cl_disp_reg_handle_t pir_disp_h;
 131         cl_disp_reg_handle_t gir_disp_h;
 132         cl_disp_reg_handle_t lr_disp_h;
 133         cl_disp_reg_handle_t pr_disp_h;
 134         cl_disp_reg_handle_t smir_disp_h;
 135         cl_disp_reg_handle_t mcmr_disp_h;
 136         cl_disp_reg_handle_t sr_disp_h;
 137 #if defined (VENDOR_RMPP_SUPPORT) && defined (DUAL_SIDED_RMPP)
 138         cl_disp_reg_handle_t mpr_disp_h;
 139 #endif
 140         cl_disp_reg_handle_t infr_disp_h;
 141         cl_disp_reg_handle_t infir_disp_h;
 142         cl_disp_reg_handle_t vlarb_disp_h;
 143         cl_disp_reg_handle_t slvl_disp_h;
 144         cl_disp_reg_handle_t pkey_disp_h;
 145         cl_disp_reg_handle_t lft_disp_h;
 146         cl_disp_reg_handle_t sir_disp_h;
 147         cl_disp_reg_handle_t mft_disp_h;
 148 } osm_sa_t;
 149 /*
 150 * FIELDS
 151 *       state
 152 *               State of this SA object
 153 *
 154 *       sm
 155 *               Pointer to the Subnet Manager object.
 156 *
 157 *       p_subn
 158 *               Pointer to the Subnet object for this subnet.
 159 *
 160 *       p_vendor
 161 *               Pointer to the vendor specific interfaces object.
 162 *
 163 *       p_log
 164 *               Pointer to the log object.
 165 *
 166 *       p_mad_pool
 167 *               Pointer to the MAD pool.
 168 *
 169 *       p_disp
 170 *               Pointer to dispatcher
 171 *
 172 *       p_lock
 173 *               Pointer to Lock for serialization
 174 *
 175 *       sa_trans_id
 176 *               Transaction ID
 177 *
 178 *       mad_ctrl
 179 *               Mad Controller
 180 *
 181 * SEE ALSO
 182 *       SM object
 183 *********/
 184
 185 /****f* OpenSM: SA/osm_sa_construct
 186 * NAME
 187 *       osm_sa_construct
 188 *
 189 * DESCRIPTION
 190 *       This function constructs an SA object.
 191 *
 192 * SYNOPSIS
 193 */
 194 void osm_sa_construct(IN osm_sa_t * const p_sa);
 195 /*
 196 * PARAMETERS
 197 *       p_sa
 198 *               [in] Pointer to a SA object to construct.
 199 *
 200 * RETURN VALUE
 201 *       This function does not return a value.
 202 *
 203 * NOTES
 204 *       Allows calling osm_sa_destroy.
 205 *
 206 *       Calling osm_sa_construct is a prerequisite to calling any other
 207 *       method except osm_sa_init.
 208 *
 209 * SEE ALSO
 210 *       SA object, osm_sa_init, osm_sa_destroy
 211 *********/
 212
 213 /****f* OpenSM: SA/osm_sa_shutdown
 214 * NAME
 215 *       osm_sa_shutdown
 216 *
 217 * DESCRIPTION
 218 *       The osm_sa_shutdown function shutdowns an SA, unregistering from all
 219 *  dispatcher messages and unbinding the QP1 mad service
 220 *
 221 * SYNOPSIS
 222 */
 223 void osm_sa_shutdown(IN osm_sa_t * const p_sa);
 224 /*
 225 * PARAMETERS
 226 *       p_sa
 227 *               [in] Pointer to a SA object to shutdown.
 228 *
 229 * RETURN VALUE
 230 *       This function does not return a value.
 231 *
 232 * SEE ALSO
 233 *       SA object, osm_sa_construct, osm_sa_init
 234 *********/
 235
 236 /****f* OpenSM: SA/osm_sa_destroy
 237 * NAME
 238 *       osm_sa_destroy
 239 *
 240 * DESCRIPTION
 241 *       The osm_sa_destroy function destroys an SA, releasing
 242 *       all resources.
 243 *
 244 * SYNOPSIS
 245 */
 246 void osm_sa_destroy(IN osm_sa_t * const p_sa);
 247 /*
 248 * PARAMETERS
 249 *       p_sa
 250 *               [in] Pointer to a SA object to destroy.
 251 *
 252 * RETURN VALUE
 253 *       This function does not return a value.
 254 *
 255 * NOTES
 256 *       Performs any necessary cleanup of the specified SA object.
 257 *       Further operations should not be attempted on the destroyed object.
 258 *       This function should only be called after a call to osm_sa_construct or
 259 *       osm_sa_init.
 260 *
 261 * SEE ALSO
 262 *       SA object, osm_sa_construct, osm_sa_init
 263 *********/
 264
 265 /****f* OpenSM: SA/osm_sa_init
 266 * NAME
 267 *       osm_sa_init
 268 *
 269 * DESCRIPTION
 270 *       The osm_sa_init function initializes a SA object for use.
 271 *
 272 * SYNOPSIS
 273 */
 274 ib_api_status_t osm_sa_init(IN osm_sm_t * const p_sm,
 275                             IN osm_sa_t * const p_sa,
 276                             IN osm_subn_t * const p_subn,
 277                             IN osm_vendor_t * const p_vendor,
 278                             IN osm_mad_pool_t * const p_mad_pool,
 279                             IN osm_log_t * const p_log,
 280                             IN osm_stats_t * const p_stats,
 281                             IN cl_dispatcher_t * const p_disp,
 282                             IN cl_plock_t * const p_lock);
 283 /*
 284 * PARAMETERS
 285 *       p_sa
 286 *               [in] Pointer to an osm_sa_t object to initialize.
 287 *
 288 *       p_subn
 289 *               [in] Pointer to the Subnet object for this subnet.
 290 *
 291 *       p_vendor
 292 *               [in] Pointer to the vendor specific interfaces object.
 293 *
 294 *       p_mad_pool
 295 *               [in] Pointer to the MAD pool.
 296 *
 297 *       p_log
 298 *               [in] Pointer to the log object.
 299 *
 300 *       p_stats
 301 *               [in] Pointer to the statistics object.
 302 *
 303 *       p_disp
 304 *               [in] Pointer to the OpenSM central Dispatcher.
 305 *
 306 *       p_lock
 307 *               [in] Pointer to the OpenSM serializing lock.
 308 *
 309 * RETURN VALUES
 310 *       CL_SUCCESS if the SA object was initialized successfully.
 311 *
 312 * NOTES
 313 *       Allows calling other SA methods.
 314 *
 315 * SEE ALSO
 316 *       SA object, osm_sa_construct, osm_sa_destroy
 317 *********/
 318
 319 /****f* OpenSM: SA/osm_sa_bind
 320 * NAME
 321 *       osm_sa_bind
 322 *
 323 * DESCRIPTION
 324 *       Binds the SA object to a port guid.
 325 *
 326 * SYNOPSIS
 327 */
 328 ib_api_status_t
 329 osm_sa_bind(IN osm_sa_t * const p_sa, IN const ib_net64_t port_guid);
 330 /*
 331 * PARAMETERS
 332 *       p_sa
 333 *               [in] Pointer to an osm_sa_t object to bind.
 334 *
 335 *       port_guid
 336 *               [in] Local port GUID with which to bind.
 337 *
 338 *
 339 * RETURN VALUES
 340 *       None
 341 *
 342 * NOTES
 343 *       A given SA object can only be bound to one port at a time.
 344 *
 345 * SEE ALSO
 346 *********/
 347
 348 /****f* OpenSM: SA/osm_sa_send
 349 * NAME
 350 *       osm_sa_send
 351 *
 352 * DESCRIPTION
 353 *       Sends SA MAD via osm_vendor_send and maintains the QP1 sent statistic
 354 *
 355 * SYNOPSIS
 356 */
 357 ib_api_status_t osm_sa_send(osm_sa_t *sa, IN osm_madw_t * const p_madw,
 358                             IN boolean_t const resp_expected);
 359
 360 /****f* IBA Base: Types/osm_sa_send_error
 361 * NAME
 362 *       osm_sa_send_error
 363 *
 364 * DESCRIPTION
 365 *       Sends a generic SA response with the specified error status.
 366 *       The payload is simply replicated from the request MAD.
 367 *
 368 * SYNOPSIS
 369 */
 370 void osm_sa_send_error(IN osm_sa_t * sa, IN const osm_madw_t * const p_madw,
 371                        IN const ib_net16_t sa_status);
 372 /*
 373 * PARAMETERS
 374 *       sa
 375 *               [in] Pointer to an osm_sa_t object.
 376 *
 377 *       p_madw
 378 *               [in] Original MAD to which the response must be sent.
 379 *
 380 *       sa_status
 381 *               [in] Status to send in the response.
 382 *
 383 * RETURN VALUES
 384 *       None.
 385 *
 386 * SEE ALSO
 387 *       SA object
 388 *********/
 389
 390 /****f* OpenSM: SA/osm_sa_respond
 391 * NAME
 392 *       osm_sa_respond
 393 *
 394 * DESCRIPTION
 395 *       Sends SA MAD response
 396 */
 397 void osm_sa_respond(osm_sa_t *sa, osm_madw_t *madw, size_t attr_size,
 398                     cl_qlist_t *list);
 399 /*
 400 * PARAMETERS
 401 *       sa
 402 *               [in] Pointer to an osm_sa_t object.
 403 *
 404 *       p_madw
 405 *               [in] Original MAD to which the response must be sent.
 406 *
 407 *       attr_size
 408 *               [in] Size of this SA attribute.
 409 *
 410 *       list
 411 *               [in] List of attribute to respond - it will be freed after
 412 *               sending.
 413 *
 414 * RETURN VALUES
 415 *       None.
 416 *
 417 * SEE ALSO
 418 *       SA object
 419 *********/
 420
 421 struct osm_opensm;
 422 /****f* OpenSM: SA/osm_sa_db_file_dump
 423 * NAME
 424 *       osm_sa_db_file_dump
 425 *
 426 * DESCRIPTION
 427 *       Dumps the SA DB to the dump file.
 428 *
 429 * SYNOPSIS
 430 */
 431 int osm_sa_db_file_dump(struct osm_opensm *p_osm);
 432 /*
 433 * PARAMETERS
 434 *       p_osm
 435 *               [in] Pointer to an osm_opensm_t object.
 436 *
 437 * RETURN VALUES
 438 *       None
 439 *
 440 *********/
 441
 442 /****f* OpenSM: SA/osm_sa_db_file_load
 443 * NAME
 444 *       osm_sa_db_file_load
 445 *
 446 * DESCRIPTION
 447 *       Loads SA DB from the file.
 448 *
 449 * SYNOPSIS
 450 */
 451 int osm_sa_db_file_load(struct osm_opensm *p_osm);
 452 /*
 453 * PARAMETERS
 454 *       p_osm
 455 *               [in] Pointer to an osm_opensm_t object.
 456 *
 457 * RETURN VALUES
 458 *       0 on success, other value on failure.
 459 *
 460 *********/
 461
 462 /****f* OpenSM: MC Member Record Receiver/osm_mcmr_rcv_find_or_create_new_mgrp
 463 * NAME
 464 *       osm_mcmr_rcv_find_or_create_new_mgrp
 465 *
 466 * DESCRIPTION
 467 *       Create new Multicast group
 468 *
 469 * SYNOPSIS
 470 */
 471
 472 ib_api_status_t
 473 osm_mcmr_rcv_find_or_create_new_mgrp(IN osm_sa_t * sa,
 474                                      IN uint64_t comp_mask,
 475                                      IN ib_member_rec_t *
 476                                      const p_recvd_mcmember_rec,
 477                                      OUT osm_mgrp_t ** pp_mgrp);
 478 /*
 479 * PARAMETERS
 480 *       p_sa
 481 *               [in] Pointer to an osm_sa_t object.
 482 *       p_recvd_mcmember_rec
 483 *               [in] Received Multicast member record
 484 *
 485 *       pp_mgrp
 486 *               [out] pointer the osm_mgrp_t object
 487 *
 488 * RETURN VALUES
 489 *       IB_SUCCESS, IB_ERROR
 490 *
 491 *********/
 492
 493 osm_mgrp_t *osm_get_mgrp_by_mgid(IN osm_sa_t * sa, IN ib_gid_t * p_mgid);
 494
 495 END_C_DECLS
 496 #endif                          /* _OSM_SA_H_ */