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

   1 /*
   2  * Copyright (c) 2004-2006 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_prtn_t.
  39  *      This object represents an IBA Partition.
  40  *      This object is part of the OpenSM family of objects.
  41  */
  42
  43 #ifndef _OSM_PARTITION_H_
  44 #define _OSM_PARTITION_H_
  45
  46 #include <iba/ib_types.h>
  47 #include <complib/cl_qmap.h>
  48 #include <complib/cl_map.h>
  49 #include <opensm/osm_log.h>
  50 #include <opensm/osm_subnet.h>
  51
  52 #ifdef __cplusplus
  53 #  define BEGIN_C_DECLS extern "C" {
  54 #  define END_C_DECLS   }
  55 #else                           /* !__cplusplus */
  56 #  define BEGIN_C_DECLS
  57 #  define END_C_DECLS
  58 #endif                          /* __cplusplus */
  59
  60 BEGIN_C_DECLS
  61 /****h* OpenSM/Partition
  62 * NAME
  63 *       Partition
  64 *
  65 * DESCRIPTION
  66 *       The Partition object encapsulates the information needed by the
  67 *       OpenSM to manage Partitions.  The OpenSM allocates one Partition
  68 *       object per Partition in the IBA subnet.
  69 *
  70 *       The Partition is not thread safe, thus callers must provide
  71 *       serialization.
  72 *
  73 *       This object should be treated as opaque and should be
  74 *       manipulated only through the provided functions.
  75 *
  76 * AUTHOR
  77 *       Steve King, Intel
  78 *
  79 *********/
  80 /****s* OpenSM: Partition/osm_prtn_t
  81 * NAME
  82 *       osm_prtn_t
  83 *
  84 * DESCRIPTION
  85 *       Partition structure.
  86 *
  87 *       The osm_prtn_t object should be treated as opaque and should
  88 *       be manipulated only through the provided functions.
  89 *
  90 * SYNOPSIS
  91 */
  92 typedef struct osm_prtn {
  93         cl_map_item_t map_item;
  94         ib_net16_t pkey;
  95         ib_net16_t mlid;
  96         uint8_t sl;
  97         cl_map_t full_guid_tbl;
  98         cl_map_t part_guid_tbl;
  99         char name[32];
 100 } osm_prtn_t;
 101 /*
 102 * FIELDS
 103 *       map_item
 104 *               Linkage structure for cl_qmap.  MUST BE FIRST MEMBER!
 105 *
 106 *       pkey
 107 *               The IBA defined P_KEY of this Partition.
 108 *
 109 *       mlid
 110 *               The network ordered LID of the well known Multicast Group
 111 *               that was created for this partition.
 112 *
 113 *       sl
 114 *               The Service Level (SL) associated with this Partiton.
 115 *
 116 *       full_guid_tbl
 117 *               Container of pointers to all Port objects in the Partition
 118 *               with full membership, indexed by port GUID.
 119 *
 120 *       part_guid_tbl
 121 *               Container of pointers to all Port objects in the Partition
 122 *               with limited membership, indexed by port GUID.
 123 *
 124 *       name
 125 *               Name of the Partition as specified in partition
 126 *               configuration.
 127 *
 128 * SEE ALSO
 129 *       Partition
 130 *********/
 131
 132 /****f* OpenSM: Partition/osm_prtn_delete
 133 * NAME
 134 *       osm_prtn_delete
 135 *
 136 * DESCRIPTION
 137 *       This function destroys and deallocates a Partition object.
 138 *
 139 * SYNOPSIS
 140 */
 141 void osm_prtn_delete(IN OUT osm_prtn_t ** const pp_prtn);
 142 /*
 143 * PARAMETERS
 144 *       pp_prtn
 145 *               [in][out] Pointer to a pointer to a Partition object to
 146 *               delete. On return, this pointer is NULL.
 147 *
 148 * RETURN VALUE
 149 *       This function does not return a value.
 150 *
 151 * NOTES
 152 *       Performs any necessary cleanup of the specified Partition object.
 153 *
 154 * SEE ALSO
 155 *       Partition, osm_prtn_new
 156 *********/
 157
 158 /****f* OpenSM: Partition/osm_prtn_new
 159 * NAME
 160 *       osm_prtn_new
 161 *
 162 * DESCRIPTION
 163 *       This function allocates and initializes a Partition object.
 164 *
 165 * SYNOPSIS
 166 */
 167 osm_prtn_t *osm_prtn_new(IN const char *name, IN const uint16_t pkey);
 168 /*
 169 * PARAMETERS
 170 *       name
 171 *               [in] Partition name string
 172 *
 173 *       pkey
 174 *               [in] Partition P_Key value
 175 *
 176 * RETURN VALUE
 177 *       Pointer to the initialize Partition object.
 178 *
 179 * NOTES
 180 *       Allows calling other partition methods.
 181 *
 182 * SEE ALSO
 183 *       Partition
 184 *********/
 185
 186 /****f* OpenSM: Partition/osm_prtn_is_guid
 187 * NAME
 188 *       osm_prtn_is_guid
 189 *
 190 * DESCRIPTION
 191 *       Indicates if a port is a member of the partition.
 192 *
 193 * SYNOPSIS
 194 */
 195 static inline boolean_t osm_prtn_is_guid(IN const osm_prtn_t * const p_prtn,
 196                                          IN const ib_net64_t guid)
 197 {
 198         return (cl_map_get(&p_prtn->full_guid_tbl, guid) != NULL) ||
 199             (cl_map_get(&p_prtn->part_guid_tbl, guid) != NULL);
 200 }
 201
 202 /*
 203 * PARAMETERS
 204 *       p_prtn
 205 *               [in] Pointer to an osm_prtn_t object.
 206 *
 207 *       guid
 208 *               [in] Port GUID.
 209 *
 210 * RETURN VALUES
 211 *       TRUE if the specified port GUID is a member of the partition,
 212 *       FALSE otherwise.
 213 *
 214 * NOTES
 215 *
 216 * SEE ALSO
 217 *********/
 218
 219 /****f* OpenSM: Partition/osm_prtn_make_partitions
 220 * NAME
 221 *       osm_prtn_make_partitions
 222 *
 223 * DESCRIPTION
 224 *       Makes all partitions in subnet.
 225 *
 226 * SYNOPSIS
 227 */
 228 ib_api_status_t osm_prtn_make_partitions(IN osm_log_t * const p_log,
 229                                          IN osm_subn_t * const p_subn);
 230 /*
 231 * PARAMETERS
 232 *       p_log
 233 *               [in] Pointer to a log object.
 234 *
 235 *       p_subn
 236 *               [in] Pointer to subnet object.
 237 *
 238 * RETURN VALUES
 239 *       IB_SUCCESS value on success.
 240 *
 241 * NOTES
 242 *
 243 * SEE ALSO
 244 *********/
 245
 246 /****f* OpenSM: Partition/osm_prtn_find_by_name
 247 * NAME
 248 *       osm_prtn_find_by_name
 249 *
 250 * DESCRIPTION
 251 *       Fides partition by name.
 252 *
 253 * SYNOPSIS
 254 */
 255 osm_prtn_t *osm_prtn_find_by_name(IN osm_subn_t * p_subn, IN const char *name);
 256 /*
 257 * PARAMETERS
 258 *       p_subn
 259 *               [in] Pointer to a subnet object.
 260 *
 261 *       name
 262 *               [in] Required partition name.
 263 *
 264 * RETURN VALUES
 265 *       Pointer to the partition object on success.
 266 *
 267 * NOTES
 268 *
 269 * SEE ALSO
 270 *********/
 271
 272 END_C_DECLS
 273 #endif                          /* _OSM_PARTITION_H_ */