1IBDM-IBNL-FILE(1)            IB DATA MODEL PACKAGE           IBDM-IBNL-FILE(1)
2
3
4

NAME

6       ibnl - a generic IB netlist format
7

DESCRIPTION

9       IBDM topology file ibdm-topo-file provide means to describe the IB fab‐
10       ric using a set of predefined systems. A system definition is provided
11       in a single file in IBNL format that describes the internal InfiniBand
12       connectivity of the system in terms of boards and devices. When IBDM
13       starts it parses all the available system definition files before it
14       handles the topology file. The files are located in the following
15       directory relative to the installation prefix: <pre‐
16       fix>/lib/ibdm1.0/ibnl.
17
18       This man page describes the IBNL file format used to define an arbi‐
19       trary IB system internal IB connectivity. It outlines the main concepts
20       used by the file, provides details for how to write such a file and
21       provides a formal definition of the file syntax in BNF like format
22       (YACC/Bison readable).
23

1. Main Concepts

25       The described file format for defining generic system IB connectivity
26       uses the following terminology:
27
28       NODE
29           The instantiation of an IB device may it be a switch or a channel
30           adapter
31
32       SUB-SYSTEM
33           The instantiation of a board or module in a system
34
35       SYSTEM
36           A definition of a board or a module
37
38       TOPSYSTEM
39           The top most system defined in the given file
40
41       SUB-SYSTEM MODIFIER
42           Many systems allow multiple variations of their subsystem such as a
43           12X version of a leaf board in a MTS9600. The modifier is a suffix
44           to the board name. The IBNL format supports assigning multiple
45           names to the same board.
46

2. File Format

48       The exact file format is provided in section 4. This section only pro‐
49       vides extra information regarding the specific semantics of various
50       sections.
51
52       The IBNL file is line sensitive as it requires different sections to
53       start on a new line. The file is broken into several SYSTEM (optional)
54       and one TOPSYSTEM sections. Each has one or more names.
55
56       Connections are defined inside the SYSTEM/TOPSYSTEM section only and
57       thus might be of two types:
58
59       1. Between any node or sub-system to other node or sub-system
60       2. From any node or sub-system to a connector of the system.
61
62       NOTE-1: The top system can define ports that might be redundant and not
63       connected to any lower level board connector. In these cases the ports
64       are simply omitted from the resulting system. This feature enables
65       defining the front panel ports of a 12X/4X such that if a 12X leaf is
66       selected only the 12X front panel ports are used.
67
68       NOTE-2:  Port width and speed provided at the lowest level have prece‐
69       dence over definitions provided at upper levels of the hierarchy.
70

3. Guidelines for writing a System IBNL File

