v1.7 spec mostly implemented, mostly untested

[dcpu16] / dcpu16.c

#include <stdlib.h>
#include <stdio.h>
#include <stdarg.h>
#include <unistd.h>
#include <string.h>
#include <errno.h>
#include <assert.h>
#include <sysexits.h>

#include "dcpu16.h"

/*
 *  emulates the DCPU16 system from http://0x10c.com/doc/dcpu-16.txt
 *  
 *  I couldn't remember ever implementing an emulator before, so this
 *  happened.  As such, consider this a toy in progress.
 *  There are likely many improvable aspects.
 *  
 *  Justin Wind <justin.wind@gmail.com>
 *    2012 04 05 - implementation started
 *    2012 04 06 - first functionality achieved
 *    2012 04 09 - minor cleanups
 *    2012 04 10 - moved cli to separate module
 *    2012 04 12 - added basic callback support for address accesses
 *    2012 05 05 - start of v1.7 revisions
 *    2012 05 08 - v1.7 revisions mostly complete
 *
 *  TODO
 *    !! v1.7 bit-shift and signed opcodes need to be reviewed/finished
 *    !! v1.7 hardware interface needs to be finished
 *    !! v1.7 interrupts need to be finished
 *    change api to print into buffers rather than stdio
 *    refactor opcode functiontables into switch statements
 *    let callbacks determine whether to override events, or just observe
 *    sort init callbacks by base addr, to call in-order
 *    make all callbacks register addr range of interest
 */

static const char * const src_id_ = "$Id$";

#define OPCODE_BASIC_BITS   5
#define OPCODE_OPERAND_B_BITS 5
#define OPCODE_OPERAND_A_BITS 6

static const char * const regnames_ = "ABCXYZIJ";

/* some default warning and debug reporting functions, which can be overridden by clients */
#define WARN(...) do { if (warn_cb_) warn_cb_(__VA_ARGS__); } while (0)
static inline void warn_(char *fmt, ...) __attribute__((format(printf, 1, 2)));
static inline
void warn_(char *fmt, ...) {
    va_list ap;

    fprintf(stderr, "[warning] ");
    va_start(ap, fmt);
    vfprintf(stderr, fmt, ap);
    va_end(ap);
    fprintf(stderr, "\n");
    fflush(stderr);
}
static void (*warn_cb_)(char *fmt, ...) = warn_;
void dcpu16_warn_cb_set(void (*fn)(char *fmt, ...)) {
    warn_cb_ = fn;
}

#ifdef DEBUG
#define TRACE(...) do { if (trace_cb_) trace_cb_(__VA_ARGS__); } while (0)
static inline void trace_(char *fmt, ...) __attribute__((format(printf, 1, 2)));
static inline
void trace_(char *fmt, ...) {
    va_list ap;

    fprintf(stdout, "[debug] ");
    va_start(ap, fmt);
    vfprintf(stdout, fmt, ap);
    va_end(ap);
    fprintf(stdout, "\n");
    fflush(stdout);
}
#else /* DEBUG */
#define TRACE(...) do {} while(0)
#endif /* DEBUG */
static void (*trace_cb_)(char *fmt, ...) =
#ifdef DEBUG
    trace_
#else /* DEBUG */
    NULL
#endif
    ;
void dcpu16_trace_cb_set(void (*fn)(char *fmt, ...)) {
    trace_cb_ = fn;
}


/*  acct_event_
 *  invokes callbacks for specified event
 */
static inline
void acct_event_(struct dcpu16 *vm, dcpu16_acct_event ev, DCPU16_WORD addr) {
    struct dcpu16_acct_cb *cb = vm->cb_table_;
    size_t i;

    for (i = 0; i < vm->cb_table_entries_; i++) {
        if ( (cb[i].mask & ev) )
            cb[i].fn(vm, ev, addr, cb[i].data);
    }
}

/* convert register name to index into register array */
static inline
off_t reg_index_(int reg) {
    return strchr(regnames_, reg) - regnames_;
}

/* add an entry to the interrupt queue */
static
int interrupt_enqueue_(struct dcpu16 *d, DCPU16_WORD message) {
    d->interrupts_[d->interrupts_tail_] = message;
    d->interrupts_tail_ += 1;
    d->interrupts_tail_ %= DCPU16_INTERRUPT_QUEUE_SIZE;

    if (d->interrupts_tail_ == d->interrupts_head_) {
        d->on_fire_ = 1;
        WARN("interrupt queue overflow (system is now on fire)");
        return -1;
    }

    return 0;
}

static
DCPU16_WORD interrupt_dequeue_(struct dcpu16 *d) {
    DCPU16_WORD message;

    if (d->interrupts_tail_ == d->interrupts_head_) {
        WARN("interrupt underflow");
        return 0;
    }

    message = d->interrupts_[d->interrupts_head_];
    d->interrupts_head_ += 1;
    d->interrupts_head_ %= DCPU16_INTERRUPT_QUEUE_SIZE;

    return message;
}

/*  value_decode_
 * sets *v to be the address of the represented value
 * value_is_a is 0 for b, 1 for a, alters behavior of some operands
 * value_data is 'nextword' for this operand, ignored if unused
 * workv is buffer to use to accumulate literal value into, before use. one exists for either potential instruction operand
 * e_addr is set to a referenced address, for accounting callback
 * pc_adjust is set to how to change the program counter
 * stack_adjust is set to how to change the stack pointer
 * cycles is set to number of cycles spent looking up operand
 *
 * zero all adjustables before decoding first operand, and pass in these values when
 * decoding next operand..
 *
 */
