contrib/ofed/management/opensm/include/opensm/osm_inform.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_inform_rec_t.
  39  *      This object represents an IBA Inform Record.
  40  *      This object is part of the OpenSM family of objects.
  41  *
  42  * Author:
  43  *    Eitan Zahavi, Mellanox
  44  */
  45
  46 #ifndef _OSM_INFR_H_
  47 #define _OSM_INFR_H_
  48
  49 #include <iba/ib_types.h>
  50 #include <complib/cl_qmap.h>
  51 #include <complib/cl_spinlock.h>
  52 #include <opensm/osm_subnet.h>
  53 #include <opensm/osm_madw.h>
  54 #include <opensm/osm_log.h>
  55 #include <opensm/osm_sa.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/Inform Record
  67 * NAME
  68 *       Inform Record
  69 *
  70 * DESCRIPTION
  71 *       The Inform record encapsulates the information needed by the
  72 *       SA to manage InformInfo registrations and sending Reports(Notice)
  73 *       when SM receives Traps for registered LIDs.
  74 *
  75 *       The inform records is not thread safe, thus callers must provide
  76 *       serialization.
  77 *
  78 *       This object should be treated as opaque and should be
  79 *       manipulated only through the provided functions.
  80 *
  81 * AUTHOR
  82 *    Eitan Zahavi, Mellanox
  83 *
  84 *********/
  85 /****s* OpenSM: Inform Record/osm_infr_t
  86 * NAME
  87 *       osm_infr_t
  88 *
  89 * DESCRIPTION
  90 *       Inform Record structure.
  91 *
  92 *       The osm_infr_t object should be treated as opaque and should
  93 *       be manipulated only through the provided functions.
  94 *
  95 * SYNOPSIS
  96 */
  97 typedef struct osm_infr {
  98         cl_list_item_t list_item;
  99         osm_bind_handle_t h_bind;
 100         osm_sa_t *sa;
 101         osm_mad_addr_t report_addr;
 102         ib_inform_info_record_t inform_record;
 103 } osm_infr_t;
 104 /*
 105 * FIELDS
 106 *       list_item
 107 *               List Item for qlist linkage.  Must be first element!!
 108 *
 109 *       h_bind
 110 *               A handle of lower level mad srvc
 111 *
 112 *       sa
 113 *               A pointer to osm_sa object
 114 *
 115 *       report_addr
 116 *               Report address
 117 *
 118 *       inform_record
 119 *               The Inform Info Record
 120 *
 121 * SEE ALSO
 122 *********/
 123
 124 /****f* OpenSM: Inform Record/osm_infr_new
 125 * NAME
 126 *       osm_infr_new
 127 *
 128 * DESCRIPTION
 129 *       Allocates and initializes a Inform Record for use.
 130 *
 131 * SYNOPSIS
 132 */
 133 osm_infr_t *osm_infr_new(IN const osm_infr_t * p_infr_rec);
 134 /*
 135 * PARAMETERS
 136 *       p_inf_rec
 137 *               [in] Pointer to IB Inform Record
 138 *
 139 * RETURN VALUES
 140 *       pointer to osm_infr_t structure.
 141 *
 142 * NOTES
 143 *       Allows calling other inform record methods.
 144 *
 145 * SEE ALSO
 146 *       Inform Record, osm_infr_delete
 147 *********/
 148
 149 /****f* OpenSM: Inform Record/osm_infr_delete
 150 * NAME
 151 *       osm_infr_delete
 152 *
 153 * DESCRIPTION
 154 *       Destroys and deallocates the osm_infr_t structure.
 155 *
 156 * SYNOPSIS
 157 */
 158 void osm_infr_delete(IN osm_infr_t * const p_infr);
 159 /*
 160 * PARAMETERS
 161 *       p_infr
 162 *               [in] Pointer to osm_infr_t structure
 163 *
 164 * SEE ALSO
 165 *       Inform Record, osm_infr_new
 166 *********/
 167
 168 /****f* OpenSM: Inform Record/osm_infr_get_by_rec
 169 * NAME
 170 *       osm_infr_get_by_rec
 171 *
 172 * DESCRIPTION
 173 *       Find a matching osm_infr_t in the subnet DB by inform_info_record
 174 *
 175 * SYNOPSIS
 176 */
 177 osm_infr_t *osm_infr_get_by_rec(IN osm_subn_t const *p_subn,
 178                                 IN osm_log_t * p_log,
 179                                 IN osm_infr_t * const p_infr_rec);
 180 /*
 181 * PARAMETERS
 182 *       p_subn
 183 *               [in] Pointer to the subnet object
 184 *
 185 *       p_log
 186 *               [in] Pointer to the log object
 187 *
 188 *       p_inf_rec
 189 *               [in] Pointer to an inform_info record
 190 *
 191 * RETURN
 192 *       The matching osm_infr_t
 193 * SEE ALSO
 194 *       Inform Record, osm_infr_new, osm_infr_delete
 195 *********/
 196
 197 void
 198 osm_infr_insert_to_db(IN osm_subn_t * p_subn,
 199                       IN osm_log_t * p_log, IN osm_infr_t * p_infr);
 200
 201 void
 202 osm_infr_remove_from_db(IN osm_subn_t * p_subn,
 203                         IN osm_log_t * p_log, IN osm_infr_t * p_infr);
 204
 205 /****f* OpenSM: Inform Record/osm_report_notice
 206 * NAME
 207 *       osm_report_notice
 208 *
 209 * DESCRIPTION
 210 * Once a Trap was received by the osm_trap_rcv, or a Trap sourced in
 211 * the SM was sent (Traps 64-67) this routine is called with a copy of
 212 * the notice data.
 213 * Given a notice attribute - compare and see if it matches the InformInfo
 214 * Element and if it does - call the Report(Notice) for the
 215 * target QP registered by the address stored in the InformInfo element
 216 *
 217 * SYNOPSIS
 218 */
 219 ib_api_status_t
 220 osm_report_notice(IN osm_log_t * const p_log,
 221                   IN osm_subn_t * p_subn, IN ib_mad_notice_attr_t * p_ntc);
 222 /*
 223 * PARAMETERS
 224 *       p_rcv
 225 *               [in] Pointer to the trap receiver
 226 *
 227 *       p_ntc
 228 *               [in] Pointer to a copy of the incoming trap notice attribute.
 229 *
 230 * RETURN
 231 *       IB_SUCCESS on good completion
 232 *
 233 * SEE ALSO
 234 *       Inform Record, osm_trap_rcv
 235 *********/
 236
 237 END_C_DECLS
 238 #endif                          /* _OSM_INFR_H_ */