资源说明：A high-level assembly language for writing homebrew software and games on retro console platforms.

wiz
===

**by Andrew G. Crowell**

Wiz is a high-level assembly language for writing homebrew software for retro console platforms.

Contact
-------

- Please report issues in the GitHub issue tracker.
- Project Website: 
- Project Discord: 
- Project GitHub: 
- My Twitter: 
- My Email: eggboycolor AT gmail DOT com
- My Github: 

Features
--------

Wiz is intended to cross-compile programs that run on specific hardware, as opposed to an abstract machine which requires a runtime library to support it. This means programs must be written with the feature set and limitations of the system being targeted in mind (registers, addressing modes, limitations on instructions), and programs are highly platform-dependent.

Here are some features that Wiz supports:

- Familiar high-level syntax and structured programming features, such as `if`, `while`, `for`, `do`/`while`, functions, etc.
- Static type system that supports integers, structures, arrays, pointers, and other types. Supports automatic type inference for initializers.
- Expressions and statements that map directly to low-level instructions.
- Raw access to the hardware. Low-level register and memory access, branching, stack manipulation, comparison, bit-twiddling, I/O, etc.
- Compile-time attributes, inlining, constant expression folding, conditional compilation, array comprehensions.
- Support for multiple different systems and output file formats.
- `bank` declarations to customize memory map and output.
- `const` and `writeonly` modifiers to prevent undesired access to memory.

Wiz supports several different CPU architectures, with hopes to support more platforms in the future!

- `6502` - MOS 6502 (used by the NES, C64, Atari 2600/5200/7800/8-bit, Apple II)
- `65c02` - MOS 65C02
- `wdc65c02` - WDC 65C02
- `rockwell65c02` - Rockwell 65C02
- `huc6280` - HuC6280 (used by the PC Engine / TurboGrafx-16)
- `wdc65816` - WDC 65816 (used by the SNES, SA-1, Apple IIgs)
- `spc700` - SPC700 (used by the SNES APU)
- `z80` - Zilog Z80 (used by the Sega Master System, Game Gear, MSX, ZX, etc)
- `gb` - Game Boy CPU / DMG-CPU / GBZ80 / SM83 / LR35902 (used by the Game Boy and Game Boy Color)

Wiz has built-in support for many ROM formats, and provides conveniences for configuring headers, and for automatically filling in checksums and rounding up ROM sizes. In some case the CPU architecture can be automatically detected by the output format. It currently exports the following output formats:

- `.bin` (raw binary format -- supports optional trimming)
- `.nes` (NES / Famicom - header config, auto-pad)
- `.gb`, `.gbc` (Game Boy - header config, auto-checksum, auto-pad)
- `.sms`, `.gg` (Sega Master System - header config, auto-checksum, auto-pad)
- `.sfc`, `.smc` (SNES / Super Famicom - header config, auto-checksum, auto-pad)
- `.pce` (TurboGrafx-16 / PC Engine)
- `.a26` (Atari 2600)

Using Wiz
---------

Usage:

```bash
wiz [options] 
```

Arguments:

- `input` - the name of the input file to load. A filename of `-` implies the standard input stream.
- `-o filename` or `--output=filename` - the name of the output file to produce. the file extension determines the output format, and can sometimes automatically suggest a target system.
- `-m sys` or `--system=sys` - specifies the target system that the program is being built for. Supported systems: `6502`, `65c02` `rockwell65c02`, `wdc65c02`, `huc6280`, `z80`, `gb`, `wdc65816`, `spc700`
- `-I dir` or `--import-dir=dir` - adds a directory to search for `import` and `embed` statements.
- `--color=setting` - sets the color preference for the terminal (Defaults to `auto`). `auto` will automatically detects if a TTY is attached, and only emits color escapes when there is one. `none` disables color. `ansi` will always use ANSI-escapes, even if no TTY is detected, or if the terminal uses different method of coloring (eg. Windows console).
- `--help` - lists a help message.
- `--version` - lists the current compiler version.

Example invocation:

```bash
wiz hello.wiz --system=6502 -o hello.nes
```

Getting Started
---------------

For now, please consult the example folder to see how Wiz can be used, or failing that, the compiler source code. Additional documentation isn't ready yet. In the future, there are plans to have a language reference, a reference for the instruction capabilities of each target, and tutorials showing how to make stuff. Help here is greatly appreciated!

For help with editing Wiz files:

- In *VS Code* install the extension "Wiz Language Support" from the extension marketplace.
- In *Sublime Text* the file `syntax/sublime2/wiz.tmLanguage` (in this repo) goes in your packages folder which you can open from Sublime Text by going to Preferences > Browse Packages.

Building Source
---------------

NOTE: All build instructions require a C++14, C++17, or later compiler. It will not build with an earlier version of the standard.

### Windows (Visual Studio)

- Install Visual Studio 2019 or later.
- Open `vc/wiz.sln` in Visual Studio. Build the solution.
- If the build succeeds, a file named `wiz.exe` should exist in the `bin/` folder under the root of this repository.

### Windows (mingw)

- Install MinGW-w64. 
- Install GnuWin32 "Make for Windows". 
- Open a terminal window, such as the Command Prompt (cmd) or something else.
- Run `make` in the terminal. For a debug target, run `make CFG=debug` instead. Feel free to add `-j8` or similar to build faster.
- If the build succeeds, a file named `wiz.exe` should exist in the `bin/` folder under the root of this repository.

### Windows (Cygwin)

- Install Cygwin
- Within Cygwin, install either GCC or Clang, and install GNU Make.
- Open a terminal window.
- Run `make` in the terminal. For a debug target, run `make CFG=debug` instead. Feel free to add `-j8` or similar to build faster.
- If the build succeeds, a file named `wiz.exe` should exist in the `bin/` folder under the root of this repository.
- NOTE: This exe produced in this fashion will require Cygwin, so it is not preferred for native Windows executable compilation.

### Mac OS X

- Install Xcode and install Command Line Tools.
- Open a terminal window.
- Run `make` in the terminal. For a debug target, run `make CFG=debug` instead. Feel free to add `-j8` or similar to build faster.
- If the build succeeds, a file named `wiz` should exist in the `bin/` folder under the root of this repository.

### Linux

- Install GCC or Clang.
- Install GNU Make.
- Run `make` in the terminal. For a debug target, run `make CFG=debug` instead. Feel free to add `-j8` or similar to build faster.
- If the build succeeds, a file named `wiz` should exist in the `bin/` folder under the root of this repository.

### Web / Emscripten

- Install emscripten.
- Install GNU Make.
- Run `make PLATFORM=emcc` in the terminal. For a debug target, run `make CFG=debug PLATFORM=emcc` instead.
- If the build succeeds, a file named `wiz.js` should exist in the `bin/` folder under the root of this repository.
- Copy the `bin/wiz.js` over `try-in-browser/wiz.js` to update the version used by the HTML try-in-browser sandbox.
- See the `try-in-browser/` test page for an example program that wraps the web version of the compiler.
- Note that the license of JSNES (JavaScript Nintendo emulator) is GPL, and if distributed with the try-in-browser code, the other code must be released under the GPL. However, the non-emulator code in this folder is explicitly MIT, so remove this emulator dependency if these licensing terms are desired.

Installing
----------

You don't need to install Wiz in order to use it. But if you want, you can install the compiler binary to your system path so that you can more easily use it. Wiz is currently only a single executable, and there are no standard libraries yet. It just has optional examples that are used by some test programs but they're not essential to running the compiler. Maybe down the road, this will change. In any case, here's some help.

### Windows

- First acquire `wiz.exe` for your platform or build it.
- Create a folder for Wiz.
- Copy `wiz.exe` into that folder.
- Add that folder to your `PATH` environment variable.
- Close and reopen any command window you had open.
- You should be now able to execute `wiz` from any folder, not just the one that contains it.

### Mac OS X, Linux

- First acquire `wiz` for your platform or build it.
- If you're using the makefile, you can use `make install` to install `wiz` to the system install location. (defaults to `/usr/local/bin` but can be customized via the `DESTDIR` and `PREFIX` variables)
- Alternatively, copy the `wiz` executable into your preferred install folder (eg. `/usr/local/bin` or wherever else)