static inline
void value_decode_(struct dcpu16 *d, DCPU16_WORD value, unsigned int value_is_a, DCPU16_WORD value_data,
                  DCPU16_WORD *work_v, DCPU16_WORD **v, DCPU16_WORD *e_addr,
                  short *pc_adjust, short *sp_adjust, unsigned int *cycle_adjust) {
    assert(value <= 0x3f);

    DCPU16_WORD pc = (DCPU16_WORD)(d->pc + *pc_adjust),
                sp = (DCPU16_WORD)(d->sp + *sp_adjust);

    TRACE("%s: pc:0x%04x sp:0x%04x value_data:0x%04x\n", 
          __func__,
          pc,
          sp,
          value_data);

    if (value <= 0x07) { /* register */
        *v = d->reg + value;
        TRACE("%s>>     %c (0x%04x)",
              __func__,
              regnames_[value],
              **v);
        return;
    }

    if (value <= 0x0f) { /* [register] */
        *v = &(d->ram[ d->reg[value & 0x07] ]);
        *e_addr = d->reg[value & 0x07];
        TRACE("%s>>     [%c] [0x%04x] (0x%04x)",
              __func__,
              regnames_[value & 0x07],
              d->reg[value & 0x07],
              **v);
        return;
    }

    if (value <= 0x17) { /* [next word + register] */
        *pc_adjust += 1; /* consume next word */
        *cycle_adjust += 1;
        *e_addr = value_data + d->reg[value & 0x07];
        *v = d->ram + *e_addr;
        TRACE("%s>>     [nextword + %c] [0x%04x + 0x%04x] (0x%04x)",
              __func__,
              regnames_[value & 0x07],
              value_data,
              d->reg[value & 0x07],
              **v);
        return;
    }

    switch (value) {
        case 0x18: /* PUSH/[--SP] or POP/[SP++] */
        if (value_is_a == 0) { /* b */
            *v = &(d->ram[sp - 1]);
            *sp_adjust -= 1;
            *e_addr = sp - 1;
            TRACE("%s>>     PUSH [0x%04x] (0x%04x)", __func__, sp - 1, **v);
        } else { /* a */
            *v = &(d->ram[sp]);
            *sp_adjust += 1;
            *e_addr = sp;
            TRACE("%s>>     POP [0x%04x] (0x%04x)", __func__, sp, **v);
        }
        break;

        case 0x19: /* PEEK/[SP] */
        *v = &(d->ram[sp]);
        *e_addr = sp;
        TRACE("%s>>     PEEK [0x%04x] (0x%04x)",
              __func__,
              sp,
              **v);
        break;

        case 0x1a: /* PICK n */
        *pc_adjust += 1;
        *cycle_adjust += 1;
        *e_addr = sp + value_data;
        *v = d->ram + *e_addr;
        TRACE("%s>>     PICK 0x%04x [0x%04x] (0x%04x)",
              __func__,
              value_data,
              sp + value_data,
              **v);
        break;

        case 0x1b: /* SP */
        *v = &(d->sp);
        TRACE("%s>>     %s (0x%04x)",
              __func__,
              "SP",
              **v);
        break;

        case 0x1c: /* PC */
        *v = &(d->pc);
        TRACE("%s>>     %s (0x%04x)",
              __func__,
              "PC",
              **v);
        break;

        case 0x1d: /* EX */
        *v = &(d->ex);
        TRACE("%s>>     %s (0x%04x)",
              __func__,
              "EX",
              **v);
        break;

        case 0x1e: /* [next word] / [[pc++]] */
        *pc_adjust += 1;
        *cycle_adjust += 1;
        *e_addr = value_data;
        *v = d->ram + *e_addr;
        TRACE("%s>>     [nextword] [0x%04x] (0x%04x)",
              __func__,
              value_data,
              **v);
        break;

        case 0x1f: /* next word (literal) / [pc++] */
        *pc_adjust += 1;
        *cycle_adjust += 1;
        *work_v = value_data;
        *v = work_v;
        TRACE("%s>>     nextword (0x%04x)",
              __func__,
              **v);
        break;

        default: /* 0x20-0x3f: literal values 0xffff-0x1e */
        *work_v = (value & 0x1f) - 1;
        *v = work_v;
        TRACE("%s>>     literal (0x%04x)",
              __func__,
              **v);
    }
}


#define OPCODE_NAME_LEN 16
struct opcode_entry {
    unsigned short value;
    char name[OPCODE_NAME_LEN];
    void (*impl)(struct dcpu16 *, DCPU16_WORD, DCPU16_WORD, DCPU16_WORD, DCPU16_WORD);
};

/* messy boilerplate for opcode handlers */

/* opcode doesn't adjust its own PC, the step function which invoked it handles that */
/* opcode does adjust stack and cycle count */

#define OP_IMPL(x) static void op_##x(struct dcpu16 *d, DCPU16_WORD val_b, DCPU16_WORD val_b_data, DCPU16_WORD val_a, DCPU16_WORD val_a_data)

#define OP_TYPE(op_type) DCPU16_WORD *a, *b;\
    DCPU16_WORD ev_a_addr = 0, ev_b_addr = 0;\
    short pc_adjust = 0, sp_adjust = 0;\
    unsigned int cycle_adjust = 0;\
    do {\
        op_type;\
        value_decode_(d, val_a, 1, val_a_data,\
                      &d->reg_work_[1], &a, &ev_a_addr,\
                      &pc_adjust, &sp_adjust, &cycle_adjust);\
        d->sp += sp_adjust;\
        d->cycle += cycle_adjust;\
    } while (0)
