contrib/ofed/management/opensm/include/vendor/osm_pkt_randomizer.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_subn_t.
  39  *      This object represents an IBA subnet.
  40  *      This object is part of the OpenSM family of objects.
  41  */
  42
  43 #ifndef _OSM_PKT_RANDOMIZER_H_
  44 #define _OSM_PKT_RANDOMIZER_H_
  45
  46 #include <iba/ib_types.h>
  47 #include <complib/cl_qmap.h>
  48 #include <complib/cl_map.h>
  49 #include <complib/cl_ptr_vector.h>
  50 #include <complib/cl_list.h>
  51 #include <opensm/osm_log.h>
  52 #include <opensm/osm_path.h>
  53 #include <opensm/osm_madw.h>
  54
  55 #ifdef __cplusplus
  56 #  define BEGIN_C_DECLS extern "C" {
  57 #  define END_C_DECLS   }
  58 #else                           /* !__cplusplus */
  59 #  define BEGIN_C_DECLS
  60 #  define END_C_DECLS
  61 #endif                          /* __cplusplus */
  62
  63 BEGIN_C_DECLS
  64 /****h* OpenSM/Packet Randomizer
  65 * NAME
  66 *       Packet Randomizer
  67 *
  68 * DESCRIPTION
  69 *       The Packet Randomizer object encapsulates the information needed for
  70 *       randomly dropping packets for debug.
  71 *
  72 *       The Packet Randomizer object is not thread safe, thus callers must
  73 *       provide serialization.
  74 *
  75 * AUTHOR
  76 *       Yael Kalka, Mellanox
  77 *
  78 *********/
  79 /****d* OpenSM: Pkt_Randomizer/osm_pkt_randomizer_t
  80 * NAME
  81 *       osm_pkt_randomizer_t
  82 *
  83 * DESCRIPTION
  84 *       Packet randomizer structure. This structure contains the various
  85 *  parameters needed by the packet randomizer.
  86 *
  87 * SYNOPSIS
  88 */
  89 typedef struct _osm_pkt_randomizer {
  90         uint8_t osm_pkt_drop_rate;
  91         uint8_t osm_pkt_num_unstable_links;
  92         uint8_t osm_pkt_unstable_link_rate;
  93         osm_dr_path_t *fault_dr_paths;
  94         uint8_t num_paths_initialized;
  95 } osm_pkt_randomizer_t;
  96
  97 /*
  98 * FIELDS
  99 *
 100 *  osm_pkt_drop_rate
 101 *     Used by the randomizer whether to drop a packet or not.
 102 *     Taken from the global variable OSM_PKT_DROP_RATE. If not given or
 103 *     if set to zero, the randomizer will not run.
 104 *
 105 *  osm_pkt_num_unstable_links
 106 *     The number of unstable links to be drawn.
 107 *     Taken from the global variable OSM_PKT_NUM_UNSTABLE_LINKS. default = 1.
 108 *
 109 *  osm_pkt_unstable_link_rate
 110 *     Used by the randomizer whether to add a packet to the unstable links
 111 *     list or not. Taken from the global variable OSM_PKT_UNSTABLE_LINK_RATE.
 112 *     default = 20.
 113 *
 114 *       fault_dr_path
 115 *               Array of osm_dr_path_t objects, that includes all the dr_paths
 116 *     that are marked as errored.
 117 *
 118 *  num_paths_initialized
 119 *     Describes the number of paths from the fault_dr_paths array that
 120 *     have already been initialized.
 121 *
 122 * SEE ALSO
 123 *       Packet Randomizer object
 124 *********/
 125
 126 /****f* OpenSM: Pkt_Randomizer/osm_pkt_randomizer_init
 127 * NAME
 128 *       osm_pkt_randomizer_init
 129 *
 130 * DESCRIPTION
 131 *       The osm_pkt_randomizer_init function initializes the Packet Randomizer object.
 132 *
 133 * SYNOPSIS
 134 */
 135 ib_api_status_t
 136 osm_pkt_randomizer_init(IN OUT osm_pkt_randomizer_t ** pp_pkt_randomizer,
 137                         IN osm_log_t * p_log);
 138 /*
 139 * PARAMETERS
 140 *  p_pkt_randomizer
 141 *     [in] Pointer to the Packet Randomizer object to be initialized.
 142 *
 143 *       p_log
 144 *               [in] Pointer to the log object.
 145 *
 146 * RETURN VALUE
 147 *       None
 148 *
 149 * NOTES
 150 *
 151 * SEE ALSO
 152 *
 153 *********/
 154
 155 /****f* OpenSM: Pkt_Randomizer/osm_pkt_randomizer_destroy
 156 * NAME
 157 *       osm_pkt_randomizer_destroy
 158 *
 159 * DESCRIPTION
 160 *       The osm_pkt_randomizer_destroy function destroys the Packet Randomizer object.
 161 *
 162 * SYNOPSIS
 163 */
 164 void
 165 osm_pkt_randomizer_destroy(IN osm_pkt_randomizer_t ** pp_pkt_randomizer,
 166                            IN osm_log_t * p_log);
 167 /*
 168 * PARAMETERS
 169 *  p_pkt_randomizer
 170 *     [in] Pointer to the Packet Randomizer object to be destroyed.
 171 *
 172 *       p_log
 173 *               [in] Pointer to the log object.
 174 *
 175 * RETURN VALUE
 176 *       None
 177 *
 178 * NOTES
 179 *
 180 * SEE ALSO
 181 *
 182 *********/
 183
 184 /****f* OpenSM: Pkt_Randomizer/osm_pkt_randomizer_madw_drop
 185 * NAME
 186 *       osm_pkt_randomizer_madw_drop
 187 *
 188 * DESCRIPTION
 189 *       The osm_pkt_randomizer_madw_drop is base function of the packet
 190 *  randomizer.
 191 *  It decides according to different random criteria whether or not
 192 *  the packet received should be dropped (according to its dr_path).
 193 *  This function is relevant both for mads sent by the SM and mads
 194 *  received by the SM.
 195 *  It returns TRUE if the mad should be dropped, and FALSE otherwise.
 196 *
 197 * SYNOPSIS
 198 */
 199 boolean_t
 200 osm_pkt_randomizer_mad_drop(IN osm_log_t * p_log,
 201                             IN osm_pkt_randomizer_t * p_pkt_randomizer,
 202                             IN const ib_mad_t * p_mad);
 203 /*
 204 * PARAMETERS
 205 *  p_subn
 206 *     [in] Pointer to the Subnet object for this subnet.
 207 *
 208 *       p_log
 209 *               [in] Pointer to the log object.
 210 *
 211 *  p_mad
 212 *     [in] Pointer to the ib_mad_t mad to be checked.
 213 *
 214 * RETURN VALUE
 215 *       TRUE if the mad should be dropped. FALSE otherwise.
 216 *
 217 * NOTES
 218 *
 219 * SEE ALSO
 220 *
 221 *********/
 222
 223 END_C_DECLS
 224 #endif                          /* _OSM_PKT_RANDOMIZER_H */