add README

1 files changed, 80 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..fa3ef03
--- /dev/null
+++ b/README
@@ -0,0 +1,80 @@
+ABOUT
+-----
+
+Saturn-tools is a suite of software for creating and manipulating disk
+images compatible with the Sega Saturn game console.
+
+REQUIREMENTS
+------------
+
+To compile this software, you will need:
+
+ - GNU make
+ - A working C99/POSIX.1-2001 toolchain for the target system
+ - A working GCC-compatible C99 toolchain for the SH2 architecture
+ - Access to a Sega Saturn game disk
+
+To use the saturn-mkiso program, you will additionally need at runtime:
+
+ - mkisofs from cdrecord, cdrkit, or another compatible source
+
+INSTALLATION
+------------
+
+Optionally, edit the config.mak file to tell the build system where to
+find your toolchains, what compilation options to use, and where to
+install the software.
+
+Run these commands to build and install the software:
+
+    make
+    make install
+
+The saturn-mkboot utility requires access at runtime to a "security
+code" binary that must be part of the boot sector before the Saturn
+will consent to boot a disk. This security code is protected by
+copyright, and is therefore not distributed as part of this package.
+Assuming you have a legitimate Sega Saturn, you can extract it
+yourself. Run:
+
+    dd if=/dev/sr0 of=securitycode.bin bs=256 skip=1 count=13
+
+Replacing /dev/sr0 with the name of the device containing a Saturn game
+disk. Place the resulting securitycode.bin file in the
+$(prefix)/share/saturn-tools/ directory (which is, by default,
+/usr/local/share/saturn-tools/) for saturn-mkboot to find it.
+
+USAGE
+-----
+
+All programs that are part of this suite will print full usage
+information when invoked with the -h option.
+
+saturn-mkboot is used to create a Saturn-compatible boot sector. The
+basic usage is as follows:
+
+    saturn-mkboot -i simple -o aip.bin
+
+The output file is specified with the -o argument. By convention, it is
+named aip.bin.
+
+The -i option identifies the bootstrap code used to launch the software
+on the disk. The "simple" boot code simply jumps to the code contained
+in the first file on the disk, and is what most homebrew Saturn
+software probably expects. The "elf" boot code assumes that the first
+file on the disk is a statically linked ELF executable and loads it.
+The argument to the -i option can be a file, or if no matching file is
+found, one of the files in the installed data directory (by default,
+/usr/local/share/saturn-tools).
+
+saturn-mkiso is used to combine the aip.bin generated by saturn-mkboot
+with the other files to go on the disk into an iso9660 image which can
+be burnt to a CD-ROM and booted on the Saturn. The basic usage is:
+
+    saturn-mkiso -b aip.bin -o disk.iso 00boot.bin...
+
+Where aip.bin is the output from saturn-mkboot, disk.iso is the output
+of this command, and 00boot.bin and any following arguments are files
+to be included on the disk. The executable code to be run is usually in
+a file named 00boot.bin to ensure it is seen as the "first" file on the
+disk.