#define OP_NBI_ (void)val_b, (void)b, (void)ev_b_addr, (void)val_b_data
#define OP_BASIC_ value_decode_(d, val_b, 0, val_b_data,\
                                &d->reg_work_[0], &b, &ev_b_addr,\
                                &pc_adjust, &sp_adjust, &cycle_adjust)
#define OP_BASIC(x) OP_TYPE(OP_BASIC_)
#define OP_NBI(x) OP_TYPE(OP_NBI_)

/* after invoking one of these header macros, the instruction and operands will have been decoded, and the control registers have been adjusted to the next instruction et cetera */

/*
    accounting helpers, these fire off the related callbacks for memory reads,
    memory writes, and execution of reserved instructions
 */
#define ACCT_R(addr) do { acct_event_(d, DCPU16_ACCT_EV_READ, addr); } while (0)
#define ACCT_W(addr) do { acct_event_(d, DCPU16_ACCT_EV_WRITE, addr); } while (0)
#define ACCT_ILL(addr) do { acct_event_(d, DCPU16_ACCT_EV_NOP, addr); } while (0)

/* extended opcodes */

/*
    N.B. this next function currently decodes values -- id est, it is
    an opcode processing terminus; however, if 'future instruction set
    expansion' happens, this will probably need to behave more like
    the OP_IMPL(_nbi_) function which invoked it, if those instructions
    have zero or differently styled operands.
*/
OP_IMPL(nbi__reserved_) {
    OP_NBI(nbi__reserved_);
    /* reserved for future expansion */

    /* fire an illegal instruction event for current instruction */
    DCPU16_WORD future_opcode = (d->ram[d->pc - pc_adjust] >> (OPCODE_BASIC_BITS + OPCODE_OPERAND_B_BITS));
    WARN("reserved future opcode 0x%04x invoked", future_opcode);

    ACCT_ILL(d->pc - pc_adjust);
}

OP_IMPL(nbi_jsr) {
    OP_NBI(nbi_jsr);
    /* pushes the address of the next instruction to the stack, then sets PC to a */

    ACCT_R(ev_a_addr);

    d->ram[ --d->sp ] = d->pc;
    d->pc = *a;

    d->cycle += 2;

    ACCT_W(d->sp + 1);
}

OP_IMPL(nbi__reserved2_) {
    OP_NBI(nbi__reserved2_);
    /* reserved */

    WARN("reserved nbi opcode invoked");

    ACCT_ILL(d->pc - pc_adjust);
}

OP_IMPL(nbi_int) {
    OP_NBI(nbi_int);

    ACCT_R(ev_a_addr);

    if (d->ia) {
        if ( interrupt_enqueue_(d, *a) ) {
            WARN("failed to queue interrupt");
            return;
        }

        if (d->interrupts_deferred_)
            return;

        d->interrupts_deferred_ = 1;
        d->ram[--d->sp] = d->pc;
        d->ram[--d->sp] = d->reg[reg_index_('A')];
        d->pc = d->ia;
        d->reg[0] = *a;
    }

    d->cycle += 4;
}

OP_IMPL(nbi_iag) {
    OP_NBI(nbi_iag);

    *a = d->ia;

    ACCT_W(ev_a_addr);
}

OP_IMPL(nbi_ias) {
    OP_NBI(nbi_ias);

    d->ia = *a;

    ACCT_R(ev_a_addr);
}

/* does this just ignore its operand? */
OP_IMPL(nbi_rfi) {
    OP_NBI(nbi_rfi);

    d->interrupts_deferred_ = 0;
    d->reg[reg_index_('A')] = d->ram[d->sp++];
    d->pc = d->ram[d->sp++];
}

OP_IMPL(nbi_iaq) {
    OP_NBI(nbi_iaq);

    if (*a) {
        d->interrupts_deferred_ = 1;
    } else {
        d->interrupts_deferred_ = 0;
    }

    ACCT_R(ev_a_addr);
}

OP_IMPL(nbi_hwn) {
    OP_NBI(nbi_hwn);

    ACCT_W(ev_a_addr);

    *a = d->hw_table_entries_;

    d->cycle += 2;
}

OP_IMPL(nbi_hwq) {
    OP_NBI(nbi_hwq);

    ACCT_R(ev_a_addr);

    if (*a >= d->hw_table_entries_) {
        WARN("hardware query for non-extant device 0x%04x", *a);
        d->reg[reg_index_('A')] = 0;
        d->reg[reg_index_('B')] = 0;
        d->reg[reg_index_('C')] = 0;
        d->reg[reg_index_('X')] = 0;
        d->reg[reg_index_('Y')] = 0;
        return;
    }

    d->reg[reg_index_('A')] = d->hw_table_[*a].id_l;
    d->reg[reg_index_('B')] = d->hw_table_[*a].id_h;
    d->reg[reg_index_('C')] = d->hw_table_[*a].ver;
    d->reg[reg_index_('X')] = d->hw_table_[*a].mfg_l;
    d->reg[reg_index_('Y')] = d->hw_table_[*a].mfg_h;

    d->cycle += 4;
}

OP_IMPL(nbi_hwi) {
    OP_NBI(nbi_hwi);

    ACCT_R(ev_a_addr);

    if (*a > d->hw_table_entries_) {
        WARN("interrupt for non-extant device 0x%04x", *a);
        return;
    }

    d->cycle += 4;
    d->hw_table_[*a].int_fn(d, d->hw_table_[*a].data);
}

