osm_sm.h revision 256281
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_sm_t. 39 * This object represents an IBA subnet. 40 * This object is part of the OpenSM family of objects. 41 */ 42 43#ifndef _OSM_SM_H_ 44#define _OSM_SM_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_dispatcher.h> 51#include <complib/cl_event_wheel.h> 52#include <vendor/osm_vendor_api.h> 53#include <opensm/osm_stats.h> 54#include <opensm/osm_subnet.h> 55#include <opensm/osm_vl15intf.h> 56#include <opensm/osm_mad_pool.h> 57#include <opensm/osm_log.h> 58#include <opensm/osm_sm_mad_ctrl.h> 59#include <opensm/osm_lid_mgr.h> 60#include <opensm/osm_ucast_mgr.h> 61#include <opensm/osm_port.h> 62#include <opensm/osm_db.h> 63#include <opensm/osm_remote_sm.h> 64 65#ifdef __cplusplus 66# define BEGIN_C_DECLS extern "C" { 67# define END_C_DECLS } 68#else /* !__cplusplus */ 69# define BEGIN_C_DECLS 70# define END_C_DECLS 71#endif /* __cplusplus */ 72 73BEGIN_C_DECLS 74/****h* OpenSM/SM 75* NAME 76* SM 77* 78* DESCRIPTION 79* The SM object encapsulates the information needed by the 80* OpenSM to instantiate a subnet manager. The OpenSM allocates 81* one SM object per subnet manager. 82* 83* The SM object is thread safe. 84* 85* This object should be treated as opaque and should 86* be manipulated only through the provided functions. 87* 88* AUTHOR 89* Steve King, Intel 90* 91*********/ 92/****s* OpenSM: SM/osm_sm_t 93* NAME 94* osm_sm_t 95* 96* DESCRIPTION 97* Subnet Manager structure. 98* 99* This object should be treated as opaque and should 100* be manipulated only through the provided functions. 101* 102* SYNOPSIS 103*/ 104typedef struct osm_sm { 105 osm_thread_state_t thread_state; 106 unsigned signal_mask; 107 cl_spinlock_t signal_lock; 108 cl_spinlock_t state_lock; 109 cl_event_t signal_event; 110 cl_event_t subnet_up_event; 111 cl_timer_t sweep_timer; 112 cl_timer_t polling_timer; 113 cl_event_wheel_t trap_aging_tracker; 114 cl_thread_t sweeper; 115 unsigned master_sm_found; 116 uint32_t retry_number; 117 ib_net64_t master_sm_guid; 118 osm_remote_sm_t *p_polling_sm; 119 osm_subn_t *p_subn; 120 osm_db_t *p_db; 121 osm_vendor_t *p_vendor; 122 osm_log_t *p_log; 123 osm_mad_pool_t *p_mad_pool; 124 osm_vl15_t *p_vl15; 125 cl_dispatcher_t *p_disp; 126 cl_plock_t *p_lock; 127 atomic32_t sm_trans_id; 128 cl_spinlock_t mgrp_lock; 129 cl_qlist_t mgrp_list; 130 osm_sm_mad_ctrl_t mad_ctrl; 131 osm_lid_mgr_t lid_mgr; 132 osm_ucast_mgr_t ucast_mgr; 133 cl_disp_reg_handle_t sweep_fail_disp_h; 134 cl_disp_reg_handle_t ni_disp_h; 135 cl_disp_reg_handle_t pi_disp_h; 136 cl_disp_reg_handle_t nd_disp_h; 137 cl_disp_reg_handle_t si_disp_h; 138 cl_disp_reg_handle_t lft_disp_h; 139 cl_disp_reg_handle_t mft_disp_h; 140 cl_disp_reg_handle_t sm_info_disp_h; 141 cl_disp_reg_handle_t trap_disp_h; 142 cl_disp_reg_handle_t slvl_disp_h; 143 cl_disp_reg_handle_t vla_disp_h; 144 cl_disp_reg_handle_t pkey_disp_h; 145} osm_sm_t; 146/* 147* FIELDS 148* p_subn 149* Pointer to the Subnet object for this subnet. 150* 151* p_db 152* Pointer to the database (persistency) object 153* 154* p_vendor 155* Pointer to the vendor specific interfaces object. 156* 157* p_log 158* Pointer to the log object. 159* 160* p_mad_pool 161* Pointer to the MAD pool. 162* 163* p_vl15 164* Pointer to the VL15 interface. 165* 166* mad_ctrl 167* MAD Controller. 168* 169* p_disp 170* Pointer to the Dispatcher. 171* 172* p_lock 173* Pointer to the serializing lock. 174* 175* SEE ALSO 176* SM object 177*********/ 178 179/****f* OpenSM: SM/osm_sm_construct 180* NAME 181* osm_sm_construct 182* 183* DESCRIPTION 184* This function constructs an SM object. 185* 186* SYNOPSIS 187*/ 188void osm_sm_construct(IN osm_sm_t * const p_sm); 189/* 190* PARAMETERS 191* p_sm 192* [in] Pointer to a SM object to construct. 193* 194* RETURN VALUE 195* This function does not return a value. 196* 197* NOTES 198* Allows calling osm_sm_init, osm_sm_destroy 199* 200* Calling osm_sm_construct is a prerequisite to calling any other 201* method except osm_sm_init. 202* 203* SEE ALSO 204* SM object, osm_sm_init, osm_sm_destroy 205*********/ 206 207/****f* OpenSM: SM/osm_sm_shutdown 208* NAME 209* osm_sm_shutdown 210* 211* DESCRIPTION 212* The osm_sm_shutdown function shutdowns an SM, stopping the sweeper 213* and unregistering all messages from the dispatcher 214* 215* SYNOPSIS 216*/ 217void osm_sm_shutdown(IN osm_sm_t * const p_sm); 218/* 219* PARAMETERS 220* p_sm 221* [in] Pointer to a SM object to shutdown. 222* 223* RETURN VALUE 224* This function does not return a value. 225* 226* SEE ALSO 227* SM object, osm_sm_construct, osm_sm_init 228*********/ 229 230/****f* OpenSM: SM/osm_sm_destroy 231* NAME 232* osm_sm_destroy 233* 234* DESCRIPTION 235* The osm_sm_destroy function destroys an SM, releasing 236* all resources. 237* 238* SYNOPSIS 239*/ 240void osm_sm_destroy(IN osm_sm_t * const p_sm); 241/* 242* PARAMETERS 243* p_sm 244* [in] Pointer to a SM object to destroy. 245* 246* RETURN VALUE 247* This function does not return a value. 248* 249* NOTES 250* Performs any necessary cleanup of the specified SM object. 251* Further operations should not be attempted on the destroyed object. 252* This function should only be called after a call to osm_sm_construct or 253* osm_sm_init. 254* 255* SEE ALSO 256* SM object, osm_sm_construct, osm_sm_init 257*********/ 258 259/****f* OpenSM: SM/osm_sm_init 260* NAME 261* osm_sm_init 262* 263* DESCRIPTION 264* The osm_sm_init function initializes a SM object for use. 265* 266* SYNOPSIS 267*/ 268ib_api_status_t 269osm_sm_init(IN osm_sm_t * const p_sm, 270 IN osm_subn_t * const p_subn, 271 IN osm_db_t * const p_db, 272 IN osm_vendor_t * const p_vendor, 273 IN osm_mad_pool_t * const p_mad_pool, 274 IN osm_vl15_t * const p_vl15, 275 IN osm_log_t * const p_log, 276 IN osm_stats_t * const p_stats, 277 IN cl_dispatcher_t * const p_disp, IN cl_plock_t * const p_lock); 278/* 279* PARAMETERS 280* p_sm 281* [in] Pointer to an osm_sm_t object to initialize. 282* 283* p_subn 284* [in] Pointer to the Subnet object for this subnet. 285* 286* p_vendor 287* [in] Pointer to the vendor specific interfaces object. 288* 289* p_mad_pool 290* [in] Pointer to the MAD pool. 291* 292* p_vl15 293* [in] Pointer to the VL15 interface. 294* 295* p_log 296* [in] Pointer to the log object. 297* 298* p_stats 299* [in] Pointer to the statistics object. 300* 301* p_disp 302* [in] Pointer to the OpenSM central Dispatcher. 303* 304* p_lock 305* [in] Pointer to the OpenSM serializing lock. 306* 307* RETURN VALUES 308* IB_SUCCESS if the SM object was initialized successfully. 309* 310* NOTES 311* Allows calling other SM methods. 312* 313* SEE ALSO 314* SM object, osm_sm_construct, osm_sm_destroy 315*********/ 316 317/****f* OpenSM: SM/osm_sm_signal 318* NAME 319* osm_sm_signal 320* 321* DESCRIPTION 322* Signal event to SM 323* 324* SYNOPSIS 325*/ 326void osm_sm_signal(IN osm_sm_t * const p_sm, osm_signal_t signal); 327/* 328* PARAMETERS 329* p_sm 330* [in] Pointer to an osm_sm_t object. 331* 332* signal 333* [in] sm signal number. 334* 335* NOTES 336* 337* SEE ALSO 338* SM object 339*********/ 340 341/****f* OpenSM: SM/osm_sm_sweep 342* NAME 343* osm_sm_sweep 344* 345* DESCRIPTION 346* Initiates a subnet sweep. 347* 348* SYNOPSIS 349*/ 350void osm_sm_sweep(IN osm_sm_t * const p_sm); 351/* 352* PARAMETERS 353* p_sm 354* [in] Pointer to an osm_sm_t object. 355* 356* RETURN VALUES 357* IB_SUCCESS if the sweep completed successfully. 358* 359* NOTES 360* 361* SEE ALSO 362* SM object 363*********/ 364 365/****f* OpenSM: SM/osm_sm_bind 366* NAME 367* osm_sm_bind 368* 369* DESCRIPTION 370* Binds the sm object to a port guid. 371* 372* SYNOPSIS 373*/ 374ib_api_status_t 375osm_sm_bind(IN osm_sm_t * const p_sm, IN const ib_net64_t port_guid); 376/* 377* PARAMETERS 378* p_sm 379* [in] Pointer to an osm_sm_t object to bind. 380* 381* port_guid 382* [in] Local port GUID with which to bind. 383* 384* 385* RETURN VALUES 386* None 387* 388* NOTES 389* A given SM object can only be bound to one port at a time. 390* 391* SEE ALSO 392*********/ 393 394/****f* OpenSM: SM/osm_req_get 395* NAME 396* osm_req_get 397* 398* DESCRIPTION 399* Starts the process to transmit a directed route request for 400* the attribute. 401* 402* SYNOPSIS 403*/ 404ib_api_status_t 405osm_req_get(IN osm_sm_t * sm, 406 IN const osm_dr_path_t * const p_path, 407 IN const uint16_t attr_id, 408 IN const uint32_t attr_mod, 409 IN const cl_disp_msgid_t err_msg, 410 IN const osm_madw_context_t * const p_context); 411/* 412* PARAMETERS 413* sm 414* [in] Pointer to an osm_sm_t object. 415* 416* p_path 417* [in] Pointer to the directed route path to the node 418* from which to retrieve the attribute. 419* 420* attr_id 421* [in] Attribute ID to request. 422* 423* attr_mod 424* [in] Attribute modifier for this request. 425* 426* err_msg 427* [in] Message id with which to post this MAD if an error occurs. 428* 429* p_context 430* [in] Mad wrapper context structure to be copied into the wrapper 431* context, and thus visible to the recipient of the response. 432* 433* RETURN VALUES 434* IB_SUCCESS if the request was successful. 435* 436* NOTES 437* This function asynchronously requests the specified attribute. 438* The response from the node will be routed through the Dispatcher 439* to the appropriate receive controller object. 440*********/ 441/****f* OpenSM: SM/osm_req_set 442* NAME 443* osm_req_set 444* 445* DESCRIPTION 446* Starts the process to transmit a directed route Set() request. 447* 448* SYNOPSIS 449*/ 450ib_api_status_t 451osm_req_set(IN osm_sm_t * sm, 452 IN const osm_dr_path_t * const p_path, 453 IN const uint8_t * const p_payload, 454 IN const size_t payload_size, 455 IN const uint16_t attr_id, 456 IN const uint32_t attr_mod, 457 IN const cl_disp_msgid_t err_msg, 458 IN const osm_madw_context_t * const p_context); 459/* 460* PARAMETERS 461* sm 462* [in] Pointer to an osm_sm_t object. 463* 464* p_path 465* [in] Pointer to the directed route path of the recipient. 466* 467* p_payload 468* [in] Pointer to the SMP payload to send. 469* 470* payload_size 471* [in] The size of the payload to be copied to the SMP data field. 472* 473* attr_id 474* [in] Attribute ID to request. 475* 476* attr_mod 477* [in] Attribute modifier for this request. 478* 479* err_msg 480* [in] Message id with which to post this MAD if an error occurs. 481* 482* p_context 483* [in] Mad wrapper context structure to be copied into the wrapper 484* context, and thus visible to the recipient of the response. 485* 486* RETURN VALUES 487* IB_SUCCESS if the request was successful. 488* 489* NOTES 490* This function asynchronously requests the specified attribute. 491* The response from the node will be routed through the Dispatcher 492* to the appropriate receive controller object. 493*********/ 494/****f* OpenSM: SM/osm_resp_send 495* NAME 496* osm_resp_send 497* 498* DESCRIPTION 499* Starts the process to transmit a directed route response. 500* 501* SYNOPSIS 502*/ 503ib_api_status_t 504osm_resp_send(IN osm_sm_t * sm, 505 IN const osm_madw_t * const p_req_madw, 506 IN const ib_net16_t status, IN const uint8_t * const p_payload); 507/* 508* PARAMETERS 509* p_resp 510* [in] Pointer to an osm_resp_t object. 511* 512* p_madw 513* [in] Pointer to the MAD Wrapper object for the requesting MAD 514* to which this response is generated. 515* 516* status 517* [in] Status for this response. 518* 519* p_payload 520* [in] Pointer to the payload of the response MAD. 521* 522* RETURN VALUES 523* IB_SUCCESS if the response was successful. 524* 525*********/ 526 527/****f* OpenSM: SM/osm_sm_mcgrp_join 528* NAME 529* osm_sm_mcgrp_join 530* 531* DESCRIPTION 532* Adds a port to the multicast group. Creates the multicast group 533* if necessary. 534* 535* This function is called by the SA. 536* 537* SYNOPSIS 538*/ 539ib_api_status_t 540osm_sm_mcgrp_join(IN osm_sm_t * const p_sm, 541 IN const ib_net16_t mlid, 542 IN const ib_net64_t port_guid, 543 IN osm_mcast_req_type_t req_type); 544/* 545* PARAMETERS 546* p_sm 547* [in] Pointer to an osm_sm_t object. 548* 549* mlid 550* [in] Multicast LID 551* 552* port_guid 553* [in] Port GUID to add to the group. 554* 555* req_type 556* [in] Type of the MC request that caused this join 557* (MC create/join). 558* 559* RETURN VALUES 560* None 561* 562* NOTES 563* 564* SEE ALSO 565*********/ 566 567/****f* OpenSM: SM/osm_sm_mcgrp_leave 568* NAME 569* osm_sm_mcgrp_leave 570* 571* DESCRIPTION 572* Removes a port from the multicast group. 573* 574* This function is called by the SA. 575* 576* SYNOPSIS 577*/ 578ib_api_status_t 579osm_sm_mcgrp_leave(IN osm_sm_t * const p_sm, 580 IN const ib_net16_t mlid, IN const ib_net64_t port_guid); 581/* 582* PARAMETERS 583* p_sm 584* [in] Pointer to an osm_sm_t object. 585* 586* mlid 587* [in] Multicast LID 588* 589* port_guid 590* [in] Port GUID to remove from the group. 591* 592* RETURN VALUES 593* None 594* 595* NOTES 596* 597* SEE ALSO 598*********/ 599 600/****f* OpenSM: OpenSM/osm_sm_wait_for_subnet_up 601* NAME 602* osm_sm_wait_for_subnet_up 603* 604* DESCRIPTION 605* Blocks the calling thread until the subnet is up. 606* 607* SYNOPSIS 608*/ 609static inline cl_status_t 610osm_sm_wait_for_subnet_up(IN osm_sm_t * const p_sm, 611 IN uint32_t const wait_us, 612 IN boolean_t const interruptible) 613{ 614 return (cl_event_wait_on(&p_sm->subnet_up_event, 615 wait_us, interruptible)); 616} 617 618/* 619* PARAMETERS 620* p_sm 621* [in] Pointer to an osm_sm_t object. 622* 623* wait_us 624* [in] Number of microseconds to wait. 625* 626* interruptible 627* [in] Indicates whether the wait operation can be interrupted 628* by external signals. 629* 630* RETURN VALUES 631* CL_SUCCESS if the wait operation succeeded in response to the event 632* being set. 633* 634* CL_TIMEOUT if the specified time period elapses. 635* 636* CL_NOT_DONE if the wait was interrupted by an external signal. 637* 638* CL_ERROR if the wait operation failed. 639* 640* NOTES 641* 642* SEE ALSO 643*********/ 644 645/****f* OpenSM: State Manager/osm_sm_is_greater_than 646* NAME 647* osm_sm_is_greater_than 648* 649* DESCRIPTION 650* Compares two SM's (14.4.1.2) 651* 652* SYNOPSIS 653*/ 654static inline boolean_t 655osm_sm_is_greater_than(IN const uint8_t l_priority, 656 IN const ib_net64_t l_guid, 657 IN const uint8_t r_priority, IN const ib_net64_t r_guid) 658{ 659 return (l_priority > r_priority 660 || (l_priority == r_priority 661 && cl_ntoh64(l_guid) < cl_ntoh64(r_guid))); 662} 663 664/* 665* PARAMETERS 666* l_priority 667* [in] Priority of the SM on the "left" 668* 669* l_guid 670* [in] GUID of the SM on the "left" 671* 672* r_priority 673* [in] Priority of the SM on the "right" 674* 675* r_guid 676* [in] GUID of the SM on the "right" 677* 678* RETURN VALUES 679* Return TRUE if an sm with l_priority and l_guid is higher than an sm 680* with r_priority and r_guid, return FALSE otherwise. 681* 682* NOTES 683* 684* SEE ALSO 685* State Manager 686*********/ 687 688/****f* OpenSM: SM State Manager/osm_sm_state_mgr_process 689* NAME 690* osm_sm_state_mgr_process 691* 692* DESCRIPTION 693* Processes and maintains the states of the SM. 694* 695* SYNOPSIS 696*/ 697ib_api_status_t osm_sm_state_mgr_process(IN osm_sm_t *sm, 698 IN osm_sm_signal_t signal); 699/* 700* PARAMETERS 701* sm 702* [in] Pointer to an osm_sm_t object. 703* 704* signal 705* [in] Signal to the state SM engine. 706* 707* RETURN VALUES 708* None. 709* 710* NOTES 711* 712* SEE ALSO 713* State Manager 714*********/ 715 716/****f* OpenSM: SM State Manager/osm_sm_state_mgr_signal_master_is_alive 717* NAME 718* osm_sm_state_mgr_signal_master_is_alive 719* 720* DESCRIPTION 721* Signals that the remote Master SM is alive. 722* Need to clear the retry_number variable. 723* 724* SYNOPSIS 725*/ 726void osm_sm_state_mgr_signal_master_is_alive(IN osm_sm_t *sm); 727/* 728* PARAMETERS 729* sm 730* [in] Pointer to an osm_sm_t object. 731* 732* RETURN VALUES 733* None. 734* 735* NOTES 736* 737* SEE ALSO 738* State Manager 739*********/ 740 741/****f* OpenSM: SM State Manager/osm_sm_state_mgr_check_legality 742* NAME 743* osm_sm_state_mgr_check_legality 744* 745* DESCRIPTION 746* Checks the legality of the signal received, according to the 747* current state of the SM state machine. 748* 749* SYNOPSIS 750*/ 751ib_api_status_t osm_sm_state_mgr_check_legality(IN osm_sm_t *sm, 752 IN osm_sm_signal_t signal); 753/* 754* PARAMETERS 755* sm 756* [in] Pointer to an osm_sm_t object. 757* 758* signal 759* [in] Signal to the state SM engine. 760* 761* RETURN VALUES 762* None. 763* 764* NOTES 765* 766* SEE ALSO 767* State Manager 768*********/ 769 770void osm_report_sm_state(osm_sm_t *sm); 771 772/****f* OpenSM: SM State Manager/osm_send_trap144 773* NAME 774* osm_send_trap144 775* 776* DESCRIPTION 777* Send trap 144 to the master SM. 778* 779* SYNOPSIS 780*/ 781int osm_send_trap144(osm_sm_t *sm, ib_net16_t local); 782/* 783* PARAMETERS 784* sm 785* [in] Pointer to an osm_sm_t object. 786* 787* local 788* [in] OtherLocalChanges mask in network byte order. 789* 790* RETURN VALUES 791* 0 on success, non-zero value otherwise. 792* 793*********/ 794 795void osm_set_sm_priority(osm_sm_t *sm, uint8_t priority); 796 797END_C_DECLS 798#endif /* _OSM_SM_H_ */ 799