Describe goals in the Readme.md

1 files changed, 59 insertions, 7 deletions

diff --git a/Readme.md b/Readme.md
index e2b8d6e..4343eea 100644
--- a/Readme.md
+++ b/Readme.md
@@ -1,15 +1,64 @@
-# Motorola M68000 ISA Disassembler
+# Motorola 68000 Disassembler
 
 > Disassemble into what `as` can assemble back
 
-This project aims to be a disassembler capable to produce assembly code that GNU
-AS will translate into the same original machine code.
+This project aims to be a disassembler that is capable to produce assembly code
+that GNU AS will translate into the same original machine code. It's only use
+case for now is Sega Mega Drive / Genesis ROM hacking. I failed to find any way
+to disassemble SMD ROMs in such a way that it would be possible to assemble it
+back with GNU AS. All disassemblers I tried produce either syntactically
+incompatible asembly listing, or it is not the same as original binary after
+translation into machine code. So I decided to build my own disassembler, that
+will do exactly what I need with full control over the process and maybe more.
 
-Currently M68000 ISA only supported is planned. This means not M680x0, but only
-M68000.
+Goals of this Motorola 68000 disassembler project in this particular repo:
+- Support all Motorola 68000 ISA instructions.
+- Flawless compatibility with GNU AS syntax. It should always emit the code on
+  which GNU AS produces absolutely identical binary (with or without linkage)
+  without errors or warnings, unless some peculiar flags has been specified.
+- Support PC trace tables. With trace tables it will disassemble traced PC
+  locations only, without attempt to disassemble everything, because not
+  everything is instruction, some code is just data.
+- Mark jump locations and bind jumps and calls to them. Mark obvious ROM read
+  accessed locations and bind the instructions to the marked locations. To make
+  it possible to split and reorganize the binary.
 
-It is planned to support PC trace tables, so it will know what code is exactly a
-code, not data.
+What could become a goal (possible features):
+- Other Motorola 680x0 instruction sets support, including ColdFire.
+- Functions and function boundaries detection.
+- Static analysis of call graph of branches and subroutine calls.
+- PC trace aided static analysis of dynamic branches and subroutine calls.
+- Base address other than `0x00000000`. It is only zero for now because it is
+  sufficient for Sega Mega Drive / Genesis ROM images.
+- Support for more than 4MiB of code size.
+- Sparse address space support (instead of single continuous 4MiB block that
+  starts at `0x00000000` offset).
+- Other assembler syntaxes (e.g. ASM68K.EXE).
+- Expose a library API.
+
+What is **not** the goal (at least not in this repo):
+- Decompilation into some high level language like C or C++.
+- Other instruction set architectures support like MIPS, x86, amd64, ARM,
+  PowerPC and so on.
+
+## Build
+
+```
+cmake -B cmake-build -S .
+cmake --build cmake-build
+```
+
+## Usage example
+
+```
+./cmake-build/m68k-disasm -t pc-trace.txt -o disasm.S original.bin
+```
+
+To get detailed help you can run:
+
+```
+./cmake-build/m68k-disasm -h`
+```
 
 ## Meta
 
@@ -22,6 +71,9 @@ This is free and unencumbered software released into the public domain. See
 Parts of this project are licensed under different license:
 - Musashi M68000 CPU emulator - MIT
 
+## Contributing
+
+Coming soon.
 
 <!-- Markdown link & img dfn's -->
 [readme-template]: https://github.com/dbader/readme-template