OP_IMPL(nbi_hcf) {
    OP_NBI(nbi_hcf);

    ACCT_R(ev_a_addr);

    d->on_fire_ = 1;
    WARN("system on fire");

    d->cycle += 9;
}

static const struct opcode_entry opcode_nbi_entries[] = {
    {0x00, "(reserved)", op_nbi__reserved_},
    {0x01, "JSR", op_nbi_jsr},
    {0x02, "(reserved)", op_nbi__reserved2_},
    {0x03, "(reserved)", op_nbi__reserved2_},
    {0x04, "(reserved)", op_nbi__reserved2_},
    {0x05, "(reserved)", op_nbi__reserved2_},
    {0x06, "(reserved)", op_nbi__reserved2_},
    {0x07, "HCF", op_nbi_hcf}, /* undocumented */
    {0x08, "INT", op_nbi_int},
    {0x09, "IAG", op_nbi_iag},
    {0x0a, "IAS", op_nbi_ias},
    {0x0b, "RFI", op_nbi_rfi},
    {0x0c, "IAQ", op_nbi_iaq},
    {0x0d, "(reserved)", op_nbi__reserved2_},
    {0x0e, "(reserved)", op_nbi__reserved2_},
    {0x0f, "(reserved)", op_nbi__reserved2_},
    {0x10, "HWN", op_nbi_hwn},
    {0x11, "HWQ", op_nbi_hwq},
    {0x12, "HWI", op_nbi_hwi},
    {0x13, "(reserved)", op_nbi__reserved2_},
    {0x00, "", NULL}
};
#define OPCODE_NBI_MAX (((sizeof(opcode_nbi_entries)) / (sizeof(struct opcode_entry))) - 1)


/* basic opcodes */

/*
    N.B. the following function does not decode values, (thus does not advance sp)
    Decoding is handled by the secondary opcode functions it calls.
*/
OP_IMPL(_nbi_) {
    /* non-basic instruction */

    /* don't do normal value decoding here */

    DCPU16_WORD nbi_opcode = val_b;
    const struct opcode_entry *e = opcode_nbi_entries;

    (void)val_b_data;

    e = opcode_nbi_entries + ( (nbi_opcode < OPCODE_NBI_MAX) ? nbi_opcode : (OPCODE_NBI_MAX - 1) );

    assert(e->impl != NULL);

    TRACE(">> %s 0x%04x", e->name, val_b);
    e->impl(d, 0, 0, val_a, val_a_data);
}

OP_IMPL(set) {
    OP_BASIC(set);
    /* sets b to a */

    ACCT_R(ev_a_addr);

    /*
        if b is a literal, it's aimed at a scratch register,
        so it's fine to update, as it won't have any effect.
     */
    *b = *a;

    d->cycle += 1;

    ACCT_W(ev_b_addr);
}

OP_IMPL(add) {
    OP_BASIC(add);
    /* sets b to b+a, sets EX to 0x0001 if there's an overflow, 0x0 otherwise */
    unsigned int acc = *b + *a;

    ACCT_R(ev_b_addr);
    ACCT_R(ev_a_addr);

    *b = acc;
    d->ex = (acc > 0xffff);

    d->cycle += 2;

    ACCT_W(ev_b_addr);
}

OP_IMPL(sub) {
    OP_BASIC(sub);
    /* sets b to b-a, sets EX to 0xffff if there's an underflow, 0x0 otherwise */
    unsigned int acc = *b - *a;

    ACCT_R(ev_b_addr);
    ACCT_R(ev_a_addr);

    *b = acc;
    d->ex = (acc > 0xffff);

    d->cycle += 2;

    ACCT_W(ev_b_addr);
}

OP_IMPL(mul) {
    OP_BASIC(mul);
    /* sets b to b*a, unsigned, sets EX to ((b*a)>>16)&0xffff */
    unsigned int acc = *b * *a;

    ACCT_R(ev_b_addr);
    ACCT_R(ev_a_addr);

    *b = acc;
    d->ex = acc >> 16;

    d->cycle += 2;

    ACCT_W(ev_b_addr);
}

OP_IMPL(mli) {
    OP_BASIC(mli);
    /* sets b to b*a, signed */
    int acc = (short)*b * (short)*a;

    ACCT_R(ev_b_addr);
    ACCT_R(ev_a_addr);

    *b = acc;
    d->ex = acc >> 16;

    d->cycle += 2;

    ACCT_W(ev_b_addr);
}

OP_IMPL(div) {
    OP_BASIC(div);
    /* sets b to b/a, sets EX to ((b<<16)/a)&0xffff. if a==0, sets a and EX to 0 instead. */

    ACCT_R(ev_b_addr);
    ACCT_R(ev_a_addr);

    if (*a == 0) {
        *b = 0;
        d->ex = 0;
    } else {
        *b = *b / *a;
        d->ex = (*b << 16) / *a;
    }

    d->cycle += 3;

    ACCT_W(ev_b_addr);
}

OP_IMPL(dvi) {
    OP_BASIC(dvi);
    /* sets b to b/a, signed, round towards 0 */

    ACCT_R(ev_b_addr);
    ACCT_R(ev_a_addr);

    if (*a == 0) {
        *b = 0;
        d->ex = 0;
    } else {
        *b = (short)*b / (short)*a;
        d->ex = (short)(*b << 16) / (short)*a;
    }

    d->cycle += 3;

    ACCT_W(ev_b_addr);
}

