Rename documentation files

2026-04-20 18:16:35 +00:00 · 2018-03-28 19:31:10 +02:00
parent 1fcbf9fd5b
commit 1a0737e4c9
21 changed files with 3 additions and 3 deletions
@@ -0,0 +1,102 @@
+# Command-line options
+
+## General options
+
+* `--version` – Display the version number and quit.
+
+* `--help` – Displays help the command line option.
+
+* `--` – End of the options, all the following parameters will be treated as input files, even if they look like options.
+
+## I/O options
+
+*  `-o <file>` – Output filename, without extension. Extension will be added automatically, `.prg` for Commodore, `.a2` for Apple and `.xex` for Atari.
+
+* `-s` – Generate also the assembly output. It is not compatible with any assembler, but it serves purely informational purpose. The file has the same nam as the output file and the extension is `.asm`.
+
+* `-g` – Generate also the label file. The label file contains labels with their addresses, with duplicates removed. It can be loaded into the monitor of the Vice emulator for debugging purposes. The file has the same nam as the output file and the extension is `.lbl`.
+
+* `-I  <dir>;<dir>` – The include directories. The current working directory is also an include directory. Those directories are searched for modules and platform definitions.
+ 
+* `-t <platform>` – Target platform. It is loaded from an `.ini` file found in any of the include directories. See also [this document](target-platforms.md).
+
+* `-r <program>` – Run given program after successful compilation. Useful for automatically launching emulators without any external scripting.
+
+
+## Verbosity options
+
+ * `-q` – Suppress all messages except for errors.
+
+* `-v`, `-vv`, `-vvv` – Increase verbosity, various levels.
+
+## Code generation options
+
+* `-fcmos-ops`, `-fno-cmos-ops` – Whether should emit CMOS opcodes.  
+`.ini` equivalent: `emit_cmos`.
+Default: yes if targeting a 65C02-compatible architecture, no otherwise.
+
+* `-fillegals`, `-fno-illegals` – Whether should emit illegal (undocumented) NMOS opcodes.  
+`.ini` equivalent: `emit_illegals`.
+Default: no.
+
+* `-f65ce02-ops`, `-fno-65ce02-ops` – Whether should emit 65CE02 opcodes.  
+`.ini` equivalent: `emit_65ce026`. 
+Default: yes if targeting 65CE02, no otherwise.
+
+* `-fhuc6280-ops`, `-fno-huc6280-ops` – Whether should emit HuC6280 opcodes.  
+`.ini` equivalent: `emit_huc6280`. 
+Default: yes if targeting HuC6280, no otherwise.
+
+* `-fno-65816-ops`, `-femulation-65816-ops`, `-fnative-65816-ops` – Which subset of 65816 instructions to support. 
+`-fnative-65816-ops` is required to use any 16-bit operations. 
+Currently, there is not much support in the compiler for the native mode.
+`.ini` equivalent: `emit_65816`. 
+Default: native if targeting 65816, no otherwise.
+
+* `-fjmp-fix`, `-fno-jmp-fix` – Whether should prevent indirect JMP bug on page boundary.  
+`.ini` equivalent: `prevent_jmp_indirect_bug`.
+Default: no if targeting a 65C02-compatible architecture, yes otherwise.
+
+* `-fzp-register`, `-fno-zp-register` – Whether should reserve 2 bytes of zero page as a pseudoregister.
+Increases language features. 
+`.ini` equivalent: `zeropage_register`.
+Default: yes.
+                    
+* `-fdecimal-mode`, `-fno-decimal-mode` – Whether decimal mode should be available.  
+`.ini` equivalent: `decimal_mode`.
+Default: no if targeting Ricoh, yes otherwise.
+
+* `-fvariable-overlap`, `-fno-variable-overlap` – Whether variables should overlap if their scopes do not intersect.  
+Default: yes.
+
+* `-fbounds-checking`, `-fnobounds-checking` – Whether should insert bounds checking on array access.  
+Default: no.
+
+* `-fcompact-dispatch-params`, `-fnocompact-dispatch-params` – 
+Whether parameter values in return dispatch statements may overlap other objects. 
+This may cause problems if the parameter table is stored next to a hardware register that has side effects when reading.  
+`.ini` equivalent: `compact_dispatch_params`. Default: yes.
+
+## Optimization options
+
+* `-O0` – Disable all optimizations.
+
+* `-O`, `-O2`, `-O3` – Optimize code, various levels.
+
+* `-O9` – Optimize code using superoptimizer (experimental). Computationally expensive, decent results.
+
+* `--inline` – Inline functions automatically (experimental). See the [documentation about inlining](../abi/inlining.md). Computationally easy, can give decent gains.
+
+* `--size` – Optimize for size, sacrificing some speed (experimental).
+
+* `--fast` – Optimize for speed, even if it increases the size a bit (experimental).
+
+* `--blast-processing` – Optimize for speed, even if it increases the size a lot (experimental).
+
+* `--dangerous-optimizations` – Use dangerous optimizations (experimental). Dangerous optimizations are more likely to result in broken code.
+
+## Warning options
+
+* `-Wall` – Enable extra warnings.
+
+* `-Wfatal` – Treat warnings as errors.
@@ -0,0 +1,65 @@
+# Famicom/NES programming guide
+
+## Program lifecycle
+
+The default Famicom vectors are defined as following:
+
+* on reset, the predefined `on_reset` routine is called, which in turn calls `main`.
+The `main` routine is not allowed to return, or the program will crash.
+
+* on NMI, the default interrupt handler calls the `nmi` routine.
+It should not be defined as `interrupt`, the handler is, so your routine shouldn't.
+
+* on IRQ, the default interrupt handler calls the `irq` routine.
+It should not be defined as `interrupt`, the handler is, so your routine shouldn't.
+
+The minimal Famicom program thus looks like this:
+
+    void main() {
+        // initialize things
+        while(true) { }
+    }
+    
+    void irq() {
+        // do things
+    }
+    
+    void nmi() {
+        // do things
+    }
+
+## Mappers
+
+To use a mapper of your choice, create a new `.ini` file with the definitions you need.
+The most important ones are `[output]format` and `[allocation]segments`.
+
+Currently, its a bit inconvenient to create programs using mappers that change the bank containing the interrupt vectors.
+Therefore, it's recommended to stick to mappers that have a fixed bank at the end of the address space.
+
+Mappers that should be fine: NROM (0), CNROM (1), UxROM(2), MMC2 (9), MMC3 (4), MMC4 (10), MMC6 (4).
+
+Mappers that can have arbitrary bank at the end and are therefore not recommended: MMC1 (1), MMC5 (5).
+
+You should define at least three segments:
+
+* `default` – from $200 to $7FF, it will represent the physical RAM of the console.
+
+* `chrrom` (sample name) – from $0000 to $1FFF, it will represent the CHRROM
+(if you need more, you can make it bigger, up to $ffff, or even add another segment of CHRROM).  
+Put there only arrays with pattern tables. Don't read from them directly, it won't work.
+
+* `prgrom` (sample name) – it will contain the code of your program and read-only data.  
+Each segment should be defined in a range it is going to be switched into.
+You should set  the `default_code_segment` to the segment that contains the $FFxx addresses.
+
+If your mapper supports it, you can add more CHRROM or PRGROM segments,
+just specify them correctly in the `[output]format` tag.
+
+The `[output]format` tag should contain a valid iNES or NES 2.0 header of the mapper of your choice
+and then all the segments in proper order (first PRGROM, then CHRROM).
+See [the MMC4 example](../../include/nes_mmc4.ini) to see how it can be done.
+
+See [the NesDev wiki](https://wiki.nesdev.com/w/index.php/NES_2.0) for more info about the NES 2.0 file format.
+
+
+
@@ -0,0 +1,54 @@
+# Getting started
+
+## Hello world example
+
+Save the following as `hello_world.mfk`:
+
+```
+import stdio
+
+array hello_world = "hello world" petscii
+
+void main(){
+    putstr(hello_world, hello_world.length)
+    while(true){}
+}
+```
+
+Compile is using the following commandline:
+
+```
+java -jar millfork.jar hello_world.mfk -o hello_world -t c64 -I path_to_millfork\include
+```
+
+Run the output executable (here using the VICE emulator):
+
+```
+x64 hello_world.prg
+```
+
+## Basic commandline usage
+
+The following options are crucial when compiling your sources:
+
+* `-o FILENAME` – specifies the base name for your output file, an appropriate file extension will be appended (`prg` for Commodore, `xex` for Atari, `a2` for Apple, `asm` for assembly output, `lbl` for label file)
+
+* `-I DIR;DIR;DIR;...` – specifies the paths to directories with modules to include.  
+
+* `-t PLATFORM` – specifies the target platform (`c64` is the default). Each platform is defined in an `.ini` file in the include directory. For the list of supported platforms, see [Supported platforms](target-platforms.md)
+
+You may be also interested in the following:
+
+* `-O`, `-O2`, `-O3` – enable optimization (various levels)
+
+* `--inline` – automatically inline functions for better optimization
+
+* `-s` – additionally generate assembly output
+
+* `-g` – additionally generate a label file, in format compatible with VICE emulator
+
+* `-r PROGRAM` – automatically launch given program after successful compilation
+
+* `-Wall` – enable all warnings
+
+* `--help` – list all commandline options
@@ -0,0 +1,154 @@
+# 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.
+
+## Supported platforms
+
+The following platforms are currently supported:
+
+* `c64` – Commodore 64
+
+* `c64_scpu` – Commodore 64 with SuperCPU in emulation mode
+
+* `c64_scpu16` – Commodore 64 with SuperCPU in native, 16-bit mode (very buggy)
+
+* `c16` – Commodore 16
+
+* `plus4` – Commodore Plus/4
+
+* `vic20` – Commodore VIC-20 without memory expansion
+
+* `vic20_3k` – Commodore VIC-20 with 3K memory expansion
+
+* `vic20_8k` – Commodore VIC-20 with 8K or 16K memory expansion
+
+* `c128` – Commodore 128 in its native mode
+
+* `pet` – Commodore PET
+
+* `nes_small` – a tiny 32K PRGROM + 8K CHRROM Famicom/NES program, using iNES mapper 0 (NROM)
+
+* `nes_mcc4` – a 128K PRGROM + 128K CHRROM + extra 8KRAM Famicom/NES program, using iNES mapper 10 (MMC4)  
+For more complex programs, you need to create your own "platform" definition.  
+Read [the NES programming guide](./famicom-programming-guide.md) for more info.
+
+* `a8` – Atari 8-bit computers
+
+* `apple2` – Apple II+/IIe/Enhanced IIe
+
+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.
+
+## 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)
+
+* `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.  
+
+
+#### `[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.
+
+* `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)
+    
+    * `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)
+    
+    * `endaddr` – little-endian 16-bit address of the last used byte of the compiled output (usually not the segment end)
+    
+    * `allocated` – all used bytes
+    
+    * `<addr>:<addr>` - inclusive range of bytes
+    
+    * `<segment>:<addr>:<addr>` - inclusive range of bytes in a given segment
+    
+* `extension` – target file extension, with or without the dot