Language Quick Guide
--------------------

This is a quick run-down of language features. This section is largely unfinished, so please consult example programs for better documentation!

### Banks

Banks are sections or segments that are used to hold the different pieces of the program, such as variables, constants, or executable code.

A bank declaration reserves a bank of memory with a given type and address. It has the following syntax:

```
bank name @ address, name @ address, name @ address : [type; size];
```

The type of bank of `bank` determines what kind of declarations can be placed there.

- `vardata` is uninitialized RAM. useful for variables that can be written to and read back at runtime. Because this section is uninitialized, variables declared here must be assigned a value at execution time. Because of these limitations, compiled code and and constant data cannot be placed here.
- `prgdata` is ROM used for program code and constants. Cannot be written to.
- `constdata` is ROM used for constants and program code. Cannot be written to.
- `chrdata` is ROM used for character / tile graphic data. This type of bank has a special meaning on platforms like the NES, where character data is on a separate memory bus. It is otherwise the same as `constdata`.
- The distinction between `prgdata` and `constdata` will only exist on Harvard architectures, where the program and constant data live on separate buses. Otherwise, just use it for clarifying the purpose of ROM banks, if it matters.
- `varinitdata` is initialized RAM. Useful for programs with code and data that get uploaded to RAM.

The size of a `bank` is the number of bytes that it will hold. Exceeding this size limitation is considered an error.

The address of a `bank` after the `@` is optional but if it appears, it must be an integer literal. Without an address, the `bank` can cannot contain label declarations.

After a bank is declared, it must be selected to be used by an `in` directive.

```
in bank {
    // ...
}
```

An address can also be provided to an `in` directive. If a `bank` previously had no address, then the address becomes the origin of the `bank`. However, if a `bank` previously had an address, the block is seeked ahead for to given address.

```
in bank @ address {
    // ...
}
```

Example:

```
bank zeropage @ 0x00 : [vardata; 256];

in zeropage {
    var timer : u8;
}
```

### Constants

A constant declaration reserves pre-initialized data that can't be written to at run-time. A constant can appear in a ROM bank, such as `prgdata`, `constdata`, or `chrdata`.

```
const name : type = value;
```

Example:
```
const hp : u8 = 100;
const wow : [u8] = [0, 1, 2, 3, 4, 5, 6];
const egg : [u16; 5] = [12345, 54321, 32333, 49293];
```

If the type is provided, the initializer is narrowed to the type provided. This means that integer initializers of type `iexpr` that have no size can be implicitly narrowed to sized integer types like `u8`, and array initializers of type `[iexpr]` can be narrowed to `[u8]`, and so on.

Note that The size of an array type can be left off, if the tyep.

If the type of a constant can be inferred from the value, then the type can be left off. However, only types with a known size can be constants. `iexpr` has unknown size, so type-suffixes on integers may be required.

Example:

```
const length = 100u8;
const message = "HELLO WORLD";
const table = embed "table.bin";
```

The name of a constant is also optional, when placing data in the ROM is desired but a label to it isn't needed.

Example:

```
const = embed "hero.chr";
```

Array comprehensions are a nice way to generate tables of data.

```
const tripled_values : [u8] = [x * 3 for let x in 0 .. 49];
```

### Variables

A variable declaration reserves a space for mutable storage. A variable can appear either in RAM bank such as `vardata`, or `varinitdata`.

```
var x : u8;
```

A variable declared in a `varinitdata` bank is allowed to have a initializer.

```
var x = 100;
```

If an initializer is given, the type can be omitted if the initializer expression has a type of known size.

```
var x =
var message = "hello";
```

A variable declared in a `vardata` bank, on the other hand, is reserved in uninitialized RAM, so it cannot have an initializer and can only be assigned a value at run-time.

### Extern Variables (Memory Mapped I/O Registers)

An `extern` variable can be used to declare a piece of external storage that exists at a specific address. Its primary use is for defining memory-mapped I/O registers on a system, so that they can referenced by name.

Example:

```
extern var reg @ 0xF000; // read/write
extern writeonly reg2 @ 0xF001; // write-only
extern const reg3 @ 0xF002; // read-only
```

### Let Definitions

A `let` definition can be used to bind a name to a constant expression. This can reduce the amount of magic numbers appearing in code. These don't require any ROM space where they're defined, but are instead are substituted into whatever expressions that use them.

```
let name = expression;
```

The expression of a `let` definition can be any valid expression. It is recommended to not pass expressions that contain
 side-effects. In the future, the compiler may forbid this, but for now this is not validated.

Example:

```
let HP = 100;
let NAME = "Hello";
```

It is also for a `let` definition to take arguments:

```
let CEILING_DIV(x, y) = (x + y - 1) / y;
let MAP_WIDTH = CEILING_DIV(1000, 8);
```

### Empty Statement

A single `;` is allowed anywhere, and is an empty statement. It has no effect.

### Assignment Statement

An assignment statement is used to store a value somewhere. Depending on where the value is stored, it can be retrieved again later.

```
dest = source; // assignment
dest += source; // compound assignment
dest++; // post-increment
dest--; // post-decrement
++dest; // pre-increment
--dest; // pre-decrement
```

The left-hand side of an assignment `=` is the destination, which can be a mutable register or a mutable location in memory. The right-hand side of an assignment `=` is the source, which can be a constant, a register, a readable memory location, or a run-time calculation. The source and destination must be of compatible type, or it is an error.

Example:

```
x = 100;
a = max_hp - hp;
damage = a;
```

After constant expression folding, any remaining run-time operations must have instructions available for them. It must be either an exact instruction that does the calcuation and stores it in the destination, or a series of instructions that first load the into the destination, and then modify the destination. For an assignment containing a binary expression like `a = b + c;`, instruction selection will first look for an exact instruction of form `a = b + c;`. Failing that, it will attempt decomposing the assignment `a = b + c` into the form `a = b; a = a + c;`.

Failing that, it is an error, and will probably require the assignment to be manually re-written in terms of multiple assignment statements. Assignments containing run-time operations cannot require an implicit temporary expression, or it is an error.

Most expressions are evaluated in left-to-right fashion, and as a result, they must be written so that they can be left-folded without temporaries. This requirement means parenthesized expressions can happen on the left, but the right-hand side will be a constant or simple term.

Example:

```
// This is OK, because it can be decomposed.
a = (5 + c) - b;
// The above becomes:
// a = 5;
// a = a + c
// a = a - b;

// This is an error, even in its reduced form:
a = b - (5 + c);
// The above becomes:
// a = b;
// a = a - (5 + c) // the (5 + c) requires a temporary.
```

Oftentimes, it won't be possible to assign a value directly to memory. In these cases, the code will need to put an intermediate assignment into a register first, and then store the register into the memory afterwards.

Example:

```
// If there's no instruction available to assign immediate values to memory, this line will be an error.
hp = 100;

// It must be re-written to use a register in the middle.
// This will work if there is a register named a,
// and there is an instruction to load an immediate to register a,
// and there is another instruction to load memory with the value of the register.
a = 100;
hp = a;
```

Assignments can be chained together if they're compatible.

Example:

```
// This is the same as:
// a = x;
// y = a;
y = a = x;

// This is the same as:
// a = hp;
// a = a - 10;
// hp = a;
hp = a = hp - 10;
```

Compound assignment operators exist for most binary arithmetic operations. For some operation `+`, the statement `a += b` is the same as writing `a = a + b;`. If the right-hand side contains a calculation it is implicitly parenthesized, so that `a += b + c` is the same as `a = a + (b + c);`

Example:

```
a += 5; // same as a = a + 5;
```

There are also unary incrementation `++` and decrementation `--` operators.

Example:

```
x++;
y--;
++x;
++y;
```

Sometimes assignments might be used for their side-effects only, such as when writing to an external hardware register. Some such registers are `writeonly`, which indicates that they cannot be read back later, or that reading back will produce an open-bus value.

```
snes.ppu.bg_mode = a;
```

Similarly, there can be side-effects that occur when reading an external hardware register.