OP_IMPL(mod) {
    OP_BASIC(mod);
    /* sets b to b%a. if a==0, sets b to 0 instead. */

    ACCT_R(ev_b_addr);
    ACCT_R(ev_a_addr);

    if (*a == 0) {
        *b = 0;
    } else {
        *b = *b % *a;
    }

    d->cycle += 3;

    ACCT_W(ev_a_addr);
}

OP_IMPL(mdi) {
    OP_BASIC(mdi);
    /* sets b to b%a, signed */

    ACCT_R(ev_b_addr);
    ACCT_R(ev_a_addr);

    if (*a == 0) {
        *b = 0;
    } else {
        *b = (short)*b % (short)*a;
    }

    d->cycle += 3;

    ACCT_W(ev_b_addr);
}

OP_IMPL(and) {
    OP_BASIC(and);
    /* sets b to b&a */

    ACCT_R(ev_b_addr);
    ACCT_R(ev_a_addr);

    *b = *b & *a;

    d->cycle += 1;

    ACCT_W(ev_b_addr);
}

OP_IMPL(bor) {
    OP_BASIC(bor);
    /* sets b to b|a */

    ACCT_R(ev_b_addr);
    ACCT_R(ev_a_addr);

    *b = *b | *a;

    d->cycle += 1;

    ACCT_W(ev_b_addr);
}

OP_IMPL(xor) {
    OP_BASIC(xor);
    /* sets b to b^a */

    ACCT_R(ev_b_addr);
    ACCT_R(ev_a_addr);

    *b = *b ^ *a;

    d->cycle += 1;

    ACCT_W(ev_b_addr);
}

OP_IMPL(shr) {
    OP_BASIC(shr);
    /* sets b to b>>>a, sets EX to ((b<<16)>>a)&0xffff */
    unsigned int acc = *b >> *a;

    ACCT_R(ev_b_addr);
    ACCT_R(ev_a_addr);

    *b = acc & 0xffff;
    d->ex = (*b << 16) >> *a;

    d->cycle += 2;

    WARN("IMPLEMENT");

    ACCT_W(ev_b_addr);
}

OP_IMPL(asr) {
    OP_BASIC(asr);
    /* sets b to b>>a, sets EX to ((b<<16)>>>a)&0xffff (arithmetic shift) (treats b as signed) */
    unsigned int acc = *b << *a;

    ACCT_R(ev_b_addr);
    ACCT_R(ev_a_addr);

    *b = acc & 0xffff;
    d->ex = (*b << 16) >> *a;

    d->cycle += 2;

    WARN("IMPLEMENT");

    ACCT_W(ev_b_addr);
}

OP_IMPL(shl) {
    OP_BASIC(shl);
    /* sets b to b<<a, sets EX to ((b<<a)>>16)&0xffff */
    unsigned int acc = *b << *a;

    ACCT_R(ev_b_addr);
    ACCT_R(ev_a_addr);

    *b = acc;

    d->ex = acc >> 16;

    d->cycle += 2;

    ACCT_W(ev_b_addr);
}

OP_IMPL(ifb) {
    OP_BASIC(ifb);
    /* performs next instruction only if (b&a)!=0 */

    ACCT_R(ev_b_addr);
    ACCT_R(ev_a_addr);

    if ((*b & *a) != 0) {
        /* */
    } else {
        d->skip_ = 1;
        d->cycle += 1;
    }

    d->cycle += 2;
}

OP_IMPL(ifc) {
    OP_BASIC(ifc);
    /* performs next instruction only if (b&a)==0 */

    ACCT_R(ev_b_addr);
    ACCT_R(ev_a_addr);

    if ((*b & *a) == 0) {
        
    } else {
        d->skip_ = 1;
        d->cycle += 1;
    }

    d->cycle += 2;
}

OP_IMPL(ife) {
    OP_BASIC(ife);
    /* performs next instruction only if b==a */

    ACCT_R(ev_b_addr);
    ACCT_R(ev_a_addr);

    if (*b == *a) {
        /* */
    } else {
        d->skip_ = 1;
        d->cycle += 1;
    }

    d->cycle += 2;
}

OP_IMPL(ifn) {
    OP_BASIC(ifn);
    /* performs next instruction only if b!=a */

    ACCT_R(ev_b_addr);
    ACCT_R(ev_a_addr);

    if (*b != *a) {
        /* */
    } else {
        d->skip_ = 1;
        d->cycle++;
    }

    d->cycle += 2;
}

OP_IMPL(ifg) {
    OP_BASIC(ifg);
    /* performs next instruction only if b>a */

    ACCT_R(ev_b_addr);
    ACCT_R(ev_a_addr);

    if (*b > *a) {
        /* */
    } else {
        d->skip_ = 1;
        d->cycle++;
    }

    d->cycle += 2;
}

OP_IMPL(ifa) {
    OP_BASIC(ifa);
    /* performs next instruction only if b>a (signed) */

    ACCT_R(ev_b_addr);
    ACCT_R(ev_a_addr);

    if (*b > *a) {
        /* */
    } else {
        d->skip_ = 1;
        d->cycle += 1;
    }

    d->cycle += 2;
}

OP_IMPL(ifl) {
    OP_BASIC(ifl);
    /* performs next instruction only if b<a */

    ACCT_R(ev_b_addr);
    ACCT_R(ev_a_addr);

    if (*b < *a) {
        /* */
    } else {
        d->skip_ = 1;
        d->cycle++;
    }

    d->cycle += 2;
}

