mirror of
https://github.com/KarolS/millfork.git
synced 2025-04-09 09:41:23 +00:00
Splitting and tweaking documentation
This commit is contained in:
Karol Stasiak
parent
9512e8e7ae
commit
ed067d3a67
18
docs/api/apple2-programming-guide.md
Normal file
18
docs/api/apple2-programming-guide.md
Normal file
@ -0,0 +1,18 @@
|
||||
[< back to index](../index.md)
|
||||
|
||||
### A note about Apple II
|
||||
|
||||
Apple II variants other than II+/IIe/Enhanced IIe are untested;
|
||||
this includes the original II, IIc and IIc+, but also later compatible computers (Apple III and IIgs).
|
||||
They may or may not work.
|
||||
|
||||
The compiler output is a raw machine code file, which then has to be put on a disk.
|
||||
You can do it using [CiderPress](http://a2ciderpress.com/),
|
||||
[AppleCommander](https://applecommander.github.io/),
|
||||
or some other tool.
|
||||
|
||||
The file has to be loaded from $0C00. An example how to put such file onto a disk using AppleCommander:
|
||||
|
||||
java -jar AppleCommander-1.3.5.jar -p disk_image.dsk FILENAME B 0xc00 < compiler_output.a2
|
||||
|
||||
Creating a bootable disk is beyond the scope of this document.
|
||||
15
docs/api/bbcmicro-programming-guide.md
Normal file
15
docs/api/bbcmicro-programming-guide.md
Normal file
@ -0,0 +1,15 @@
|
||||
[< back to index](../index.md)
|
||||
|
||||
### A note about BBC Micro
|
||||
|
||||
The default configuration file puts the start address for the program at $0E00.
|
||||
|
||||
The compiler outputs two files: a raw machine code file without an extension and a `.inf` file with file metadata.
|
||||
To use the file, you need to put it on a disk or a disk image.
|
||||
You can for example use tools like BBC Disk Explorer.
|
||||
|
||||
After putting it on a disk, the file can be run with:
|
||||
|
||||
*RUN "FILENAME"
|
||||
|
||||
Currently, multipart BBC Micro programs are not supported.
|
||||
112
docs/api/custom-plaftorm.md
Normal file
112
docs/api/custom-plaftorm.md
Normal file
@ -0,0 +1,112 @@
|
||||
[< back to index](../index.md)
|
||||
|
||||
## Adding a custom platform
|
||||
|
||||
Every platform is defined in an `.ini` file with an appropriate name.
|
||||
|
||||
#### `[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)
|
||||
|
||||
* `z80` (Zilog Z80; experimental and very incomplete)
|
||||
|
||||
* `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`
|
||||
|
||||
* `emit_cmos` – whether the compiler should emit CMOS instructions, default is `true` on compatible processors and `false` elsewhere
|
||||
|
||||
* `emit_65816` – which 65816 instructions should the compiler emit, either `no`, `emulation` or `native`
|
||||
|
||||
* `decimal_mode` – whether the compiler should emit decimal instructions, default is `false` on `ricoh` and `strictricoh` and `true` elsewhere
|
||||
|
||||
* `ro_arrays` – whether the compiler should warn upon array writes, default is `false`
|
||||
|
||||
* `prevent_jmp_indirect_bug` – whether the compiler should try to avoid the indirect JMP bug,
|
||||
default is `false` on 65C02-compatible processors and `true` elsewhere
|
||||
|
||||
* `compact_dispatch_params` – whether parameter values in return dispatch statements may overlap other objects, default is `true`
|
||||
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`
|
||||
|
||||
|
||||
#### `[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.
|
||||
Only used for 6502-based targets.
|
||||
|
||||
* `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`
|
||||
|
||||
* `segment_NAME_start` – the first address used for automatic allocation in the segment.
|
||||
Note that the `default` segment shouldn't start before $200, as the $0-$1FF range is reserved for the zeropage and the stack.
|
||||
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`.
|
||||
|
||||
#### `[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)
|
||||
|
||||
* `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)
|
||||
|
||||
* `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
|
||||
|
||||
* `extension` – target file extension, with or without the dot
|
||||
|
||||
* `bbc_inf` – should the `.inf` file with file metadata for BBC Micro be created
|
||||
12
docs/api/lunix-programming-guide.md
Normal file
12
docs/api/lunix-programming-guide.md
Normal file
@ -0,0 +1,12 @@
|
||||
[< back to index](../index.md)
|
||||
|
||||
### A note about LUnix
|
||||
|
||||
LUnix uses relocatable code, which means that object addresses (`.addr`) are not constants.
|
||||
To help with this problem, new constants are defined, with a `.rawaddr` suffix.
|
||||
They are not relocated, so to use them, you need to manually relocate them
|
||||
by adding `relocation_offset` to their high bytes:
|
||||
|
||||
pointer p
|
||||
p = variable.rawaddr
|
||||
p.hi += relocation_offset
|
||||
@ -2,8 +2,11 @@
|
||||
|
||||
# Target platforms
|
||||
|
||||
Currently, Millfork supports creating disk- or tape-based programs for Commodore, Apple and Atari 8-bit computers,
|
||||
but it may be expanded to support other 6502-based platforms in the future.
|
||||
Currently, Millfork supports creating disk- or tape-based programs for Commodore, Apple, BBC and Atari 8-bit computers
|
||||
and cartridge-based programs for Famicom/NES and Atari 2600,
|
||||
but it may be expanded to support other 6502-based and Z80-based platforms in the future.
|
||||
|
||||
To add a custom platform yourself, see [the custom platform adding guide](./custom-plaftorm.md).
|
||||
|
||||
## Supported platforms
|
||||
|
||||
@ -16,6 +19,8 @@ The following platforms are currently supported:
|
||||
* `c64_scpu16` – Commodore 64 with SuperCPU in native, 16-bit mode (very buggy)
|
||||
|
||||
* `lunix` – Commodore 64 or 128 running LUnix/LNG 0.21
|
||||
Certain language features work differently on this target.
|
||||
Read [the LUnix programming guide](./lunix-programming-guide.md) for more info.
|
||||
|
||||
* `c16` – Commodore 16
|
||||
|
||||
@ -42,8 +47,12 @@ Read [the NES programming guide](./famicom-programming-guide.md) for more info.
|
||||
* `a8` – Atari 8-bit computers
|
||||
|
||||
* `bbcmicro` – BBC Micro model B (32k RAM)
|
||||
The compiler only emits raw binaries, not disk images.
|
||||
Read [the BBC Micro programming guide](./bbcmicro-programming-guide.md) for more info.
|
||||
|
||||
* `apple2` – Apple II+/IIe/Enhanced IIe
|
||||
* `apple2` – Apple II+/IIe/Enhanced IIe.
|
||||
The compiler only emits raw binaries, not disk images.
|
||||
Read [the Apple 2 programming guide](./apple2-programming-guide.md) for more info.
|
||||
|
||||
* `pc88` – NEC PC-88 (very incomplete and not usable for anything yet)
|
||||
|
||||
@ -51,156 +60,3 @@ The primary and most tested platform is Commodore 64.
|
||||
|
||||
Currently, targets that assume that the program will be loaded from disk or tape are better tested.
|
||||
Cartridge targets may exhibit unexpected bugs.
|
||||
|
||||
### A note about Apple II
|
||||
|
||||
Apple II variants other than II+/IIe/Enhanced IIe are untested;
|
||||
this includes the original II, IIc and IIc+, but also later compatible computers (Apple III and IIgs).
|
||||
They may or may not work.
|
||||
|
||||
The compiler output is a raw machine code file, which then has to be put on a disk.
|
||||
You can do it using [CiderPress](http://a2ciderpress.com/),
|
||||
[AppleCommander](https://applecommander.github.io/),
|
||||
or some other tool.
|
||||
|
||||
The file has to be loaded from $0C00. An example how to put such file onto a disk using AppleCommander:
|
||||
|
||||
java -jar AppleCommander-1.3.5.jar -p disk_image.dsk FILENAME B 0xc00 < compiler_output.a2
|
||||
|
||||
Creating a bootable disk is beyond the scope of this document.
|
||||
|
||||
### A note about BBC Micro
|
||||
|
||||
The default configuration file puts the start address for the program at $0E00.
|
||||
|
||||
The compiler outputs two files: a raw machine code file without an extension and a `.inf` file with file metadata.
|
||||
To use the file, you need to put it on a disk or a disk image.
|
||||
You can for example use tools like BBC Disk Explorer.
|
||||
|
||||
After putting it on a disk, the file can be run with:
|
||||
|
||||
*RUN "FILENAME"
|
||||
|
||||
Currently, multipart BBC Micro programs are not supported.
|
||||
|
||||
### A note about LUnix
|
||||
|
||||
LUnix uses relocatable code, which means that object addresses (`.addr`) are not constants.
|
||||
To help with this problem, new constants are defined, with a `.rawaddr` suffix.
|
||||
They are not relocated, so to use them, you need to manually relocate them
|
||||
by adding `relocation_offset` to their high bytes:
|
||||
|
||||
pointer p
|
||||
p = variable.rawaddr
|
||||
p.hi += relocation_offset
|
||||
|
||||
## Adding a custom platform
|
||||
|
||||
Every platform is defined in an `.ini` file with an appropriate name.
|
||||
|
||||
#### `[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)
|
||||
|
||||
* `z80` (Zilog Z80; experimental and very incomplete)
|
||||
|
||||
* `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`
|
||||
|
||||
* `emit_cmos` – whether the compiler should emit CMOS instructions, default is `true` on compatible processors and `false` elsewhere
|
||||
|
||||
* `emit_65816` – which 65816 instructions should the compiler emit, either `no`, `emulation` or `native`
|
||||
|
||||
* `decimal_mode` – whether the compiler should emit decimal instructions, default is `false` on `ricoh` and `strictricoh` and `true` elsewhere
|
||||
|
||||
* `ro_arrays` – whether the compiler should warn upon array writes, default is `false`
|
||||
|
||||
* `prevent_jmp_indirect_bug` – whether the compiler should try to avoid the indirect JMP bug,
|
||||
default is `false` on 65C02-compatible processors and `true` elsewhere
|
||||
|
||||
* `compact_dispatch_params` – whether parameter values in return dispatch statements may overlap other objects, default is `true`
|
||||
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`
|
||||
|
||||
|
||||
#### `[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.
|
||||
Only used for 6502-based targets.
|
||||
|
||||
* `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`
|
||||
|
||||
* `segment_NAME_start` – the first address used for automatic allocation in the segment.
|
||||
Note that the `default` segment shouldn't start before $200, as the $0-$1FF range is reserved for the zeropage and the stack.
|
||||
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`.
|
||||
|
||||
#### `[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)
|
||||
|
||||
* `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)
|
||||
|
||||
* `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
|
||||
|
||||
* `extension` – target file extension, with or without the dot
|
||||
|
||||
* `bbc_inf` – should the `.inf` file with file metadata for BBC Micro be created
|
||||
|
||||
@ -11,6 +11,8 @@
|
||||
|
||||
* [Target platform reference](api/target-platforms.md)
|
||||
|
||||
* [Defining a custom platform](api/custom-platform.md)
|
||||
|
||||
## Language reference
|
||||
|
||||
* [Syntax](lang/syntax.md)
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user