Assignments may also result in processor status flag registers being changed as a side-effect. Sometimes, a throw-away calculation in some registers or temporary memory might be performed simply to affect a conditional flag. The effect on flags depends on what sequence of instructions are generated as a result of the assignment. Not every operation affects every flag consistently, due to the design of the processor hardware. Knowing what instructions affect flags and which don't requires some study.

A common-to-find flag is the `zero` flag. If an instruction affects the zero flag, it might be used to indicate whether the result of the last operation was equal to zero. This side-effect can be used sometimes to avoid an extra comparison instruction later.

Example:

```
x = 10;
do {
    x--;
} while !zero;
```

A `carry` flag is a common flag to be affected by arithmetic operations such as addition/subtraction. The interpretation of a `carry` flag is dependent on the system. There are operations like add with carry `+#`, subtract with carry `-#`, rotate left with carry `<<<<#`, and rotate right with carry `>>>>#` which depend upon the last state of the `carry`. These operations can be useful for extending arithmetic operations to work on larger numeric values.

Example:

```
// add 0x0134 to bc.
c = a = c + 0x34;
b = a = b +# 0x01;
```

Some CPUs allow the `carry` to be set or cleared by assigning to it.

Examples:

```
carry = false;
carry = true;
```

### Call Statement

A call statement is a kind of statement that invokes a function. If the function being called produces a return value, the value is discarded. If the function call returns, the code following it will execute. Intrinsic instructions can also be called in the same manner.

```
function(argument1, argument2, argument3);
```

### Block Statement

A block statement is a scoped section of code that contains a collection of statements. It is started with an opening brace `{` and must be terminated later with a closing brace `}`. All declarations within.

Many types of statement contain block statements as part of their syntax. For these kinds of statements, the braces delimiting a block statement are not optional, even if only a single statement is present.

### If Statement

An `if` statement allows a block of code to be executed conditionally. The condition of an `if` statement is some expression of type `bool`. If a condition evaluates to `true`, then the block directly following it is executed. Otherwise, the block immediately following the condition is skipped, and the next alternative delimited by an `else if` is evaluated. Finally, there is `else` when all other alternatives have evaluated to `false`.

```
if condition {
    statements;
} else if condition {
    statements;
} else {
    statements;
}
```

A conditional expression can be a register term of type `bool` or its negation, or some combination of multiple `bool` operands with `&&` and `||` operators

Example:

```
a = hp;
if zero {
    dead();
}
```

There are also high-level operators for comparison: `==`, `!=`, `<`, `>=`, `>`, `<=`. Which kinds of comparisons are possible, and which registers can perform comparisons, depends on the target system.

Example:

```
a = gold;
x = item_index;

if a >= item_cost[x] {
    a -= item_cost[x];
    gold = a;
    buy_item(x);
} else {
    not_enough();
}
```

A conditional statement can also use "side-effect expressions" that evaluate some operation as required before a conditional expression. This sort of "setup-and-test" conditional can make some code read better, used carefully.

Example:

```
if { a = attack - defense; } && (carry || zero) {
    block_attack();
}
```

It is possible to use bit-indexing `$` to test a single-bit of a value and get its boolean result. Which registers are capable of this, as well as the bits that can be selected, depends on the target system.

Example:

```
if b$7 {
    vertical_flip();
} else if b$6 {
    horizontal_flip();
}
```

### While Statement

A `while` statement allows a block of code to be executed conditionally 0 or more times. The block is repeated as long as the condition provided still evaluates to `true`.

```
while condition {
    statement;
    statement;
    statement;
}
```

Example:

```
x = count;
while !zero {
    beep();
    x--;
}
```

### Do/While Statement

A `do` ... `while` statement allows a block of code to be executed unconditionally once, followed by conditional execution 0 or more times. The block is entered once, and will repeat more times as long as the condition provided still evaluates to `true`.

```
do {
    statement;
    statement;
    statement;
} while condition;
```

Note that `do` ... `while` statements are slightly more efficient than `while` statements, because they fall-through to the next code once the condition is `false`, and only jump to the top of the loop if the condition is still `true`.

### For Statement

A `for` statement allows iteration over a sequence of values, and executes a block of code for each step through the sequence.

```
for iterator in iterable {
    statement;
    statement;
    statement;
}
```

Currently, `for` loops only support iteration on comple-time integer ranges.

```
for counter in start .. end {
    statement;
    statement;
    statement;
}

for counter in start .. end by step {
    statement;
    statement;
    statement;
}
```

Example:

```
for x in 0 .. 31 {
    beep();
}
```


`start .. end` is an inclusive range. If the loop terminates normally, then after the loop, the counter provided will have the first value that is outside of the sequence.

Example:

```
// x is a u8 register that can be incremented and decremented.

// x will now be 32.
for x in 0 .. 31 {
    // ...
}

// x will be 0 after the loop.
for x in 31 .. 0 by -1 {
    // ...
}

// x will be 0 after the loop.
for x in 0 .. 255 {
    // ...
}
```

### Return Statements

A `return` statement is used to return from the currently executing function.

```
return;
return if condition;
```

If used in a function that has no return type, it cannot have a return value. If used in a function that has a return type, the return value must be of the same type.

Example:

```
func collect_egg() {
    a = egg_count;
    if a >= 5 {
        return;
    }

    egg_count++;
}

func triple(value : u8 in b) : u8 in a {
    return b + b + b;
}
```

A `return` that exists outside of any function body is a low-level `return` instruction. This would pop a location from the stack and jump there.

### Tail-Call Statements

A statement of form `return f();` is a tail-call statement. It gets subsituted for a `goto`, and avoids the overhead of subroutine call that would push a program counter to the stack. However, unlike a `goto`, a tail-call will evaluate arguments to a function, like a normal function call.

```
func call_subroutine(dest : u16 in hl) {
    goto *(dest as *func);
}
```

### Goto Statements

A `goto` is a low-level form of branching which jumps to another part of the program. Most high-level control structures are internally implemented in terms of `goto`.

```
goto destination;
goto destination if condition;
```

The destination of a `goto` can be a label, a function, or a function pointer expression.

Example:

```
x--; goto there if zero;

loop:
    goto loop;

there:
```

Code that uses `goto` should ensure that everything is already set up correctly before branching, because `goto` does not pass any arguments to its destination. If a `goto` that passes arguments to a function is required, use a tail-call statement of form `return f(arg, arg, arg)` instead.

### Break and Continue

Loop statements such as `while`, `do` ... `while`, `for` have two forms of branching statements in their blocks: `break` and `continue`.

```
break;
continue;
break if condition;
continue if condition;
```

A `break` statement will terminate a loop early, and jump ahead to the code that immediately follows a loop's block.

A `continue` statement will skip to the next iteration of the loop. In `for` loops, this will skip to the code that performs an increment and branch. In `while` and `do` ... `while` loops, this will skip to the conditional branch of the loop.

### Functions and Labels

A function is a piece of code that performs a specific set of actions and operations. They can be executed by other parts of the program, and can take arguments and produce a return value.

```
func f(arg : argument_type, arg2 : argument_type2, arg3 : argument_type3) : return_type {
    statement;
    statement;
    statement;
}
```

Example:

```
func poke(dest : u16 in hl, value : u8 in a) {
    *(dest as *u8) = a;
}

func sum(left : u8 in b, right : u8 in c) : u8 in a {
    return left + right;
}
```

Labels are like functions, but will never return, and cannot be passed arguments. As a low-level detail, labels of form `f:` are effectively the same thing as an empty-fallthrough function `#[fallthrough] func f() {}` placed directly before whatever code is executed. A label can be used in any bank that has a known address. (An address is currently required, but eventually, this requirement could relaxed to allow banks which use relative addressing only.)

Example:

```
label:
    goto label;
```

Labels or functions can be the target of call expressions, or `goto` statements.

### Inline Functions

An `inline func` is like `func` but inlined directly wherever it is used. As a consequence, the contents of the function are inserted wherever it is called, and the function has no address.

Example:

```
inline func times_two() {
    a = a << 1;
}

a = 20;
times_two();
times_two();
```

An `inline func` can still `return`, like a normal function. However, it will not use the stack. Instead, it will jump to a hidden return label that exists at the end of the function.

Because an `inline func` has no address, an `inline func` cannot be stored in a function pointer, and cannot be branched to from a `goto` or tail-call statement.