OP_IMPL(ifu) {
    OP_BASIC(ifu);
    /* performs next instruction only if b<a (signed) */

    ACCT_R(ev_b_addr);
    ACCT_R(ev_a_addr);

    if (*b < *a) {
        /* */
    } else {
        d->skip_ = 1;
        d->cycle += 1;
    }

    d->cycle += 2;
}

OP_IMPL(adx) {
    OP_BASIC(adx);
    /* sets b to b+a+EX, sets EX to 0x0001 if overflow, 0x0 otherwise */
    unsigned int acc;

    ACCT_R(ev_b_addr);
    ACCT_R(ev_a_addr);

    acc = *b + *a + d->ex;
    *b = acc & 0xffff;
    if (acc > 0xffff)
        d->ex = 0x0001;
    else
        d->ex = 0x0000;

    d->cycle += 3;

    ACCT_W(ev_b_addr);
}

OP_IMPL(sbx) {
    OP_BASIC(sbx);
    /* sets b to b-a+EX, sets EX to 0xffff if underflow, 0x0 otherwise */
    unsigned int acc;

    ACCT_R(ev_b_addr);
    ACCT_R(ev_a_addr);

    acc = *b - *a + d->ex;
    *b = acc & 0xffff;
    if (acc > 0xffff)
        d->ex = 0xffff;
    else
        d->ex = 0;

    d->cycle += 3;

    ACCT_W(ev_b_addr);
}

OP_IMPL(sti) {
    OP_BASIC(sti);
    /* sets b to a, then increases I and J by 1 */

    ACCT_R(ev_b_addr);
    ACCT_R(ev_a_addr);

    *b = *a;
    d->reg[reg_index_('I')] += 1;
    d->reg[reg_index_('J')] += 1;

    d->cycle += 2;

    ACCT_W(ev_b_addr);
}

OP_IMPL(std) {
    OP_BASIC(std);
    /* sets b to a, then decreases I and J by 1 */

    ACCT_R(ev_b_addr);
    ACCT_R(ev_a_addr);

    *b = *a;
    d->reg[reg_index_('I')] -= 1;
    d->reg[reg_index_('J')] -= 1;

    d->cycle += 2;

    ACCT_W(ev_b_addr);
}

OP_IMPL(_reserved_) {
    OP_BASIC(_reserved_);

    WARN("reserved opcode invoked");

    ACCT_ILL(d->pc - pc_adjust);
}

static const struct opcode_entry opcode_basic_entries[] = {
    {0x00, "(nbi)", op__nbi_},
    {0x01, "SET", op_set },
    {0x02, "ADD", op_add },
    {0x03, "SUB", op_sub },
    {0x04, "MUL", op_mul },
    {0x05, "MLI", op_mli },
    {0x06, "DIV", op_div },
    {0x07, "DVI", op_dvi },
    {0x08, "MOD", op_mod },
    {0x09, "MDI", op_mdi },
    {0x0a, "AND", op_and },
    {0x0b, "BOR", op_bor },
    {0x0c, "XOR", op_xor },
    {0x0d, "SHR", op_shr },
    {0x0e, "ASR", op_asr },
    {0x0f, "SHL", op_shl },
    {0x10, "IFB", op_ifb },
    {0x11, "IFC", op_ifc },
    {0x12, "IFE", op_ife },
    {0x13, "IFN", op_ifn },
    {0x14, "IFG", op_ifg },
    {0x15, "IFA", op_ifa },
    {0x16, "IFL", op_ifl },
    {0x17, "IFU", op_ifu },
    {0x18, "(reserved)", op__reserved_ },
    {0x19, "(reserved)", op__reserved_ },
    {0x1a, "ADX", op_adx },
    {0x1b, "SBX", op_sbx },
    {0x1c, "(reserved)", op__reserved_ },
    {0x1d, "(reserved)", op__reserved_ },
    {0x1e, "STI", op_sti },
    {0x1f, "STD", op_std },
    {0x00, "", NULL }
};

static inline
void dump_operand_value_(DCPU16_WORD value, DCPU16_WORD nextword, unsigned int value_position) {
    if (value <= 0x07) {
        printf(" %c", regnames_[value]);
    } else if (value <= 0x0f) {
        printf(" [%c]", regnames_[value & 0x07]);
    } else if (value <= 0x17) {
        printf(" [0x%04x + %c]", nextword, regnames_[value & 0x07]);
    } else switch (value) {
        case 0x18:
            if (value_position == 0) { /* b */
                printf(" PUSH");
            } else {
                printf(" POP");
            }
            break;
        case 0x19: printf(" PEEK"); break;
        case 0x1a: printf(" PICK 0x%04x", nextword); break;
        case 0x1b: printf(" SP"); break;
        case 0x1c: printf(" PC"); break;
        case 0x1d: printf(" EX"); break;
        case 0x1e: printf(" [0x%04x]", nextword); break;
        case 0x1f: printf(" 0x%04x", nextword); break;
        default:   printf(" 0x%02x", value - 0x21);
    }
}


