docs/wiki/geda-icarus_xnf.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   2  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html>
   4 <head>
   5   <link rel="stylesheet" media="screen" type="text/css" href="./style.css" />
   6   <link rel="stylesheet" media="screen" type="text/css" href="./design.css" />
   7   <link rel="stylesheet" media="print" type="text/css" href="./print.css" />
   8
   9   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  10 </head>
  11 <body>
  12
  13 <h1 id="xilinxnetlistformat">Xilinx Netlist Format</h1>
  14 <div class="level1">
  15 <pre class="code">WHAT IS XNF
  16
  17 XNF is the Xilinx Netlist Format. This is somewhat specific to the
  18 Xilinx tool chain, but it is sufficiently ubiquitous that it&#039;s still
  19 worth it. This format can be fed to place and route tools and
  20 simulators. Since some third party simulators accept XNF, the format
  21 may be useful even independent of Xilinx parts.
  22
  23 Icarus Verilog supports XNF as specified by the Xilinx Netlist Format
  24 Specification, Version 6.1.
  25
  26 GENERATE XNF OUTPUT -- THE SHORT STORY
  27
  28 The easiest way to compile for XNF output is with the &quot;verilog&quot;
  29 command (man verilog) and the -X switch:
  30
  31         % iverilog -fpart=4010e -fncf=prog.ncf -txnf prog.v
  32
  33 This generates from the prog.v Verilog source file the prog.xnf output
  34 and the prog.ncf netlist constraints file. The verilog program
  35 arranges to call the preprocessor and the ivl compiler with all the
  36 correct switches for generating XNF.
  37
  38 GENERATING XNF MACROS
  39
  40 Icarus Verilog can be used to generate XNF implementations of devices
  41 that are written in Verilog and used by schematic editors such as
  42 OrCAD. The trick here is that the code generator automatically notices
  43 ports to the root module and generates the PIN= attributes needed so
  44 that external tools can link to the generated XNF.
  45
  46 Icarus Verilog chooses a name for the pin. The name it chooses is the
  47 port name of the module. If the port is a vector, a pin is generated
  48 for all the bits of the vector with the bit number appended. For
  49 example:
  50
  51         module foo(in);
  52         input [3:0] in;
  53
  54 causes the single bit ports ``in0&#039;&#039; through ``in3&#039;&#039; be
  55 generated. Internally, the XNF file uses the bussed names instead of
  56 the pin name.
  57
  58 The implication of this is that there is a chance of name collision
  59 with the generated XNF macro if the port names are chosen badly. It is
  60 best to not end a port name with decimal digits, as that can cause
  61 trouble at link time. Also, XNF is not case sensitive and that should
  62 be accounted for as well.
  63
  64 XNF PADS IN VERILOG SOURCE
  65
  66 You can assign wires to pads using the Icarus Verilog $attribute
  67 extension. Attach to a scalar signal (wire or register) the PAD
  68 attribute with the value that specifies the direction and pin
  69 number. For example:
  70
  71         wire foo, bar, bid;
  72         $attribute(foo, &quot;PAD&quot;, &quot;i1&quot;); // Input pad on pin 1
  73         $attribute(bar, &quot;PAD&quot;, &quot;o2&quot;); // Output pad on pin 2
  74         $attribute(bid, &quot;PAD&quot;, &quot;b3&quot;); // Bi-directional pad on pin 3
  75
  76 The XNFIO function uses these attributes to locate signals that are
  77 connected to pads, and generates XNF I/O block devices to connect to
  78 the pad to do the FPGA pin buffering that is needed. So the Verilog
  79 programmer need not in general specify the IBUF/OBUF buffers.
  80
  81 If the programmer does connect buffers to pads, the compiler will
  82 notice them and convert them to I/OBUFs automatically. For example:
  83
  84         buf b1 (sig, foo);
  85
  86 connects to pad foo, so will be converted into an XNF IBUF
  87 device. Also:
  88
  89         bufif1 bt (bar, value, en);
  90
  91 connects to pad bar so will automatically be converted into an OBUFT
  92 device. Icarus Verilog understands OBUF, IBUF and OBUFT (with optionally
  93 inverted enable) devices and will convert Verilog devices from the
  94 source, or generate missing devices.
  95
  96 In addition, the Verilog programmer may explicitly declare a device as
  97 an I/OBUF by attaching an attribute to the device, like so:
  98
  99         buf b1 (sig, foo);
 100         $attribute(b1, &quot;XNF-LCA&quot;, &quot;OBUF:O,I&quot;);
 101
 102 This latter feature is not entirely recommended as it expects that the
 103 programmer really knows how the pins of the XNF device are to be
 104 connected. It also bypasses the efforts of the compiler, so is not
 105 checked for correctness.
 106
 107 XNF STORAGE ELEMENTS
 108
 109 Storage elements in XNF include flip-flops, latches and CLB
 110 rams. These devices are generated from the LPM equivalents that the
 111 -Fsynth functor synthesizes from behavioral descriptions.
 112
 113 Flip-flops, or more specifically DFF devices, are generated to
 114 implement behavioral code like this:
 115
 116         reg Q;
 117         always @(posedge clk) Q &lt;= &lt;expr&gt;;
 118
 119 The edge can be positive or negative, and the expression can be any
 120 synthesizable expression. Furthermore, the register &quot;Q&quot; can have
 121 width, which will cause the appropriate number of flip-flops to be
 122 created. A clock enable expression can also be added like so:
 123
 124         reg Q;
 125         always @(posedge clk) if (&lt;ce&gt;) Q &lt;= &lt;expr&gt;;
 126
 127 The &lt;ce&gt; expression can be any synthesizable expression.
 128
 129 With or without the CE, the generated DFF devices are written into the
 130 XNF output one bit at a time, with the clock input inverted if necessary.
 131
 132 Xilinx parts also support CLB circuitry as synchronous RAMS. These
 133 devices are created from Verilog memories if the properties are
 134 right. The behavioral description that the -Fsynth functor matches to
 135 get a synchronous RAM looks very similar to that for a DFF:
 136
 137         reg [15:0] M;
 138         always @(posedge clk) if (&lt;we&gt;) M[&lt;addr&gt;] &lt;= &lt;expr&gt;;
 139
 140 Note that in this case the l-value of the assignment is an addressed
 141 memory. This statement models writes into the memory. Reads from the
 142 device can be modeled with ordinary structural code, i.e.:
 143
 144         assign foo &lt;= M[&lt;addr&gt;];
 145
 146 For the memory to be synthesizable in the XNF target, the address
 147 lines for writes and reads must be connected. This corresponds to the
 148 limitations of the real hardware.
 149
 150 OTHER XNF SPECIAL DEVICES
 151
 152 There are certain special devices in XNF that Verilog does not
 153 naturally represent, although there are similar more generic Verilog
 154 devices. The most obvious and useful example is the clock driver,
 155 otherwise known as the global buffer BUFG. As with pads, Icarus
 156 Verilog uses the $attribute extension to allow you to specify special
 157 devices.
 158
 159 The $attribute statement can be applied to devices much the same way
 160 one applies them to wires. For example, to turn a buffer into a clock
 161 buffer:
 162
 163         wire iclk, clk;
 164         buf BUFG (clk, iclk);
 165         $attribute(iclk, &quot;PAD&quot;, &quot;i1&quot;);
 166         $attribute(BUFG, &quot;XNF-LCA&quot;, &quot;BUFG:O,I&quot;);
 167
 168 The above statements cause the buffer BUFG to be emitted in the XNF
 169 output as a BUFG device with the first signal called &quot;O&quot; and the
 170 second called &quot;I&quot;. The rest of this example connects the input of the
 171 BUFG to a signal from the input pin #1 and connects the output to the
 172 internal wire &quot;clk&quot;. Incidentally, this example will cause an IBUF to
 173 be generated to connect the iclk signal to input pin #1.
 174
 175 SUMMARY OF IVL SUPPORT FOR XNF
 176
 177 Icarus Verilog has a code generator and synthesis functions that
 178 support generation of XNF netlists. The XNF modules also allow the
 179 programmer to use $attributes to control certain aspects of code
 180 generation.
 181
 182 XNF code generation is enabled with the ``-t xnf&#039;&#039; flag on the command
 183 line. The code generator needs to know the type of part to generate
 184 code for, so the ``-fpart=&lt;type&gt;&#039;&#039; flag is also needed. For example,
 185 to generate code for the 4010E the command line might start out as:
 186
 187          ivl -txnf -fpart=4010e -Fsynth -Fnodangle -Fxnfio [...]
 188
 189 Icarus Verilog includes the functions ``synth&#039;&#039; and ``xnfio&#039;&#039; to
 190 perform transformations and optimizations on the design before code is
 191 generated. The ``synth&#039;&#039; function matches certain behavioral constructs
 192 to structural components, and the xnfio function generates pads and
 193 fills the IOBs.
 194
 195 SUPPORTED FLAGS
 196
 197     -fpart=&lt;part&gt;
 198         Specify the type of part to target. This string is written
 199         literally into the PART, record of the XNF, and may also be
 200         used to control synthesis and placement.
 201
 202     -fncf=&lt;path&gt;
 203         Cause the code generator to write into &lt;path&gt; the netlist
 204         constraints needed for controlling placement and timing. This
 205         switch is required if pin assignments are assigned in the
 206         Verilog source.
 207
 208 THE SYNTH FUNCTION
 209
 210 This function does synthesis transformations on the entered design,
 211 making it possible to generate XNF netlist components from certain
 212 behavioral constructs. This is needed in Verilog for example to model
 213 some of the synchronous components of the XNF library.
 214
 215 It is a bit much to expect a Verilog compiler in general to generate
 216 components from arbitrary behavioral descriptions, so the synth
 217 function works by matching statements that have some documented
 218 structure, and substituting them for the equivalent XNF component. A
 219 fully synthesize-able design, then, is one where the behavioral
 220 statements can all be matched and substituted by the synth function.
 221
 222 THE XNFIO FUNCTION
 223
 224 The &quot;xnfio&quot; function transforms the netlist where the IOBs are
 225 concerned. The signals with PAD attributes are checked, and
 226 surrounding circuitry generated to conform to the logic available in
 227 the IOB.
 228
 229 If the pad is an OPAD, the function will look for an existing buf or
 230 not gate connected to the PAD signal. If the gate is appropriately
 231 connected, the buf or not gate will be turned into an OBUF. This pulls
 232 the buf or inverter into the IOB, freeing a CLB and providing the
 233 required pin circuitry.
 234
 235 If the pad is an IPAD, the function will look for a buf, and convert
 236 that to an IBUF. Since Xilinx IOBs cannot invert the output from an
 237 IBUF, NOT gates cannot be absorbed as in the OPAD case.
 238
 239
 240 /*
 241  * Copyright (c) 1998-1999 Stephen Williams (steve@icarus.com)
 242  *
 243  *    This source code is free software; you can redistribute it
 244  *    and/or modify it in source code form under the terms of the GNU
 245  *    General Public License as published by the Free Software
 246  *    Foundation; either version 2 of the License, or (at your option)
 247  *    any later version.
 248  *
 249  *    This program is distributed in the hope that it will be useful,
 250  *    but WITHOUT ANY WARRANTY; without even the implied warranty of
 251  *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 252  *    GNU General Public License for more details.
 253  *
 254  *    You should have received a copy of the GNU General Public License
 255  *    along with this program; if not, write to the Free Software
 256  *    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 257  */
 258
 259
 260  $Log: xnf.txt,v $
 261  Revision 1.16  2003/07/15 03:49:22  steve
 262   Spelling fixes.
 263
 264  Revision 1.15  2003/01/30 16:23:08  steve
 265   Spelling fixes.
 266
 267  Revision 1.14  2000/08/01 21:32:40  steve
 268   Use the iverilog command in documentation.
 269
 270  Revision 1.13  2000/08/01 02:48:42  steve
 271   Support &lt;= in synthesis of DFF and ram devices.
 272
 273  Revision 1.12  2000/07/25 22:49:32  steve
 274   memory is not a data type in verilog.
 275
 276  Revision 1.11  2000/04/23 23:03:13  steve
 277   automatically generate macro interface code.
 278
 279  Revision 1.10  1999/12/05 19:30:43  steve
 280   Generate XNF RAMS from synthesized memories.
 281
 282  Revision 1.9  1999/11/18 03:52:20  steve
 283   Turn NetTmp objects into normal local NetNet objects,
 284   and add the nodangle functor to clean up the local
 285   symbols generated by elaboration and other steps.
 286
 287  Revision 1.8  1999/11/06 04:51:42  steve
 288   Support writing some XNF things into an NCF file.
 289
 290  Revision 1.7  1999/11/03 05:18:18  steve
 291   XNF synthesis now uses the synth functor.
 292
 293  Revision 1.6  1999/11/02 01:43:55  steve
 294   Fix iobuf and iobufif handling.
 295
 296  Revision 1.5  1999/10/09 17:52:27  steve
 297   support XNF OBUFT devices.
 298
 299  Revision 1.4  1999/08/14 22:48:21  steve
 300   Mention the sigfold function.
 301
 302  Revision 1.3  1999/07/22 02:05:20  steve
 303   is_constant method for PEConcat.
 304
 305  Revision 1.2  1999/07/18 21:17:51  steve
 306   Add support for CE input to XNF DFF, and do
 307   complete cleanup of replaced design nodes.
 308
 309  Revision 1.1  1999/05/01 02:57:11  steve
 310   XNF target documentation.</pre>
 311
 312 </div>
 313 </body>
 314 </html>