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 news for November 1996.

Mailing lists

To keep up to date with the toolkit, you can send messages to the authors at toolkit@cs.princeton.edu. We also have two mailing lists about the toolkit; toolkit-interest@cs.virginia.edu goes to people who have expressed some interest in the toolkit, and it carries most general announcements about the toolkit. toolkit-users@cs.virginia.edu goes to people who are actually using the toolkit, and it carries discussion among users. You can subscribe by sending one of

subscribe toolkit-interest
subscribe toolkit-users

to majordomo@virginia.edu. The inverse operations are

unsubscribe toolkit-interest
unsubscribe toolkit-users

And you can try who toolkit-users and so on to see who is on the list.

It's still a good idea to report problems to toolkit@cs.princeton.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.

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.

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. 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. 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.2.

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.