### Inline For Statement

An `inline for` allows unrolling a loop at compile-time. The iterator of the loop is optional but exists only for the scope of the `inline for` block. The value of the iteration at each iteration can be used by expressions within the loop.

```
inline for let iterator in iterable {
    statement;
    statement;
    statement;
}

inline for in iterable {
    statement;
    statement;
    statement;
}
```

Unlike a normal `for` statement, other iterables like arrays can be used as an iterable.

Example:

```
inline for let i in 1 .. 3 {
    hoot(i);
}

inline for in 1 .. 100 {
    nop();
}

inline for let i in [1, 2, 8, 10, 5, 3, 1] {
    y = i;
    draw();
}
```

### Attributes

Attributes are a form of special metadata that can be placed before a statement, directive, or declaration. They can provide the compiler with extra details about a particular piece of code.

Example:

```
#[fallthrough] func lasagna() {
    idx8();
    #[idx8] {
        x = 9;
    }

    idx16();
    #[idx16] {
        xx = 99;
        yy = xx;
    }

    while true {}
}

#[nmi] func vblank() {
    // ...
}

let INCLUDE_THIS_MESSAGE = true;

#[compile_if(INCLUDE_THIS_MESSAGE)] const message = "HI THIS IS A CONDITIONALLY COMPILED MESSAGE";

```

Attributes

- `compile_if(condition)` - indicates that some code should only be compiled if a particular compile-time boolean condition is `true`. If the condition is `false`, the code tagged with the attribute is not emitted.
- `fallthrough` - indicates the function might fall through into the immediately following code, and disables the implicit return at the end of the function. Useful for tagging functions that are guaranteed to never return, or functions that are meant to fall into some other code afterwards.
- `nmi` - indicates that a function handles a non-maskable interrupt request. All `return;` instructions will be translated into `nmireturn;` instead. (eg. `rti` on 6502, `retn` on Z80)
- `irq` - indicates that a function handles a maskable interrupt request. All `return;` instructions will be translated into `irqreturn;` instead.  (eg. `rti` on 6502, `reti` on Z80)

65816 Attributes

- `mem8` - assumes the tagged statements will be using an 8-bit accumulator and main memory-related instructions. (eg. accumulator arithmetic, storing/loading from accumulator, bit-shifting accumulator/memory)
- `mem16` - assumes the tagged statements will be using an 16-bit accumulator and main memory-related instructions.  (eg. accumulator arithmetic, storing/loading from accumulator, bit-shifting accumulator/memory)
- `idx8` - assumes the tagged statements will be using 8-bit index registers and indexing-related instructions. (eg. indexing, storing/loading from index registers, push/pop)
- `idx16` - assumes the tagged statements will be using 16-bit index registers and indexing-related instructions.  (eg. indexing, storing/loading from index registers, push/pop)

### Config Directives

Depending on the output file format selected for the program, there are extra options that can be configured.

```
config {
    option = value,
    option = value,
    option = value
}
```

See Formats section for possible options.

### Types

Built-in Types:

```
// Boolean
bool
// Compie-time integer expression ("arbitrary precision", unknown size, but currently 128-bit)
iexpr
// Unsigned sized integer
u8
u16
u24
u32
u64
// Signed sized integer
i8
i16
i24
i32
i64
```

Array Types:

```
// Array. eg. [u8; 100]
[T; N]
// Implicitly-sized array type. (size determined by initializer)
[T]
```

Designated Storage Types:

```
// Designated storage for parameter-passing and named locals.
// eg. u8 in a
T in expr
```

User-defined types:

```
// Structure. Data members have increasing start addresses.
struct Point {
    x : u8,
    y : u8
}

// Union. Data members have the same start address.
union Union {
    byte : u8,
    word : u16
}

// Enum. A strongly-typed enumeration type.
// Uses the same storage as its underlying type.
// It cannot be used as integer without casting.
enum ItemType : u8 {
    Consumable,
    Key,
    Weapon,
    Armor,
    Accessory,
}

// Type alias. Gives another name to the same type.
// A typealias is interchangable with the type it aliases.
typealias byte = u8;
```

### Expressions

```
    (a) // parentheses

    -a // signed negation. integer
    +a // signed identity. integer

    // Arithmetic operators.
    // integer + integer -> integer
    a + b // add. integer + integer -> integer
    a +# b // add with carry. integer +# integer -> integer
    a - b // subtract. integer - integer -> integer
    a -# b // subtract with carry. integer -# integer -> integer
    a * b // multiply. integer * integer -> integer
    a / b // divide. integer / integer -> integer
    a % b // modulo. integer % integer -> integer
    a << b // arithmetic left shift. integer << integer -> integer
    a >> b // arithmetic right shift. integer >> integer -> integer
    a <<< b // logical left shift. integer <<< integer -> integer
    a >>> b // logical right shift. integer >>> integer -> integer
    a <<<< b // left rotate (N bits). integer <<<< integer -> integer
    a >>>> b // right rotate (N bits). integer >>>> integer -> integer
    a <<<<# b // left rotate with carry (N+1 bits). integer <<<<# integer -> integer
    a >>>># b // right rotate with carry (N+1 bits). integer >>>># integer -> integer

    // Logical operators.
    !a // logical negation. bool
    a && b // logical and. bool && bool -> bool
    a || b // logical or. bool || bool -> bool

    ~a // bitwise negation. integer | integer -> integer
    a & b // bitwise and. integer | integer -> integer
    a | b // bitwise or. integer | integer -> integer
    a ^ b // bitwise xor. integer ^ integer -> integer
    a $ b // bit indexing. integer $ integer -> bool
    <:a // low byte access (bits 0 .. 7). integer -> u8
    >:a // high byte access (bits 8 .. 15). integer -> u8
    #:a // bank byte access (bits 16 .. 23). integer -> u8

    a++ // post-increment. integer
    a-- // post-decrement. integer
    ++a // pre-increment. integer
    --a // pre-decrement. integer

    *a // indirection. *T -> T
    &a // address of. term must be an addressable l-value. T -> *T
    a[n] // indexing. returns the nth element of a. Possibly the nth item from its start address.
    a.b // member access.

    a as T // cast operator.

    f(a, b, c, d) // call.

    1 // unsized integer expression. iexpr
    1u8 // integer with size suffix. in this case, u8

    "hello" // string literal. [u8; N]
    [expr for let iterator in iterable] // array comprehension. [T; N]
    [expr; size] // array pad literal. [T; N]
    [expr, expr, expr] // array literal. [T; N]
    (a, b, c, d) // tuple literal (reserved but not implemented yet). (T, T2, T3, ..., TN)

    a ~ b // concatenation [T; M] ~ [T; N] -> [T; M + N]
```

### Imports

To include another file in the program, use `import` directives.

```
import "path";
```

The path is a string literal. This path is the name of the .wiz file, without its extension.

Example:

```
import "nes";
import "magic";
```

### Embeds

To include a binary asset, use `embed` expressions.

```
embed "path"
```

The path passed to an `embed` should include the file extension. The contents of the embedded file are loaded into compiler memory and cached, and then inserted verbatim as a `[u8]` expression anywhere they are embedded.

Example:

```
const data = embed "hero.chr";
```

Platforms
---------

The registers, addressing modes and operations all vary depending on the system.

TODO: write about each platform's specifics.

### MOS 6502

The MOS 6502 was a very popular 8-bit CPU used by a number of 8-bit game consoles and computer systems. Some common machines that used the 6502:

- NES
- Atari 2600 (VCS)
- Atari 5200
- Atari 7800
- Atari 8-bit family (400, 800, 1200, 800XL, 1200XL, etc)
- Commodore 64
- Commodore 128
- Commodore VIC-20
- Apple II

Miscellaneous:

- `sizeof(*u8) = sizeof(u16)`
- `sizeof(far *u8) = sizeof(u24)`
- `carry` is the inverse of the borrow flag in subtraction/comparison (`true` when no borrow)

Registers:

