/* asm.h -- slot packer for hand-assembled test programs.
 *
 * This is not the compiler capsule (JUSTIFICATION.md section 9).  It exists so
 * that tests can write a DECOMPOSITION.md definition opcode by opcode and have
 * the slots, literals and branch targets laid out the way section 1.2 and
 * section 2 require, instead of packing words by hand in every test.
 *
 * Layout rules it applies:
 *
 *   - Opcodes fill slots 0..5 left to right; a full word is written out and a
 *     new one started.  Unused slots are padded with `nop`.
 *   - A literal is `@p` in a slot plus its value in the word after the
 *     instruction word.  Several literals in one word follow it in order.
 *   - `;` and `ex` close the word, since nothing after them executes.
 *   - A branch closes the word, since the bits to its right are its address.
 *     If the next free slot is 4 or 5 the word is closed first, because
 *     branches are legal in slots 0-3 only.
 *   - A branch target must lie in the same page as P at the time the branch
 *     executes, for the reach of the slot it landed in.  Otherwise the
 *     assembler sets its error flag rather than emit a branch that goes
 *     somewhere else.
 */
#ifndef V4_ASM_H
#define V4_ASM_H

#include "v4/iword.h"
#include "v4/node.h"

typedef struct {
    v4_node *n;
    v4_cell  here;                    /* address of the word being built */
    v4_iword cur;
    unsigned slot;                    /* next free slot, 0..V4_SLOT_COUNT */
    v4_cell  lit[V4_SLOT_COUNT];      /* literals owed after this word */
    unsigned nlit;
    int      error;
} v4_asm;

/* A branch whose target is not known yet. */
typedef struct {
    v4_cell  addr;                    /* the word holding the branch */
    unsigned slot;
    v4_cell  p;                       /* P when the branch executes */
} v4_asm_ref;

void v4_asm_begin(v4_asm *as, v4_node *n, v4_cell origin);

/* Any opcode that is neither a branch nor `@p`. */
void v4_asm_op(v4_asm *as, unsigned op);

/* `@p` and its value. */
void v4_asm_lit(v4_asm *as, v4_cell value);

/* jump, call, next, if, -if to a known address. */
void v4_asm_branch(v4_asm *as, unsigned op, v4_cell target);

/* The same with the target supplied later by v4_asm_resolve. */
v4_asm_ref v4_asm_branch_fwd(v4_asm *as, unsigned op);
void       v4_asm_resolve(v4_asm *as, v4_asm_ref ref, v4_cell target);

/* Close the word being built and return the address of the next one.  This is
 * how a label is taken: branch targets are word addresses. */
v4_cell v4_asm_label(v4_asm *as);

/* 1 if nothing went wrong so far.  Closes the word being built. */
int v4_asm_ok(v4_asm *as);

#endif /* V4_ASM_H */