.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "IBDM-IBNL-FILE 1"
.TH IBDM-IBNL-FILE 1 "2008-06-16" "IBDM 1.0" "IB DATA MODEL PACKAGE"
.SH "NAME"
\&\fBibnl\fR \- a generic IB netlist format
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\s-1IBDM\s0 topology file \fBibdm-topo-file\fR provide means to describe the \s-1IB\s0 fabric using a set of predefined systems. A system definition is provided in a single file in \s-1IBNL\s0 format that describes the internal InfiniBand connectivity of the system in terms of boards and devices. When \s-1IBDM\s0 starts it parses all the available system definition files before it handles the topology file. The files are located in the following directory relative to the installation prefix: <prefix>/lib/ibdm1.0/ibnl.
.PP
This man page describes the \s-1IBNL\s0 file format used to define an arbitrary \s-1IB\s0 system internal \s-1IB\s0 connectivity. It outlines the main concepts used by the file, provides details for how to write such a file and provides a formal definition of the file syntax in \s-1BNF\s0 like format (YACC/Bison readable).
.SH "1. Main Concepts"
.IX Header "1. Main Concepts"
The described file format for defining generic system \s-1IB\s0 connectivity uses the following terminology:
.IP "\s-1NODE\s0" 4
.IX Item "NODE"
The instantiation of an \s-1IB\s0 device may it be a switch or a channel adapter
.IP "SUB-SYSTEM" 4
.IX Item "SUB-SYSTEM"
The instantiation of a board or module in a system
.IP "\s-1SYSTEM\s0" 4
.IX Item "SYSTEM"
A definition of a board or a module
.IP "\s-1TOPSYSTEM\s0" 4
.IX Item "TOPSYSTEM"
The top most system defined in the given file
.IP "SUB-SYSTEM \s-1MODIFIER\s0" 4
.IX Item "SUB-SYSTEM MODIFIER"
Many systems allow multiple variations of their subsystem such as a 12X version of a leaf board in a \s-1MTS9600\s0. The modifier is a suffix to the board name. The \s-1IBNL\s0 format supports assigning multiple names to the same board.
.SH "2. File Format"
.IX Header "2. File Format"
The exact file format is provided in section 4. This section only provides extra information regarding the specific semantics of various sections.
.PP
The \s-1IBNL\s0 file is line sensitive as it requires different sections to start on a new line. The file is broken into several \s-1SYSTEM\s0 (optional) and one \s-1TOPSYSTEM\s0 sections. Each has one or more names.
.PP
Connections are defined inside the \s-1SYSTEM/TOPSYSTEM\s0 section only and thus might be of two types:
.IP "1. Between any node or sub-system to other node or sub-system" 4
.IX Item "1. Between any node or sub-system to other node or sub-system"
.PD 0
.IP "2. From any node or sub-system to a connector of the system." 4
.IX Item "2. From any node or sub-system to a connector of the system."
.PD
.PP
\&\s-1NOTE\-1:\s0 The top system can define ports that might be redundant and not connected to any lower level board connector. In these cases the ports are simply omitted from the resulting system. This feature enables defining the front panel ports of a 12X/4X such that if a 12X leaf is selected only the 12X front panel ports are used.
.PP
\&\s-1NOTE\-2:\s0  Port width and speed provided at the lowest level have precedence over definitions provided at upper levels of the hierarchy.
.SH "3. Guidelines for writing a System IBNL File"
.IX Header "3. Guidelines for writing a System IBNL File"
The following procedure should be followed in order to provide a new system \s-1IBNL:\s0
.IP "a)" 4
Name the file after the system name: <any sys name (no spaces)>.ibnl
.IP "b)" 4
Define a \s-1SYSTEM\s0 section for each board included in the system
.IP "c)" 4
The port names of the boards are just strings, we use the simple format of Pn where N is just a serial number but you can pick any name you want. Just make sure it is unique.
.IP "d)" 4
When different flavors of the boards exists like when you have a 4x and 12x option for a board name the optional boards with a modifier postfix. An example for such system that supports a \s-1LEAF\s0 board of 12x and 4x types would be to define two \s-1SYSTEMS:\s0
.RS 4
.Sp
.RS 4
\&\s-1SYSTEM\s0 \s-1LEAF\s0,LEAF:4x,LEAF:4X
.Sp
\&...
.Sp
\&\s-1SYSTEM\s0 LEAF:12x,LEAF:12X
.Sp
\&...
.Sp
\&\s-1NOTE\-3:\s0 The instantiations of the \s-1LEAF\s0 boards in another board or the top system need not specify the postfix and are being decided upon only when the topology file is being parsed. The \*(L"\s-1SYSTEM\s0 \s-1LEAF\s0\*(R" with no postfix will be used by default. To continue the example here is how the LEAFs are instantiated in the top system:
.Sp
.RS 4
\&\s-1TOPSYSTEM\s0 MyIbSystem
.Sp
\&\s-1LEAF\s0 leaf1
.Sp
\&...
.Sp
\&\s-1LEAF\s0 leaf2
.Sp
\&...
.RE
.RE
.RS 4
.Sp
The actual 4x or 12x version of the \s-1LEAF\s0 board can then be specified in the topology file \s-1CFG\s0 section to select the right combination of optional boards in the system. An example will be:
.Sp
.RS 4
MyIbSystem N001 \s-1CFG:\s0 leaf2=12x
.Sp
In this case leaf1 will be 4x as no special modifier is defined for it (and \s-1LEAF\s0 is by default a 4x leaf). Leaf2 will be 12x as defined in the \s-1CFG\s0 section.
.RE
.IP "e)" 4
Special considerations should be made to design the top system section when several optional board types exist. Top system section might include multiple definitions for front panel plugs like P1\-4x and P1\-12x (yes these are just names that should follow the writing on the front or back panels). As the different flavors of the boards are not required to define the same names for their ports including a 12x port might leave some of the top level connections dangling (not connected) and thus the front panel ports of the other flavor will be removed from the final system definition. As an example let us consider a simple board \s-1LEAF\s0 with 3 4x port flavor and one 12x port flavors. We recommend connecting it in the top level using the following scheme:
.RS 4
.Sp
.RS 4
\&\s-1SYSTEM\s0 LEAF:4x
.Sp
\&\s-1NODE\s0 U1
.Sp
1 \-4x\-> 4XP1
.Sp
2 \-4x\-> 4XP2
.Sp
3 \-4x\-> 4XP3
.Sp
\&...
.Sp
\&\s-1SYSTEM\s0 LEAF:12x
.Sp
\&\s-1NODE\s0 U1
.Sp
1 \-12x\-> 12XP1
.Sp
\&...
.Sp
\&\s-1TOPSYSTEM\s0 myIbSystem
.Sp
\&\s-1SUBSYSTEM\s0 \s-1LEAF\s0 leaf1
.Sp
4XP1 \-> L1/P1
.Sp
4XP2 \-> L1/P2
.Sp
4XP3 \-> L1/P3
.Sp
12XP1 \-> L1/P1\-12x
.RE
.RE
.RS 4
.IP "f)" 4
Place the file in the <prefix>/lib/IBDM/ibdm1.0/ibnl directory
.IP "g)" 4
Check the new file syntax by placing it in the ibnl directory as described above, creating a simple topology (\fBibdm-topo-file\fR file with one such system and running \fBibdmtr\fR utility to parse it tracing a simple path through it.
.SH "4. Formal definition in YACC Syntax:"
.IX Header "4. Formal definition in YACC Syntax:"
\&\s-1INT\s0 ::= ([1\-9][0\-9]*|0) ;
.Sp
\&\s-1WIDTH\s0 ::= (4x|8x|12x) ;
.Sp
\&\s-1SPEED\s0 ::= (2.5G|5G|10G) ;
.Sp
\&\s-1NODETYPE\s0 ::= (SW|CA|HCA) ;
.Sp
\&\s-1NAME\s0 ::= ([\e[\e]\e\e\e*/A\-Za\-z0\-9_.:%@~]+) ;
.Sp
\&\s-1NL:\s0
\&\s-1LINE\s0
| \s-1NL\s0 \s-1LINE\s0;
.Sp
\&\s-1ONL:\s0
| \s-1NL\s0;
.Sp
ibnl: \s-1ONL\s0 systems topsystem;
.Sp
systems:
| systems system ;
.Sp
sub_inst_attributes:
| sub_inst_attributes sub_inst_attribute \s-1NL\s0;
.Sp
sub_inst_attribute:
\&\s-1NAME\s0 '=' \s-1NAME\s0 '=' \s-1NAME\s0
| \s-1NAME\s0 '=' \s-1NAME\s0 '=' \s-1INT\s0
| \s-1NAME\s0 '=' \s-1NAME\s0 ;
.Sp
topsystem:
\&\s-1TOPSYSTEM\s0 system_names \s-1NL\s0 sub_inst_attributes insts ;
.Sp
system:
\&\s-1SYSTEM\s0 system_names \s-1NL\s0 insts ;
.Sp
system_names:
system_name
| system_names ',' system_name ;
.Sp
system_name:
\&\s-1NAME\s0 ;
.Sp
insts:
| insts node
| insts subsystem ;
.Sp
node:
node_header \s-1NL\s0 node_connections ;
.Sp
node_header:
\&\s-1NODE\s0 \s-1NODETYPE\s0 \s-1INT\s0 \s-1NAME\s0 \s-1NAME\s0 ;
.Sp
node_connections:
| node_connections node_connection \s-1NL\s0 ;
.Sp
node_connection:
node_to_node_link
| node_to_port_link ;
.Sp
node_to_node_link:
\&\s-1INT\s0 '\-' \s-1WIDTH\s0 '\-' \s-1SPEED\s0 '\-' '>' \s-1NAME\s0
| \s-1INT\s0 '\-' \s-1WIDTH\s0 '\-' '>' \s-1NAME\s0 \s-1INT\s0
| \s-1INT\s0 '\-' \s-1SPEED\s0 '\-' '>' \s-1NAME\s0 \s-1INT\s0
| \s-1INT\s0 '\-' '>' \s-1NAME\s0 \s-1INT\s0 ;
.Sp
node_to_port_link:
\&\s-1INT\s0 '\-' \s-1WIDTH\s0 '\-' \s-1SPEED\s0 '\-' '>' \s-1NAME\s0
| \s-1INT\s0 '\-' \s-1WIDTH\s0 '\-' '>' \s-1NAME\s0
| \s-1INT\s0 '\-' \s-1SPEED\s0 '\-' '>' \s-1NAME\s0
| \s-1INT\s0 '\-' '>' \s-1NAME\s0 ;
.Sp
subsystem:
subsystem_header \s-1NL\s0 subsystem_connections ;
.Sp
subsystem_header:
\&\s-1SUBSYSTEM\s0 \s-1NAME\s0 \s-1NAME\s0 ;
.Sp
subsystem_connections:
| subsystem_connections subsystem_connection \s-1NL\s0 ;
.Sp
subsystem_connection:
subsystem_to_subsystem_link
| subsystem_to_port_link ;
.Sp
subsystem_to_subsystem_link:
\&\s-1NAME\s0 '\-' \s-1WIDTH\s0 '\-' \s-1SPEED\s0 '\-' '>' \s-1NAME\s0 \s-1NAME\s0
| \s-1NAME\s0 '\-' \s-1WIDTH\s0 '\-' '>' \s-1NAME\s0 \s-1NAME\s0
| \s-1NAME\s0 '\-' \s-1SPEED\s0 '\-' '>' \s-1NAME\s0 \s-1NAME\s0
| \s-1NAME\s0 '\-' '>' \s-1NAME\s0 \s-1NAME\s0 ;
.Sp
subsystem_to_port_link:
\&\s-1NAME\s0 '\-' \s-1WIDTH\s0 '\-' \s-1SPEED\s0 '\-' '>' \s-1NAME\s0
| \s-1NAME\s0 '\-' \s-1WIDTH\s0 '\-' '>' \s-1NAME\s0
| \s-1NAME\s0 '\-' \s-1SPEED\s0 '\-' '>' \s-1NAME\s0
| \s-1NAME\s0 '\-' '>' \s-1NAME\s0 ;
.SH "AUTHOR"
.IX Header "AUTHOR"
Eitan Zahavi, Mellanox Technologies \s-1LTD\s0, eitan@mellanox.co.il