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

   1 /*
   2  * Copyright (c) 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 osmtest_t.
  39  * This object represents the OSMTest Test object.
  40  *
  41  */
  42
  43 #ifndef _OSMTEST_H_
  44 #define _OSMTEST_H_
  45
  46 #include <complib/cl_qmap.h>
  47 #include <opensm/osm_log.h>
  48 #include <vendor/osm_vendor_api.h>
  49 #include <vendor/osm_vendor_sa_api.h>
  50 #include <opensm/osm_mad_pool.h>
  51 #include <opensm/osm_helper.h>
  52 #include "osmtest_base.h"
  53 #include "osmtest_subnet.h"
  54
  55 enum OSMT_FLOWS {
  56         OSMT_FLOW_ALL = 0,
  57         OSMT_FLOW_CREATE_INVENTORY,
  58         OSMT_FLOW_VALIDATE_INVENTORY,
  59         OSMT_FLOW_SERVICE_REGISTRATION,
  60         OSMT_FLOW_EVENT_FORWARDING,
  61         OSMT_FLOW_STRESS_SA,
  62         OSMT_FLOW_MULTICAST,
  63         OSMT_FLOW_QOS,
  64         OSMT_FLOW_TRAP,
  65 };
  66
  67 /****s* OpenSM: Subnet/osmtest_opt_t
  68  * NAME
  69  * osmtest_opt_t
  70  *
  71  * DESCRIPTION
  72  * Subnet options structure.  This structure contains the various
  73  * site specific configuration parameters for osmtest.
  74  *
  75  * SYNOPSIS
  76  */
  77 typedef struct _osmtest_opt {
  78         uint32_t transaction_timeout;
  79         boolean_t force_log_flush;
  80         boolean_t create;
  81         uint32_t retry_count;
  82         uint32_t stress;
  83         uint32_t mmode;
  84         char file_name[OSMTEST_FILE_PATH_MAX];
  85         uint8_t flow;
  86         uint8_t wait_time;
  87         char *log_file;
  88         boolean_t ignore_path_records;
  89 } osmtest_opt_t;
  90
  91 /*
  92  * FIELDS
  93  *
  94  * SEE ALSO
  95  *********/
  96
  97 /****h* OSMTest/OSMTest
  98  * NAME
  99  * OSMTest
 100  *
 101  * DESCRIPTION
 102  * The OSMTest object tests an SM/SA for conformance to a known
 103  * set of data about an Infiniband subnet.
 104  *
 105  * AUTHOR
 106  * Steve King, Intel
 107  *
 108  *********/
 109
 110 /****s* OSMTest/osmtest_t
 111  * NAME
 112  * osmtest_t
 113  *
 114  * DESCRIPTION
 115  * OSMTest structure.
 116  *
 117  * This object should be treated as opaque and should
 118  * be manipulated only through the provided functions.
 119  *
 120  * SYNOPSIS
 121  */
 122 typedef struct _osmtest {
 123         osm_log_t log;
 124         struct _osm_vendor *p_vendor;
 125         osm_bind_handle_t h_bind;
 126         osm_mad_pool_t mad_pool;
 127
 128         osmtest_opt_t opt;
 129         ib_port_attr_t local_port;
 130         subnet_t exp_subn;
 131         cl_qpool_t node_pool;
 132         cl_qpool_t port_pool;
 133         cl_qpool_t link_pool;
 134
 135         uint16_t max_lid;
 136 } osmtest_t;
 137
 138 /*
 139  * FIELDS
 140  * log
 141  *    Log facility used by all OSMTest components.
 142  *
 143  * p_vendor
 144  *    Pointer to the vendor transport layer.
 145  *
 146  *  h_bind
 147  *     The bind handle obtained by osm_vendor_sa_api/osmv_bind_sa
 148  *
 149  *  mad_pool
 150  *     The mad pool provided for teh vendor layer to allocate mad wrappers in
 151  *
 152  * opt
 153  *    osmtest options structure
 154  *
 155  * local_port
 156  *    Port attributes for the port over which osmtest is running.
 157  *
 158  * exp_subn
 159  *    Subnet object representing the expected subnet
 160  *
 161  * node_pool
 162  *    Pool of objects for use in populating the subnet databases.
 163  *
 164  * port_pool
 165  *    Pool of objects for use in populating the subnet databases.
 166  *
 167  * link_pool
 168  *    Pool of objects for use in populating the subnet databases.
 169  *
 170  * SEE ALSO
 171  *********/
 172
 173 /****s* OpenSM: Subnet/osmtest_req_context_t
 174  * NAME
 175  * osmtest_req_context_t
 176  *
 177  * DESCRIPTION
 178  * Query context for ib_query callback function.
 179  *
 180  * SYNOPSIS
 181  */
 182 typedef struct _osmtest_req_context {
 183         osmtest_t *p_osmt;
 184         osmv_query_res_t result;
 185 } osmtest_req_context_t;
 186
 187 typedef struct _osmtest_mgrp_t {
 188         cl_map_item_t map_item;
 189         ib_member_rec_t mcmember_rec;
 190 } osmtest_mgrp_t;
 191
 192 /*
 193  * FIELDS
 194  *
 195  * SEE ALSO
 196  *********/
 197
 198 /****f* OSMTest/osmtest_construct
 199  * NAME
 200  * osmtest_construct
 201  *
 202  * DESCRIPTION
 203  * This function constructs an OSMTest object.
 204  *
 205  * SYNOPSIS
 206  */
 207 void osmtest_construct(IN osmtest_t * const p_osmt);
 208
 209 /*
 210  * PARAMETERS
 211  * p_osmt
 212  *    [in] Pointer to a OSMTest object to construct.
 213  *
 214  * RETURN VALUE
 215  * This function does not return a value.
 216  *
 217  * NOTES
 218  * Allows calling osmtest_init, osmtest_destroy.
 219  *
 220  * Calling osmtest_construct is a prerequisite to calling any other
 221  * method except osmtest_init.
 222  *
 223  * SEE ALSO
 224  * SM object, osmtest_init, osmtest_destroy
 225  *********/
 226
 227 /****f* OSMTest/osmtest_destroy
 228  * NAME
 229  * osmtest_destroy
 230  *
 231  * DESCRIPTION
 232  * The osmtest_destroy function destroys an osmtest object, releasing
 233  * all resources.
 234  *
 235  * SYNOPSIS
 236  */
 237 void osmtest_destroy(IN osmtest_t * const p_osmt);
 238
 239 /*
 240  * PARAMETERS
 241  * p_osmt
 242  *    [in] Pointer to a OSMTest object to destroy.
 243  *
 244  * RETURN VALUE
 245  * This function does not return a value.
 246  *
 247  * NOTES
 248  * Performs any necessary cleanup of the specified OSMTest object.
 249  * Further operations should not be attempted on the destroyed object.
 250  * This function should only be called after a call to osmtest_construct or
 251  * osmtest_init.
 252  *
 253  * SEE ALSO
 254  * SM object, osmtest_construct, osmtest_init
 255  *********/
 256
 257 /****f* OSMTest/osmtest_init
 258  * NAME
 259  * osmtest_init
 260  *
 261  * DESCRIPTION
 262  * The osmtest_init function initializes a OSMTest object for use.
 263  *
 264  * SYNOPSIS
 265  */
 266 ib_api_status_t osmtest_init(IN osmtest_t * const p_osmt,
 267                              IN const osmtest_opt_t * const p_opt,
 268                              IN const osm_log_level_t log_flags);
 269
 270 /*
 271  * PARAMETERS
 272  * p_osmt
 273  *    [in] Pointer to an osmtest_t object to initialize.
 274  *
 275  * p_opt
 276  *    [in] Pointer to the options structure.
 277  *
 278  * log_flags
 279  *    [in] Log level flags to set.
 280  *
 281  * RETURN VALUES
 282  * IB_SUCCESS if the OSMTest object was initialized successfully.
 283  *
 284  * NOTES
 285  * Allows calling other OSMTest methods.
 286  *
 287  * SEE ALSO
 288  * SM object, osmtest_construct, osmtest_destroy
 289  *********/
 290
 291 /****f* OSMTest/osmtest_run
 292  * NAME
 293  * osmtest_run
 294  *
 295  * DESCRIPTION
 296  * Runs the osmtest suite.
 297  *
 298  * SYNOPSIS
 299  */
 300 ib_api_status_t osmtest_run(IN osmtest_t * const p_osmt);
 301
 302 /*
 303  * PARAMETERS
 304  * p_osmt
 305  *    [in] Pointer to an osmtest_t object.
 306  *
 307  * guid
 308  *    [in] Port GUID over which to run the test suite.
 309  *
 310  * RETURN VALUES
 311  * IB_SUCCESS
 312  *
 313  * NOTES
 314  *
 315  * SEE ALSO
 316  *********/
 317
 318 /****f* OSMTest/osmtest_bind
 319  * NAME
 320  * osmtest_bind
 321  *
 322  * DESCRIPTION
 323  * Binds osmtest to a local port.
 324  *
 325  * SYNOPSIS
 326  */
 327 ib_api_status_t osmtest_bind(IN osmtest_t * p_osmt,
 328                              IN uint16_t max_lid, IN ib_net64_t guid OPTIONAL);
 329
 330 /*
 331  * PARAMETERS
 332  * p_osmt
 333  *    [in] Pointer to an osmtest_t object.
 334  *
 335  *  max_lid
 336  *     [in] The maximal lid to query about (if RMPP is not supported)
 337  *
 338  * guid
 339  *    [in] Port GUID over which to run the test suite.
 340  *    If zero, the bind function will display a menu of local
 341  *    port guids and wait for user input.
 342  *
 343  * RETURN VALUES
 344  * IB_SUCCESS
 345  *
 346  * NOTES
 347  *
 348  * SEE ALSO
 349  *********/
 350
 351 /****f* OSMTest/osmtest_query_res_cb
 352  * NAME
 353  * osmtest_query_res_cb
 354  *
 355  * DESCRIPTION
 356  * A Callback for the query to invoke on completion
 357  *
 358  * SYNOPSIS
 359  */
 360 void osmtest_query_res_cb(IN osmv_query_res_t * p_rec);
 361 /*
 362  * PARAMETERS
 363  * p_rec
 364  *    [in] Pointer to an ib_query_rec_t object used for the query.
 365  *
 366  * RETURN VALUES
 367  * NONE
 368  *
 369  * NOTES
 370  *
 371  * SEE ALSO
 372  *********/
 373
 374 /****f* OSMTest/ib_get_mad_status_str
 375  * NAME
 376  * ib_get_mad_status_str
 377  *
 378  * DESCRIPTION
 379  * return the string representing the given  mad status
 380  *
 381  * SYNOPSIS
 382  */
 383 const char *ib_get_mad_status_str(IN const ib_mad_t * const p_mad);
 384 /*
 385  * PARAMETERS
 386  * p_mad
 387  *    [in] Pointer to the mad payload
 388  *
 389  * RETURN VALUES
 390  * NONE
 391  *
 392  * NOTES
 393  *
 394  * SEE ALSO
 395  *********/
 396
 397 /****f* OSMTest/osmt_run_service_records_flow
 398  * NAME
 399  * osmt_run_service_records_flow
 400  *
 401  * DESCRIPTION
 402  * Run the service record testing flow.
 403  *
 404  * SYNOPSIS
 405  */
 406 ib_api_status_t osmt_run_service_records_flow(IN osmtest_t * const p_osmt);
 407 /*
 408  * PARAMETERS
 409  *  p_osmt
 410  *    [in] Pointer to the osmtest obj
 411  *
 412  * RETURN VALUES
 413  * IB_SUCCESS if PASS
 414  *
 415  * NOTES
 416  *
 417  * SEE ALSO
 418  *********/
 419
 420 ib_api_status_t osmt_run_inform_info_flow(IN osmtest_t * const p_osmt);
 421
 422 /****f* OSMTest/osmt_run_slvl_and_vlarb_records_flow
 423  * NAME
 424  * osmt_run_slvl_and_vlarb_records_flow
 425  *
 426  * DESCRIPTION
 427  * Run the sl2vl and vlarb tables testing flow.
 428  *
 429  * SYNOPSIS
 430  */
 431 ib_api_status_t
 432 osmt_run_slvl_and_vlarb_records_flow(IN osmtest_t * const p_osmt);
 433 /*
 434  * PARAMETERS
 435  *  p_osmt
 436  *    [in] Pointer to the osmtest obj
 437  *
 438  * RETURN VALUES
 439  * IB_SUCCESS if PASS
 440  *
 441  * NOTES
 442  *
 443  * SEE ALSO
 444  *********/
 445
 446 /****f* OSMTest/osmt_run_mcast_flow
 447  * NAME
 448  * osmt_run_mcast_flow
 449  *
 450  * DESCRIPTION
 451  * Run the multicast test flow
 452  *
 453  * SYNOPSIS
 454  */
 455 ib_api_status_t osmt_run_mcast_flow(IN osmtest_t * const p_osmt);
 456 /*
 457  * PARAMETERS
 458  *  p_osmt
 459  *    [in] Pointer to the osmtest obj
 460  *
 461  * RETURN VALUES
 462  * IB_SUCCESS if PASS
 463  *
 464  * NOTES
 465  *
 466  * SEE ALSO
 467  *********/
 468
 469 /****f* OSMTest/osmt_run_trap64_65_flow
 470  * NAME
 471  * osmt_run_trap64_65_flow
 472  *
 473  * DESCRIPTION
 474  * Run the trap 64/65 test flow. This test is ran with
 475  * an outside tool.
 476  *
 477  * SYNOPSIS
 478  */
 479 ib_api_status_t osmt_run_trap64_65_flow(IN osmtest_t * const p_osmt);
 480 /*
 481  * PARAMETERS
 482  *  p_osmt
 483  *    [in] Pointer to the osmtest obj
 484  *
 485  * RETURN VALUES
 486  * IB_SUCCESS if PASS
 487  *
 488  * NOTES
 489  *
 490  * SEE ALSO
 491  *********/
 492
 493 ib_api_status_t
 494 osmtest_get_all_recs(IN osmtest_t * const p_osmt,
 495                      IN ib_net16_t const attr_id,
 496                      IN size_t const attr_size,
 497                      IN OUT osmtest_req_context_t * const p_context);
 498
 499 ib_api_status_t
 500 osmtest_get_local_port_lmc(IN osmtest_t * const p_osmt,
 501                            IN ib_net16_t lid, OUT uint8_t * const p_lmc);
 502
 503 /*
 504  * A few auxiliary macros for logging
 505  */
 506
 507 #define EXPECTING_ERRORS_START "[[ ===== Expecting Errors - START ===== "
 508 #define EXPECTING_ERRORS_END   "   ===== Expecting Errors  -  END ===== ]]"
 509
 510 #endif                          /* _OSMTEST_H_ */