How to read an NCD file

Sometimes we end up with two versions of the same design, where one works and one doesn’t work. If the code is the same, typically the problem is in placement of your primitives. In this case we would like to compare the two designs at a to find out what exactly has changed in the placements.

This is where reading the NCD file (the Native Circuit Description file) can be useful. The NCD file is the product of PAR and the file used by bitgen to generate the bitstream.

My preferred method for checking out the NCD file is using FPGA Editor, but you can also read the file directly if for example you wanted a script to do the work. The NCD file is not a readable file, but Xilinx has provided a tool for converting it into a readable file: XDL.

If you run a command prompt and type “xdl” you get the following message:

Release 12.1 - xdl M.53d (nt)
Xdl is a single tool with 3 fundamental modes:
* Report Device Resource Information
* Convert NCD to XDL (ncd2xdl)
* Convert XDL to NCD (xdl2ncd)
Report generates a report of the physical resources
available for a specific part.
Ncd2xdl reads in an NCD file and generates an ASCII XDL file.
Xdl2ncd reads in an XDL file and generates an NCD file.
XDL is also a fully featured Physical Design language that
Native Circuit Description (NCD). This access enables all
users to write tools to address their individual FPGA
design needs.
To find out the switches available for each mode, enter the
mode switch and the -h switch as shown in the examples below:
% xdl -h -report
% xdl -h -ncd2xdl
% xdl -h -xdl2ncd
To find out which parts are available, run partgen as follows:
% partgen -i
% partgen -i -arch virtex


As you get from the message, to convert an NCD file to readable ASCII (XDL) file, you should type: xdl -ncd2xdl filename.ncd

where filename.ncd is the filename of your NCD file. The resulting XDL file will have the same filename but with .xdl as the extension. It can be a hundred or more megabytes so don’t expect just any editor to be able to open it.

Another useful option of the XDL tool is conversion from XDL file back to NCD, which you could then use to generate a bitstream with bitgen. The reason you would do this is if you had some small modifications to make to the design and you didn’t want to go through building the entire project from scratch again.

Here is the help message for the NCD2XDL option:

Release 12.1 - xdl M.53d (nt)
Usage: xdl.exe [-ncd2xdl] [-nopips] [-noformat] [-nw] [-force_cfg] <ncdfile> [<x
dlfile>]
Parameters:
<ncdfile> The input NCD file. If the .ncd extension is
not specified, it is appended automatically.
<xdlfile> The output XDL file. If the <xdlfile> is not
specified, the file name is created from the
<ncdfile> name by replacing the .ncd extension
with a .xdl extension.
Switches:
-ncd2xdl      Mode specifier.
-noformat     Don't format the report for readability.
-nopips       Don't report pips.
-nw           Don't allow overwriting of an existing XDL file.
-force_cfg    Force the display of config strings. The config
strings have removed the equations and RAM
initialization data. Depending on the level of
core security associated with the design and the
individual blocks the results could vary.
You cannot recreate a valid ncd from this xdl.
Sample Usage:
% xdl -ncd2xdl design
% xdl -ncd2xdl design.ncd
% xdl -ncd2xdl design.ncd design.xdl
% xdl -ncd2xdl -noformat design.ncd design.xdl
% xdl -ncd2xdl -nopips design.ncd design.xdl


Here is the help message for the XDL2NCD option:

Release 12.1 - xdl M.53d (nt)
Usage: xdl.exe [-xdl2ncd] [-force] [-nopips] <xdlfile> [<ncdfile>]
Parameters:
<xdlfile> The input XDL file. If the .xdl extension is
not specified, it is appended automatically.
<ncdfile> The output NCD file. If the <ncdfile> is not
specified, the file name is created from the
<xdlfile> name by replacing the .xdl extension
with a .ncd extension.
Switches:
-force    Force NCD creation in spite of DRC errors.
-nopips   Omit PIP routing information.
-xdl2ncd  Mode specifier.
Sample Usage:
% xdl -xdl2ncd foo.ncd
% xdl -xdl2ncd foo.ncd bar.xdl
% xdl -xdl2ncd foo bar
% xdl -xdl2ncd -force foo bar
% xdl -xdl2ncd -nopips foo bar