2019-07-15 12:21:50 +00:00
[< back to index ](../doc_index.md )
2018-07-01 22:45:53 +00:00
## Adding a custom platform
Every platform is defined in an `.ini` file with an appropriate name.
2018-12-17 09:41:28 +00:00
As an extension, multiline entries are supported:
if a line ends with a backslash character, the value continues to the next line.
2018-07-01 22:45:53 +00:00
#### `[compilation]` section
* `arch` – CPU architecture. It defines which instructions are available. Available values:
* `nmos` (original 6502)
* `strict` (NMOS without illegal instructions)
* `ricoh` (Ricoh 2A03/2A07, NMOS without decimal mode)
* `strictricoh` (Ricoh 2A03/2A07 without illegal instructions)
* `cmos` (WDC 65C02 or 65SC02)
* `65ce02` (CSG 65CE02; experimental)
* `huc6280` (Hudson HuC6280; experimental)
* `65816` (WDC 65816/65802; experimental; currently only programs that use only 16-bit addressing are supported)
2019-05-31 15:27:38 +00:00
* `z80` (Zilog Z80)
2018-07-27 17:12:54 +00:00
2019-06-12 10:06:02 +00:00
* `strictz80` (Z80 without illegal instructions)
2019-05-31 15:27:38 +00:00
* `i8080` (Intel 8080)
2018-07-27 17:12:54 +00:00
2019-05-31 15:27:38 +00:00
* `i8085` (Intel 8085)
2019-06-12 10:06:02 +00:00
* `strict8085` (Intel 8085 without illegal instructions)
2019-05-31 15:27:38 +00:00
* `gameboy` (Sharp LR35902; experimental)
2019-05-31 15:03:35 +00:00
* `i8086` (Intel 8086; very experimental, very buggy and very, very incomplete –
see the [8086 support disclaimer ](../lang/x86disclaimer.md ))
2018-07-01 22:45:53 +00:00
2019-06-12 10:06:02 +00:00
* `encoding` – default encoding for console I/O. Default: `ascii` .
See [the list of available encodings ](../lang/text.md ).
2018-07-06 22:58:44 +00:00
* `screen_encoding` – default encoding for screencodes (literals with encoding specified as `scr` ).
Default: the same as `encoding` .
2018-07-01 22:45:53 +00:00
* `modules` – comma-separated list of modules that will be automatically imported
* other compilation options (they can be overridden using commandline options):
* `emit_illegals` – whether the compiler should emit illegal instructions, default `false`
2019-06-12 10:06:02 +00:00
* `emit_cmos` – whether the compiler should emit 65C02 instructions, default is `true` on compatible processors and `false` elsewhere
2018-07-01 22:45:53 +00:00
* `emit_65816` – which 65816 instructions should the compiler emit, either `no` , `emulation` or `native`
2018-08-03 11:06:23 +00:00
* `decimal_mode` – whether the compiler should emit decimal instructions, default is `false` on `ricoh` and `strictricoh` and `true` elsewhere;
if disabled, a software decimal mode will be used
2019-06-12 10:06:02 +00:00
* `emit_8085` – whether the compiler should emit Intel 8085 instructions, default is `true` on compatible processors and `false` elsewhere
* `emit_x80` – whether the compiler should emit instructions present on Sharp LR35902 and Z80, but absent on Intel 8080, default is `true` on compatible processors and `false` elsewhere
* `emit_z80` – whether the compiler should emit Zilog Z80 instructions not covered by `emit_x80` , default is `true` on compatible processors and `false` elsewhere
2018-07-01 22:45:53 +00:00
* `prevent_jmp_indirect_bug` – whether the compiler should try to avoid the indirect JMP bug,
2018-07-03 21:28:05 +00:00
default is `false` on 65C02-compatible or non-6502 processors and `true` elsewhere
2018-07-01 22:45:53 +00:00
2018-12-27 00:18:29 +00:00
* `compact_dispatch_params` – whether parameter values in return dispatch statements may overlap other objects, default is `true` .
2018-07-01 22:45:53 +00:00
This may cause problems if the parameter table is stored next to a hardware register that has side effects when reading.
* `lunix` – generate relocatable code for LUnix/LNG, default is `false`
2018-07-03 21:28:05 +00:00
2018-08-03 11:06:23 +00:00
* `zeropage_register` – reserve a certain amount of bytes of zero page as a pseudoregister to increase language features.
Default: `4` if targeting a 6502-based architecture, `0` otherwise.
`true` is a synonym of the current compiler default (currently: 4) and `false` is a synonym for 0.
2018-07-03 21:28:05 +00:00
* `inline` - inline functions automatically by default, default is `false` .
* `ipo` - enable interprocedural optimization, default is `false` .
2018-07-06 22:58:44 +00:00
2018-12-27 00:18:29 +00:00
* `function_fallthrough` – whether should replace a tail call by simply putting one function after another, default is `true` .
* `function_deduplication` – whether identical functions should be merged into one function, default is `true` .
* `subroutine_extraction` – whether identical fragments of functions should be extracted into subroutines, default is `false` .
2018-07-06 22:58:44 +00:00
* `lenient_encoding` - allow for automatic substitution of invalid characters in string literals using the default encodings, default is `false` .
2018-08-01 10:50:05 +00:00
* `use_shadow_registers_for_irq` – use Z80 shadow registers in interrupt routines, default is `true` for Z80 and `false` otherwise
2019-06-05 16:34:32 +00:00
* `ix_stack` – use the IX register to access stack variables, default is `true` for Z80 and 8086, `false` otherwise
2018-08-01 10:50:05 +00:00
* `iy_stack` – use the IY register to access stack variables, default is `false`
* `ix_scratch` – allow using the IY register for other purposes, default is `false`
* `iy_scratch` – allow using the IY register for other purposes, default is `false`
2018-08-01 19:16:20 +00:00
2019-06-05 16:34:32 +00:00
* `software_stack` – use software stack for stack variables, default is `false` . Applicable only to 6502-based targets.
2018-12-14 21:01:52 +00:00
2019-05-31 15:27:38 +00:00
* `output_intel_syntax` – use Intel syntax instead of Zilog syntax, default is `true` for Intel 8080/8085 and `false` otherwise
2018-08-01 10:50:05 +00:00
2018-07-01 22:45:53 +00:00
2018-07-12 16:30:35 +00:00
#### `[define]` section
This section defines values of features of the target.
See the [preprocessor documentation ](../lang/preprocessor.md ) for more info.
2018-07-01 22:45:53 +00:00
#### `[allocation]` section
* `zp_pointers` –
either a list of comma separated zeropage addresses that can be used by the program as zeropage pointers, or `all` for all.
Each value should be the address of the first of two free bytes in the zeropage.
2019-06-26 16:33:59 +00:00
Only used for 6502-based targets. Cannot be used together with `zp_bytes` .
* `zp_bytes` –
either a list of comma separated zeropage byte addresses or address ranges that can be used by the program in zeropage, or `all` for all.
Only used for 6502-based targets. Cannot be used together with `zp_pointers` .
2018-07-01 22:45:53 +00:00
* `segments` – a comma-separated list of segment names.
A segment named `default` is always required.
Default: `default` . In all options below, `NAME` refers to a segment name.
* `default_code_segment` – the default segment for code and initialized arrays.
Note that the default segment for uninitialized arrays and variables is always `default` .
Default: `default`
2019-06-28 14:28:49 +00:00
* `ram_init_segment` – the segment storing a copy of initial values for preinitialized writable arrays and variables.
The segment cannot be `default` . See [the ROM vs RAM guide ](./rom-vs-ram.md ) for more information.
Default: none.
2018-07-01 22:45:53 +00:00
* `segment_NAME_start` – the first address used for automatic allocation in the segment.
2019-06-05 16:34:32 +00:00
Note that on 6502-like targets, the `default` segment shouldn't start before $200, as the $0-$1FF range is reserved for the zeropage and the stack.
2018-07-01 22:45:53 +00:00
The `main` function will be placed as close to the beginning of its segment as possible, but not necessarily at `segment_NAME_start`
* `segment_NAME_end` – the last address in the segment
* `segment_NAME_codeend` – the last address in the segment for code and initialized arrays.
Only uninitialized variables are allowed between `segment_NAME_codeend` and `segment_NAME_end` .
Default: the same as `segment_NAME_end` .
* `segment_NAME_datastart` – the first address used for non-zeropage variables, or `after_code` if the variables should be allocated after the code.
Default: `after_code` .
2019-06-14 09:39:11 +00:00
* `segment_NAME_bank` – the bank number the segment belongs to. Default: `0` .
For better debugging on NES, RAM segments should use bank number `$ff` .
2019-08-16 16:00:04 +00:00
* `segment_NAME_fill` – the byte value used to fill gaps and other unused space in the bank. Default: `0` .
2018-07-01 22:45:53 +00:00
#### `[output]` section
* `style` – how multi-segment programs should be output:
* `single` – output a single file, based mostly, but not necessarily only on data in the `default` segment (the default)
* `lunix` – like `single` , but add data necessary for relocation between code and data (requires `lunix` option in the `compilation` section)
* `per_segment` – generate a separate file with each segment
* `format` – output file format; a comma-separated list of tokens:
* literal byte values
* `startaddr` – little-endian 16-bit address of the first used byte of the compiled output (not necessarily the segment start)
2019-07-28 00:00:59 +00:00
* `startaddr_be` – the same, but big-endian
2018-07-01 22:45:53 +00:00
* `startpage` – the high byte of `startaddr`
* `endaddr` – little-endian 16-bit address of the last used byte of the compiled output (usually not the segment end)
2019-07-28 00:00:59 +00:00
* `endaddr_be` – the same, but big-endian
* `length` – little-endian 16-bit length of the compiled output; `endaddr - startaddr + 1`
* `length_be` – the same, but big-endian
2018-07-01 22:45:53 +00:00
* `allocated` – all used bytes
* `pagecount` – the number of pages used by all used bytes (including partially filled pages)
* `<addr>:<addr>` - inclusive range of bytes
* `<segment>:<addr>:<addr>` - inclusive range of bytes in a given segment
* `d88` - a D88 floppy disk image for PC-88
2018-07-03 21:28:05 +00:00
* `tap` - a tape disk image for ZX Spectrum
2018-07-01 22:45:53 +00:00
* `extension` – target file extension, with or without the dot
* `bbc_inf` – should the `.inf` file with file metadata for BBC Micro be created
2019-01-11 14:17:48 +00:00
* `gb_checksum` – should the main output file be patched with Game Boy-compatible checksums
2019-06-14 09:39:11 +00:00
* `labels` – format of the label file:
* `vice` (the default) – format compatible with the Vice emulator. The extension is `.lbl` .
* `nesasm` – format used by the NESASM assembler. The extension is `.fns` .
* `sym` – format used by the WLA/DX assembler. The extension is `.sym` .
* `fceux` – multi-file format used by the FCEUX emulator. The extension is `.nl` .