- `a : u8` - the accumulator
- `x : u8` - index register x
- `y : u8` - index register y
- `s : u8` - stack pointer register
- `p : u8` - processor flag register
- `zero : bool` - the zero flag, used to indicate if the result of the last operation resulted in the value 0.
- `carry : bool` - the carry flag, used to indicate if the last operation resulted in a carry outside of the range 0 .. 255. For addition, the `carry` flag is `true` when an addition resulted in a carry, and `false` otherwise. For subtraction and comparison, the `carry` flag is `false` when there is a borrow (left-hand side was less than the right-hand side), and `true` otherwise. The `carry` also indicates the bit shifted out from a bit-shift operation.
- `negative : bool` - the negative flag, used to indicate the sign bit (bit 7) of the last operation.
- `overflow : bool` - the overflow flag, used to indicate if the last operation resulted an arithmetic overflow. If an overflow happened, the sign bit (bit 7) of the result is flipped.
- `decimal : bool` - the decimal flag, used to indicate whether decimal mode is active. If `true`, numbers are treated as if they are packed binary-coded decimal (BCD) format. If `false`, numbers are treated as binary numbers. Some 6502 CPUs like the 2A03/2A07 used in the NES do not have a decimal mode, so BCD arithmetic must be manually accomplished through software.
- `nointerrupt : bool` - the interrupt disable flag, used to indicate that maskable interrupt requests (IRQ) are disallowed. This will not disable non-maskable interrupts (NMI).

Intrinsics:

- `cmp(left, right)` - compares two values, by performing a subtraction without storing the result in memory. `zero` indicates whether `left == right`, `carry` indicates whether `left >= right`.
- `bit(mem)` - bitwise test between the accumulator and a value in memory. `zero` indicates whether `(a & mem) == 0`, `overflow` is set to `mem $ 6`, and `negative` is set to `mem $ 7`.
- `irqcall(code)` - manually requests an IRQ, code is a parameter that is put after irqcall opcode, which can be read from the IRQ handler routine.
- `push(value)` - pushes the given value to the stack.
- `pop(value)` - pushes the given value to the stack.
- `nop()` - does nothing, and uses 1 byte and 2 cycles.

Tests and Branches:

- `a`, `x` and `y` can be used with comparison operators (`==`, `!=`, `<`, `>`, `<=`, or `>=`) inside conditional branches. A branch like `if a >= 5 { ... }` becomes `if { cmp(a, 5); } && carry { ... }`.
- `a & mem == 0` or `a & mem != 0` can be used as a conditional branches. `if a & mem == 0 { ... }` becomes `if { bit(mem); } && zero { ... }` and `if a & mem != 0 { ... }` becomes `if { bit(mem) } && !zero { ... }`
- `mem $ 6` can be used as a conditional branch for testing bit 6 of memory. `if mem $ 6 { ... }` becomes `if { bit(mem); } && overflow { ... }`
- `mem $ 7` can be used as a conditional branch for testing bit 7 of memory. `if mem $ 7 { ... }` becomes `if { bit(mem); } && negative { ... }`

Addressing Modes:

- `{0..255}` - immediate
- `*({0..255} as *u8)` - zero-page
- `*(({0..255} + x) as *u8)` - zero-page indexed by x
- `*(({0..255} + y) as *u8)` - zero-page indexed by y
- `*(*(({0..255} + x) as *u16) as *u8)` - zero-page indexed by x indirect
- `*(({0..255} + y) as *u8)` - zero-page indexed by y
- `*((*({0..255} as *u16) + y) as *u8)` - zero-page indirect indexed by y
- `*({0..65535} as *u8)` - absolute indexed by x
- `*(({0..65535} + x) as *u8)` - absolute indexed by x
- `*(({0..65535} + y) as *u8)` - absolute indexed by y

Instructions:

```
a = {0..255}
a = *({0..255} as *u8)
a = *(({0..255} + x) as *u8)
a = *(*(({0..255} + x) as *u16) as *u8)
a = *(*(({0..255} as *u16) + y) as *u8)
a = *({0..65535} as *u8)
a = *(({0..65535} + x) as *u8)
a = *(({0..65535} + y) as *u8)

a += {0..255}
a += *({0..255} as *u8)
a += *(({0..255} + x) as *u8)
a += *(*(({0..255} + x) as *u16) as *u8)
a += *(*(({0..255} as *u16) + y) as *u8)
a += *({0..65535} as *u8)
a += *(({0..65535} + x) as *u8)
a += *(({0..65535} + y) as *u8)

a +#= {0..255}
a +#= *({0..255} as *u8)
a +#= *(({0..255} + x) as *u8)
a +#= *(*(({0..255} + x) as *u16) as *u8)
a +#= *(*(({0..255} as *u16) + y) as *u8)
a +#= *({0..65535} as *u8)
a +#= *(({0..65535} + x) as *u8)
a +#= *(({0..65535} + y) as *u8)

a -= {0..255}
a -= *({0..255} as *u8)
a -= *(({0..255} + x) as *u8)
a -= *(*(({0..255} + x) as *u16) as *u8)
a -= *(*(({0..255} as *u16) + y) as *u8)
a -= *({0..65535} as *u8)
a -= *(({0..65535} + x) as *u8)
a -= *(({0..65535} + y) as *u8)

a -#= {0..255}
a -#= *({0..255} as *u8)
a -#= *(({0..255} + x) as *u8)
a -#= *(*(({0..255} + x) as *u16) as *u8)
a -#= *(*(({0..255} as *u16) + y) as *u8)
a -#= *({0..65535} as *u8)
a -#= *(({0..65535} + x) as *u8)
a -#= *(({0..65535} + y) as *u8)

a |= {0..255}
a |= *({0..255} as *u8)
a |= *(({0..255} + x) as *u8)
a |= *(*(({0..255} + x) as *u16) as *u8)
a |= *(*(({0..255} as *u16) + y) as *u8)
a |= *({0..65535} as *u8)
a |= *(({0..65535} + x) as *u8)
a |= *(({0..65535} + y) as *u8)

a &= {0..255}
a &= *({0..255} as *u8)
a &= *(({0..255} + x) as *u8)
a &= *(*(({0..255} + x) as *u16) as *u8)
a &= *(*(({0..255} as *u16) + y) as *u8)
a &= *({0..65535} as *u8)
a &= *(({0..65535} + x) as *u8)
a &= *(({0..65535} + y) as *u8)

a ^= {0..255}
a ^= *({0..255} as *u8)
a ^= *(({0..255} + x) as *u8)
a ^= *(*(({0..255} + x) as *u16) as *u8)
a ^= *(*(({0..255} as *u16) + y) as *u8)
a ^= *({0..65535} as *u8)
a ^= *(({0..65535} + x) as *u8)
a ^= *(({0..65535} + y) as *u8)

{0..255} = a
*({0..255} as *u8) = a
*(({0..255} + x) as *u8) = a
*(*(({0..255} + x) as *u16) as *u8) = a
*(*(({0..255} as *u16) + y) as *u8) = a
*({0..65535} as *u8) = a
*(({0..65535} + x) as *u8) = a
*(({0..65535} + y) as *u8) = a

cmp(a, {0..255})
cmp(a, *({0..255} as *u8))
cmp(a, *(({0..255} + x) as *u8))
cmp(a, *(*(({0..255} + x) as *u16) as *u8))
cmp(a, *(*(({0..255} as *u16) + y) as *u8))
cmp(a, *({0..65535} as *u8))
cmp(a, *(({0..65535} + x) as *u8))
cmp(a, *(({0..65535} + y) as *u8))

bit(*({0..255} as *u8))
bit(*({0..65535} as *u8))

a = x
x = a
a = y
y = a
x = s
s = x

x = {0..255};
x = *({0..255} as *u8)
x = *(({0..255} + y) as *u8)
x = *({0..65535} as *u8)
x = *(({0..65535} + y) as *u8)

*({0..255} as *u8) = x
*(({0..255} + y) as *u8) = x
*({0..65535} as *u8) = x

cmp(x, {0..255})
cmp(x, *({0..255} as *u8))
cmp(x, *({0..65535} as *u8))

y = {0..255};
y = *({0..255} as *u8)
y = *(({0..255} + y) as *u8)
y = *({0..65535} as *u8)
y = *(({0..65535} + y) as *u8)

*({0..255} as *u8) = y
*(({0..255} + x) as *u8) = y
*({0..65535} as *u8) = y

cmp(y, {0..255})
cmp(y, *({0..255} as *u8))
cmp(y, *({0..65535} as *u8))

push(a)
push(p)

a = pop()
p = pop()

++*({0..255} as *u8)
++*(({0..255} + x) as *u8)
++*({0..65535} as *u8)
++*(({0..65535} + x) as *u8)
++x
++y

--*({0..255} as *u8)
--*(({0..255} + x) as *u8)
--*({0..65535} as *u8)
--*(({0..65535} + x) as *u8)
--x
--y

a = ~a
a = -a

a <<= {0..7}
*({0..255} as *u8) <<= {0..7}
*(({0..255} + x) as *u8) <<= {0..7}
*({0..65535} as *u8) <<= {0..7}
*(({0..65535} + x) as *u8) <<= {0..7}

a <<<= {0..7}
*({0..255} as *u8) <<<= {0..7}
*(({0..255} + x) as *u8) <<<= {0..7}
*({0..65535} as *u8) <<<= {0..7}
*(({0..65535} + x) as *u8) <<<= {0..7}

a >>>= {0..7}
*({0..255} as *u8) >>>= {0..7}
*(({0..255} + x) as *u8) >>>= {0..7}
*({0..65535} as *u8) >>>= {0..7}
*(({0..65535} + x) as *u8) >>>= {0..7}

a <<<<#= {0..7}
*({0..255} as *u8) <<<<#= {0..7}
*(({0..255} + x) as *u8) <<<<#= {0..7}
*({0..65535} as *u8) <<<<#= {0..7}
*(({0..65535} + x) as *u8) <<<<#= {0..7}

a >>>>#= {0..7}
*({0..255} as *u8) >>>>#= {0..7}
*(({0..255} + x) as *u8) >>>>#= {0..7}
*({0..65535} as *u8) >>>>#= {0..7}
*(({0..65535} + x) as *u8) >>>>#= {0..7}

goto {-128..127} if zero
goto {-128..127} if !zero
goto {-128..127} if carry
goto {-128..127} if !carry
goto {-128..127} if negative
goto {-128..127} if !negative
goto {-128..127} if overflow
goto {-128..127} if !overflow

goto {0..65535}
^goto {0..65535} if zero
^goto {0..65535} if !zero
^goto {0..65535} if carry
^goto {0..65535} if !carry
^goto {0..65535} if negative
^goto {0..65535} if !negative
^goto {0..65535} if overflow
^goto {0..65535} if !overflow

goto *({0..65535} as *u16)

return
irqreturn
nmireturn

irqcall({0..255})

nop()

carry = false
carry = true

decimal = false
decimal = true

nointerrupt = false
nointerrupt = true

overflow = false
```

