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
73 BEGIN_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 */
104 typedef 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 */
188 void 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 */
217 void 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 */
240 void 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 */
268 ib_api_status_t
269 osm_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 */
326 void 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 */
350 void 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 */
374 ib_api_status_t
375 osm_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 */
404 ib_api_status_t
405 osm_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 */
450 ib_api_status_t
451 osm_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 */
503 ib_api_status_t
504 osm_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 */
539 ib_api_status_t
540 osm_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 */
578 ib_api_status_t
579 osm_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 */
609 static inline cl_status_t
osm_sm_wait_for_subnet_up(IN osm_sm_t * const p_sm,IN uint32_t const wait_us,IN boolean_t const interruptible)610 osm_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 */
654 static inline boolean_t
osm_sm_is_greater_than(IN const uint8_t l_priority,IN const ib_net64_t l_guid,IN const uint8_t r_priority,IN const ib_net64_t r_guid)655 osm_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 */
697 ib_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 */
726 void 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 */
751 ib_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
770 void 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 */
781 int 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
795 void osm_set_sm_priority(osm_sm_t *sm, uint8_t priority);
796
797 END_C_DECLS
798 #endif /* _OSM_SM_H_ */
799