python-dcpu_16/README.mdown

What is this?

A DCPU-16 implementation in Python. See the spec.

But what's the goal of this? There's another one already!

Well, what's wrong with taking another stab at it? Besides, I personnally felt it was too C-ish, and not pythonic enough (whatever that means, but you should read this). I wanted to revive whatever low-level (admittedly limited) ASM knowledge I had (from 6800/68000) and sharpen my Python-fu. The spirit of the thing is to be educative for everyone (including me).

How do I use this?

It's meant to be used interactively via the Python REPL as well as programmatically. I might implement a specific ASM REPL at some point.

An example of a Python REPL session:

>>> from dcpu_16 import CPU
>>> c = CPU(debug=True)
>>> c.load_m()                  # loads demo program
>>> c.step()                    # step by one instruction
 << SET
 << c.r[0x0]
 << c.m[0x0001]
 << A=0030 B=0000 C=0000 X=0000 Y=0000 Z=0000 I=0000 J=0000 PC=0002 SP=0000 O=0000
>>> c.pc = 0xA                  # jump to 'loopy thing'
>>> c.step()
 << SET
 << c.r[0x6]
 << 0x000A
 << A=0030 B=0000 C=0000 X=0000 Y=0000 Z=0000 I=000A J=0000 PC=000B SP=0000 O=0000
>>> c.reset()                   # reset CPU
>>> c.clear()                   # clear memory
>>> c.dump_r()                  # get CPU register state as string
'A=0000 B=0000 C=0000 X=0000 Y=0000 Z=0000 I=0000 J=0000 PC=0000 SP=0000 O=0000'

What is the status of this?

It's not bug-free yet, the implementation itself is still a WIP and the whole of the spec example does not pass yet. But hey, that's what you get in a few late hours. Fixes coming, I promise.

Features

Opcodes and valcodes are as declarative as possible using decorators, leaving the dispatcher as a quasi-one-liner and leveraging dict power instead of if/elif.

Using functions/methods mean there are doctrings everywhere, hence documentation is both very local and as exhaustive as possible. Try help(dcpu_16).

You can use cpu[] to dispatch valcodes and get/set directly without having to handle a pointer structure.

The CPU is a class, so you can instantiate a bunch of them. I might move memory outside the CPU so that it would be shared by CPU instances (SMP!)