### MOS 65C02

The MOS 65C02 is like the MOS 6502, but also has some extra instructions.

Extra Intrinsics:

- `test_and_reset(mem)` - like `bit(mem)`, but also uses the accumulator to turn off bits in mem, as if `mem &= ~a;` is applied.
- `test_and_set(mem)` - like `bit(mem)`, but also uses the accumulator to turn on bits in mem, as if `mem |= a;` is applied.

Extra Instructions:

```
a = *(*({0..255} as *u16) as *u8)
a += *(*({0..255} as *u16) as *u8)
a +#= *(*({0..255} as *u16) as *u8)
a -= *(*({0..255} as *u16) as *u8)
a -#= *(*({0..255} as *u16) as *u8)
a |= *(*({0..255} as *u16) as *u8)
a &= *(*({0..255} as *u16) as *u8)
a ^= *(*({0..255} as *u16) as *u8)
*(*({0..255} as *u16) as *u8) = a
cmp(a, *(*({0..255} as *u16) as *u8))

bit({0..255})
bit(*(({0..255} + x) as *u8))
bit(*(({0..65535} + x) as *u8))

++a
--a

goto {-128..127}
^goto {0..65535}

goto *(({0..65535} + x) as *u16)

push(x)
push(y)

x = pop()
y = pop()

*({0..255} as *u8) = 0
*(({0..255} + x) as *u8) = 0
*({0..65535} as *u8) = 0
*(({0..65535} + x) as *u8) = 0

test_and_reset(*({0..255} as *u8))
test_and_reset(*({0..65535} as *u8))

test_and_set(*({0..255} as *u8))
test_and_set(*({0..65535} as *u8))
```

### Rockwell 65C02

The Rockwell 65C02 is like the MOS 65C02, but also has some extra instructions.

Extra Instructions:

```
goto {-128..127} if *({0..255} as *u8) $ {0..7}
goto {-128..127} if !(*({0..255} as *u8)) $ {0..7}
^goto {0..65535} if *({0..255} as *u8) $ {0..7}
^goto {0..65535} if !(*({0..255} as *u8)) $ {0..7}

*({0..255} as *u8) $ {0..7} = false
*({0..255} as *u8) $ {0..7} = true
```

### WDC 65C02

The WDC 65C02 is like the Rockwell 65C02 but also has some extra instructions.

Extra Intrinsics:
- `stop_until_reset()` - stops execution until a hardware reset occurs.
- `wait_until_reset()` - sleeps until a hardware interrupt occurs.

Extra Instructions:

```
stop_until_reset()
wait_until_interrupt()
```

### HuC 6280

The HuC6280 is like the Rockwell 65C02, but has some extra registers and instructions. Also, zero page instructions are at 0x2000 .. 0x20FF rather than the usual 0x00 .. 0xFF of other 6502 processors. This can be bank-switched with the `mpr1` register.

Extra Registers:

- `turbo_speed : bool` - CPU turbo mode setting
- `vdc_select : u8` - VDC address select register (fast access)
- `vdc_data_l : u8` - VDC data register low (fast access)
- `vdc_data_h : u8` - VDC data register high (fast access)
- The VDC registers are also available in a memory mapped I/O registers, these registers are just for special quick-write instructions in the CPU.
- `mpr0 : u8` - mapper register 0, maps the memory bank available at address range `0x0000 .. 0x1FFF`.
- `mpr1 : u8` - mapper register 1, maps the memory bank available at address range `0x2000 .. 0x3FFF`. Affects zero page.
- `mpr2 : u8` - mapper register 2, maps the memory bank available at address range `0x4000 .. 0x5FFF`.
- `mpr3 : u8` - mapper register 3, maps the memory bank available at address range `0x6000 .. 0x7FFF`.
- `mpr4 : u8` - mapper register 4, maps the memory bank available at address range `0x8000 .. 0x9FFF`.
- `mpr5 : u8` - mapper register 5, maps the memory bank available at address range `0xA000 .. 0xBFFF`.
- `mpr6 : u8` - mapper register 6, maps the memory bank available at address range `0xC000 .. 0xDFFF`.
- `mpr7 : u8` - mapper register 7, maps the memory bank available at address range `0xE000 .. 0xFFFF`.

Extra Intrinsics

- `swap(left, right)` - exchanges the values between the left and right operand.
- `transfer_alternate_to_increment(source, dest, len)` - transfers `len` bytes of data from an alternating `source` address (`source`, `source + 1`, `source`, ...) to an incrementing `dest` address (`dest`, `dest + 1`, `dest + 2`, ...).
- `transfer_increment_to_alternate(source, dest, len)` - transfers `len` bytes of data from an incrementing `source` address (`source`, `source + 1`, `source + 2`, ...)  to an alternating `dest` address (`dest`, `dest + 1`, `dest`, ...).
- `transfer_decrement_to_decrement(source, dest, len)` - transfers `len` bytes of data from an decrementing `source` address address (`source`, `source - 1`, `source - 2`, ...) to an decrementing `dest` address (`dest`, `dest - 1`, `dest - 2`, ...).
- `transfer_increment_to_increment(source, dest, len)` - transfers `len` bytes of data from an incrementing `source` address address (`source`, `source + 1`, `source + 2`, ...) to an incrementing `dest` address (`dest`, `dest + 1`, `dest + 2`, ...).
- `transfer_increment_to_fixed(source, dest, len)` - transfers `len` bytes of data from an incrementing `source` address address (`source`, `source + 1`, `source + 2`, ...) to a fixed `dest` address (`dest`, `dest`, `dest`, ...).
- `mpr_set(mask, a)` - sets `mpr0` .. `mpr7` registers to the value in the accumulator, using `mask` to indicate which of registers are being selected to update. For N = 0 .. 7, if `mask $ N` is `true` (`(mask & (1 << N)) != 0`), then `mprN` will be set to `a`.
- `tst(imm, mem)` - like `bit` but the `zero` flag is the result of whether `(imm & bit) == 0`.

