1IBDMSH(1)                    IB DATA MODEL PACKAGE                   IBDMSH(1)
2
3
4

NAME

6       ibdmsh IB DATA MODEL - Extentended TCL shell
7

DESCRIPTION

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
13       The following sub sections provide detailed definition for those
14       objects and API.
15

IBDM Constants

17       Node Types
18
19       The following constants are used by the node object type field
20
21           [ Constant : int  ] $IB_UNKNOWN_NODE_TYPE = IB_UNKNOWN_NODE_TYPE
22
23           [ Constant : int  ] $IB_SW_NODE = IB_SW_NODE
24
25           [ Constant : int  ] $IB_CA_NODE = IB_CA_NODE
26
27       Log Verbosity Flags
28
29       The following constants are used as argument bits for the global vari‐
30       able $FabricUtilsVerboseLevel
31
32           [ Constant : int  ] $FABU_LOG_NONE = 0x0
33
34           [ Constant : int  ] $FABU_LOG_ERROR = 0x1
35
36           [ Constant : int  ] $FABU_LOG_INFO = 0x2
37
38           [ Constant : int  ]  $FABU_LOG_VERBOSE = 0x4
39

IBDM Globals

41       Log level: set to FABU_LOG* values
42
43           [ Global : int ] $FabricUtilsVerboseLevel
44

IBDM Objects