/* split a sequence of (one to three) words into the components of an instruction */
static inline
void instruction_decode_(DCPU16_WORD *mem, DCPU16_WORD addr,
                         DCPU16_WORD *opcode, DCPU16_WORD *b, DCPU16_WORD **b_data, DCPU16_WORD *a, DCPU16_WORD **a_data,
                         DCPU16_WORD *instr_len) {
    *opcode = *a = *b = mem[addr];
    *opcode = mem[addr] & ((1 << OPCODE_BASIC_BITS) - 1);
    *b = (mem[addr] >> OPCODE_BASIC_BITS) & ((1 << OPCODE_OPERAND_B_BITS) - 1);
    *a = (mem[addr] >> (OPCODE_BASIC_BITS + OPCODE_OPERAND_B_BITS)) & ((1 << OPCODE_OPERAND_A_BITS) - 1);
    *instr_len = 1;

    if ( (*b >= 0x10 && *b <= 0x17) || *b == 0x1e || *b == 0x1f ) {
        *b_data = mem + (DCPU16_WORD)(addr + *instr_len);
        TRACE("**b_data:%hu", **b_data);
        *instr_len += 1;
    } else {
        *b_data = NULL;
    }

    if ( (*opcode != 0x0000 || (*opcode == 0 && *b != 0x0000) )
    &&   ( (*a >= 0x10 && *a <= 0x17) || *a == 0x1e || *a == 0x1f) ) {
        *a_data = mem + (DCPU16_WORD)(addr + *instr_len);
        TRACE("**a_data:%hu", **a_data);
        *instr_len += 1;
    } else {
        *a_data = NULL;
    }

#if 0
    TRACE("\n%s: [0x%04x]:0x%04x op:0x%02x b:0x%02x (b_data:0x%04x) a:0x%02x (a_data:0x%04x) len:0x%02x\n",
            __func__, 
            addr,
            mem[addr],
            *opcode,
            *b,
            *b_data ? **b_data : 0,
            *a,
            *a_data ? **a_data : 0,
            *instr_len);
#endif
}

/*  dcpu16_mnemonify_buf
    print words as words
 */
DCPU16_WORD dcpu16_mnemonify_buf(DCPU16_WORD *buf) {
    DCPU16_WORD opcode, b, a, instr_len, *b_data, *a_data;
    const struct opcode_entry *e;

    instruction_decode_(buf, 0, &opcode, &b, &b_data, &a, &a_data, &instr_len);

    if (opcode == 0x0000)
        e = opcode_nbi_entries +
            ( (b < OPCODE_NBI_MAX) ? b : (OPCODE_NBI_MAX - 1) );
    else
        e = opcode_basic_entries + opcode;
    printf("%s", e->name);

    if (opcode) {
        dump_operand_value_(b, b_data ? *b_data : 0, 0);
        printf(",");
    }

    if (opcode || b) {
        dump_operand_value_(a, a_data ? *a_data : 0, 1);
    }

    return instr_len;
}

/*  dcpu16_disassemble_print
    print the words of the instruction at addr, followed by its assembly representation
    returns the length of the instruction in words
 */
DCPU16_WORD dcpu16_disassemble_print(struct dcpu16 *d, DCPU16_WORD addr) {
    DCPU16_WORD opcode, b, a, instr_len, i, *b_data, *a_data;
    DCPU16_WORD buf[3] = { d->ram[addr], d->ram[(DCPU16_WORD)(addr + 1)], d->ram[(DCPU16_WORD)(addr + 2)] };
    unsigned int indent = 0;
    unsigned int partial = 0;

    if (!d) return 0;

#if 0
    /*
        Check the previous instruction, to see if this one should be
        indented.  This check isn't foolproof, as preceeding addresses
        could be data which happen to match instructions..
    */
    for (i = 3; i; i--) {
        instruction_decode_(d->ram, (DCPU16_WORD)(addr - i), &opcode, &b, &b_data, &a, &a_data, &instr_len);
        if (instr_len > i)
            partial++;
        if (instr_len == i
        &&  (opcode >= 0x10 && opcode <= 0x17) ) {
            indent++;
            break;
        }
    }
#endif

    /* just need instr_len */
    instruction_decode_(d->ram, addr, &opcode, &b, &b_data, &a, &a_data, &instr_len);

    /* show the raw words */
    printf("%04x", d->ram[addr]);
    for (i = 1; i < instr_len; i++) {
        printf(" %04x", d->ram[addr + i]);
    }

    /* align things neatly, show the instruction */
    printf("%s%s ;%s%s",
           instr_len < 3 ? "     " : "",
           instr_len < 2 ? "     " : "",
           partial ? "*" : " ",
           indent ? "  " : "");

    dcpu16_mnemonify_buf(buf);

    return instr_len;
}

/* execute the next instruction */
void dcpu16_step(struct dcpu16 *d) {
    DCPU16_WORD opcode, b, a, instr_len, *b_data, *a_data;
    const struct opcode_entry *e;

    if (!d) return;

    acct_event_(d, DCPU16_ACCT_EV_CYCLE, d->pc);

    /* if we're currently servicing interrupts */
    if (d->interrupts_deferred_ == 0) {
        /* and there are interrupts to be serviced */
        if (d->interrupts_head_ != d->interrupts_tail_) {
            DCPU16_WORD message;
            message = interrupt_dequeue_(d);

            if (d->ia) {
                TRACE("servicing interrupt IA:0x%04x message:0x%04x \n", d->ia, message);
                /* then service the next interrupt */
                d->interrupts_deferred_ = 1;
                d->ram[--d->sp] = d->pc;
                d->ram[--d->sp] = d->reg[reg_index_('A')];
                d->pc = d->ia;
                d->reg[0] = message;
            } else {
                TRACE("ignoring interrupt IA:0");
            }
        }
    }

    /* and make sure to execute an instruction after an interrupt */

    instruction_decode_(d->ram, d->pc, &opcode, &b, &b_data, &a, &a_data, &instr_len);

    for (e = opcode_basic_entries; e->impl; e++) {
        if (e->value == opcode) {
            TRACE("%s>> %s 0x%04x, 0x%04x", __func__, e->name, b, a);
            e->impl(d, b, b_data ? *b_data : 0, a, a_data ? *a_data : 0);
            break;
        }
    }

    /* get ready for the next one */
    d->pc += instr_len;

    /* and jump over next instr(s) if needed */
    if (d->skip_) {
        instruction_decode_(d->ram, d->pc, &opcode, &b, &b_data, &a, &a_data, &instr_len);
        d->pc += instr_len;
        TRACE("++ SKIPPED %x words", instr_len);
        if (opcode >= 0x10 && opcode <= 0x17) {
            /* skipping a branch instruction? skip branch's skippable instruction as well */
            d->cycle += 1;
            instruction_decode_(d->ram, d->pc, &opcode, &b, &b_data, &a, &a_data, &instr_len);
            d->pc += instr_len;
            TRACE("++ SKIPPED %x words", instr_len);
        }
        d->skip_ = 0;
    }
}

