ZDevtools 2.0.0

Around 10 years ago I released a package I called ZDevtools, which consisted of a Z-machine assembler and disassembler. I created these to aid in the development of Bocfel, not to be generally useful tools; but they can be useful for interpreter developers, if nothing else.

I worked sporadically on this for years, till I finally got sick of C and rewrote the whole thing in Rust. That alone wouldn’t be interesting or cause for a new release, but I also added what I call a “visual” disassembly mode, which looks like this:

│2cb: get_child - 1OP                                                │
 ┌─ Short form
 │   ┌─ Operand type: Variable
 │   │     ┌─ @get_child
┌┴┐ ┌┴┐ ┌──┴──┐
1 0 1 0 0 0 1 0 

Operand: 11111111 (Gef)

Store: 00010101 (21) -> G05

┌─ Branch if true
│ ┌─ 14-bit branch
│ │              ┌─ +27 (2e8)
│ │ ┌────────────┴────────────┐
1 0 0 0 0 0 0 0 0 0 0 1 1 0 1 1 

It’s kind of fun to see how Z-code looks down to the bit level, I think.

Anyway, I’ve decided to package this up and, with great fanfare, make a 2.0.0 release. It’s available at https://cspiegel.github.io/zdevtools/, which is a rather bare-bones site I threw together for this.

As with the original release, the assembler is really quite limited, in that it doesn’t support object creation, amongst other things. The disassembler is also less “smart” than txd, because it doesn’t try to find any code which can’t be reached via the initial program counter (txd has knowledge about how Inform and Infocom lay things out). With that being said, because it doesn’t think about Inform or Infocom games, it is capable of disassembling some stories that txd has trouble with (e.g. those created with the assembler included here…)

Only the source code is provided, and a Rust compiler (plus Cargo) is required to build this.

Feel free to report bugs to https://github.com/cspiegel/zdevtools/issues.


I have not tried it yet, but the visual disassembly look very nice.

Great work!

Wouldn’t there be one problem, though, with only following from Initial PC that you mostly disassemble the library code?

Regarding TXD. I have look quite a bit at TXD myself lately (I’m trying to do a program that reverse engineer a z-file as far as possible and therefore base a lot of decisions on what compiler that was used). TXD tries to analyse the grammar, but that can be excluded. It is here it is most tied to the compiler. But when it is disassembling it does it in two passes. The first pass scans, starting at the end of the dictionary, and tries every byte as a starting point and sees if it disassemble to a valid routine. The second pass then prints all the valid routines.

TXD mostly run into problems because it is missing support for some new opcodes (print_unicode, check_unicode and buffer_screen) and that it sometimes determines that a routine has ended, even if it has not.

Would you be willing to create a page for it on IFWiki (ZDevtools - IFWiki)? You could use Form:Software - IFWiki :+1:

Yep, this won’t find any action routines, for example. I wrote the disassembler because txd wouldn’t work with files I created with my own assembler. All code I needed was reachable from the initial PC so it was good enough for me.

However, you can pass routine addresses (with -a or -A) to the disassembler, and it will disassemble all of them. So if you know the addresses of action routines, you can simply pass those.

The original release (20110529) includes a script which parses the output of infodump -g, converting it to an address list, and has an example in the README of how to pass that to the disassembler. I didn’t include the script in 2.0.0, but it’s still valid, and should still work, though you’ll need version 2.0.1 (that I just released) due to a boneheaded mistake I made in branch/store instruction disassembly. I have a local branch that calls infodump directly, obviating the need to use this script, and once I’m sure it works right, I’ll include it in a future release.

1 Like

Done! When filling it out I realized I didn’t include any license information in the release, so new releases are coming fast and furious today: 2.0.2 was just released, the sole change being the inclusion of license information (MIT).