46       This section decribes the various object types exposed by IBDM.
47
48       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
52       Fabric: fabric:<idx>
53
54       System: system:<fab idx>:<sys name>
55
56       SysPort: sysport:<fab idx>:<sys name>:<port name>
57
58       Node: node:<fab idx>:<node name>
59
60       Port: port:<fab idx>:<node name>/<port num>
61
62       IBDM Objects are standard Swig-Tcl objects. As such they have two fla‐
63       vors for their usage: Variables, Objects.
64
65       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
70          Example:
71          set nodes [ibdm_get_nodes]
72          set node  [lindex $nodes 0]
73          IBNode_numPorts_get $node
74
75       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
80          Once declared the <obj-name> can be used in conjunction to
81          with the standard "configure" and "cget" commands.
82
83          Example (following the previous one):
84          IBFabric VaTech -this $fabric
85          VaTech cget -NodeByName
86
87          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
93       class IBPort
94
95       The following are the different fields and methods of the IB Port class
96       which describes an IB device (chip) physical port.
97
98       [ Member data: returns IBPort * ] -p_remotePort
99              Port connected on the other side of link
100
101       [ Member data: returns IBSysPort * ] -p_sysPort
102              The system port (if any) connected to
103
104       [ Member data: returns IBNode * ] -p_node
105              The node the port is part of.
106
107       [ Member data: returns int ] -num
108              Physical ports are identified by number.
109
110       [ Member data: returns unsigned int  ] -base_lid
111              The base lid assigned to the port.
112
113       [ Member data: returns IBLinkWidth * ] -width
114              The link width of the port
115
116       [ Member data: returns IBLinkSpeed * ] -speed
117              The link speed of the port
118
119       [ Member data: returns unsigned int  ] -counter1
120              A generic value to be used by various algorithms
121
122       [ Constructor: returns IBPort * ] IBPort name p_nodePtr number
123              IBPort constructor
124
125       [ Member : returns new_uint64_t  ] guid_get
126              Obtain the guid of the port
127
128       [ Member : returns void  ] guid_set guid
129              Modify the guid of the port
130
131       [ 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
135       [ Member : returns void  ] connect p_otherPort ?width? ?speed?
136              Connect the port to another node port with optional width and
137              speed parameters
138
139       [ Member : returns int  ] disconnect
140              Disconnect the port. Return 0 if successful
141
142       class IBNode
143
144       The IB Node class represents a single IB Device (chip)
145
146       [ Member data: returns string * ] -name
147              Name of the node (instance name of the chip)
148
149       [ Member data: returns IBNodeType  ] -type
150              Either a $IB_SW_NODE or $IB_CA_NODE
151
152       [ Member data: returns uint16_t * ] -devId
153              The device ID of the node
154
155       [ Member data: returns uint16_t * ] -revId
156              The device revision Id.
157
158       [ Member data: returns uint16_t * ] -vendId
159              The device Vendor ID.
160
161       [ Member data: returns string * ] -attributes
162              Comma-sep string of arbitrary attributes k=v
163
164       [ Member data: returns uint8_t ] -rank
165              The rank of the node (0 is a root)
166
167       [ Member data: returns IBSystem * ] -p_system
168              What system we belong to
169
170       [ Member data: returns IBFabric * ] -p_fabric
171              What fabric we belong to.
172
173       [ Member data: returns unsigned int  ] -numPorts
174              Number of physical ports
175
176       [ Member data: returns vec_pport * ] -Ports
177              Vector of all the ports
178
179       [ 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
183       [ 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
187       [ Member : returns new_uint64_t  ] guid_get
188              Obtain the node GUID
189
190       [ Member : returns void  ] guid_set guid
191              Set the node GUID
192
193       [ Constructor: returns IBNode * ] IBNode name n p_fab p_sys t np
194              Constractor
195
196       [ Member : returns IBPort * ] makePort num
197              Create a new port by its number (if required) return the port
198              pointer
199
200       [ Member : returns IBPort * ] getPort num
201              Get a port by number num = 1..N:
202
203       [ Member : returns void  ] setHops p_port lid hops
204              Set the min hop for the given port (* is all) lid pair
205
206       [ Member : returns int  ] getHops p_port lid
207              Get the min number of hops defined for the given port or all
208
209       [ Member : returns IBPort * ] getFirstMinHopPort lid
210              Scan the node ports and find the first port with min hop to the
211              lid
212
213       [ Member : returns void  ] setLFTPortForLid lid portNum
214              Set the Linear Forwarding Table for the given LID
215
216       [ Member : returns int  ] getLFTPortForLid lid
217              Get the LFT for a given LID
218
219       [ Member : returns void  ] repHopTable
220              Dump out the min hop table of the node
221
222       class IBSysPort
223
224       The IBSysPort class represents an IB plug on the system front or back
225       pannels
226
227       [ Member data: returns string * ] -name
228              The front pannel name (silk) of the port
229
230       [ Member data: returns IBSysPort * ] -p_remoteSysPort
231              If connected the other side sys port
232
233       [ Member data: returns IBSystem * ] -p_system
234              System it benongs to
235
236       [ Member data: returns IBPort * ] -p_nodePort
237              The node port it connects to.
238
239       [ Constructor: returns IBSysPort * ] IBSysPort name n p_sys
240              Constructor
241
242       [ Member : returns void  ] connect p_otherSysPort ?width? ?speed?
243              Connect two SysPorts
244
245       [ Member : returns int  ] disconnect
246              Disconnect the SysPort (and ports). Return 0 if successful
247
248       class IBSystem
249
250       The IBSystem class represents an entire chassis
251
252       [ Member data: returns string * ] -name
253              The "host" name of the system
254
255       [ 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
259       [ Member data: returns IBFabric * ] -p_fabric
260              Fabric the system belongs to
261
262       [ Member data: returns map_str_pnode * ] -NodeByName
263              Provide the node pointer by its name
264
265       [ Member data: returns map_str_psysport * ] -PortByName
266              A map provising pointer to the SysPort by name
267
268       [ Constructor: returns IBSystem * ] IBSystem name n p_fab t
269              Constractor
270
271       [ Member : returns new_uint64_t  ] guid_get
272              Obtain the system image GUID
273
274       [ Member : returns void  ] guid_set guid
275              Set the system image GUID
276
277       [ Member : returns IBSysPort * ] makeSysPort pName
278              Make sure we got the port defined (so define it if not)
279
280       [ Member : returns IBPort * ] getSysPortNodePortByName sysPortName
281              Get the node port for the given sys port by name
282
283       [ Member : returns IBSysPort * ] getSysPort name
284              Get a Sys Port by name
285
286       class IBFabric
287
288       Represents an entire IB subnet made of systems
289
290       [ Member data: returns map_str_pnode * ] -NodeByName
291              Provide a list of node name and pointer pairs
292
293       [ Member data: returns map_str_psys * ] -SystemByName
294              Provide a list of system name and pointer pairs
295
296       [ Member data: returns vec_pport * ] -PortByLid
297              Provides a list of system port name and pointer pairs
298
299       [ Member data: returns map_guid_pnode * ] -NodeByGuid
300              Provides a list of node guid and node pointer pairs
301
302       [ Member data: returns map_guid_psys * ] -SystemByGuid
303              Provides a list of system image guid and system pointer pairs
304
305       [ Member data: returns map_guid_pport * ] -PortByGuid
306              Provides a list of port guid and port pointer pairs
307
308       [ Member data: returns unsigned int  ] -minLid
309              Track min lid used.
310
311       [ Member data: returns unsigned int  ] -maxLid
312              Track max lid used.
313
314       [ Member data: returns unsigned int  ] -lmc
315              LMC value used
316
317       [ Member : returns IBNode * ] makeNode n p_sys type numPorts
318              Get the node by its name (create one of does not exist)
319
320       [ Member : returns IBNode * ] getNode name
321              Get the node by its name
322
323       [ Member : returns list_pnode * ] getNodesByType type
324              Return the list of node pointers matching the required type
325
326       [ Member : returns IBSystem * ] makeGenericSystem name
327              Create a new generic system - basically an empty container for
328              nodes...
329
330       [ Member : returns IBSystem * ] makeSystem name type
331              Create a new system - the type must have a registed factory.
332
333       [ Member : returns IBSystem * ] getSystem name
334              Get system by name
335
336       [ Member : returns IBSystem * ] getSystemByGuid guid
337              get the system by its guid
338
339       [ Member : returns IBNode * ] getNodeByGuid guid
340              get the node by its guid
341
342       [ Member : returns IBPort * ] getPortByGuid guid
343              get the port by its guid
344
345       [ 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
350       [ Member : returns int  ] parseCables fn
351              Parse the cables file and build the fabric
352
353       [ Member : returns int  ] parseTopology fn
354              Parse Topology File and build the fabric
355
356       [ 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
363       [ Member : returns int  ] parseSubnetLinks fn
364              Parse the OpenSM subnet.lst file and build the fabric from it.
365
366       [ Member : returns int  ] parseFdbFile fn
367              Parse OpenSM FDB dump file and fill in the switches LFT tables
368
369       [ Member : returns int  ] parseMCFdbFile fn
370              Parse an OpenSM MCFDBs file and set the MFT table accordingly
371
372       [ Member : returns int  ] parsePSLFile fn
373              Parse Path to SL mapping file. Each line with: src_node_guid
374              DLID SL
375
376       Used by credit loop check
377
378       [ 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
382       [ Member : returns void  ] setLidPort lid p_port
383              Set a lid port
384
385       [ Member : returns IBPort * ] getPortByLid lid
386              Get a port by lid
387
388       [ returns IBFabric * ] new_IBFabric
389              Construct a new fabric
390
391       [ returns void  ] delete_IBFabric p_fabric
392              Destruct a fabric
393

IBDM Functions

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
399       Subnet Utilities
400
401       The file holds a set of utilities to be run on the subnet to mimic
402       OpenSM initialization and analyze the results:
403
404       [ returns int  ] ibdmAssignLids p_smNodePort ?lmc?
405              Assign LIDs with an optional LMC (multiple LID per port)
406
407       [ returns int  ] ibdmCalcMinHopTables p_fabric
408              Calculate and populate the MinHopTables required for running
409              OpenSM style routing.
410
411       [ returns int  ] ibdmCalcUpDnMinHopTbls p_fabric rootNodesNameRex
412              Calculate and populate the MinHopTables following Up/Down rule.
413
414       [ returns int  ] ibdmOsmRoute p_fabric
415              Route the fabric with OpenSM style routing
416
417       [ returns int  ] ibdmEnhancedRoute p_fabric
418              Route the fabric with OpenSM style routing enhanced with better
419              support for LMC > 0
420
421       [ returns int  ] ibdmFatTreeRoute p_fabric rootNodes
422              Route the fabric using algorithm that fits only full fat trees
423
424       [ 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
428       [ returns int  ] ibdmVerifyCAtoCARoutes p_fabric
429              Make sure all (H)CAs are connected to each other based on the
430              LFT settings
431
432       [ 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
436       [ 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
443       [ returns list_pnode  ] ibdmFindSymmetricalTreeRoots p_fabric
444              Analyze the tree topology and find the roots of the tree based
445              on its symmetry
446
447       [ returns list_pnode  ] ibdmFindRootNodesByMinHop p_fabric
448              Based on the MinHopTable find the roots of the tree. A 5%
449              assymetry is allowed
450
451       [ returns int  ] ibdmRankFabricByRoots p_fabric rootNodes
452              Given the list of root nodes (names) rank the nodes (root = 0)
453
454       [ returns int  ] ibdmReportNonUpDownCa2CaPaths p_fabric rootNodes
455              Analyze the routes to make sure Up/Down rule is maintained
456
457       [ returns int  ] ibdmCheckMulticastGroups p_fabric
458              Verify connectivity of multicast routing
459
460       [ returns int  ] ibdmCheckFabricMCGrpsForCreditLoopPotential p_fabric
461       rootNodes
462              Analyze multicast routing to make sure it obeys Up/Down rule
463
464       [ 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
470       Tracing Utilities
471
472       These functions allows tracing paths reporting back the visited nodes
473
474       [ returns int  ] ibdmTraceDRPathRoute p_smNodePort drPathPortNums
475              Trace a directed route path from the given port
476
477       [ returns int  ] ibdmTraceRouteByMinHops p_fabric slid dlid
478              Trace a path along the MinHop from the source to destination
479              LIDs
480
481       [ 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
486       Topology Matching Utilities
487
488       The following utilities matches two fabrics providing both missmatch
489       messages and a unified fabric
490
491       [ 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
496       [ 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
501       Congestion Analysis Utilities
502
503       Provide ability to track and report link oversubscription
504
505       [ returns int  ] ibdmCongInit p_fabric
506              Initialize the tracking system
507
508       [ returns int  ] ibdmCongCleanup p_fabric
509              Cleanup the counters and deallocate
510
511       [ returns int  ] ibdmCongClear p_fabric
512              Cleanup counters
513
514       [ returns int  ] ibdmCongTrace p_fabric srcLid dstLid
515              Trace a path between the LIDs updating link usage info
516
517       [ returns int  ] ibdmCongReport p_fabric
518              Report the resulting congestion information
519
520       [ returns int  ] ibdmCongDump p_fabric
521              Dump all congestion tracking info
522

AUTHOR

524       Eitan Zahavi, Mellanox Technologies LTD, eitan@mellanox.co.il
525
526
527
528IBDM 1.0                          2009-03-16                         IBDMSH(1)
Impressum