Extra Instructions:

```
a = 0
x = 0
y = 0

turbo_speed = false
turbo_speed = true

swap(a, x)
swap(a, y)
swap(x, y)

*(x as *u8) += {0..255}
*(x as *u8) += *({0..255} as *u8)
*(x as *u8) += *(({0..255} + x) as *u8)
*(x as *u8) += *(*(({0..255} + x) as *u16) as *u8)
*(x as *u8) += *(*(({0..255} as *u16) + y) as *u8)
*(x as *u8) += *({0..65535} as *u8)
*(x as *u8) += *(({0..65535} + x) as *u8)
*(x as *u8) += *(({0..65535} + y) as *u8)

*(x as *u8) +#= {0..255}
*(x as *u8) +#= *({0..255} as *u8)
*(x as *u8) +#= *(({0..255} + x) as *u8)
*(x as *u8) +#= *(*(({0..255} + x) as *u16) as *u8)
*(x as *u8) +#= *(*(({0..255} as *u16) + y) as *u8)
*(x as *u8) +#= *({0..65535} as *u8)
*(x as *u8) +#= *(({0..65535} + x) as *u8)
*(x as *u8) +#= *(({0..65535} + y) as *u8)

*(x as *u8) |= {0..255}
*(x as *u8) |= *({0..255} as *u8)
*(x as *u8) |= *(({0..255} + x) as *u8)
*(x as *u8) |= *(*(({0..255} + x) as *u16) as *u8)
*(x as *u8) |= *(*(({0..255} as *u16) + y) as *u8)
*(x as *u8) |= *({0..65535} as *u8)
*(x as *u8) |= *(({0..65535} + x) as *u8)
*(x as *u8) |= *(({0..65535} + y) as *u8)

*(x as *u8) &= {0..255}
*(x as *u8) &= *({0..255} as *u8)
*(x as *u8) &= *(({0..255} + x) as *u8)
*(x as *u8) &= *(*(({0..255} + x) as *u16) as *u8)
*(x as *u8) &= *(*(({0..255} as *u16) + y) as *u8)
*(x as *u8) &= *({0..65535} as *u8)
*(x as *u8) &= *(({0..65535} + x) as *u8)
*(x as *u8) &= *(({0..65535} + y) as *u8)

*(x as *u8) ^= {0..255}
*(x as *u8) ^= *({0..255} as *u8)
*(x as *u8) ^= *(({0..255} + x) as *u8)
*(x as *u8) ^= *(*(({0..255} + x) as *u16) as *u8)
*(x as *u8) ^= *(*(({0..255} as *u16) + y) as *u8)
*(x as *u8) ^= *({0..65535} as *u8)
*(x as *u8) ^= *(({0..65535} + x) as *u8)
*(x as *u8) ^= *(({0..65535} + y) as *u8)

vdc_select = {0..255}
vdc_data_l = {0..255}
vdc_data_h = {0..255}

transfer_alternate_to_increment({0..65535}, {0..65535}, {0..65535})
transfer_increment_to_alternate({0..65535}, {0..65535}, {0..65535})
transfer_decrement_to_decrement({0..65535}, {0..65535}, {0..65535})
transfer_increment_to_increment({0..65535}, {0..65535}, {0..65535})
transfer_increment_to_fixed({0..65535}, {0..65535}, {0..65535})

mpr_set({0..255}, a)
mpr0 = a
mpr1 = a
mpr2 = a
mpr3 = a
mpr4 = a
mpr5 = a
mpr6 = a
mpr7 = a
a = mpr0
a = mpr1
a = mpr2
a = mpr3
a = mpr4
a = mpr5
a = mpr6
a = mpr7

tst({0..255}, *({0..255} as *u8))
tst({0..255}, *(({0..255} + x) as *u8))
tst({0..255}, *(({0..65535} + x) as *u8))
tst({0..255}, *(({0..65535} + x) as *u8))
```

### Zilog Z80

Miscellaneous

- `sizeof(*u8) = sizeof(u16)`
- `sizeof(far *u8) = sizeof(u24)`
- `carry` acts as a borrow flag in subtraction/comparison

Registers

- `a : u8` - accumulator
- `b : u8`, `c : u8`, `d : u8`, `e : u8`, `h : u8`, `l : u8` - general registers
- `ixh : u8`, `ixl : u8`, `iyh : u8`, `iyl : u8` - index register sub-registers (undocumented)
- `af : u16` - accumulator + flags pair
- `bc : u16`, `de : u8`, `hl : u8` - general register pairs
- `ix : u16`, `iy : u8` - index registers
- `zero : bool` - the zero flag, used to indicate if the result of the last operation resulted in the value 0.
- `carry : bool` - the carry flag, used to indicate if the last operation resulted in a carry outside of the range 0 .. 255. For addition, the `carry` flag is `true` when an addition resulted in a carry, and `false` otherwise. For subtraction and comparison, the `carry` flag is `true` when there is a borrow (left-hand side was less than the right-hand side), and `false` otherwise. The `carry` also indicates the bit shifted out from a bit-shift operation.
- `overflow : bool`
- `negative : bool`
- `interrupt : bool` - the interrupt enable flag, used to indicate whether maskable interrupts should be activated.
- `interrupt_mode : u8`
- `interrupt_page : u8`
- `memory_refresh : u8`

Intrinsics

- `push(value)`
- `pop()`
- `nop()`
- `halt()`
- `decimal_adjust()`
- `swap(left, right)`
- `swap_shadow()`
- `load_increment()`
- `load_decrement()`
- `load_increment_repeat()`
- `load_decrement_repeat()`
- `bit`
- `cmp`
- `comare_increment`
- `comare_decrement`
- `comare_increment_repeat`
- `comare_decrement_repeat`
- `rotate_left_digits`
- `rotate_right_digits`
- `io_read`
- `io_read_increment`
- `io_read_decrement`
- `io_read_increment_repeat`
- `io_read_decrement_repeat`
- `io_write`
- `io_write_increment`
- `io_write_decrement`
- `io_write_increment_repeat`
- `io_write_decrement_repeat`
- `decrement_branch_not_zero`

Addressing Modes

- TODO

Instructions

```
TODO
```

Documentation TODO

### Game Boy

Miscellaneous

- `sizeof(*u8) = sizeof(u16)`
- `sizeof(far *u8) = sizeof(u24)`
- `carry` acts as a borrow flag in subtraction/comparison

Registers

- `a : u8` - accumulator
- `b : u8`, `c : u8`, `d : u8`, `e : u8`, `h : u8`, `l : u8` - general registers
- `af : u16` - accumulator + flags pair
- `bc : u16`, `de : u8`, `hl : u8` - general register pairs
- `zero : bool` - the zero flag, used to indicate if the result of the last operation resulted in the value 0.
- `carry : bool` - the carry flag, used to indicate if the last operation resulted in a carry outside of the range 0 .. 255. For addition, the `carry` flag is `true` when an addition resulted in a carry, and `false` otherwise. For subtraction and comparison, the `carry` flag is `true` when there is a borrow (left-hand side was less than the right-hand side), and `false` otherwise. The `carry` also indicates the bit shifted out from a bit-shift operation.
- `interrupt : bool` - the interrupt enable flag, used to indicate whether maskable interrupts should be activated.

Intrinsics

