| |
 Getting
Started
|
| |
|
To use Torc, it is first necessary to download
the virtual machine image, or check out a working copy of
the Subversion repository, as discussed here.
The virtual machine image is available as an OVA file,
compatible with VirtualBox, VMware, and other virtualization
engines. It comes preconfigured with Torc, Boost, and
GCC, for easy exploration and startup.
|
| Requirements |
|
Torc currently has the
following requirements:
- GCC
4.2.1 or later
- Boost
1.42 or later
- 3 GB of disk space (not necessary for user
executables)
Torc releases are tested under these and other environments:
- CentOS 5.6, gcc 4.2.1, Boost 1.42
- OS X 10.6 Server, gcc 4.6.1, Boost 1.46.1
- RHEL (Red Hat) Server 5.7, gcc 4.2.4, Boost 1.42
- Ubuntu 10.04.2 LTS, gcc 4.2.1, Boost 1.42
- Windows 7 (Cygwin), gcc 4.5.3, Boost 1.46.1
GCC and Boost must be installed and available before any
Torc code can be built. If you are working from the
virtual machine image, these tools are preinstalled.
A full list of tested build configurations can be found here.
|
| Building
the Code |
|
Torc is
most easily built in a Linux-like environment. Xcode
and Eclipse projects are included as a convenience for
building and exploring the code.
The top-level Makefile resides in the src directory.
Use the following commands to start the build process:
The first time you build Torc you will see a message stating
that BOOST_INCLUDE_DIR and BOOST_LIB_DIR must be set prior
to compiling Torc. These can be set on the
commandline, as environment variables, or editing the
Makefile.local file that is automatically generated when you
first type 'make' in the src directory. For issues
with building Torc see the FAQ.
These commands will compile and link the unit test
application and the example executables. All of the
remaining steps will take place in the src directory.
|
Example
Executables
|
|
The example
executables provide basic demonstrations of the four
main APIs: Architecture, Bitstream, Generic, and
Physical.
The Bitstream API example reads a bitstream and writes its
packets to the console.
./BitstreamExample regression/VirtexUnitTest.reference.bit
The Architecture API opens a Virtex6 device, looks up a
logic site output, and shows all wires that can be driven by
that output pin.
The Generic API example generates no output on the console,
but instead changes the INIT property of a LUT
instance. Perform a diff on the original and modified
EDIF files to observe the changed INIT property.
./GenericExample
diff regression/GenericExample.reference.edf regression/GenericExample.generated.edf
The Physical API example reads an XDL file, looks up its
design root, and writes it back out without any
modifications:
./PhysicalExample regression/DesignUnitTest.reference.xdl
The EDIF obfuscator example reads an EDIF file, replaces
names with MD5 hashes, and writes out the modified
file. Ports belonging to the top-level design remain
unobfuscated.
./EdifObfuscator [edif_file]
|
|
| Sandbox |
|
The example code in
src/torc/examples is also available in sandbox, where it can
be built and modified at will:
|
|
Unit
Tests
|
|
Torc uses the Boost.Test
framework to perform unit testing of classes and
functions. Some of the unit tests are trivial, while
others provide good examples of how to work with the various
parts of Torc. The full collection of unit tests
currently includes some failing tests, some of which serve
as deliberate to-do placeholders, but can nonetheless be
invoked as a partial sanity check for the code.
The following syntax supports invoking specific test suites
or test cases:
./TorcTest -t [test_suite]/[test_case]
./TorcTest -t common/DevicesUnitTest
|
|
|
