Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Prettified README.

  • Loading branch information...
commit 2c7637a9fc33a068891846afce618e6be441ca71 1 parent d86cfac
@hellige authored
Showing with 67 additions and 24 deletions.
  1. +66 −23 README → README.md
  2. +1 −1  TODO
View
89 README → README.md
@@ -1,28 +1,42 @@
DCPU-16 Playground
+==================
This is an emulator, assembler, and an implementation of the Forth programming
language for notch's DCPU-16. See http://0x10c.com/doc/dcpu-16.txt for details,
-although that spec is now unofficially superseded. Newer specs are collected
-here:
- https://github.com/0x10cStandardsCommittee/0x10c-Specifications/tree/master/MOJANG
+although that spec is now unofficially superseded. Newer specs are scattered
+about:
+
+ * DCPU-16 v1.7: http://pastebin.com/raw.php?i=Q4JvQvnM
+ * NE_LEM1802: http://0x10c.com/highnerd/rc_1/lem1802.txt
+ * Keyboard: http://dcpu.com/highnerd/rc_1/keyboard.txt
+ * Clock: http://dcpu.com/highnerd/rc_1/clock.txt
There are also a couple of useful scripts for swapping endianness of binary
images and dumping to hex in a format supported by some other emulators.
Quick Start
+-----------
To build, just run:
- make
+
+ make
+
To run the goforth interpreter image:
- ./goforth
+
+ ./goforth
+
Other images can be run with:
- ./dcpu blah.img
+
+ ./dcpu blah.img
+
For options, just try:
- ./dcpu
+
+ ./dcpu
The Emulator
+------------
The emulator is written in C and supports both curses and SDL (if available at
compile-time) for video display. It's well tested and has a number of nice
@@ -55,9 +69,13 @@ shift/control in isolation.
For best colors, run in a terminal with good color support. You may have to
fiddle around to get curses to realize your colors are good. For example,
try setting
- TERM=xterm-256color
+
+ TERM=xterm-256color
+
if you're not having any luck. You can use
- ./dcpu colortest.img
+
+ ./dcpu colortest.img
+
to test things out. Apparently ncurses 5 doesn't really support 256 distinct
color pairs (well, it supports 256, but the first pair is reserved). So if
you have ncurses 5 (most Linux distros, it seems), white-on-white will probably
@@ -65,9 +83,10 @@ appear as your default terminal colors instead.
goforth
+-------
- 'i figured i owned just dark skies, and that darkness fit me best.
- go, folks, go forth. trust your brain! trust your body!'
+> 'i figured i owned just dark skies, and that darkness fit me best.
+> go, folks, go forth. trust your brain! trust your body!'
The real fun starts in goforth.dasm and goforth.ft. goforth is an
implementation of the Forth programming language for DCPU-16. There's still
@@ -82,71 +101,95 @@ although custom images would be quite easy to create...)
The older (DCPU-16 1.1) version of goforth was tested on several other
emulators:
+
* Notch's 'official' prototype, from http://dcpu.com/highnerd
+
goforth runs correctly in this emulator, and you can play with it
online here: http://matt.immute.net/files/goforth
(This gives some evidence that my emulator is in good shape as well!)
+
* interfect's dcpu-emu: https://bitbucket.org/interfect/dcpu-emu
+
Runs correctly.
+
* DCPU Studio: http://badsector.github.com/dcpustud
+
Seems to run correctly (with 'use big endian words' and 'use keyboard
buffer' options), but keyboard input is broken. I get mostly the right
keypresses, but something about the buffer management is screwy and I
end up losing sync, having to press keys twice, etc. I don't want to invest
more time in keyboard compatibility until there's actually a spec.
+
* deNULL's web emulator: http://dcpu.ru
+
Seems to run correctly here, too, but the keyboard input is significantly
different (all letters are caps, punctuation doesn't work) so it's a little
hard to do too much testing.
+
* http://0x10co.de
+
Again, everything looks good, but keyboard input is (again, but
differently) broken, so it's hard to do much. And again, I'm going to wait
for a spec.
+
I am most interested in hearing whether the new 1.7 version works on other
emulators, but I've been busy updating my own and haven't checked the status
of many other emulators yet. As far as I know, there is not yet any official
1.7-compatible emulator from Notch.
+
* http://0x10co.de/hiwhx
+
Post-1.7, the keyboard handling is better specified and things look
very good. There are a couple of fishy things, but I will boldly say
that they're bugs in 0x10co.de, until I hear otherwise. ;)
+
* http://fasm.elasticbeanstalk.com/?proj=rs5s77
+
(The link is to a slightly out-of-date goforth image.) This looks very
good. You won't see a cursor, because it seems to interpret the blink bit
as "do not show", and it seems slower than it should be, but apart from
that, everything looks good.
+
* deNULL's web emulator: http://dcpu.ru
+
As in the case of 0x10co.de, things look pretty good, but signed math
is broken. It thinks -50/5, 50/-5 and 50/5 are all equal to 50 under DVI.
DIV does know that 50/5 is 10.
In order to bootstrap the image, I've augmented the DCPU instruction set with
three new instructions (all in non-basic format):
- img: dump ram to the file core.img, from address 0x0000 to (but not
- including) the address in the 'a' argument. if 'a' is 0, dump the
- entire heap (0x0000 to 0x10000)
- die: exit the emulator
- dbg: enter the emulator debugger
+
+ img: dump ram to the file core.img, from address 0x0000 to (but not
+ including) the address in the 'a' argument. if 'a' is 0, dump the
+ entire heap (0x0000 to 0x10000)
+ die: exit the emulator
+ dbg: enter the emulator debugger
+
The latter two instructions are only used in special cases and are easily
avoided. img is needed only to bootstrap the forth image.
-ONCE AGAIN, THE BOOTSTRAPPED IMAGE WILL RUN ON ANY EMULATOR.
+**ONCE AGAIN, THE BOOTSTRAPPED IMAGE WILL RUN ON ANY EMULATOR.**
The Assembler
+-------------
-The assembler (masm) is in Python and has a number of idiosyncrasies. The
-syntax has diverged from the consensus DCPU-16 assembler syntax in some
-rather pointless ways, and it's quite limited. It works for my purposes,
-but I don't recommend that you use it.
+The assembler (masm) is written in Python and has a number of idiosyncrasies.
+The syntax has diverged from the consensus DCPU-16 assembler syntax in some
+rather pointless ways, and it's quite limited. It works for my purposes, but
+I don't recommend that you use it. For a more full-featured and standard
+assembler, I recommend Jon Povey's das: https://github.com/jonpovey/das.
Credits
+-------
-The built-in disassembler includes code from Brian Swetland's DCPU-16 emulator,
-see the file disassembler.c for license and copyright info.
+The built-in disassembler includes code from [Brian Swetland's DCPU-16
+emulator][1], see the file disassembler.c for license and copyright info.
Thanks to Corbin Simpson for various improvements to goforth.
Thanks to Juan Felipe Garcia Catalan for contributing the goforth assembler
(see asm.ft).
+
+[1]: https://github.com/swetland/dcpu16
View
2  TODO
@@ -5,7 +5,7 @@ emulator:
goforth:
- move all raw assembler to before forthstart
- data stack in sp
- - assembler
+ - double-word arithmetic
misc:
- list of 1.7-compatible tools?
- 1.7 emulator test cases?
Please sign in to comment.
Something went wrong with that request. Please try again.