72       The following procedure should be followed in order to provide a new
73       system IBNL:
74
75       a)  Name the file after the system name: <any sys name (no spa‐
76           ces)>.ibnl
77
78       b)  Define a SYSTEM section for each board included in the system
79
80       c)  The port names of the boards are just strings, we use the simple
81           format of Pn where N is just a serial number but you can pick any
82           name you want. Just make sure it is unique.
83
84       d)  When different flavors of the boards exists like when you have a 4x
85           and 12x option for a board name the optional boards with a modifier
86           postfix. An example for such system that supports a LEAF board of
87           12x and 4x types would be to define two SYSTEMS:
88
89               SYSTEM LEAF,LEAF:4x,LEAF:4X
90
91               ...
92
93               SYSTEM LEAF:12x,LEAF:12X
94
95               ...
96
97               NOTE-3: The instantiations of the LEAF boards in another board
98               or the top system need not specify the postfix and are being
99               decided upon only when the topology file is being parsed. The
100               "SYSTEM LEAF" with no postfix will be used by default. To con‐
101               tinue the example here is how the LEAFs are instantiated in the
102               top system:
103
104                   TOPSYSTEM MyIbSystem
105
106                   LEAF leaf1
107
108                   ...
109
110                   LEAF leaf2
111
112                   ...
113
114               The actual 4x or 12x version of the LEAF board can then be
115               specified in the topology file CFG section to select the right
116               combination of optional boards in the system. An example will
117               be:
118
119                   MyIbSystem N001 CFG: leaf2=12x
120
121                   In this case leaf1 will be 4x as no special modifier is
122                   defined for it (and LEAF is by default a 4x leaf). Leaf2
123                   will be 12x as defined in the CFG section.
124
125               e)  Special considerations should be made to design the top
126                   system section when several optional board types exist. Top
127                   system section might include multiple definitions for front
128                   panel plugs like P1-4x and P1-12x (yes these are just names
129                   that should follow the writing on the front or back pan‐
130                   els). As the different flavors of the boards are not
131                   required to define the same names for their ports including
132                   a 12x port might leave some of the top level connections
133                   dangling (not connected) and thus the front panel ports of
134                   the other flavor will be removed from the final system def‐
135                   inition. As an example let us consider a simple board LEAF
136                   with 3 4x port flavor and one 12x port flavors. We recom‐
137                   mend connecting it in the top level using the following
138                   scheme:
139
140                       SYSTEM LEAF:4x
141
142                       NODE U1
143
144                       1 -4x-> 4XP1
145
146                       2 -4x-> 4XP2
147
148                       3 -4x-> 4XP3
149
150                       ...
151
152                       SYSTEM LEAF:12x
153
154                       NODE U1
155
156                       1 -12x-> 12XP1
157
158                       ...
159
160                       TOPSYSTEM myIbSystem
161
162                       SUBSYSTEM LEAF leaf1
163
164                       4XP1 -> L1/P1
165
166                       4XP2 -> L1/P2
167
168                       4XP3 -> L1/P3
169
170                       12XP1 -> L1/P1-12x
171
172                   f)  Place the file in the <prefix>/lib/IBDM/ibdm1.0/ibnl
173                       directory
174
175                   g)  Check the new file syntax by placing it in the ibnl
176                       directory as described above, creating a simple topol‐
177                       ogy (ibdm-topo-file file with one such system and run‐
178                       ning ibdmtr utility to parse it tracing a simple path
179                       through it.
180

4. Formal definition in YACC Syntax:

182       INT ::= ([1-9][0-9]*⎪0) ;
183
184       WIDTH ::= (4x⎪8x⎪12x) ;
185
186       SPEED ::= (2.5G⎪5G⎪10G) ;
187
188       NODETYPE ::= (SW⎪CA⎪HCA) ;
189
190       NAME ::= ([\[\]\\\*/A-Za-z0-9_.:%@~]+) ;
191
192       NL: LINE ⎪ NL LINE;
193
194       ONL: ⎪ NL;
195
196       ibnl: ONL systems topsystem;
197
198       systems: ⎪ systems system ;
199
200       sub_inst_attributes: ⎪ sub_inst_attributes sub_inst_attribute NL;
201
202       sub_inst_attribute: NAME '=' NAME '=' NAME ⎪ NAME '=' NAME '=' INT ⎪
203       NAME '=' NAME ;
204
205       topsystem: TOPSYSTEM system_names NL sub_inst_attributes insts ;
206
207       system: SYSTEM system_names NL insts ;
208
209       system_names: system_name ⎪ system_names ',' system_name ;
210
211       system_name: NAME ;
212
213       insts: ⎪ insts node ⎪ insts subsystem ;
214
215       node: node_header NL node_connections ;
216
217       node_header: NODE NODETYPE INT NAME NAME ;
218
219       node_connections: ⎪ node_connections node_connection NL ;
220
221       node_connection: node_to_node_link ⎪ node_to_port_link ;
222
223       node_to_node_link: INT '-' WIDTH '-' SPEED '-' '>' NAME ⎪ INT '-' WIDTH
224       '-' '>' NAME INT ⎪ INT '-' SPEED '-' '>' NAME INT ⎪ INT '-' '>' NAME
225       INT ;
226
227       node_to_port_link: INT '-' WIDTH '-' SPEED '-' '>' NAME ⎪ INT '-' WIDTH
228       '-' '>' NAME ⎪ INT '-' SPEED '-' '>' NAME ⎪ INT '-' '>' NAME ;
229
230       subsystem: subsystem_header NL subsystem_connections ;
231
232       subsystem_header: SUBSYSTEM NAME NAME ;
233
234       subsystem_connections: ⎪ subsystem_connections subsystem_connection NL
235       ;
236
237       subsystem_connection: subsystem_to_subsystem_link ⎪ subsys‐
238       tem_to_port_link ;
239
240       subsystem_to_subsystem_link: NAME '-' WIDTH '-' SPEED '-' '>' NAME NAME
241       ⎪ NAME '-' WIDTH '-' '>' NAME NAME ⎪ NAME '-' SPEED '-' '>' NAME NAME ⎪
242       NAME '-' '>' NAME NAME ;
243
244       subsystem_to_port_link: NAME '-' WIDTH '-' SPEED '-' '>' NAME ⎪ NAME
245       '-' WIDTH '-' '>' NAME ⎪ NAME '-' SPEED '-' '>' NAME ⎪ NAME '-' '>'
246       NAME ;
247

AUTHOR

249       Eitan Zahavi, Mellanox Technologies LTD, eitan@mellanox.co.il
250
251
252
253IBDM 1.0                          2008-06-16                 IBDM-IBNL-FILE(1)
Impressum