The New Jersey Machine-Code Toolkit

The New Jersey Machine-Code Toolkit helps programmers write applications that process machine code---assemblers, disassemblers, code generators, tracers, profilers, and debuggers. The toolkit lets programmers encode and decode machine instructions symbolically. Encoding and decoding are automated based on compact specifications. The toolkit is a joint project of Mary Fernández and Norman Ramsey.

You can take a shortcut straight to the source distribution.

There is (old) news for November 1998, as well as really old news. The main news is that you can now download the ML version of the toolkit.

I've started a Toolkit FAQ

News flash! You can now browse generated decoders on the web!

Mailing lists

To keep up to date with the toolkit, you can send messages to the authors at toolkit@eecs.harvard.edu. We also have two mailing lists about the toolkit; toolkit-interest@lists.eecs.harvard.edu goes to people who have expressed some interest in the toolkit, and it carries most general announcements about the toolkit. toolkit-users@lists.eecs.harvard.edu goes to people who are actually using the toolkit, and it carries discussion among users, as well as all the traffic from toolkit-interest. You can subscribe or unsubscribe by putting your email address in this form.

It's still a good idea to report problems to toolkit@eecs.harvard.edu.

Version 0.5 (November 1996)

The toolkit is now in version 0.5. This release is a bugfix release, timed to coincide with the acceptance of our TOPLAS paper. The release fixes many bugs, especially in generated decoders.

We have added and validated an Alpha specification.

We save release notes from previous versions of the toolkit.

There is no ``upgrade path'' from earlier versions to 0.5. Get new everything.

ML Version (November 1998)

The ML implementation of the toolkit is distributed ``as is,'' for experimental purposes only.

Distribution

If you think you might want to use the toolkit, a reference manual and source distribution are available. There are annotated specifications (read the report or browse the source directory for the MIPS, SPARC, Intel Pentium, and Alpha, which show how to use the toolkit to describe real machines. There is also an unannotated specification for the PowerPC 604. Finally there is a toy example that will give you more ideas about how to build applications, and there is a rudimentary disassembler for the SPARC that you may find useful.

Papers

There are two papers describing the main ideas:

Norman Ramsey and Mary Fernández. The New Jersey Machine-Code Toolkit. Proceedings of the 1995 USENIX Technical Conference, New Orleans, LA, January 1995, pp 289-302. [Abstract] [HTML version].
An overview, and the place to begin.
Norman Ramsey and Mary Fernández. Specifying Representations of Machine Instructions. To appear in ACM Transactions on Programming Languages and Systems. [Abstract] [HTML version]
This is a comprehensive journal paper that focuses on SLED, the toolkit's specification language.

This paper describes how to test SLED specifications:

Mary Fernández and Norman Ramsey. Automatic Checking of Instruction Specifications. To appear in the 1997 International Conference on Software Engineering. [Abstract]

Those who actually want to use the toolkit will probably find the following technical reports useful:

Norman Ramsey and Mary Fernández. New Jersey Machine-Code Toolkit architecture specifications. Originally Technical Report TR-470-94, Department of Computer Science, Princeton University, October 1994.
These annotated descriptions of the MIPS, SPARC, and Intel Pentium show the toolkit's specification language in action. Highly recommended for anyone planning to write machine descriptions for the toolkit.
Norman Ramsey and Mary Fernández. New Jersey Machine-Code Toolkit reference manual. Originally Technical Report TR-471-94, Department of Computer Science, Princeton University, October 1994.
The manual describes the complete specification language and explains how to use version 0.5.

The toolkit project has also led to a machine-independent method of relocating instructions, described in

Norman Ramsey. Relocating machine instructions by currying, Proceedings of the ACM SIGPLAN '96 Conference on Programming Language Design and Implementation, in SIGPLAN Notices 31, 5 (May 1996), 226-236. [Abstract]

The toolkit's equation solver is described in

Norman Ramsey. A simple solver for linear equations containing nonlinear operators. Software---Practice & Experience, 26(4):467--487, April 1996. An earlier version appeared as Technical Report 95-068, Purdue University, Dept of Computer Sciences, November 1995.

Back to Norman Ramsey's home page.