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_node_t.
39 * This object represents an IBA node.
40 * This object is part of the OpenSM family of objects.
41 */
42
43 #ifndef _OSM_NODE_H_
44 #define _OSM_NODE_H_
45
46 #include <complib/cl_qmap.h>
47 #include <iba/ib_types.h>
48 #include <opensm/osm_base.h>
49 #include <opensm/osm_port.h>
50 #include <opensm/osm_path.h>
51 #include <opensm/osm_madw.h>
52
53 #ifdef __cplusplus
54 # define BEGIN_C_DECLS extern "C" {
55 # define END_C_DECLS }
56 #else /* !__cplusplus */
57 # define BEGIN_C_DECLS
58 # define END_C_DECLS
59 #endif /* __cplusplus */
60
61 BEGIN_C_DECLS
62
63 struct osm_switch;
64
65 /****h* OpenSM/Node
66 * NAME
67 * Node
68 *
69 * DESCRIPTION
70 * The Node object encapsulates the information needed by the
71 * OpenSM to manage nodes. The OpenSM allocates one Node object
72 * per node in the IBA subnet.
73 *
74 * The Node object is not thread safe, thus callers must provide
75 * serialization.
76 *
77 * This object should be treated as opaque and should be
78 * manipulated only through the provided functions.
79 *
80 * AUTHOR
81 * Steve King, Intel
82 *
83 *********/
84
85 /****s* OpenSM: Node/osm_node_t
86 * NAME
87 * osm_node_t
88 *
89 * DESCRIPTION
90 * Node structure.
91 *
92 * This object should be treated as opaque and should
93 * be manipulated only through the provided functions.
94 *
95 * SYNOPSIS
96 */
97 typedef struct osm_node {
98 cl_map_item_t map_item;
99 struct osm_switch *sw;
100 ib_node_info_t node_info;
101 ib_node_desc_t node_desc;
102 uint32_t discovery_count;
103 uint32_t physp_tbl_size;
104 char *print_desc;
105 osm_physp_t physp_table[1];
106 } osm_node_t;
107 /*
108 * FIELDS
109 * map_item
110 * Linkage structure for cl_qmap. MUST BE FIRST MEMBER!
111 *
112 * sw
113 * For switch node contains pointer to appropriate osm_switch
114 * structure. NULL for non-switch nodes. Can be used for fast
115 * access to switch object and for simple node type detection
116 *
117 * node_info
118 * The IBA defined NodeInfo data for this node.
119 *
120 * node_desc
121 * The IBA defined NodeDescription data for this node.
122 *
123 * discovery_count
124 * The number of times this node has been discovered
125 * during the current fabric sweep. This number is reset
126 * to zero at the start of a sweep.
127 *
128 * phsyp_tbl_size
129 * The size of the physp_table array. This value is one greater
130 * than the number of ports in the node, since port numbers
131 * start with 1 for some bizzare reason.
132 *
133 * print_desc
134 * A printable version of the node description.
135 *
136 * phsyp_table
137 * Array of physical port objects belonging to this node.
138 * Index is contiguous by local port number.
139 * For switches, port 0 is the always the management port (14.2.5.6).
140 * MUST BE LAST MEMBER! - Since it grows !!!!
141 *
142 * SEE ALSO
143 * Node object
144 *********/
145
146 /****f* OpenSM: Node/osm_node_delete
147 * NAME
148 * osm_node_delete
149 *
150 * DESCRIPTION
151 * The osm_node_delete function destroys a node, releasing
152 * all resources.
153 *
154 * SYNOPSIS
155 */
156 void osm_node_delete(IN OUT osm_node_t ** const p_node);
157 /*
158 * PARAMETERS
159 * p_node
160 * [in][out] Pointer to a Pointer a Node object to destroy.
161 * On return, the pointer to set to NULL.
162 *
163 * RETURN VALUE
164 * This function does not return a value.
165 *
166 * NOTES
167 * Performs any necessary cleanup of the specified Node object.
168 * This function should only be called after a call to osm_node_new.
169 *
170 * SEE ALSO
171 * Node object, osm_node_new
172 *********/
173
174 /****f* OpenSM: Node/osm_node_new
175 * NAME
176 * osm_node_new
177 *
178 * DESCRIPTION
179 * The osm_node_new function initializes a Node object for use.
180 *
181 * SYNOPSIS
182 */
183 osm_node_t *osm_node_new(IN const osm_madw_t * const p_madw);
184 /*
185 * PARAMETERS
186 * p_madw
187 * [in] Pointer to a osm_madw_t object containing a mad with
188 * the node's NodeInfo attribute. The caller may discard the
189 * osm_madw_t structure after calling osm_node_new.
190 *
191 * RETURN VALUES
192 * On success, a pointer to the new initialized osm_node_t structure.
193 * NULL otherwise.
194 *
195 * NOTES
196 *
197 * SEE ALSO
198 * Node object
199 *********/
200
201 /****f* OpenSM: Node/osm_node_get_physp_ptr
202 * NAME
203 * osm_node_get_physp_ptr
204 *
205 * DESCRIPTION
206 * Returns a pointer to the physical port object at the
207 * specified local port number.
208 *
209 * SYNOPSIS
210 */
osm_node_get_physp_ptr(IN osm_node_t * const p_node,IN const uint32_t port_num)211 static inline osm_physp_t *osm_node_get_physp_ptr(IN osm_node_t * const p_node,
212 IN const uint32_t port_num)
213 {
214
215 CL_ASSERT(port_num < p_node->physp_tbl_size);
216 return osm_physp_is_valid(&p_node->physp_table[port_num]) ?
217 &p_node->physp_table[port_num] : NULL;
218 }
219
220 /*
221 * PARAMETERS
222 * p_node
223 * [in] Pointer to an osm_node_t object.
224 *
225 * port_num
226 * [in] Local port number.
227 *
228 * RETURN VALUES
229 * Returns a pointer to the physical port object at the
230 * specified local port number.
231 * A return value of zero means the port number was out of range.
232 *
233 * NOTES
234 *
235 * SEE ALSO
236 * Node object
237 *********/
238
239 /****f* OpenSM: Node/osm_node_get_type
240 * NAME
241 * osm_node_get_type
242 *
243 * DESCRIPTION
244 * Returns the type of this node.
245 *
246 * SYNOPSIS
247 */
osm_node_get_type(IN const osm_node_t * const p_node)248 static inline uint8_t osm_node_get_type(IN const osm_node_t * const p_node)
249 {
250 return (p_node->node_info.node_type);
251 }
252
253 /*
254 * PARAMETERS
255 * p_node
256 * [in] Pointer to an osm_node_t object.
257 *
258 * RETURN VALUES
259 * Returns the IBA defined type of this node.
260 *
261 * NOTES
262 *
263 * SEE ALSO
264 * Node object
265 *********/
266
267 /****f* OpenSM: Node/osm_node_get_num_physp
268 * NAME
269 * osm_node_get_num_physp
270 *
271 * DESCRIPTION
272 * Returns the type of this node.
273 *
274 * SYNOPSIS
275 */
osm_node_get_num_physp(IN const osm_node_t * const p_node)276 static inline uint8_t osm_node_get_num_physp(IN const osm_node_t * const p_node)
277 {
278 return ((uint8_t) p_node->physp_tbl_size);
279 }
280
281 /*
282 * PARAMETERS
283 * p_node
284 * [in] Pointer to an osm_node_t object.
285 *
286 * RETURN VALUES
287 * Returns the IBA defined type of this node.
288 *
289 * NOTES
290 *
291 * SEE ALSO
292 * Node object
293 *********/
294
295 /****f* OpenSM: Node/osm_node_get_remote_node
296 * NAME
297 * osm_node_get_remote_node
298 *
299 * DESCRIPTION
300 * Returns a pointer to the node on the other end of the
301 * specified port.
302 * Returns NULL if no remote node exists.
303 *
304 * SYNOPSIS
305 */
306 osm_node_t *osm_node_get_remote_node(IN osm_node_t * const p_node,
307 IN const uint8_t port_num,
308 OUT uint8_t * p_remote_port_num);
309 /*
310 * PARAMETERS
311 * p_node
312 * [in] Pointer to an osm_node_t object.
313 *
314 * port_num
315 * [in] Port number in p_node through which to get the remote node.
316 *
317 * p_remote_port_num
318 * [out] Port number in the remote's node through which this
319 * link exists. The caller may specify NULL for this pointer
320 * if the port number isn't needed.
321 *
322 * RETURN VALUES
323 * Returns a pointer to the node on the other end of the
324 * specified port.
325 * Returns NULL if no remote node exists.
326 *
327 * NOTES
328 *
329 * SEE ALSO
330 * Node object
331 *********/
332
333 /****f* OpenSM: Node/osm_node_get_base_lid
334 * NAME
335 * osm_node_get_base_lid
336 *
337 * DESCRIPTION
338 * Returns the LID value of the specified port on this node.
339 *
340 * SYNOPSIS
341 */
342 static inline ib_net16_t
osm_node_get_base_lid(IN const osm_node_t * const p_node,IN const uint32_t port_num)343 osm_node_get_base_lid(IN const osm_node_t * const p_node,
344 IN const uint32_t port_num)
345 {
346 CL_ASSERT(port_num < p_node->physp_tbl_size);
347 return (osm_physp_get_base_lid(&p_node->physp_table[port_num]));
348 }
349
350 /*
351 * PARAMETERS
352 * p_node
353 * [in] Pointer to an osm_node_t object.
354 *
355 * port_num
356 * [in] Local port number.
357 *
358 * RETURN VALUES
359 * Returns a pointer to the physical port object at the
360 * specified local port number.
361 * A return value of zero means the port number was out of range.
362 *
363 * NOTES
364 *
365 * SEE ALSO
366 * Node object
367 *********/
368
369 /****f* OpenSM: Node/osm_node_get_remote_base_lid
370 * NAME
371 * osm_node_get_remote_base_lid
372 *
373 * DESCRIPTION
374 * Returns the base LID value of the port on the other side
375 * of the wire from the specified port on this node.
376 *
377 * SYNOPSIS
378 */
379 ib_net16_t
380 osm_node_get_remote_base_lid(IN osm_node_t * const p_node,
381 IN const uint32_t port_num);
382 /*
383 * PARAMETERS
384 * p_node
385 * [in] Pointer to an osm_node_t object.
386 *
387 * port_num
388 * [in] Local port number.
389 *
390 * RETURN VALUES
391 * Returns a pointer to the physical port object at the
392 * specified local port number.
393 * A return value of zero means the port number was out of range.
394 *
395 * NOTES
396 *
397 * SEE ALSO
398 * Node object
399 *********/
400
401 /****f* OpenSM: Node/osm_node_get_lmc
402 * NAME
403 * osm_node_get_lmc
404 *
405 * DESCRIPTION
406 * Returns the LMC value of the specified port on this node.
407 *
408 * SYNOPSIS
409 */
410 static inline uint8_t
osm_node_get_lmc(IN const osm_node_t * const p_node,IN const uint32_t port_num)411 osm_node_get_lmc(IN const osm_node_t * const p_node, IN const uint32_t port_num)
412 {
413 CL_ASSERT(port_num < p_node->physp_tbl_size);
414 return (osm_physp_get_lmc(&p_node->physp_table[port_num]));
415 }
416
417 /*
418 * PARAMETERS
419 * p_node
420 * [in] Pointer to an osm_node_t object.
421 *
422 * port_num
423 * [in] Local port number.
424 *
425 * RETURN VALUES
426 * Returns the LMC value of the specified port on this node.
427 *
428 * NOTES
429 *
430 * SEE ALSO
431 * Node object
432 *********/
433
434 /****f* OpenSM: Node/osm_node_init_physp
435 * NAME
436 * osm_node_init_physp
437 *
438 * DESCRIPTION
439 * Initializes a physical port for the given node.
440 *
441 * SYNOPSIS
442 */
443 void
444 osm_node_init_physp(IN osm_node_t * const p_node,
445 IN const osm_madw_t * const p_madw);
446 /*
447 * PARAMETERS
448 * p_node
449 * [in] Pointer to an osm_node_t object.
450 *
451 * p_madw
452 * [in] Pointer to a osm_madw_t object containing a mad with
453 * the node's NodeInfo attribute as discovered through the
454 * Physical Port to add to the node. The caller may discard the
455 * osm_madw_t structure after calling osm_node_new.
456 *
457 * RETURN VALUES
458 * None.
459 *
460 * NOTES
461 *
462 * SEE ALSO
463 * Node object, Physical Port object.
464 *********/
465
466 /****f* OpenSM: Node/osm_node_get_node_guid
467 * NAME
468 * osm_node_get_node_guid
469 *
470 * DESCRIPTION
471 * Returns the node GUID of this node.
472 *
473 * SYNOPSIS
474 */
475 static inline ib_net64_t
osm_node_get_node_guid(IN const osm_node_t * const p_node)476 osm_node_get_node_guid(IN const osm_node_t * const p_node)
477 {
478 return (p_node->node_info.node_guid);
479 }
480
481 /*
482 * PARAMETERS
483 * p_node
484 * [in] Pointer to an osm_node_t object.
485 *
486 * RETURN VALUES
487 * Returns the node GUID of this node.
488 *
489 * NOTES
490 *
491 * SEE ALSO
492 * Node object
493 *********/
494
495 /****f* OpenSM: Node/osm_node_link
496 * NAME
497 * osm_node_link
498 *
499 * DESCRIPTION
500 * Logically connects a node to another node through the specified port.
501 *
502 * SYNOPSIS
503 */
504 void
505 osm_node_link(IN osm_node_t * const p_node,
506 IN const uint8_t port_num,
507 IN osm_node_t * const p_remote_node,
508 IN const uint8_t remote_port_num);
509 /*
510 * PARAMETERS
511 * p_node
512 * [in] Pointer to an osm_node_t object.
513 *
514 * port_num
515 * [in] Port number in p_node through which to create the link.
516 *
517 * p_remote_node
518 * [in] Pointer to the remote port object.
519 *
520 * remote_port_num
521 * [in] Port number in the remote's node through which to
522 * create this link.
523 *
524 * RETURN VALUES
525 * None.
526 *
527 * NOTES
528 *
529 * SEE ALSO
530 * Node object
531 *********/
532
533 /****f* OpenSM: Node/osm_node_unlink
534 * NAME
535 * osm_node_unlink
536 *
537 * DESCRIPTION
538 * Logically disconnects a node from another node through
539 * the specified port.
540 *
541 * SYNOPSIS
542 */
543 void
544 osm_node_unlink(IN osm_node_t * const p_node,
545 IN const uint8_t port_num,
546 IN osm_node_t * const p_remote_node,
547 IN const uint8_t remote_port_num);
548 /*
549 * PARAMETERS
550 * p_node
551 * [in] Pointer to an osm_node_t object.
552 *
553 * port_num
554 * [in] Port number in p_node through which to unlink.
555 *
556 * p_remote_node
557 * [in] Pointer to the remote port object.
558 *
559 * remote_port_num
560 * [in] Port number in the remote's node through which to unlink.
561 *
562 * RETURN VALUES
563 * None.
564 *
565 * NOTES
566 *
567 * SEE ALSO
568 * Node object
569 *********/
570
571 /****f* OpenSM: Node/osm_node_link_exists
572 * NAME
573 * osm_node_link_exists
574 *
575 * DESCRIPTION
576 * Return TRUE if a link exists between the specified nodes on
577 * the specified ports.
578 * Returns FALSE otherwise.
579 *
580 * SYNOPSIS
581 */
582 boolean_t
583 osm_node_link_exists(IN osm_node_t * const p_node,
584 IN const uint8_t port_num,
585 IN osm_node_t * const p_remote_node,
586 IN const uint8_t remote_port_num);
587 /*
588 * PARAMETERS
589 * p_node
590 * [in] Pointer to an osm_node_t object.
591 *
592 * port_num
593 * [in] Port number in p_node through which to check the link.
594 *
595 * p_remote_node
596 * [in] Pointer to the remote port object.
597 *
598 * remote_port_num
599 * [in] Port number in the remote's node through which to
600 * check this link.
601 *
602 * RETURN VALUES
603 * Return TRUE if a link exists between the specified nodes on
604 * the specified ports.
605 * Returns FALSE otherwise.
606 *
607 * NOTES
608 *
609 * SEE ALSO
610 * Node object
611 *********/
612
613 /****f* OpenSM: Node/osm_node_has_any_link
614 * NAME
615 * osm_node_has_any_link
616 *
617 * DESCRIPTION
618 * Return TRUE if a any link exists from the specified nodes on
619 * the specified port.
620 * Returns FALSE otherwise.
621 *
622 * SYNOPSIS
623 */
624 boolean_t
625 osm_node_has_any_link(IN osm_node_t * const p_node, IN const uint8_t port_num);
626 /*
627 * PARAMETERS
628 * p_node
629 * [in] Pointer to an osm_node_t object.
630 *
631 * port_num
632 * [in] Port number in p_node through which to check the link.
633 *
634 * RETURN VALUES
635 * Return TRUE if a any link exists from the specified nodes on
636 * the specified port.
637 * Returns FALSE otherwise.
638 *
639 * NOTES
640 *
641 * SEE ALSO
642 * Node object
643 *********/
644
645 /****f* OpenSM: Node/osm_node_link_has_valid_ports
646 * NAME
647 * osm_node_link_has_valid_ports
648 *
649 * DESCRIPTION
650 * Return TRUE if both ports in the link are valid (initialized).
651 * Returns FALSE otherwise.
652 *
653 * SYNOPSIS
654 */
655 boolean_t
656 osm_node_link_has_valid_ports(IN osm_node_t * const p_node,
657 IN const uint8_t port_num,
658 IN osm_node_t * const p_remote_node,
659 IN const uint8_t remote_port_num);
660 /*
661 * PARAMETERS
662 * p_node
663 * [in] Pointer to an osm_node_t object.
664 *
665 * port_num
666 * [in] Port number in p_node through which to check the link.
667 *
668 * RETURN VALUES
669 * Return TRUE if both ports in the link are valid (initialized).
670 * Returns FALSE otherwise.
671 *
672 * NOTES
673 *
674 * SEE ALSO
675 * Node object
676 *********/
677
678 END_C_DECLS
679 #endif /* _OSM_NODE_H_ */
680