Getting Started
To use Torc, it is first necessary to download the virtual machine image, or check out a working copy of the 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:
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:
cd src
make
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 Support.
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.
./ArchitectureExample
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:
cd sandbox
make
Unit Tests
Torc uses the Boost.Testatum 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.
./TorcTest
The following syntax supports invoking specific test suites or test cases:
./TorcTest -t [test_suite]/[test_case]
./TorcTest -t common/DevicesUnitTest