/*
    print the current state of the machine
    shows current cycle count, registers, and next instruction
*/
void dcpu16_state_print(struct dcpu16 *d) {
    unsigned int i;

    if (!d) return;

    printf("  ");
    for (i = 0; i < 8; i++)
        printf("  %c:0x%04x", regnames_[i], d->reg[i]);
    printf("\n");

    printf("(0x%08llx) %2s:0x%04x %2s:0x%04x %2s:0x%04x %2s:0x%04x [%2s]:",
           d->cycle,
           "EX", d->ex,
           "SP", d->sp,
           "PC", d->pc,
           "IA", d->ia,
           "PC");

    dcpu16_disassemble_print(d, d->pc);
    printf("\n");
}

/*  dcpu16_dump_ram
 *  print raw ram contents from start to stop
 */
void dcpu16_dump_ram(struct dcpu16 *d, DCPU16_WORD start, DCPU16_WORD end) {
    unsigned int i, j;
    const unsigned int n = 8; /* words per line */

    if (!d) return;

    for (i = start, j = 0; i <= end; i++, j++) {
        if (j % n == 0)
            printf("0x%04x:\t", i);
        printf(" %04x%s", d->ram[i], (j % n) == (n - 1) ? "\n" : "");
    }
    if ((j % n) != (n - 1))
        printf("\n");
}

/*  dcpu16_hw_add
 *  registers new 'hardware' device with system
 */
int dcpu16_hw_add(struct dcpu16 *vm, struct dcpu16_hw *hw) {
    if (!vm || !hw)
        return -1;

    if (vm->hw_table_entries_ == vm->hw_table_allocated_) {
        size_t new_entries = vm->hw_table_allocated_ + 32;
        void *tmp_ptr = realloc(vm->hw_table_, new_entries * sizeof * (vm->hw_table_));
        if (tmp_ptr == NULL) {
            fprintf(stderr, "%s():%s", "realloc", strerror(errno));
            return -1;
        }
        vm->hw_table_ = tmp_ptr;
        vm->hw_table_allocated_ += 32;
    }

    memcpy(vm->hw_table_ + vm->hw_table_entries_, hw, sizeof *hw);
    vm->hw_table_entries_++;

    return 0;
}

/*  dcpu16_acct_add
 *  Register callback fn to be triggered whenever event matching any events
 *  in bitwise mask occur.
 */
int dcpu16_acct_add(struct dcpu16 *vm, dcpu16_acct_event mask, dcpu16_ev_cb_t *fn, void *data) {
    struct dcpu16_acct_cb cb;

    cb.mask = mask;
    cb.fn = fn;
    cb.data = data;

    if (vm->cb_table_entries_ == vm->cb_table_allocated_) {
        size_t new_entries = vm->cb_table_allocated_ + 32;
        void *tmp_ptr = realloc(vm->cb_table_, new_entries * sizeof *(vm->cb_table_));
        if (tmp_ptr == NULL) {
            fprintf(stderr, "%s():%s", "realloc", strerror(errno));
            return -1;
        }
        vm->cb_table_ = tmp_ptr;
        vm->cb_table_allocated_ += 32;
    }

    memcpy(vm->cb_table_ + vm->cb_table_entries_, &cb, sizeof cb);
    vm->cb_table_entries_++;

    return 0;
}

/*  dcpu16_reset
 *  signals cpu to reset, clearing runstate and ram, then reload any init callbacks
 */
void dcpu16_reset(struct dcpu16 *d) {
    if (!d) return;

    d->cycle = 0;
    memset(d->reg, 0, sizeof d->reg);
    d->pc = 0;
    d->sp = 0;
    d->ex = 0;
    d->ia = 0;
    d->skip_ = 0;
    memset(d->ram, 0, sizeof d->ram);

    acct_event_(d, DCPU16_ACCT_EV_RESET, 0);
}

/*  dcpu16_new
 *  allocate a new dcpu16 instance
 */
struct dcpu16 *dcpu16_new(void) {
    struct dcpu16 *vm;

    vm = calloc(1, sizeof *vm);
    if (vm == NULL)
        WARN("%s: %s(%zu): %s", __func__, "calloc", strerror(errno));

    return vm;
}

/*  dcpu16_delete
 *  release a dcpu16 instance
 */
void dcpu16_delete(struct dcpu16 **vm) {
    if (!vm || !*vm) return;

    free(*vm);
    *vm = NULL;
}