| |
 Examples |
| |
|
Refer to Getting Started for
information on how to build the following examples:
|
|
torc/examples/ArchitectureExample.cpp
|
|
The architecture API
example demonstrates basic use of the device
database. It begins by initializing a
DirectoryTree object with the invocation path of the
executable. The location of the executable
will serve as the reference point for all other
directories, and in particular for the "devices"
directory with all of its device databases.
A DeviceDesignator object is initialized for
convenience with a particular Virtex6 device,
package, and speed grade (the package and speed
grade being optional), which it parses.
Functions in the DeviceDesignator class allow access
to the family, device, package, and speed grade.
The device database object is then constructed,
using the designator object to determine which
device and package to load. The appropriate
database file is read from disk, and is used to
populate all wiring, logic, and package information
for the device.
Once the device database is initialized, the code
looks up a particular logic site, and then looks up
a particular site pin. That pin is returned as
a "tilewire," a numeric combination of a wire index
and a tile index, and is written to the
output. The arcs that can connect this wire to
other wires are output as well.
#include "torc/Architecture.hpp"
#include "torc/Common.hpp"
#include <iostream>
using namespace torc::common;
using namespace torc::architecture;
using namespace torc::architecture::xilinx;
int main(int argc, char* argv[]) {
// construct and initialize the device database
(void) argc;
DirectoryTree directoryTree(argv[0]);
DeviceDesignator designator("xc6vlx75tff484-1");
DDB ddb(designator);
// look up a site output and convert it to a tilewire
const Sites& sites = ddb.getSites();
SiteIndex index = sites.findSiteIndex("SLICE_X0Y119");
const Site& site = sites.getSite(index);
Tilewire pinTilewire = site.getPinTilewire("A");
std::cout << ddb << pinTilewire << std::endl;
// look up arcs that connect from this tilewire
ArcVector sinks;
ddb.expandSegmentSinks(pinTilewire, sinks);
ArcVector::const_iterator pos = sinks.begin();
ArcVector::const_iterator end = sinks.end();
while(pos < end)
std::cout << "\t" << *pos++ << std::endl;
return 0;
}
The tilewire is a lightweight encapsulation of an
integer that lacks any knowledge of the current
database. Its annotated output is made
possible because the code first inserted the
database object ddb into the output stream
("std::cout << ddb"). This insertion
only needs to be done one time per stream.
Without this insertion, the tilewire output would
simply be the combination of its tile and wire
indexes, for example "189@186".
WARNING: Need to check segment packing.
Reading device xc6vlx75t ("./torc/devices/xc6vlx75t.db")...
Database 1.0.0 build 2, Vendor "Release 12.2 - xdl M.63c (lin64)"
Reading family Virtex6 ("./torc/devices/Virtex6.db")...
Reading 96 tile types...
Reading wire info for 96 tile types...
Reading 3 speed grades (-3, -2, -1) ...
Reading 2 packages (ff484, ff784) ...
Reading tile map for 22733 tiles (127 rows x 179 columns)...
Reading 22733 tiles...
Reading 38074 segments...
1673499 total segments
Reading irregular arcs for 22733 tiles...
Reading 51 site types...
Reading 210 primitive pin maps...
Reading 22509 sites...
Read 2566212 bytes from Virtex6
Read 14450208 bytes from xc6vlx75t
CLBLM_M_A@[1,7] CLBLM "CLBLM_X1Y119" (189@186) OUTPUT
CLBLM_M_A@[1,7] CLBLM "CLBLM_X1Y119" (189@186) OUTPUT >> CLBLM_LOGIC_OUTS12@[1,7] CLBLM "CLBLM_X1Y119" (121@186)
CLBLM_M_A@[1,7] CLBLM "CLBLM_X1Y119" (189@186) OUTPUT >> CLBLM_M_AMUX@[1,7] CLBLM "CLBLM_X1Y119" (197@186) OUTPUT
|
|
torc/examples/BitstreamExample.cpp
|
|
The bitstream API
example reads a bitstream file specified on the
command line, determined the correct architecture,
reads and parses its packets into a new Bitstream
object (which is itself a vector of packets), and
writes those packets to the standard output.
#include "torc/Bitstream.hpp"
#include "torc/Common.hpp"
#include <fstream>
#include <iostream>
using namespace torc::common;
using namespace torc::bitstream;
int main(int argc, char* argv[]) {
// we need an input bitstream
if(argc != 2) {
std::cout << "Usage: " << argv[0] << " bitstream.bit" << std::endl;
exit(-1);
}
// read the bitstream
boost::filesystem::path bitstreamPath = argv[1];
BitstreamSharedPtr bitstreamPtr = Factory::newBitstreamPtr(bitstreamPath);
// write the bitstream digest to the console
std::cout << *bitstreamPtr << std::endl;
return 0;
}
After the bitstream has been read and parsed, the
bitstream object is "inserted" into the standard
output. An output helper class formats the
output as a sequence of bitstream packets, complete
with symbolic bit field constants.
Design VirtexUnitTest.reference.ncd (v50bg256) @ 2011/01/26 11:51:59: 69900 bytes (17475 words)
00000058: DUMMY
0000005c: SYNC
00000060: TYPE1 WRITE CMD RCRC
00000068: TYPE1 WRITE FLR: 0000000b
00000070: TYPE1 WRITE COR: 00803f2d (DonePipe:No, DriveDone:No, Capture:Continuous, ConfigRate:[UNKNOWN 2],
StartupClk:Cclk, LOCK_WAIT:1, SHUTDOWN:0, DONE_cycle:4, LCK_cycle:NoWait, GTS_cycle:5, GWE_cycle:6, GSR_cycle:6)
00000078: TYPE1 WRITE MASK: 00000000 (Security:Protected, Persist:Protected, GTS_USER_B:Protected)
00000080: TYPE1 WRITE CMD SWITCH
00000088: TYPE1 WRITE FAR: 00000000
00000090: TYPE1 WRITE CMD WCFG
00000098: TYPE1 WRITE FDRI: 00000000 words
0000009c: TYPE2 WRITE FDRI: 00003e04 words
0000f8b0: TYPE1 WRITE FAR: 02000000
0000f8b8: TYPE1 WRITE FDRI: 0000030c words
000104ec: TYPE1 WRITE FAR: 02020000
000104f4: TYPE1 WRITE FDRI: 00000300 words
000110f8: TYPE1 WRITE CRC: 000018fa
00011100: TYPE1 WRITE CMD LFRM
00011108: TYPE1 WRITE FDRI: 0000000c words
0001113c: TYPE1 WRITE CMD START
00011144: TYPE1 WRITE CTL: 00000000 (Security:None, Persist:No, GTS_USER_B:IoDisabled)
0001114c: TYPE1 WRITE CRC: 0000e15a
00011154: [UNKNOWN TYPE 0]
00011158: [UNKNOWN TYPE 0]
0001115c: [UNKNOWN TYPE 0]
00011160: [UNKNOWN TYPE 0]
Bitfield constants can also be initialized
symbolically for convenience, as is done in
torc/bitstream/VirtexBitstreamUnitTest.cpp.
|
|
torc/examples/GenericExample.cpp
|
|
The generic API
example reads an EDIF file, updates a property, and
writes the file back out. Like the other
examples, this one too begins by initializing the
DirectoryTree. The code then specifies the two
files it will work with, the first one already
existing in the regression directory, and the second
one to be used to output the modified design.
The code opens the reference file and imports the
EDIF design into its object model. It then
looks up a particular library, cell, and view, to
find an instance of interest. The INIT
property for that instance is changed from its
previous value of "8" to "6", effectively turning
this 2-input LUT from an AND gate into an XOR
gate. The code then opens the output file and
lets the exporter write out the resulting EDIF.
#include "torc/Generic.hpp"
#include "torc/Common.hpp"
#include <fstream>
#include <boost/regex.hpp>
using namespace std;
using namespace torc::generic;
int main(int argc, char* argv[]) {
// build the file paths
(void) argc;
torc::common::DirectoryTree directoryTree(argv[0]);
boost::filesystem::path referencePath = torc::common::DirectoryTree::getExecutablePath()
/ "regression" / "GenericExample.reference.edf";
boost::filesystem::path generatedPath = torc::common::DirectoryTree::getExecutablePath()
/ "regression" / "GenericExample.generated.edf";
// import the EDIF design
string inFileName = referencePath.string();
fstream fileStream(inFileName.c_str());
ObjectFactorySharedPtr factoryPtr(new ObjectFactory());
EdifImporter importer(factoryPtr);
importer(fileStream, inFileName);
// look up an instance of interest
RootSharedPtr rootPtr = importer.getRootPtr();
InstanceSharedPtr instancePtr = rootPtr->findLibrary("work")->findCell("and")
->findView("verilog")->findInstance("oZ0");
// change the INIT property (LUT mask) to XOR
PropertySharedPtr initPropertyPtr = instancePtr->getProperty("INIT");
string originalMask = initPropertyPtr->getValue().get<Value::String>();
std::cout << "The original LUT mask was \"" << originalMask << "\"." << std::endl;
Value xorMask(Value::eValueTypeString, string("6"));
initPropertyPtr->setValue(xorMask);
// export the EDIF design
string outFileName = generatedPath.string();
fstream edifExport(outFileName.c_str(), ios_base::out);
EdifExporter exporter(edifExport);
exporter(rootPtr);
return 0;
}
This example generates little console output, but
its effects can be seen with the following diff
command:
diff regression/GenericExample.reference.edf regression/GenericExample.generated.edf
The expected output is:
47c47
< (property INIT (string "8"))
---
> (property INIT (string "6"))
|
|
torc/examples/PhysicalExample.cpp
|
|
The physical API
example reads in an XDL file that must be specified
by the user, looks up the design root, and simply
writes the design back out. (A few XDL files
are available in the regression directory.)
Because the input file is specified on the command
line, there is no need to create and initialize a
DirectoryTree object in this example. The code
opens the input file, and then imports all of the
XDL into its object mode. The root of that
object model is obtained from the importer, and can
be used to traverse or manipulate anything in the
design.
Even though no changes are made to the design in
this example, the code is written back out with a
different extension.
#include "torc/Physical.hpp"
#include <fstream>
/// \brief Standard main() function.
int main(int argc, char* argv[]) {
// import the XDL design
if(argc < 2) return 0;
std::string inFileName(argv[1]);
std::fstream fileStream(inFileName.c_str());
if(!fileStream.good()) return -1;
torc::physical::XdlImporter importer;
importer(fileStream, inFileName);
// look up the design (and do something with it ...)
torc::physical::DesignSharedPtr designPtr = importer.getDesignPtr();
// export the XDL design
std::string outFileName = boost::filesystem::path(inFileName).replace_extension().string()
+ ".mod.xdl";
std::fstream xdlExport(outFileName.c_str(), std::ios_base::out);
torc::physical::XdlExporter fileExporter(xdlExport);
fileExporter(designPtr);
return 0;
}
Note that there is a subclass of
torc::physical::XdlImporter named
torc::architecture::XdlImporter. The
architecture-aware importer identifies the design
device, initializes the corresponding device
database, and populates all wire usage
information. Code like that in the example
above, based on torc::architecture::XdlImporter,
could serve as the basis for a stand-alone XDL
router or placer.
This example generates no console output.
Modifications to the design are left as an exercise
to the reader.
|
|
| torc/examples/EdifObfuscator.cpp |
|
The EDIF obfuscator
example reads an EDIF file specified by the user,
and replaces all possible names and identifiers with
MD5 hashes. Names and identifiers that are not
replaced include those in any vendor libraries, as
well as those belonging to the design's top-level
ports.
The sample output below shows a simple EDIF design
after obfuscation. The vendor VIRTEX library
is not obfuscated, nor are the top-level ports of
the design (the "and" cell in this case).
(edif (rename and "AND")
(edifVersion 2 0 0)
(edifLevel 0)
(keywordMap (keywordLevel 0))
(library VIRTEX
(ediflevel 0) (technology (numberDefinition))
(cell LUT2
(cellType GENERIC)
(view PRIM
(viewType NETLIST)
(interface
(port I0
(direction INPUT)
)
(port I1
(direction INPUT)
)
(port O
(direction OUTPUT)
)
)
)
)
)
(library work
(ediflevel 0) (technology (numberDefinition))
(cell
(rename and "AND")
(cellType GENERIC)
(view verilog
(viewType NETLIST)
(interface
(port i0
(direction INPUT)
)
(port i1
(direction INPUT)
)
(port o
(direction OUTPUT)
)
)
(contents
(instance icfcd208495d565ef66e7dff9f98764da
(viewRef PRIM (cellRef LUT2 (libraryRef VIRTEX)))
(property INIT (string ))
)
(net ic4ca4238a0b923820dcc509a6f75849b
(joined
(portRef i0)
(portRef I0 (instanceRef icfcd208495d565ef66e7dff9f98764da))
)
)
(net ic81e728d9d4c2f636f067f89cc14862c
(joined
(portRef i1)
(portRef I1 (instanceRef icfcd208495d565ef66e7dff9f98764da))
)
)
(net ieccbc87e4b5ce2fe28308fd9f2a7baf3
(joined
(portRef o)
(portRef O (instanceRef icfcd208495d565ef66e7dff9f98764da))
)
)
)
)
)
)
(design (rename and "AND") (cellRef and (libraryRef work))
(property PART (string "xc5vlx30ff324-1")
(owner "Xilinx"))
)
)
|
|
|