- `push(value)` - pushes a value to the stack.
- `pop()` - pops a value from the stack.
- `nop()` - does nothing, but takes 1 byte and 4 cycles.
- `halt()` - halts execution until the next interrupt occurs. saves CPU and battery.
- `stop()` - goes into a low-power sleep until a joy-pad interrupt occurs. also used after changing the Game Boy Color's speed to apply the change, by setting the joy-pad register to force an immediate wake.
- `decimal_adjust()` - corrects the result in the accumulator after performing arithmetic on packed binary-coded decimal (BCD) values. put a call to this after an addition or subtraction involving packed BCD values.
- `swap_digits(r)` - swaps the low and high nybbles of the register `r`.
- `debug_break()` - emits an `ld b, b` nop opcode can be used to triggers a breakpoint in the Game Boy emulator BGB.
- `bit(r, n)` - test bit `n` of the register `r`, and updates the `zero` flag.
- `cmp(left, right)` - compares two values, by performing a subtraction without storing the result in memory. `zero` indicates whether `left == right`, `carry` indicates whether `left < right`.

Addressing Modes

- TODO

Instructions

```
TODO
```

Documentation TODO

### WDC 65816

Documentation TODO

### SPC 700

Miscellaneous

- TODO

Registers

- `a : u8` - accumulator
- `x : u8` - index register x
- `y : u8` - index register y
- `sp : u8` - stack pointer register
- `psw : u8` - processor status word register
- `ya : u16` - ya register pair
- `negative : bool`
- `overflow : bool`
- `direct_page : bool`
- `interrupt : bool`
- `zero : bool`
- `carry : bool`

Instrinsics

- `push(value)`
- `pop()`
- `irqcall()`
- `nop()`
- `sleep()`
- `stop()`
- `swap_digits(a)`
- `test_and_set(a, mem)`
- `test_and_clear(a, mem)`
- `divmod(ya, x)`
- `decimal_adjust_add()`
- `decimal_adjust_sub()`
- `cmp(left, right)`
- `compare_branch_not_equal(a, operand, destination)`
- `decrement_branch_not_equal(operand, destination)`

Addressing Modes

- TODO

Instructions

```
TODO
```

Documentation TODO

Formats
-------

### Binary

The default format for any program being output. Wiz peforms no special header or footer handling.

Config options:

- `trim` (bool) - if `true`, then the unused portion at the end of final bank in the output will be trimmed from the file. Useful for shortening the size of binaries that are going to be embedded in another program. (Defaults to `false`)

### Nintendo Entertainment System / Famicom

The iNES format is an emulator format for NES ROMs that is commonly supported. It has the `.nes` file extension.

Format Specifics:

- 16-byte iNES header at the start of the output binary
- PRG banks defined by `constdata` or `prgdata` bank. Padded to nearest multiple of 16 KiB.
- CHR banks defined by `chrdata` banks. Padded to nearest multiple of 8 KiB.

Config options:

- `cart_type` (string) - the type of cartridge that the cart is using. It can be one of the following strings:

```
"nrom"
"sxrom"
"mmc1"
"uxrom"
"cnrom"
"txrom"
"mmc3"
"mmc6"
"exrom"
"mmc5"
"axrom"
"pxrom"
"mmc2"
"fxrom"
"mmc4"
"color-dreams"
"cprom"
"24c02"
"ss8806"
"n163"
"vrc4a"
"vrc4c"
"vrc2a"
"vrc2b"
"vrc4e"
"vrc6a"
"vrc4b"
"vrc4d"
"vrc6b"
"action-53"
"unrom512"
"bnrom"
"rambo1"
"gxrom"
"mxrom"
"after-burner"
"fme7"
"sunsoft5b"
"codemasters"
"vrc3"
"vrc1"
"n109"
"vrc7"
"gtrom"
"txsrom"
"tqrom"
"24c01"
"dxrom"
"n118"
"n175"
"n340"
"action52"
"codemasters-quattro"
```

- `cart_type_id` (integer) - the type of cartridge that the cart is using, as an iNES mapper number. Takes precedence over `cart_type_id`, so use this if `cart_type` is not recognized. (If a cart type name is missing, feel free to request it!)
- If neither `cart_type` nor `cart_type_id` are specified, then the cart is NROM (mapper 0). This no special memory mapper, so it is limited to a view of 32K of ROM at addresses 0x8000 .. 0xFFFF in memory.
- `vertical_mirror` (bool) - whether or not this cart uses vertical mirroring. (Defaults to `false`)
- `battery` (bool) - whether or not this cart uses battery backed save RAM. (Defaults to `false`)
- `four_screen` (bool) - whether or not this cart contains RAM for extra nametables, allowing use of all four screens without PPU nametable mirroring. (Defaults to `false`)
- `prg_ram_size` (integer) - the number of bytes to use for PRG RAM. Must be divisble by 8192 bytes, and can be no more than 2088960 bytes (8192 bytes * 255 banks). (Defaults to 0)

### Game Boy

The Game Boy has a standardized header format that is is contained a fixed location in ROM. The file format on disk has a `.gb` extension. Wiz will automatically fill in the necessary fields to get a basic booting Game Boy ROM. This includes the Nintendo logo image, and the checksum, necessary to get past the boot screen of the Game Boy.

Format Specifics:

- 0x100 .. 0x150 in the first bank of ROM will be reserved for the Game Boy header.
- A checksum is automatically calculated and inserted into the header.
- The program ROM is automatically padded to nearest size permitted by the Game Boy header format.

Config options:

- `cart_type` (string) - the type of cartridge that the cart is using. It can be one of the following strings:

```
"rom"
"mbc1"
"mbc1-ram"
"mbc1-ram-battery"
"mbc2"
"mbc2-battery"
"rom-ram"
"rom-ram-battery"
"mmm01"
"mmm01-ram"
"mmm01-ram-battery"
"mbc3-timer-battery"
"mbc3-timer-ram-battery"
"mbc3"
"mbc3-ram"
"mbc3-ram-battery"
"mbc4"
"mbc4-ram"
"mbc4-ram-battery"
"mbc5"
"mbc5-ram"
"mbc5-ram-battery"
"mbc5-rumble"
"mbc5-rumble-ram"
"mbc5-rumble-ram-battery"
"mmm01"
"camera"
"tama5"
"huc3"
"huc1"
```

- `cart_type_id` (integer) - the type of cartridge mapper that the cart is using, as a numeric ID used by the Game Boy header format. Takes precedence over `cart_type_id`, so use this if `cart_type` is not recognized. (If a cart type name is missing, feel free to request it!)
- If neither `cart_type` nor `cart_type_id` are specified, then the ROM has no memory bank controller, and it is limited to a view of 32K of ROM at addresses 0x0000 .. 0x7FFF in memory.
- `title` (string) - The name of the program. The max length is 11 if there is `manufacturer` code, and 15 on legacy carts that do not have one. (Defaults to the output filename with extension removed, truncated to the maximum length requirement of the title)
- `gbc_compatible` (bool) - Whether or not this cart is compatible with Game Boy Color features. If `true`, the cart will boot with Game Boy Color functionality when played on a Game Boy Color compatible system. A GBC-compatible game can still be played on an original DMG-compatible model of Game Boy. (Defaults to `false`)
- `gbc_exclusive` (bool) - Whether or not this cart is exclusive to the Game Boy Color. If `true`, the cart will boot with Game Boy Color functionality when played on a Game Boy Color compatible system. Takes precedence over `gbc_compatible` if it is `true`. A GBC-exclusive game should not be played on an original DMG-compatible model of Game Boy. However, it is still up to the program to detect if it is being played on a Game Boy Color system, and stop if an incompatible system is used. (Defaults to `false`)
- `sgb_compatible` (bool) - Whether or not this cart is compatible with Super Game Boy features. If `true`, the cart is able to use extra functionality on a Super Game Boy, allowing communication with the Super Game Boy program through the Game Boy joypad port. Most emulators will expect a SGB border to be uploaded if this flag is enabled. (Defaults to `false`)
- `ram_size` (integer) - The amount of on-cartridge RAM that this cart has available. (Defaults to 0) Must be a size that is supported by the Game Boy header format. Possible values include:

```
0
2048
8192
32768
65536
131072
```

- `international` (bool) - Whether or not this game is an international release outside of Japan. (Defaults to `false`)
- `licensee` (string) - A two-character string representing the licensee / creator of the game. (Defaults to `""`)
- `old_licensee` (integer) - A legacy licensee code indicating the ID of the licensee / creator of this game. All newer releases have a legacy license

联系我们：verysource_com

CopyRight © 2008-2022 verySource.Com All Rights reserved.　京ICP备17048824号-1　京公网安备：11010502034788