l65

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #cli #claude-code #codex #developer-tools #react #windows

★ 20 Open GitHub ↗

Lightweight cross-assembler suite for 6502, Z80/SM83 and NEC 7801

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# l65

A family of lightweight cross-assemblers:

- `l65` — 6502
- `lz80` — Z80 / SM83
- `l7801` — NEC 7801

The assemblers operate from within Lua, and are written in Lua. This means assembler mnemonics become regular Lua statements anywhere in the middle of Lua code. Lua then acts as a dynamic preprocessor of itself, the assembler and linker.

l65 is a 6502 assembler, with libraries for Atari 2600 VCS and NES.

lz80 is a Z80 assembler, with libraries for GameBoy SM83.

l7801 is a NEC µPD7801 assembler, with samples for Super Cassette Vision, created and maintained by [@MooZ] (https://github.com/BlockoS).

Table of Contents
=================

* [Concept - How It Works](#concept---how-it-works)
  * [Command Line Usage](#command-line-usage)
  * [Samples - Getting Started](#samples---getting-started)
  * [API](#api)
     * [Lua Extensions](#lua-extensions)
        * [Lambda Functions](#lambda-functions)
        * [Binary Numbers](#binary-numbers)
     * [Globals](#globals)
        * [getopt(optstring, ...)](#getoptoptstring-)
     * [Instruction List](#instruction-list)
        * [Regular Opcodes](#regular-opcodes)
        * [Undocumented Opcodes](#undocumented-opcodes)
        * [Deriving Function Names](#deriving-function-names)
        * [Late and Early Operands](#late-and-early-operands)
        * [Toggling Encapsulation](#toggling-encapsulation)
     * [Data Definition](#data-definition)
        * [dc.b ... ; byte(...) ; byte_hi(...) ; byte_lo(...)](#dcb---byte--byte_hi--byte_lo)
        * [dc.w ... ; word(...)](#dcw---word)
        * [dc.l ... ; long(...)](#dcl---long)
        * [charset([s] [, f])](#charsets--f)
        * [byte_normalize(v)](#byte_normalizev)
        * [word_normalize(v)](#word_normalizev)
        * [long_normalize(v)](#long_normalizev)
     * [Assembler Functions (6502.lua)](#assembler-functions-6502lua)
        * [Module Properties](#module-properties)
        * [location(start [, finish]) ; location(opt)](#locationstart--finish--locationopt)
           * [Other Fields](#other-fields)
        * [@@name ; section(name) ; section(opt)](#name--sectionname--sectionopt)
           * [Other Fields](#other-fields-1)
        * [@name ; label(name)](#name--labelname)
           * [Other Fields](#other-fields-2)
        * [samepage ... end](#samepage--end)
        * [crosspage ... end](#crosspage--end)
        * [skip(bytes)](#skipbytes)
        * [relate(section1, section2 [, [offset1,] offset2])](#relatesection1-section2--offset1-offset2)
        * [sleep(cycles [, noillegal])](#sleepcycles--noillegal)
        * [op_resolve(v)](#op_resolvev)
        * [link()](#link)
        * [resolve()](#resolve)
        * [genbin([filler])](#genbinfiller)
        * [writebin(filename)](#writebinfilename)
        * [writesym(filename [, format])](#writesymfilename--format)
     * [Parser Functions](#parser-functions)
        * [Pragmas](#pragmas)
           * [syntax6502 on|off](#syntax6502-onoff)
           * [encapsulate on|off](#encapsulate-onoff)
           * [encapsulate opcode funcname](#encapsulate-opcode-funcname)
           * [add_opcode opcode addressing](#add_opcode-opcode-addressing)
           * [alias opcode newname](#alias-opcode-newname)
        * [l65 Module](#l65-module)
           * [parse(src [, src_name])](#parsesrc--src_name)
           * [format(ast)](#formatast)
           * [searcher_index](#searcher_index)
           * [search_path](#search_path)
           * [report(success, ...)](#reportsuccess-)
           * [msghandler(msg)](#msghandlermsg)
           * [load_embedded(name)](#load_embeddedname)
           * [searcher(name)](#searchername)
           * [load, loadfile, dofile ; installhooks(), uninstallhooks()](#load-loadfile-dofile--installhooks-uninstallhooks)
           * [image(filename)](#imagefilename)
     * [Platform Modules](#platform-modules)
  * [LZ80](#lz80)
  * [Building](#building)
     * [Windows](#windows)
     * [Linux](#linux)
  * [Vim files installation](#vim-files-installation)
  * [Visual Studio Code extension](#vscode-extension)
  * [TODO List](#todo-list)
  * [Credits](#credits)
  * [License](#license)

## Concept - How It Works

l65 hooks into Lua `require` and related functionalities to add a parsing pass before Lua compilation. This pass transforms 6502 statements into regular Lua function calls. It applies only to files with extension '.l65', not '.lua'.

Since l65 features a linker, every symbol referenced has to be resolved after link, not at the time the opcode function gets executed. As such, the operand is encapsulated into a function for delayed execution: `rts` translates to `rtsimp()`, a global function call, which by default resolves to the `6502.lua` module set as the `__index` field of the metatable of the l65 source file's `_ENV`. Every function call translates to a name comprised of the mnemonic followed by a 3 characters addressing mode.

Spatial arrangement follows [nimble65](https://bitbucket.org/kylearan/nimble65) naming: *locations* define ROM areas, containing *sections* with some positional constraints, made of a sequence of instructions and/or data. Sections which are not fixed in space are then positioned during link phase within the locations. Then the resolve phase sets numeric values into the `symbols` table, and `genbin` creates a byte table representing the final ROM.

## Command Line Usage

```
Usage: l65 [options] file [args]
Options:
  -d <file>        Dump the Lua code after l65 parsing into file
  -h               Display this information
  -v               Display the release version
```

`args` are passed as arguments to the l65 script in `file`. The global function [getopt](#getoptoptstring-) is available to parse them.

## Samples - Getting Started

Have a look at these files in the `samples` folder to get started with l65:
 * `l65_operator_syntax.l65`: a self-validating comparison of 6502 mnemonic and operator syntax encodings.
 * `vcs_basic.l65`: a 2Kb VCS ROM which just shows color bands.
 * `vcs_hooks.l65`: shows how to insert your own instructions into the pipeline, here to get the cycle count and size of the kernel. Also, it does not use the main loop helpers nor mapper functions to show the actual code involved.
 * `vcs_hello.l65`: a VCS 'Hello World' using the playfield.
 * `vcs_banks.l65`: demonstrates 2 methods to call functions across banks.
 * `vcs_flush.l65`: a port of flewww's famous flush logo from the demo [.bin](http://www.pouet.net/prod.php?which=69666)
 * `vcs_spr48.l65`: a port of [.bin](http://www.pouet.net/prod.php?which=69666) title 48 pixels sprite animation.
 * `vcs_music.l65`: imports and plays back a TIATracker .ttt file directly.
 * `vcs_mcart.l65`: imports all TIATracker .ttt files in the folder supplied as arg, or current directory, and builds a music cart.

* `nes_hello.l65`: a NES 'Hello World' using BG tiles, and automatic positioned font within a 4kB CHR rom page.

* `gb_hello.lz80`: a Game Boy “Hello World” using pre-encoded 2bpp font tiles and the `charset` helper.
 * `gb_bank1.lz80`: switches related text sections at the same address between two MBC1 ROM banks.
 * `gb_celeste.lz80`: a native lz80 conversion of [joshop's Celeste Classic port to Game Boy](https://joshop.itch.io/celeste-game-boy), with PB16-compressed graphics and a sample-local map asset.
 * `gb_hugetracker.lz80`: a Game Boy ROM that imports and plays the upstream hUGETracker sample song [“Fish 'n Chips” by Jester](https://github.com/SuperDisk/hUGETracker/tree/hUGETracker/sample-songs) (converted by SuperDisk) through the full four-channel hUGEDriver port.
 * `gb_operator_syntax.lz80`: a self-validating Game Boy opcode corpus covering every valid base and CB-prefixed encoding, plus all available operator-syntax equivalents.
 * `gb_pb16.lz80`: build-time PB8/PB16 compression and callable Game Boy PB16 decompression.
 * `gb_cgb_speed.lz80`: a CGB-only ROM that switches the CPU to double speed.
 * `gb_helpers.lz80`: reset initialization, joypad input, buffered OAM DMA, debugger symbols, and debugfile actions.
 * `gb_infrared.lz80`: CGB infrared receiver polling, emitter control, and low-power shutdown.
 * `gb_mbc1.lz80`: a Game Boy ROM using the MBC1 mapper helper and a switchable ROM bank.
 * `gb_mbc3_rtc.lz80`: an MBC3 RTC cartridge that reads a coherent clock snapshot.
 * `gb_mbc5.lz80`: a Game Boy ROM using MBC5 9-bit ROM bank switching and RAM bank switching.
 * `gb_timer_serial.lz80`: divider, programmable timer, and serial transfer helpers.
 * `gb_twister.lz80`: a Game Boy raster twister that selects a separately projected, shaded cuboid slice during every scanline's HBlank.

There's also `vcspal.act`, a palette file for authoring software for VCS. Use this palette or a similar one to create 8b PNG for `l65.image` and helper loaders depending on it. You can generate such a palette, or a GPL one for GIMP using [vcsconv](https://github.com/g012/vcsconv) `authpalette` command.

## API

### Lua Extensions

#### Lambda Functions

Since anonymous functions are core to l65, the extension syntax such as `\a,b(a+b)` is available to define them: it expands to `function(a,b) return a+b end`.

#### Binary Numbers

A simple parsing of number literals in the form of `0b11011` converts this base-2 / binary number into a decimal number after the l65 pass. There is no support for them in other places though - no format type for `string.format` or anything else.

#### 6502 Operator Syntax

l65 provides operator syntax as a second spelling for common data movement,
arithmetic, comparison, shift, increment, and decrement instructions. Mnemonic
syntax remains available. Immediate operands use `#`, ordinary expressions are
memory addresses, and square brackets select the 6502 indirect modes:

| Operator syntax | Mnemonic syntax |
|---|---|
| `a := #value` | `lda #value` |
| `a := address` | `lda address` |
| `a := address,x` | `lda address,x` |
| `a := address,y` | `lda address,y` |
| `a := [zp,x]` | `lda (zp,x)` |
| `a := [zp],y` | `lda (zp),y` |
| `address := a` | `sta address` |
| `address,x := a` | `sta address,x` |
| `[zp,x] := a` | `sta (zp,x)` |
| `[zp],y := a` | `sta (zp),y` |
| `x := #value`, `y := #value` | `ldx #value`, `ldy #value` |
| `x := a`, `a := x` | `tax`, `txa` |
| `y := a`, `a := y` | `tay`, `tya` |
| `x := sp`, `sp := x` | `tsx`, `txs` |
| `a += operand`, `a -= operand` | `adc operand`, `sbc operand` |
| `a &= operand`, `a \|= operand`, `a ^= operand` | `and operand`, `ora operand`, `eor operand` |
| `a ?= operand`, `x ?= operand`, `y ?= operand` | `cmp operand`, `cpx operand`, `cpy operand` |
| `a <<=`, `a >>=` | `asl`, `lsr` |
| `address <<=`, `address >>=` | `asl address`, `lsr address` |
| `address++`, `address--` | `inc address`, `dec address` |
| `x++`, `x--`, `y++`, `y--` | `inx`, `dex`, `iny`, `dey` |

All memory forms use the same addressing-mode resolution as mnemonic syntax,
including automatic zero-page versus absolute selection, delayed operand
evaluation, and the safe absolute fallback for addresses not known while
sections are sized. The operators lower directly to their listed instructions
and do not introduce instruction-sequence optimizations. An attached `--` is
the decrement operator; put whitespace before `--` when beginning a comment
after an operand.

### Globals

#### getopt(optstring, ...)

Taken from [Posix Get Opt](http://lua-users.org/wiki/PosixGetOpt).
Parse args in `...` using `optstring`, the same way as `getopt` from Posix.

Usage:

```lua
--
-- opt is either the option character, "?", or ":".
--
-- If opt is the option character, arg is either a string or false--if optstring
-- did not specify a required argument.
--
-- If opt is either "?" or ":", then arg is the unknown option or the option
-- lacking the required argument. Like the standard says, there's really only
-- one scenario for ":" to ever be returned. And per the standard, unless
-- optstring begins with a colon, "?" is returned instead.
--
for opt, arg in getopt(":a:b", ...) do
        print("opt:", opt, "arg:", arg)
end
```

### Instruction List

#### Regular Opcodes

|   |   |   |   |   |   |   |   |
|---|---|---|---|---|---|---|---|
|adc|and|asl|bcc|bcs|beq|bit|bmi|
|bne|bpl|brk|bvc|bvs|clc|cld|cli|
|clv|cmp|cpx|cpy|dec|dex|dey|eor|
|inc|inx|iny|jmp|jsr|lda|ldx|ldy|
|lsr|nop|ora|pha|php|pla|plp|rol|
|ror|rti|rts|sbc|sec|sed|sei|sta|
|stx|sty|tax|tay|tsx|txa|txs|tya|

#### Undocumented Opcodes

|   |   |   |   |   |   |   |   |
|---|---|---|---|---|---|---|---|
|anc|ane|arr|asr|dcp|isb|jam|las|
|lax|rla|rra|sax|sbx|sha|shs|shx|
|shy|slo|sre|

#### Deriving Function Names

Each opcode is parsed by l65 then transformed to a Lua function call inside the 6502 module by concatenating the name of the opcode with one of the following addressing mode:

|Mode|Code|
|----|----|
|implied|imp|
|immediate|imm|
|zeropage|zpg|
|zeropage,x|zpx|
|zeropage,y|zpy|
|absolute|abs|
|absolute,x|abx|
|absolute,y|aby|
|(indirect)|ind|
|(indirect,x)|inx|
|(indirect),y|iny|
|relative|rel|

So for instance, `cpy #6` becomes `cpyimm(6)`, and `dec 0x80,x` becomes `deczpx(0x80)`.
There's no `Accumulator` addressing mode, use `implied` instead.

For opcodes which have both a zeropage (byte size) addressing and a matching absolute (word size) addressing, the mode can be forced using `.b` or `.w` suffix on the opcode. This may be required if the first operand can't be resolved at the beginning of the link phase, but resolves to a zeropage (byte size) addressing after link: if resolve fails when computing the size of the instruction, absolute (word size) is assumed. These opcodes, without suffix, use the following addressing codes:

|Mode|Code|
|----|----|
|zeropage or absolute|zab|
|zeropage,x or absolute,x|zax|
|zeropage,y or absolute,y|zay|

#### Late and Early Operands

The first operand of each opcode is by default encapsulated into a function for late processing during link and binary generation phases, if it's not a simple number or string. So:

```lua
    sta WSYNC
-- translates to:
    stazab(function(_o,_f) return _o+_f( WSYNC) end)
```

An optional second operand can be specified, regardless of the addressing mode, which is not encapsulated and added later to the result of the first encapsulated parameter. The default function for the first operand simply adds the second operand to it, but any function can be specified instead.
In the example above, `_o` is the value of the second operand, and `_f` is a function used to resolve the value of the first operand (see [op_resolve](#op_resolve-v)).

```lua
    lda TIM1T,i
    lda (bla,5,x)
    lda (bla,4),y
-- translates to:
    ldazab(function(_o,_f) return _o+_f( TIM1T) end,i)
    ldainx (function(_o,_f) return _o+_f(bla) end,5)
    ldainy (function(_o,_f) return _o+_f(bla) end,4)
```

This is useful in case the value you want to use as operand is a reference to a global variable for instance. Since the function is evaluated later, the value might have changed in the meantime. Consider this:

```lua
    bla = 5
    lda (\o,f(print(o,bla) or o+bla),bla,x) -- for lda (bla,bla,x), or lda (bla+bla,x) in another assembler
    bla = 3
-- translates to:
    bla = 5
    ldainx (function(o,f) return print(o,bla) or o+bla end,bla)
    bla = 3
-- and prints:
5       3
```

So specifying `bla` in the first operand got us the value 3, ie the *last* value of the global `bla`, whereas using it in the second operand caused an immediate resolve of its value, which is 5 at the *ldainx function call*.

Note that the first operand function must be *reentrant*: it cannot have side effects, as it may be called more than once if its value can't be resolved at the beginning of the link phase. If you do need to specify side effects for it, consider hooking into the instructions before and after, to temporarily modify the `pcall` and/or `pcall_za` fields of the 6502.lua module used to attempt resolving before link is complete.

#### Toggling Encapsulation

Besides the use of `pragmas`, automatic encapsulation can be toggled from its current state for the current instruction using `!`. So if, as default, it is enabled:

```lua
    sta WSYNC
    sta !WSYNC
-- translates to:
    stazab(function(_o,_f) return _o+_f( WSYNC) end)
    stazab(WSYNC)
```

### Data Definition

#### dc.b ... ; byte(...) ; byte_hi(...) ; byte_lo(...)

Insert byte data into the current section.

Each argument is either a byte size number, a function evaluated after resolve phase and returning exactly one byte size number, a table of byte size numbers, or a string using the current [character set](#charsets--f).

`dc.b` encapsulates each of its arguments into a parameter-less function. For each argument, the current encapsulation state can be inverted using `!`.

`byte_hi` arguments can instead be any size, and the bits 8 to 15 are taken as the final byte value. Conversely, `byte_lo` keeps bits 0 to 7.

#### dc.w ... ; word(...)

Insert a word as two bytes in little-endian order.

Each argument is either a string to be used as key in the `symbols` table, a section, a label, a word size number, a function evaluated after resolve phase and returning exactly one word size number, or a table of word size numbers.

`dc.w` encapsulates each of its arguments into a parameter-less function. For each argument, the current encapsulation state can be inverted using `!`.

#### dc.l ... ; long(...)

Insert a long as four bytes in little-endian order.

Each argument is either a string to be used as key in the `symbols` table, a section, a label, a long size number, a function evaluated after resolve phase and returning exactly one long size number, or a table of long size numbers.

`dc.l` encapsulates each of its arguments into a parameter-less function. For each argument, the current encapsulation state can be inverted using `!`.

#### charset([s] [, f])

Set a new character set to be used for next string data in byte(). Without argument, revert to Lua charset.

`s`: string of all the letters of charset, or a table of the charset as returned by a previous `charset` call to set again, in which case `f` is ignored.

`f`: letter index offset, added to each letter index, or a function to transform the letter index.

Return the charset table.

#### byte_normalize(v)

Check if `v` is within byte range, call `error` if it is not, or convert negative values to positive values if it is.

#### word_normalize(v)

Check if `v` is within word range, call `error` if it is not, or convert negative values to positive values if it is.

#### long_normalize(v)

Check if `v` is within long range, call `error` if it is not, or convert negative values to positive values if it is.

### Assembler Functions (6502.lua)

#### Module Properties

`strip`: defaults to `true`. Set to `false` to disable dead stripping of relocatable sections.

`strip_empty`: defaults to `false`. Set to `true` to enable stripping of empty sections; otherwise, they are positioned at the start of the container location.

`pcall`: defaults to system's `pcall`. Set to an empty function returning `false` to disable early evaluation of expressions during link phase for computing the size of each section. This will force all opcodes without an explicit size to default to the largest possible size...

`pcall_za`: ...unless this field is set to system's `pcall`. Defaults to module's `pcall`. This field is used only by the `za*` (`zab`, `zax`, `zay`) virtual addressing modes, to discriminate between zeropage and absolute addressing.

`bin_filler`: byte used by `genbin()` to fill unwritten output space. Defaults to 0; targets may choose a different value.

`zeropage`: a function with one number parameter, returning its zeropage byte value if it is within zero/direct page addressing range, nothing otherwise. Set by default to page [0x0000, 0x00ff].

`symbols`: list of symbols, resolved or not. Values can be anything before the resolve phase, but must be numbers after (except for the metatable fields). Set as the metatable of the 6502 module, which itself should be set as the metatable of the current `_ENV` environment.

`locations`:  list of all the registered locations.

`location_current`: the currently active location, in which any new section is added to.

`sections`: list of all the registered sections.

`section_current`: the currently active section, in which any new data or instruction is added to.

`label_current`: the previous non-local label name.

`relations`: a list of all the registered relationships.

`before_link`: a list of hook functions called just before the linking phase.

`id()`: return a new unique numeric identifier.

`stats`: a table of statistics regarding the build:
 * `cycles`: the total 6502 cycle count of the program, assuming no branch is taken and no page is crossed.
 * `used`: the total ROM bytes actually used by the program.
 * `unused`: total empty ROM space.
 * `resolved_count`: number of symbols resolved during resolve phase.
 * `bin_size`: final binary size.
 * `__tostring()`: string conversion function, intended to print ROM information to the user.

#### location(start [, finish]) ; location(opt)

Create a ROM area starting at `start` or `opt[1]`. If `finish` or `opt[2]` is set, it is the last byte of the area, inclusive; otherwise, the area is unbounded.

If `opt` is an already existing location table, it sets this location as current and returns.

`opt.rorg` specifies a relocated origin: all references to symbols within this section are computed as if `start` had the value of `opt.rorg`. If it is a number, it's converted to a function adding `opt.rorg` - `opt[1]`.

If `opt.nofill` resolves to `true`, the optional gap between this location and the next is not filled up with the filler byte.

`opt.name` is displayed within `stats.__tostring()`.

When using the `opt` version, `opt` is first set as the actual location table, so custom properties are preserved.

Return the location table.

##### Other Fields

* `type`: the string `'location'`.
 * `sections`: list of sections inside this location.
 * `chunks`: a list of unused memory sections of the location area. Manipulated during link phase. Each entry has `id`, `start`, and `size` fields.
 * `used`: memory within the section containing data or instructions.
 * `unused`: wasted memory within the section, containing nothing.
 * `stops_at`: for unbounded locations, position of the last used byte.

#### @@name ; section(name) ; section(opt)

Create a section within the current location, using name `name`, `opt[1]`, or a generated unique name. Also create a label with this name.

If `opt` is an already existing section table, it sets this section as current, its owner location as current, and returns.

If `opt.org` is set, the section is fixed and must start at this address in ROM; otherwise, it can be positioned anywhere within the location during link phase.

`opt.align` requests the section starts on an address multiple of `opt.align`. If `opt.offset` is specified, then it is the reference point from the start of the section which must be aligned, instead of the start of the section itself.

If `opt.strong` resolves to `true`, the section will not be stripped even if it has no reference and stripping is active. If `opt.weak` resolves to `true`, the section is stripped if its size is 0, and the references to it will fail to resolve.

When using the `opt` version, `opt` is first set as the actual section table, so custom properties are preserved.

Return the section table.

##### Other Fields

* `type`: the string `'section'`.
 * `id`: a unique number identifier.
 * `label`: the name of this section.
 * `size`: the computed size of the section during link phase.
 * `cycles`: the sum of cycle count of the instructions within `instructions`, after link phase.
 * `refcount`: a positive number if this section is referenced.
 * `location`: the location containing this section, the currently active one at the point of the section function call.
 * `instructions`: the list of opcode functions contained within this section. Each instruction can contain:
   - `size`: a number or function returning the size of the opcode and its operands.
   - `cycles`: the number of cycles the instruction needs to execute.
   - `bin`: a byte or a function returning the binary representation of the opcode and its operands.
   - `offset`: the number of bytes from the start of the section at which this instruction is located; set during link phase.
 * `constraints`: the list of constraints within the section, filled by `samepage` and `crosspage` blocks. Each constraint has a `type` set to `'samepage'` or `'crosspage'`,  `from` and inclusive `to` indices into `instructions`, and after link phase a `start` and inclusive `finish` address position.
 * `holes`: a list of holes created by [skip](#skipbytes). Each hole has `start` index into `instructions` and a `size` number set to the parameter of `skip`.

#### @name ; label(name)

Create a label, that is a named reference to a position into the current section. If `name` starts with an `_`, the name is local to the previous one, and the final name is the previous non-local label name concatenated with this one; as such, a local label can be referenced outside its scope if named in full, with the parent prefix.

An entry with the label name referencing this label is added into the symbols table, and resolved during resolve phase.

Return the name of the label, and the label table.

##### Other Fields

* `type`: the string `'label'`.
 * `section`: the section containing this label.
 * `label`: the name of this label.
 * `size`: a function grabbing this label offset into the section during link phase.
 * `resolve`: a function returning the address of this label, after link phase succeeded.
 * `bin`: a function setting the `label_current` to this label name, if it's not local.

#### samepage ... end

Add a constraint into the current section: all the instructions or data within the block must not cross a 256 bytes page.

#### crosspage ... end

Add a constraint into the current section: the instructions or data within the block must span over at least two 256 byte pages.

#### skip(bytes)

Insert a hole in the current section of size `bytes`, which can be used by another relocatable section.

#### relate(section1, section2 [, [offset1,] offset2])

Add a position relationship between `section1` and `section2`, with `offset1` bytes from selected position for `section2`, and `offset2` bytes from selected position for `section1`, in relation to their containing locations. If `offset1` is omitted, `-offset2` is used.

This is used to ensure two sections in different locations will start at the same or related offset. For instance, if the location of `section1` starts at 0xE000 and the location of `section2` starts at 0xF000, and the linker sets `section1` to 0xE100, then `relate(section1, section2)` implies that `section2` is at 0xF100.

Related sections are positioned before other relocatable sections during link phase.

#### sleep(cycles [, noillegal])

Generate instructions into the current section to waste `cycles` cycles. If `noillegal` resolves to `true`, trashes NZ flags; otherwise, it uses illegal opcodes to preserve the flags.

#### op_resolve(v)

Performs basic operations on `v` according to its type to attempt to turn it into a number. If it's a function, it's called, if it's a string, a label or a section, it gets its address from the `symbols` table, and otherwise it fails with a call to `error`.

#### link()

Link the sections, ie set their position into their parent locations. It triggers an early evaluation of operands, to determine their size, using the 6502 `pcall` and `pcall_za` fields.

#### resolve()

Resolve symbols to numeric address values: if the value is a function, it calls it; if it's a table and has a `resolve` function field, it calls it; if it's a string, it's an index into `symbols`.

It then sets a metatable for the table `symbols` used for resolving local label references during `genbin`, as they need to know the current parent label for that.

It calls `link` if needed.

#### genbin([filler])

Generate the binary as a table, using `filler` byte to fill gaps. `filler` defaults to `bin_filler`, which is initially 0 (`brk` opcode on 6502).
It calls `resolve` first if needed.

Return a table, where each entry is a byte.

#### writebin(filename)

Write the final binary into `filename`.

#### writesym(filename [, format])

Write one or more symbol files into `filename` (prefix in case of multiple outputs) for debuggers. The last `_` in a label is turned into a `.`, to get stripping of the prefixed global label working in Stella. As such, it's best to avoid using `_` in local label names, after the initial one.

`format` defaults to 'dasm'.
All platforms: 'dasm', 'lua'.
NES: 'mesen', 'fceux'.
Game Boy: 'rgbds', with aliases 'bgb', 'mesen', 'sameboy', 'mgba', and
'emulicious' for the same standard `.sym` output.

### Parser Functions

#### Pragmas

##### syntax6502 on|off

Enable or disable 6502 syntax parsing, besides pragma itself. Default is `on`.
For instance:

```lua
#pragma syntax6502 off
lda = 5 if lda < 6 then sta=7 end -- 'lda' is now available for use normally
#pragma syntax6502 on
lda #5 -- 'lda' is now an opcode again: generates 'ldaimm(5)'
```

##### encapsulate on|off

Enable or disable automatic encapsulation of first operand of opcodes. It also inverts the meaning of `!`, which toggles the encapsulation behaviour only for the current opcode. Default is `on`.

```lua
    lda !g(),v -- disable encapsulation of 'g()': ldazab(g(),v)
#pragma encapsulate off
    lda f,v -- 'f' is not encapsulated: ldazab(f,v)
    lda !_toto+15,16,x -- '_toto+15' is encapsulated: ldazax(function(_o,_f) return _o+_f(_toto+15) end,16)
    lda #15 -- '15' is never encapsulated, as it is a number: ldaimm(15)
#pragma encapsulate on
```

##### encapsulate opcode funcname

Add the following behaviour: Parse `opcode`, parse a single expression as operand, and encapsulate it as an argument to `funcname`. For instance:

```lua
-- translate 'far x' to 'farcall(function() return x end)', farcall is defined in vcs.l65
-- encapsulation allows referencing of yet undefined sections
#pragma encapsulate far farcall
    far kernel -- generates 'farcall(function() return kernel end)'
-- translate 'xsr x' to 'xcall(function() return x end)', xcall is defined in vcs.l65
#pragma encapsulate xsr xcall
    xsr myfunc -- generates 'xcall(function() return myfunc end)'
```

##### add_opcode opcode addressing

Add `opcode` with `addressing` code to the opcode tables. The resulting function must be globally available. For instance:

```lua
-- translate 'rtx' to 'rtximp()', rtximp is defined as global in vcs.l65
#pragma add_opcode rtx imp
    rtx -- generates 'rtximp()'
```

Operands parsing is done as per implied by the addressing mode, like other opcodes.

##### alias opcode newname

Create an alias `newname` for opcode `opcode`, retaining the original name as well. For instance:

```lua
#pragma alias and dna
    dna #0x3F -- same as and #0x3F
```

Note that aliasing `and` might be a good idea, since it's also a keyword for expressions in Lua. Consider this:

```lua
lda time; and#7 -- ';' is required here to prevent considering it as ldazab(time and #7)
lda time dna#7 -- using dna, no more ambiguity: ldazab(time) andimm(7)
```

#### l65 Module

##### parse(src [, src_name])

Parse `src` as l65, using `src_name` for error reporting.

Return `true` and an AST table on success; `false` and an error string otherwise.

##### format(ast)

Transform `ast` into a string.

Return a string of `ast` on success; raise an error otherwise.

##### searcher_index

The index at which to insert the l65 file searcher, followed by the embedded scripts searcher. Defaults to 2.

##### search_path

The search path used by the l65 file searcher. Defaults to filename if current directory, then with added '.l65' extension, then in l65 executable directory, then in l65 executable directory with '.l65' extension.

##### report(success, ...)

If `success` resolves to `true`, it returns all of its arguments. Otherwise, it writes the message, which is the first field of `...`, to `stderr` and exits the program.

##### msghandler(msg)

The function used for `xpcall` of the input file given on command line. It merges two stacktraces when an error happens in a late eval function.

##### load_embedded(name)

The searcher for scripts included into the l65 executable binary.

##### searcher(name)

The searcher for l65 files on disk.

##### load, loadfile, dofile ; installhooks(), uninstallhooks()

Hook functions to load l65 chunks and files automatically. Installed by default. Use `l65.installhooks()` and `l65.uninstallhooks()` to set the hooks or restore the original functions.

##### image(filename)

A C function, calling stb_image on `filename`, with only 8b palette-based PNG support. It does not translate colors to RGB triplets, but keeps the palette index as the value of the pixel.

Return `nil` and an error message on failure, or a table with the following fields on success:
 * `filename`: PNG filename
 * `width`: image width, in pixels
 * `height`: image height, in pixels
 * [1..width\*height]: the pixels, as palette indices (all bytes)

### PB8 and PB16 compression

The embedded `pb` module ports Damian Yerrick's PB8 and PB16 encoders to Lua,
so assets can be compressed without an external Python step. `pb.pb8(data)`
and `pb.pb16(data)` accept a raw string or byte table; `pb.pb8_file(filename)`
and `pb.pb16_file(filename)` read an asset directly. All return a byte table
suitable for `byte(...)`. The last packet is padded to eight decoded bytes.

Game Boy programs can emit callable PB8 and PB16 routines in the current ROM
location with `pb8_unpacker()` and `pb16_unpacker()`. Their
`pb8_unpack_packet()` / `pb8_unpack_block(packet)` and
`pb16_unpack_packet()` / `pb16_unpack_block(packet)` bodies are also available
inline. Both packet forms expand eight bytes from DE to HL. The PB8 block form
expands `8 * C` bytes, while PB16 expands `16 * B` bytes. PB16's temporary byte
defaults to HRAM and can be relocated by setting `pb16_byte0` before emitting
the routines.

### Platform Modules

`vcs.l65` is a helper file for developing on Atari 2600 VCS. It's embedded into the l65 executable. It sets the 6502.lua module as metatable of the current `_ENV`, defines all TIA and PIA symbols, some helper constants and functions, as well as mapper helpers and automatic cross bank call functions. See the samples directory for usage examples, and browse vcs.l65 directly for the list of self-explanatory helpers.

`nes.l65` is for NES/Famicom. It provides templates for some mappers, including 0-NROM, 1-MMC1, 2-UxROM, 3-CNROM, 4-MMC3, 5-MMC5, and 66-GxROM.

## LZ80

`gb.lz80` provides cartridge declarations for ROM-only, MBC1, MBC2, MBC3,
and MBC5 through `mappers.ROM`, `mappers.MBC1`, `mappers.MBC2`,
`mappers.MBC3`, and `mappers.MBC5`.
For every 32 KiB cartridge (`rom_banks = 2`), `rom`, `rom0`, `rom1`, and
`romx` alias the same contiguous `$0000-$7FFF` location, so relocatable
sections do not need to choose a ROM bank. Larger cartridges retain separate
fixed and switchable locations.
Declare an RTC-equipped MBC3 cartridge with `mappers.MBC3{ rtc = true }`;
this selects the timer+battery cartridge type.

`gb.lz80` exposes the constants from
[gbdev hardware.inc v5.3.0](https://raw.githubusercontent.com/gbdev/hardware.inc/v5.3.0/hardware.inc)
directly, without RGBDS's register-name `r` prefix. This includes register
aliases, bit positions and masks such as `LCDC_ON`, `LCDC_BG_ON`, `STAT_BUSY`,
`AUDENA_ON`, screen/tile/OAM dimensions, interrupt vectors, CGB controls, and
common MBC values. `PAD_*` uses hardware.inc's conventional layout;
its bit positions and masks match the values returned by `read_joy`.

As with l65, lz80 immediate operands always use the `#` prefix: for example,
`ld sp,#0xfffe` and `cp #144`. For `ld` and `ldh`, bare operands denote memory
addresses (`ld a,variable`, `ld variable,a`, `ldh a,SCX`), while register-indirect
operands use parentheses (`ld a,(hl)`, `ldh a,(c)`). Direct branch and call
destinations remain unprefixed; indirect jumps use parentheses (`jp (hl)`).
Parenthesized absolute addresses such as `ld a,(variable)` are rejected.

LZ80 also provides an optional operator syntax. Unbracketed values are
immediates (except register names), square brackets dereference memory, and
`[hl+]` / `[hl-]` select the Game Boy incrementing/decrementing loads:

| Operator syntax | Mnemonic syntax |
|---|---|
| `a := 3` | `ld a,#3` |
| `hl := foo` | `ld hl,#foo` |
| `a := [foo]` | `ld a,foo` |
| `a := [hl]` | `ld a,(hl)` |
| `[hl] := a` | `ld (hl),a` |
| `hl := sp+4` | `ld hl,sp+#4` |
| `sp := hl` | `ld sp,hl` |
| `a += b` | `add a,b` |
| `a -= 4` | `sub #4` |
| `a &= 0x3f` | `ana #0x3f` |
| `a \|= 0x80` | `ora #0x80` |
| `a ^= a` | `xor a` |
| `hl++`, `c--`, `[hl]++` | `inc hl`, `dec c`, `inc (hl)` |
| `[hl+] := a`, `a := [hl-]` | `ldi (hl),a`, `ldd a,(hl)` |
| `jr.nz label`, `jp.z label` | `jr nz,label`, `jp z,label` |

Lua's `#` length operator can be used in immediate expressions. Mnemonic
syntax therefore uses two hashes (`ld c,##hello` or `ld hl,sp+##hello`): the
first marks the operand as immediate and the second is Lua's length operator.
Operator values are already immediate, so they use one (`c := #hello` or
`hl := sp+#hello`).

Operator immediates are normally delayed until symbol resolution. Prefix the
right-hand expression with `!` to evaluate it while the macro is being emitted,
for example `a := !bytes[i]`, `hl := !address()`, or
`a := !(value or 0x91)`. This is the operator equivalent of disabling operand
encapsulation in mnemonic syntax.

A `[` beginning a new line always starts a new operator memory statement; it
does not index the Lua expression on the preceding line. Thus consecutive
assignments such as `a := value` followed by `[LCDC] := a` do not require a
semicolon.

The operator syntax lowers directly to the corresponding instruction and does
not optimize instruction sequences. In particular, `a := 0` emits `ld a,#0`;
only `a ^= a` emits `xor a`. Instructions without an unambiguous operator form,
such as `adc`, rotations, bit operations, `call`, `ret`, and `rst`, retain their
mnemonic syntax. Bit operations also accept bracketed memory in operator-style
source, for example `set 3,[hl]`.

Game Boy operator assignments through A select the shorter `ldh` encoding when
the resolved memory address is in `$ff00`-`$ffff`. This choice is delayed so
constants declared later in the source also work: `[LCDC] := a` and
`a := [LCDC]` emit `ldh LCDC,a` and `ldh a,LCDC`. Mnemonic syntax remains
explicit: `ld` always emits the absolute form, while `ldh` always emits the
high-page form.

### Game Boy debugfiles

`gb.lz80` can generate version-1 Game Boy
[debugfiles](https://github.com/aaaaaa123456789/gb-debugfiles/blob/master/debugfile.md).
Annotations emit no ROM bytes, and actions placed inside code are resolved to
their final bank and address after linking:

```lua
dbg_group("checks", "Runtime checks")

@@main
    dbg_log("Entering main")

@@loop
    runtime_assert("@sp >= $ff80", "Stack escaped HRAM")
    -- ...
    jr loop

end_dbg_group()

writebin(filename .. ".gb")
writesym(filename .. ".sym", "rgbds")
writedebug(filename .. ".dbg", { symfile = filename .. ".sym" })
```

`dbg_action(commands, condition, flags)` adds an action at the current code
position; flags default to `x`. `dbg_watch(address, flags, commands, condition)`
accepts explicit symbols, numeric addresses, ranges, or address lists.
`dbg_break`, `dbg_log`, `dbg_alert`, `runtime_assert`, `unreachable`, `dbg_var`,
`dbg_group`, and `end_dbg_group` provide common operations. `dbg_line` accepts
any single raw line from the specification for directives or commands that do
not need a dedicated helper. `getdebugfile` returns the generated text, while
`writedebug` writes it to disk; both accept either a symfile path or an options
table containing `symfile` and an optional `version`.

## Building

With Zig installed, build all three assemblers with:

```sh
zig build
```

The executables are installed in `zig-out/bin/`. Their Lua assembler and
platform modules are embedded, so rerun `zig build` after editing those files.

Alternatively, use CMake to build a standalone executable. Following are basic
instructions if you've never used CMake.

### Windows

32b version:
```
mkdir build\win32
cd build\win32
cmake -G "Visual Studio 15 2017" ..\..
cd ..
cmake --build win32 --config Release
```

64b version:
```
mkdir build\win64
cd build\win64
cmake -G "Visual Studio 15 2017 Win64" ..\..
cd ..
cmake --build win64 --config Release
```

### Linux

```
mkdir -p build/linux
cd build/linux
cmake ../.. -DCMAKE_BUILD_TYPE=Release
make
```

Force 32b build on 64b system:
```
mkdir -p build/linux32
cd build/linux32
cmake ../.. -DCMAKE_BUILD_TYPE=Release -DCMAKE_C_FLAGS=-m32
make
```

## Vim files installation

* copy `vim/*` into `~/vimfiles/`
 * add `au BufRead,BufNewFile *.l65 set syntax=l65 filetype=l65` to `~/.vimrc` (or `~/_vimrc` on Windows)
 * add `au BufRead,BufNewFile *.l7801 set syntax=l7801 filetype=l7801` for l7801 files
 * add `au BufRead,BufNewFile *.lz80 set syntax=lz80 filetype=lz80` for lz80 files

Note that the syntax file includes some highlighting for features only activated via pragmas: `dna`, `xsr`, `rtx` and `far`. If you do not want to use these keywords, remove them from the syntax file.

## Visual Studio Code extension

Install the "l65" extension from the marketplace or check [l65-vscode](https://github.com/g012/l65-vscode) repository.

## TODO List

* helpers to inter-operate with cc/ca65 and dasm

## Credits

Developed by g012, using:
 * [Lua 5.3.4](https://www.lua.org)
 * [LuaMinify](https://github.com/stravant/LuaMinify)
 * [LuaFileSystem](https://keplerproject.github.io/luafilesystem)
 * [LPeg](http://www.inf.puc-rio.br/~roberto/lpeg)
 * [stb_image](https://github.com/nothings/stb)
 * [dkjson](http://dkolf.de/src/dkjson-lua.fsl)
 * Lua syntax file shipping with [vim](http://www.vim.org)
 * Lua indent file from [vim-lua](https://github.com/tbastos/vim-lua)

Projects which inspired l65:
 * [nimble65](https://bitbucket.org/kylearan/nimble65)
 * [k65](http://devkk.net/wiki/index.php?title=K65)

## License

l65 is licensed under the MIT License, see LICENSE for more information.

l65

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README