[Freemint-discuss] Disassembly of TOS 1.00 with Ghidra

[Vincent R. <vin...@fr...>]

Hi, and happy new year to all of you.

Here is my present:
A (partial) disassembly of TOS 1.00 using Ghidra

Everything is here, including explanations:
https://github.com/disastos/tos100fr

Here is some background.

Recently, someone told me about a strange GEMDOS bug happening only on 
TOS 1.00. I quickly managed to reproduce it with a program of mine. As 
it was simple enough to be bug-free, the problem was obviously inside 
TOS 1.00. I'm used to trace the ROM with MonST2, no problem for that. 
But as the GEMDOS is written in C, and uses rather complex structures, 
it quickly becomes hard to follow. Then I looked at Thorsten's 
(excellent) reconstructed sources. It helped a lot, but unfortunately 
the bug was in memory management. And that part of the code changed 
between TOS 1.00 (my target) and TOS 1.04 (Thorsten's sources). So it 
wasn't enough. So I decided to disassemble the TOS 1.00 using Ghidra. 
Not entirely, of course, but at least the offending GEMDOS functions. I 
finally found the bug, then a workaround, and everyone was happy. I 
still need to clarify a few things, then I will tell more. Anyway, 
that's another topic.

During that investigation, I practiced Ghidra a lot. And definitely, 
that's a really powerful tool. And Free. Not completely polished, but 
definitely very usable, as soon as you have understood the basics. My 
conclusion is that Ghidra is *the* tool to learn for anyone interested 
in reverse engineering (just like Git for source control).

Ghidra is a bit bloated (not so much, for nowadays standards). It 
requires a Java JDK as runtime, then it can be downloaded as a simple 
zip archive. And run from a .bat file. After an austere project 
management window, the main tool opens. It is a nice workspace-like 
window, see the screenshot on GitHub.

Basically, you start creating a new project by specifying the 68000 CPU. 
Import the ROM binary (I used tos100fr.img). Then it is automatically 
analyzed, and disassembled to both assembly language and C.
Be sure that the disassembly is as good as possible. But there are no 
miracles. You do get labels and cross-references, but the names are 
meaningless. Fortunately, just press L to rename a label and it will 
change everywhere. Same in the C decompilation, you can rename 
functions, parameters, variables, etc. For code using structs (such as 
basepage), it's quite unreadable. But as soon as you define the actual 
struct and correctly specify the type of the variables, the 
decompilation becomes completely usable, and you're able to understand 
the algorithms.

And this works really well, thanks to the hard work of Thorsten on the 
reconstruction of TOS 1.4 sources. Even if there are some important 
differences, the major code base is similar, when not identical. Of 
course, the addresses of the internal functions are different. But after 
renaming some labels, it's just like a puzzle: highly addictive. With 
more labels, you are able to identify more functions, and so on. So 
after my initial bugfix, I continued to add labels. And finally, I found 
most major functions of BIOS/XBIOS/BDOS/VDI. Bad luck with AES/Desktop, 
because due to the infamous Line-F obfuscation (to reduce code size), 
Ghidra is lost. Maybe something could be done with a proper script. 
Again another topic.

Anyway, as I disassembled most of the TOS 1.00, and added a lot of 
labels and structs from Thorsten's sources, I considered it was worth to 
share this work. It can help a lot to find bugs, and understand things 
from the origins. As that 40-years old TOS has been considered as 
abandonware for a long time, it shouldn't be a problem to put that 
disassembly and related documentation on GitHub.

I don't plan to work much more on that project. Or maybe, occasionally. 
But other people may have additional needs, to disassemble other parts, 
etc. So this needs to be a collaborative project.

This is why I've created a new GitHub Organization to hold that project. 
I named it DisasTOS, meaning "Disassembly of TOS, and more". Currently, 
it only holds this single TOS 1.0 project. But this could work equally 
well for TOS 4.04 for example. Or even some user programs such as 
FOLDRXXX.PRG for example. My idea is to easily give write access to the 
DisasTOS organization, so many developers can contribute. Between 
disassembly and documentation, there is much to do.

So if people are interested, here is a new toy. Feel free to contribute. 
Really, it is worth to learn Ghidra. I won't do much more myself on that 
topic.

Just one more thing:
Unfortunately, Ghidra projects can't be easily shared. They actually 
can, but that requires a Ghidra Server. And we don't have one. If this 
project becomes popular, we could consider to setup a Guidra Server 
somewhere. It just needs to be able to run Java, and a Ghidra instance. 
But for now, let's start like this. What I have set up is really not 
convenient, but that's a starting point. Basically, Ghidra projects can 
be archived into a GAR archive. I've put such archive in the GitHub 
project, so any developer must unpack/work/repack/push the archive. As 
it is a binary file, it doesn't support multiple concurrent 
modifications. So a only single user can work on the project as the same 
time. That's a severe restriction. The only solution seems to be usage 
of a Ghidra Server. We will see if we finally need that.

Enjoy!

-- 
Vincent Rivière