1IBDMSH(1) IB DATA MODEL PACKAGE IBDMSH(1)
2
6 ibdmsh IB DATA MODEL - Extentended TCL shell
7
9 ibdmsh is a TCL shell extended with interface for the IB data model.
10 To use this shell you will write TCL code that directly access the IB
11 data model objects and functions.
12 The following sub sections provide detailed definition for those
14 objects and API.
15
17 Node Types
18 The following constants are used by the node object type field
20 [ Constant : int ] $IB_UNKNOWN_NODE_TYPE = IB_UNKNOWN_NODE_TYPE
22 [ Constant : int ] $IB_SW_NODE = IB_SW_NODE
24 [ Constant : int ] $IB_CA_NODE = IB_CA_NODE
26 Log Verbosity Flags
28 The following constants are used as argument bits for the global vari‐
30 able $FabricUtilsVerboseLevel
31 [ Constant : int ] $FABU_LOG_NONE = 0x0
33 [ Constant : int ] $FABU_LOG_ERROR = 0x1
35 [ Constant : int ] $FABU_LOG_INFO = 0x2
37 [ Constant : int ] $FABU_LOG_VERBOSE = 0x4
39
41 Log level: set to FABU_LOG* values
42 [ Global : int ] $FabricUtilsVerboseLevel
44
46 This section decribes the various object types exposed by IBDM.
47 IBDM exposes some of its internal objects. The objects identifiers
49 returned by the various function calls are formatted according to the
50 following rules:
51 Fabric: fabric:<idx>
53 System: system:<fab idx>:<sys name>
55 SysPort: sysport:<fab idx>:<sys name>:<port name>
57 Node: node:<fab idx>:<node name>
59 Port: port:<fab idx>:<node name>/<port num>
61 IBDM Objects are standard Swig-Tcl objects. As such they have two fla‐
63 vors for their usage: Variables, Objects.
64 Variables/Pointers:
66 For each object attribute a "get" and "set" methods are provided.
67 The format of the methods is: <class>_<attribute>_<get⎪set>.
68 The "set" method is only available for read/write attributes.
69 Example:
71 set nodes [ibdm_get_nodes]
72 set node [lindex $nodes 0]
73 IBNode_numPorts_get $node
74 Objects:
76 Given an object pointer one can convert it to a Tcl "Object"
77 using the following command:
78 <class> <obj_name> -this <obj pointer>
79 Once declared the <obj-name> can be used in conjunction to
81 with the standard "configure" and "cget" commands.
82 Example (following the previous one):
84 IBFabric VaTech -this $fabric
85 VaTech cget -NodeByName
86 To delete an object symbol (and enable its mapping to another
88 pointer) use:
89 rename <obj name> ""
90 for example:
91 rename VaTech ""
92 class IBPort
94 The following are the different fields and methods of the IB Port class
96 which describes an IB device (chip) physical port.
97 [ Member data: returns IBPort * ] -p_remotePort
99 Port connected on the other side of link
100 [ Member data: returns IBSysPort * ] -p_sysPort
102 The system port (if any) connected to
103 [ Member data: returns IBNode * ] -p_node
105 The node the port is part of.
106 [ Member data: returns int ] -num
108 Physical ports are identified by number.
109 [ Member data: returns unsigned int ] -base_lid
111 The base lid assigned to the port.
112 [ Member data: returns IBLinkWidth * ] -width
114 The link width of the port
115 [ Member data: returns IBLinkSpeed * ] -speed
117 The link speed of the port
118 [ Member data: returns unsigned int ] -counter1
120 A generic value to be used by various algorithms
121 [ Constructor: returns IBPort * ] IBPort name p_nodePtr number
123 IBPort constructor
124 [ Member : returns new_uint64_t ] guid_get
126 Obtain the guid of the port
127 [ Member : returns void ] guid_set guid
129 Modify the guid of the port
130 [ Member : returns new_string ] getName
132 Get the port name: A device port connected to system port (front
133 pannel) returns the front pannel port name.
134 [ Member : returns void ] connect p_otherPort ?width? ?speed?
136 Connect the port to another node port with optional width and
137 speed parameters
138 [ Member : returns int ] disconnect
140 Disconnect the port. Return 0 if successful
141 class IBNode
143 The IB Node class represents a single IB Device (chip)
145 [ Member data: returns string * ] -name
147 Name of the node (instance name of the chip)
148 [ Member data: returns IBNodeType ] -type
150 Either a $IB_SW_NODE or $IB_CA_NODE
151 [ Member data: returns uint16_t * ] -devId
153 The device ID of the node
154 [ Member data: returns uint16_t * ] -revId
156 The device revision Id.
157 [ Member data: returns uint16_t * ] -vendId
159 The device Vendor ID.
160 [ Member data: returns string * ] -attributes
162 Comma-sep string of arbitrary attributes k=v
163 [ Member data: returns uint8_t ] -rank
165 The rank of the node (0 is a root)
166 [ Member data: returns IBSystem * ] -p_system
168 What system we belong to
169 [ Member data: returns IBFabric * ] -p_fabric
171 What fabric we belong to.
172 [ Member data: returns unsigned int ] -numPorts
174 Number of physical ports
175 [ Member data: returns vec_pport * ] -Ports
177 Vector of all the ports
178 [ Member data: returns vec_vec_byte * ] -MinHopsTable
180 A table of the number of hops required to get from each port to
181 each target LID
182 [ Member data: returns vec_byte * ] -LFT
184 The LFT of this node (for switches only) which is a long vector
185 of target ports - index is the LID
186 [ Member : returns new_uint64_t ] guid_get
188 Obtain the node GUID
189 [ Member : returns void ] guid_set guid
191 Set the node GUID
192 [ Constructor: returns IBNode * ] IBNode name n p_fab p_sys t np
194 Constractor
195 [ Member : returns IBPort * ] makePort num
197 Create a new port by its number (if required) return the port
198 pointer
199 [ Member : returns IBPort * ] getPort num
201 Get a port by number num = 1..N:
202 [ Member : returns void ] setHops p_port lid hops
204 Set the min hop for the given port (* is all) lid pair
205 [ Member : returns int ] getHops p_port lid
207 Get the min number of hops defined for the given port or all
208 [ Member : returns IBPort * ] getFirstMinHopPort lid
210 Scan the node ports and find the first port with min hop to the
211 lid
212 [ Member : returns void ] setLFTPortForLid lid portNum
214 Set the Linear Forwarding Table for the given LID
215 [ Member : returns int ] getLFTPortForLid lid
217 Get the LFT for a given LID
218 [ Member : returns void ] repHopTable
220 Dump out the min hop table of the node
221 class IBSysPort
223 The IBSysPort class represents an IB plug on the system front or back
225 pannels
226 [ Member data: returns string * ] -name
228 The front pannel name (silk) of the port
229 [ Member data: returns IBSysPort * ] -p_remoteSysPort
231 If connected the other side sys port
232 [ Member data: returns IBSystem * ] -p_system
234 System it benongs to
235 [ Member data: returns IBPort * ] -p_nodePort
237 The node port it connects to.
238 [ Constructor: returns IBSysPort * ] IBSysPort name n p_sys
240 Constructor
241 [ Member : returns void ] connect p_otherSysPort ?width? ?speed?
243 Connect two SysPorts
244 [ Member : returns int ] disconnect
246 Disconnect the SysPort (and ports). Return 0 if successful
247 class IBSystem
249 The IBSystem class represents an entire chassis
251 [ Member data: returns string * ] -name
253 The "host" name of the system
254 [ Member data: returns string * ] -type
256 What is the type i.e. Cougar, Buffalo, MTS2400, etc. A corre‐
257 sponding IBNL file should exist - defining this system type
258 [ Member data: returns IBFabric * ] -p_fabric
260 Fabric the system belongs to
261 [ Member data: returns map_str_pnode * ] -NodeByName
263 Provide the node pointer by its name
264 [ Member data: returns map_str_psysport * ] -PortByName
266 A map provising pointer to the SysPort by name
267 [ Constructor: returns IBSystem * ] IBSystem name n p_fab t
269 Constractor
270 [ Member : returns new_uint64_t ] guid_get
272 Obtain the system image GUID
273 [ Member : returns void ] guid_set guid
275 Set the system image GUID
276 [ Member : returns IBSysPort * ] makeSysPort pName
278 Make sure we got the port defined (so define it if not)
279 [ Member : returns IBPort * ] getSysPortNodePortByName sysPortName
281 Get the node port for the given sys port by name
282 [ Member : returns IBSysPort * ] getSysPort name
284 Get a Sys Port by name
285 class IBFabric
287 Represents an entire IB subnet made of systems
289 [ Member data: returns map_str_pnode * ] -NodeByName
291 Provide a list of node name and pointer pairs
292 [ Member data: returns map_str_psys * ] -SystemByName
294 Provide a list of system name and pointer pairs
295 [ Member data: returns vec_pport * ] -PortByLid
297 Provides a list of system port name and pointer pairs
298 [ Member data: returns map_guid_pnode * ] -NodeByGuid
300 Provides a list of node guid and node pointer pairs
301 [ Member data: returns map_guid_psys * ] -SystemByGuid
303 Provides a list of system image guid and system pointer pairs
304 [ Member data: returns map_guid_pport * ] -PortByGuid
306 Provides a list of port guid and port pointer pairs
307 [ Member data: returns unsigned int ] -minLid
309 Track min lid used.
310 [ Member data: returns unsigned int ] -maxLid
312 Track max lid used.
313 [ Member data: returns unsigned int ] -lmc
315 LMC value used
316 [ Member : returns IBNode * ] makeNode n p_sys type numPorts
318 Get the node by its name (create one of does not exist)
319 [ Member : returns IBNode * ] getNode name
321 Get the node by its name
322 [ Member : returns list_pnode * ] getNodesByType type
324 Return the list of node pointers matching the required type
325 [ Member : returns IBSystem * ] makeGenericSystem name
327 Create a new generic system - basically an empty container for
328 nodes...
329 [ Member : returns IBSystem * ] makeSystem name type
331 Create a new system - the type must have a registed factory.
332 [ Member : returns IBSystem * ] getSystem name
334 Get system by name
335 [ Member : returns IBSystem * ] getSystemByGuid guid
337 get the system by its guid
338 [ Member : returns IBNode * ] getNodeByGuid guid
340 get the node by its guid
341 [ Member : returns IBPort * ] getPortByGuid guid
343 get the port by its guid
344 [ Member : returns void ] addCable t1 n1 p1 t2 n2 p2 ?width? ?speed?
346 Adds a cable given two sets of node type, node name and port
347 number. Optionally use a given width and speed for the connec‐
348 tion
349 [ Member : returns int ] parseCables fn
351 Parse the cables file and build the fabric
352 [ Member : returns int ] parseTopology fn
354 Parse Topology File and build the fabric
355 [ Member : returns int ] addLink type1 numPorts1 sysGuid1 nodeGuid1
357 portGuid1 vend1 devId1 rev1 desc1 lid1 portNum1 type2 numPorts2 sys‐
358 Guid2 nodeGuid2 portGuid2 vend2 devId2 rev2 desc2 lid2 portNum2 ?width?
359 ?speed?
360 Add a link into the fabric - this will create system and nodes
361 as required.
362 [ Member : returns int ] parseSubnetLinks fn
364 Parse the OpenSM subnet.lst file and build the fabric from it.
365 [ Member : returns int ] parseFdbFile fn
367 Parse OpenSM FDB dump file and fill in the switches LFT tables
368 [ Member : returns int ] parseMCFdbFile fn
370 Parse an OpenSM MCFDBs file and set the MFT table accordingly
371 [ Member : returns int ] parsePSLFile fn
373 Parse Path to SL mapping file. Each line with: src_node_guid
374 DLID SL
375 Used by credit loop check
377 [ Member : returns int ] parseSLVLFile fn
379 Parse SLVL tables file. Each line holds: sw_node_guid in_port
380 out_port 0x(sl0)(sl1) 0x(sl2)(sl3)...
381 [ Member : returns void ] setLidPort lid p_port
383 Set a lid port
384 [ Member : returns IBPort * ] getPortByLid lid
386 Get a port by lid
387 [ returns IBFabric * ] new_IBFabric
389 Construct a new fabric
390 [ returns void ] delete_IBFabric p_fabric
392 Destruct a fabric
393
395 This section provide the details about the functions IBDM exposes. The
396 order follows the expected order in a regular IBDM flow. They all
397 return 0 on succes.
398 Subnet Utilities
400 The file holds a set of utilities to be run on the subnet to mimic
402 OpenSM initialization and analyze the results:
403 [ returns int ] ibdmAssignLids p_smNodePort ?lmc?
405 Assign LIDs with an optional LMC (multiple LID per port)
406 [ returns int ] ibdmCalcMinHopTables p_fabric
408 Calculate and populate the MinHopTables required for running
409 OpenSM style routing.
410 [ returns int ] ibdmCalcUpDnMinHopTbls p_fabric rootNodesNameRex
412 Calculate and populate the MinHopTables following Up/Down rule.
413 [ returns int ] ibdmOsmRoute p_fabric
415 Route the fabric with OpenSM style routing
416 [ returns int ] ibdmEnhancedRoute p_fabric
418 Route the fabric with OpenSM style routing enhanced with better
419 support for LMC > 0
420 [ returns int ] ibdmFatTreeRoute p_fabric rootNodes
422 Route the fabric using algorithm that fits only full fat trees
423 [ returns int ] ibdmFatTreeAnalysis p_fabric
425 Analyze the fabric to see if it is a fat tree and route it if it
426 is
427 [ returns int ] ibdmVerifyCAtoCARoutes p_fabric
429 Make sure all (H)CAs are connected to each other based on the
430 LFT settings
431 [ returns int ] ibdmVerifyAllPaths p_fabric
433 Make sure all Switches and (H)CAs are connected to each other
434 based on the LFT settings
435 [ returns int ] ibdmAnalyzeLoops p_fabric
437 A rigorous check for credit loops. This algorithm does a full
438 and accurate check but its reporting of credit loop paths is
439 hard to interpret. If you know the roots of the tree (or the
440 tree is symmetrical) it is preferable to use the ibdmReport‐
441 NonUpDownCa2CaPaths
442 [ returns list_pnode ] ibdmFindSymmetricalTreeRoots p_fabric
444 Analyze the tree topology and find the roots of the tree based
445 on its symmetry
446 [ returns list_pnode ] ibdmFindRootNodesByMinHop p_fabric
448 Based on the MinHopTable find the roots of the tree. A 5%
449 assymetry is allowed
450 [ returns int ] ibdmRankFabricByRoots p_fabric rootNodes
452 Given the list of root nodes (names) rank the nodes (root = 0)
453 [ returns int ] ibdmReportNonUpDownCa2CaPaths p_fabric rootNodes
455 Analyze the routes to make sure Up/Down rule is maintained
456 [ returns int ] ibdmCheckMulticastGroups p_fabric
458 Verify connectivity of multicast routing
459 [ returns int ] ibdmCheckFabricMCGrpsForCreditLoopPotential p_fabric
461 rootNodes
462 Analyze multicast routing to make sure it obeys Up/Down rule
463 [ returns int ] ibdmLinkCoverageAnalysis p_fabric rootNodes
465 Prepare a schedule for transmission from a set of sources to
466 destinations such that in each stage there are no links that are
467 over subscribed and after all stages all the links of the fabric
468 were excersized
469 Tracing Utilities
471 These functions allows tracing paths reporting back the visited nodes
473 [ returns int ] ibdmTraceDRPathRoute p_smNodePort drPathPortNums
475 Trace a directed route path from the given port
476 [ returns int ] ibdmTraceRouteByMinHops p_fabric slid dlid
478 Trace a path along the MinHop from the source to destination
479 LIDs
480 [ returns int ] ibdmTraceRouteByLFT p_fabric slid dlid hops
482 p_nodesList
483 Trace a path following the LFT updating the hops and node list
484 variables
485 Topology Matching Utilities
487 The following utilities matches two fabrics providing both missmatch
489 messages and a unified fabric
490 [ returns int ] ibdmMatchFabrics p_spec_fabric p_discovered_fabric
492 anchorNodeName anchorPortNum anchorPortGuid
493 Match a topology based fabric with a discovered one starting at
494 the enchor port
495 [ returns int ] ibdmBuildMergedFabric p_spec_fabric p_discovered_fab‐
497 ric p_merged_fabric
498 After matching using ibdmMatchFabrics populate the "merged fab‐
499 ric" with information merged for the matched nodes
500 Congestion Analysis Utilities
502 Provide ability to track and report link oversubscription
504 [ returns int ] ibdmCongInit p_fabric
506 Initialize the tracking system
507 [ returns int ] ibdmCongCleanup p_fabric
509 Cleanup the counters and deallocate
510 [ returns int ] ibdmCongClear p_fabric
512 Cleanup counters
513 [ returns int ] ibdmCongTrace p_fabric srcLid dstLid
515 Trace a path between the LIDs updating link usage info
516 [ returns int ] ibdmCongReport p_fabric
518 Report the resulting congestion information
519 [ returns int ] ibdmCongDump p_fabric
521 Dump all congestion tracking info
522
524 Eitan Zahavi, Mellanox Technologies LTD, eitan@mellanox.co.il
525IBDM 1.0 2009-03-16 IBDMSH(1)