mirror of
https://github.com/KarolS/millfork.git
synced 2024-12-23 23:30:22 +00:00
Documentation fixes
This commit is contained in:
parent
9164e78a2d
commit
326e9d0585
@ -15,7 +15,7 @@ Variables in Millfork can belong to one of the following storage classes:
|
|||||||
Variables can also belong to one of the following memory areas
|
Variables can also belong to one of the following memory areas
|
||||||
(unless overridden with the `@` operator):
|
(unless overridden with the `@` operator):
|
||||||
|
|
||||||
* zeropage: all `pointer` variables and parameters with no defined memory segment (6502-like targets only)
|
* zeropage: some variables and parameters with no defined memory segment, preferring pointers (6502-like targets only)
|
||||||
|
|
||||||
* high RAM: all the other variables and parameters
|
* high RAM: all the other variables and parameters
|
||||||
|
|
||||||
|
@ -22,6 +22,7 @@ Extension will be added automatically,
|
|||||||
no extension for BBC micro program file,
|
no extension for BBC micro program file,
|
||||||
`.inf` for BBC Micro metadata,
|
`.inf` for BBC Micro metadata,
|
||||||
`.d88` for PC-88 disk images,
|
`.d88` for PC-88 disk images,
|
||||||
|
`.com` for CP/M executables,
|
||||||
`.rom` for MSX cartridge images,
|
`.rom` for MSX cartridge images,
|
||||||
`.tap` for ZX-Spectrum tape images.
|
`.tap` for ZX-Spectrum tape images.
|
||||||
|
|
||||||
@ -65,14 +66,32 @@ Choose syntax for assembly output on 8080-like targets.
|
|||||||
|
|
||||||
## Code generation options
|
## Code generation options
|
||||||
|
|
||||||
* `-fcmos-ops`, `-fno-cmos-ops` – Whether should emit CMOS opcodes.
|
#### For all targets
|
||||||
`.ini` equivalent: `emit_cmos`.
|
|
||||||
Default: yes if targeting a 65C02-compatible architecture, no otherwise.
|
|
||||||
|
|
||||||
* `-fillegals`, `-fno-illegals` – Whether should emit illegal (undocumented) NMOS opcodes.
|
* `-fvariable-overlap`, `-fno-variable-overlap` – Whether variables should overlap if their scopes do not intersect.
|
||||||
|
Default: yes.
|
||||||
|
|
||||||
|
* `-fbounds-checking`, `-fno-bounds-checking` – Whether should insert bounds checking on array access.
|
||||||
|
Default: no.
|
||||||
|
|
||||||
|
* `-fcompact-dispatch-params`, `-fno-compact-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.
|
||||||
|
|
||||||
|
* `-flenient-encoding`, `-fno-lenient-encoding` –
|
||||||
|
Whether the compiler should allow for invalid characters in string/character literals that use the default encodings and replace them with alternatives.
|
||||||
|
`.ini` equivalent: `lenient_encoding`. Default: yes on Apple II, no otherwise.
|
||||||
|
|
||||||
|
* `-fillegals`, `-fno-illegals` – Whether should emit illegal (undocumented) NMOS or Z80 opcodes.
|
||||||
`.ini` equivalent: `emit_illegals`.
|
`.ini` equivalent: `emit_illegals`.
|
||||||
Default: no.
|
Default: no.
|
||||||
|
|
||||||
|
#### 6502-related
|
||||||
|
|
||||||
|
* `-fcmos-ops`, `-fno-cmos-ops` – Whether should emit CMOS opcodes.
|
||||||
|
`.ini` equivalent: `emit_cmos`.
|
||||||
|
Default: yes if targeting a 65C02-compatible architecture, no otherwise.
|
||||||
* `-f65ce02-ops`, `-fno-65ce02-ops` – Whether should emit 65CE02 opcodes.
|
* `-f65ce02-ops`, `-fno-65ce02-ops` – Whether should emit 65CE02 opcodes.
|
||||||
`.ini` equivalent: `emit_65ce026`.
|
`.ini` equivalent: `emit_65ce026`.
|
||||||
Default: yes if targeting 65CE02, no otherwise.
|
Default: yes if targeting 65CE02, no otherwise.
|
||||||
@ -103,20 +122,11 @@ If disabled, a sofware decimal mode will be used.
|
|||||||
`.ini` equivalent: `decimal_mode`.
|
`.ini` equivalent: `decimal_mode`.
|
||||||
Default: no if targeting Ricoh, yes otherwise.
|
Default: no if targeting Ricoh, yes otherwise.
|
||||||
|
|
||||||
* `-fvariable-overlap`, `-fno-variable-overlap` – Whether variables should overlap if their scopes do not intersect.
|
* `-fsoftware-stack`, `-fno-software-stack` –
|
||||||
Default: yes.
|
Use a software stack for stack variables.
|
||||||
|
`.ini` equivalent: `software_stack`. Default: no.
|
||||||
|
|
||||||
* `-fbounds-checking`, `-fno-bounds-checking` – Whether should insert bounds checking on array access.
|
#### 8080/Z80-related
|
||||||
Default: no.
|
|
||||||
|
|
||||||
* `-fcompact-dispatch-params`, `-fno-compact-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.
|
|
||||||
|
|
||||||
* `-flenient-encoding`, `-fno-lenient-encoding` –
|
|
||||||
Whether the compiler should allow for invalid characters in string/character literals that use the default encodings and replace them with alternatives.
|
|
||||||
`.ini` equivalent: `lenient_encoding`. Default: yes on Apple II, no otherwise.
|
|
||||||
|
|
||||||
* `-fshadow-irq`, `-fno-shadow-irq` –
|
* `-fshadow-irq`, `-fno-shadow-irq` –
|
||||||
Whether the interrupt routines should make use of Z80 shadow registers.
|
Whether the interrupt routines should make use of Z80 shadow registers.
|
||||||
@ -124,7 +134,7 @@ Whether the interrupt routines should make use of Z80 shadow registers.
|
|||||||
|
|
||||||
* `-fuse-ix-for-stack`, `-fuse-iy-for-stack`, `-fno-use-index-for-stack` –
|
* `-fuse-ix-for-stack`, `-fuse-iy-for-stack`, `-fno-use-index-for-stack` –
|
||||||
Which of Z80 index registers should be used for accessing stack variables, if any.
|
Which of Z80 index registers should be used for accessing stack variables, if any.
|
||||||
`.ini` equivalent: `ix_stack` and `iy_stack`. Default: IX on Z80, no otherwise.
|
`.ini` equivalent: `ix_stack` and `iy_stack`. Default: IX on Z80 and 8086, no otherwise.
|
||||||
|
|
||||||
* `-fuse-ix-for-scratch`, `-fno-use-ix-for-scratch` –
|
* `-fuse-ix-for-scratch`, `-fno-use-ix-for-scratch` –
|
||||||
Allow using the IX register for other purposes.
|
Allow using the IX register for other purposes.
|
||||||
@ -134,10 +144,6 @@ Allow using the IX register for other purposes.
|
|||||||
Allow using the IY register for other purposes.
|
Allow using the IY register for other purposes.
|
||||||
`.ini` equivalent: `iy_scratch`. Default: no.
|
`.ini` equivalent: `iy_scratch`. Default: no.
|
||||||
|
|
||||||
* `-fsoftware-stack`, `-fno-software-stack` –
|
|
||||||
Use a software stack for stack variables.
|
|
||||||
`.ini` equivalent: `software_stack`. Default: no.
|
|
||||||
|
|
||||||
## Optimization options
|
## Optimization options
|
||||||
|
|
||||||
* `-O0` – Disable all optimizations except unused global symbol removal.
|
* `-O0` – Disable all optimizations except unused global symbol removal.
|
||||||
@ -181,7 +187,7 @@ Whether identical fragments of functions should be extracted into subroutines.
|
|||||||
Default: no.
|
Default: no.
|
||||||
|
|
||||||
* `-Os`, `--size` – Optimize for size, sacrificing some speed (experimental).
|
* `-Os`, `--size` – Optimize for size, sacrificing some speed (experimental).
|
||||||
Also enables `-fcode-deduplication`.
|
Also enables `-fsubroutine-extraction`.
|
||||||
|
|
||||||
* `-Of`, `--fast` – Optimize for speed, even if it increases the size a bit (experimental).
|
* `-Of`, `--fast` – Optimize for speed, even if it increases the size a bit (experimental).
|
||||||
Also enables `-finline`.
|
Also enables `-finline`.
|
||||||
|
@ -58,7 +58,7 @@ Default: the same as `encoding`.
|
|||||||
* `decimal_mode` – whether the compiler should emit decimal instructions, default is `false` on `ricoh` and `strictricoh` and `true` elsewhere;
|
* `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
|
if disabled, a software decimal mode will be used
|
||||||
|
|
||||||
* `ro_arrays` – whether the compiler should warn upon array writes, default is `false`
|
* `ro_arrays` – (deprecated) 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,
|
* `prevent_jmp_indirect_bug` – whether the compiler should try to avoid the indirect JMP bug,
|
||||||
default is `false` on 65C02-compatible or non-6502 processors and `true` elsewhere
|
default is `false` on 65C02-compatible or non-6502 processors and `true` elsewhere
|
||||||
@ -86,7 +86,7 @@ Default: the same as `encoding`.
|
|||||||
|
|
||||||
* `use_shadow_registers_for_irq` – use Z80 shadow registers in interrupt routines, default is `true` for Z80 and `false` otherwise
|
* `use_shadow_registers_for_irq` – use Z80 shadow registers in interrupt routines, default is `true` for Z80 and `false` otherwise
|
||||||
|
|
||||||
* `ix_stack` – use the IX register to access stack variables, default is `true` for Z80 and `false` otherwise
|
* `ix_stack` – use the IX register to access stack variables, default is `true` for Z80 and 8086, `false` otherwise
|
||||||
|
|
||||||
* `iy_stack` – use the IY register to access stack variables, default is `false`
|
* `iy_stack` – use the IY register to access stack variables, default is `false`
|
||||||
|
|
||||||
@ -94,7 +94,7 @@ Default: the same as `encoding`.
|
|||||||
|
|
||||||
* `iy_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`
|
||||||
|
|
||||||
* `software_stach` – use software stack for stack variables, default is `false`
|
* `software_stack` – use software stack for stack variables, default is `false`. Applicable only to 6502-based targets.
|
||||||
|
|
||||||
* `output_intel_syntax` – use Intel syntax instead of Zilog syntax, default is `true` for Intel 8080/8085 and `false` otherwise
|
* `output_intel_syntax` – use Intel syntax instead of Zilog syntax, default is `true` for Intel 8080/8085 and `false` otherwise
|
||||||
|
|
||||||
@ -120,7 +120,7 @@ Note that the default segment for uninitialized arrays and variables is always `
|
|||||||
Default: `default`
|
Default: `default`
|
||||||
|
|
||||||
* `segment_NAME_start` – the first address used for automatic allocation in the segment.
|
* `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.
|
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.
|
||||||
The `main` function will be placed as close to the beginning of its segment as possible, but not necessarily at `segment_NAME_start`
|
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_end` – the last address in the segment
|
||||||
|
@ -31,9 +31,23 @@ x64 hello_world.prg
|
|||||||
|
|
||||||
The following options are obligatory when compiling your sources:
|
The following options are obligatory 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 computers, `a2` for Apple, `asm` for assembly output, `lbl` for label file, `inf` for BBC file metadata, `dsk` for PC-88, `tap` for ZX Spectrum, `nes` for Famicom, `bin` for Atari 2600)
|
* `-o FILENAME` – specifies the base name for your output file, an appropriate file extension will be appended
|
||||||
|
(`prg` for Commodore,
|
||||||
|
`xex` for Atari computers,
|
||||||
|
`a2` for Apple,
|
||||||
|
`asm` for assembly output,
|
||||||
|
`lbl` for label file,
|
||||||
|
`inf` for BBC file metadata,
|
||||||
|
`dsk` for PC-88,
|
||||||
|
`tap` for ZX Spectrum,
|
||||||
|
`rom` for MSX cartridges,
|
||||||
|
`com` for CP/M,
|
||||||
|
`nes` for Famicom,
|
||||||
|
`bin` for Atari 2600)
|
||||||
|
|
||||||
* `-t PLATFORM` – specifies the target platform. Each platform is defined in an `.ini` file in the include directory. For the list of supported platforms, see [Supported platforms](target-platforms.md)
|
* `-t PLATFORM` – specifies the target platform.
|
||||||
|
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:
|
You may be also interested in the following:
|
||||||
|
|
||||||
|
@ -18,7 +18,7 @@ The goal of Millfork is to succeed where Atalan failed.
|
|||||||
Large programs in Millfork have been developed for Commodore 64.
|
Large programs in Millfork have been developed for Commodore 64.
|
||||||
|
|
||||||
Millfork was also tested (via emulators) to run trivial programs on other 8-bit Commodore computers,
|
Millfork was also tested (via emulators) to run trivial programs on other 8-bit Commodore computers,
|
||||||
Atari 8-bit computers, Apple II, BBC Micro, ZX Spectrum 48k, NEC PC-88, CP/M, NES, Game Boy, Atari 2600 and MS-DOS.
|
Atari 8-bit computers, Apple II, BBC Micro, ZX Spectrum 48k, NEC PC-88, MSX, CP/M, NES, Game Boy, Atari 2600 and MS-DOS.
|
||||||
|
|
||||||
Support for other devices using supported processors can be easily added, usually without even modifying the compiler.
|
Support for other devices using supported processors can be easily added, usually without even modifying the compiler.
|
||||||
|
|
||||||
|
@ -36,6 +36,7 @@ Syntax:
|
|||||||
so this function only has to preserve the zeropage pseudoregisters.
|
so this function only has to preserve the zeropage pseudoregisters.
|
||||||
An example is the Commodore 64 interrupt handler that calls the function at an address read from $314/$315.
|
An example is the Commodore 64 interrupt handler that calls the function at an address read from $314/$315.
|
||||||
Unlike hardware handlers with `interrupt`, you can treat functions with `kernal_interrupt` like normal functions.
|
Unlike hardware handlers with `interrupt`, you can treat functions with `kernal_interrupt` like normal functions.
|
||||||
|
On non-6502-based targets, functions marked as `kernal_interrupt` don't differ from normal functions.
|
||||||
|
|
||||||
* `<return_type>` is a valid return type, see [Types](./types.md)
|
* `<return_type>` is a valid return type, see [Types](./types.md)
|
||||||
|
|
||||||
@ -45,7 +46,7 @@ Syntax:
|
|||||||
The function will be allocated at the address divisible by alignment.
|
The function will be allocated at the address divisible by alignment.
|
||||||
`fast` means different things depending on the target platform:
|
`fast` means different things depending on the target platform:
|
||||||
|
|
||||||
* on 6502, it means that the function will not cross a page boundary
|
* on 6502, it means that the function will not cross a page boundary if possible
|
||||||
* on Z80, it is ignored
|
* on Z80, it is ignored
|
||||||
|
|
||||||
* `<address>` is a constant expression that defines where in the memory the function is or will be located.
|
* `<address>` is a constant expression that defines where in the memory the function is or will be located.
|
||||||
|
@ -8,7 +8,7 @@ Most expressions involving single bytes compile,
|
|||||||
but for larger types usually you need to use in-place modification operators.
|
but for larger types usually you need to use in-place modification operators.
|
||||||
Further improvements to the compiler may increase the number of acceptable combinations.
|
Further improvements to the compiler may increase the number of acceptable combinations.
|
||||||
|
|
||||||
Certain expressions require the commandline flag `-fzp-register` (`.ini` equivalent: `zeropage_register`) to be enabled.
|
On 6502-like targets, certain expressions require the commandline flag `-fzp-register` (`.ini` equivalent: `zeropage_register`) to be enabled.
|
||||||
They will be marked with (zpreg) next to them.
|
They will be marked with (zpreg) next to them.
|
||||||
The flag is enabled by default, but you can disable it if you need to.
|
The flag is enabled by default, but you can disable it if you need to.
|
||||||
|
|
||||||
|
@ -36,6 +36,10 @@ It is possible to make a safe nested call to a non-nesting safe function, provid
|
|||||||
* the non-nested parameters have to have the same values in all co-occurring calls: `f(5, f(5, 6, 7), 7)`
|
* the non-nested parameters have to have the same values in all co-occurring calls: `f(5, f(5, 6, 7), 7)`
|
||||||
|
|
||||||
In all other cases, the nested call may cause undefined behaviour.
|
In all other cases, the nested call may cause undefined behaviour.
|
||||||
|
In such cases, it's recommended to introduce a temporary variable:
|
||||||
|
|
||||||
|
tmp_f11 = f(1,1)
|
||||||
|
f(0, tmp_f11)
|
||||||
|
|
||||||
## Recursion safety
|
## Recursion safety
|
||||||
|
|
||||||
@ -54,6 +58,15 @@ In all other cases, the recursive call may cause undefined behaviour.
|
|||||||
The easiest, but suboptimal way to make a function recursion-safe is to make all local variables stack-allocated
|
The easiest, but suboptimal way to make a function recursion-safe is to make all local variables stack-allocated
|
||||||
and assign all parameters to variables as soon as possible. This is slow though, so don't do it unless really necessary.
|
and assign all parameters to variables as soon as possible. This is slow though, so don't do it unless really necessary.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
word fibonacci(byte i) {
|
||||||
|
if i < 2 { return 1 }
|
||||||
|
stack byte j
|
||||||
|
j = i
|
||||||
|
return fibonacci(j-1) + fibonacci(j-2)
|
||||||
|
}
|
||||||
|
|
||||||
## Interrupt safety
|
## Interrupt safety
|
||||||
|
|
||||||
A function is interrupt-safe if it can be safely called, either directly or indirectly,
|
A function is interrupt-safe if it can be safely called, either directly or indirectly,
|
||||||
|
@ -46,7 +46,7 @@ For every variable `x` larger than a byte, extra subvariables are defined:
|
|||||||
|
|
||||||
* constituent bytes, from low to high: `x.lo`, `x.hi`
|
* constituent bytes, from low to high: `x.lo`, `x.hi`
|
||||||
|
|
||||||
* if `x` is of type `farword`:
|
* if `x` is of type `int24`:
|
||||||
|
|
||||||
* constituent bytes, from low to high: `x.b0`, `x.b1`, `x.b2`
|
* constituent bytes, from low to high: `x.b0`, `x.b1`, `x.b2`
|
||||||
|
|
||||||
|
@ -100,14 +100,20 @@ equal to the number of variants in the enumeration.
|
|||||||
|
|
||||||
Assigment between numeric types and enumerations is not possible without an explicit type cast:
|
Assigment between numeric types and enumerations is not possible without an explicit type cast:
|
||||||
|
|
||||||
enum E {}
|
enum E { EA, EB }
|
||||||
byte b
|
byte b
|
||||||
E e
|
E e
|
||||||
|
e = EA // ok
|
||||||
e = b // won't compile
|
e = b // won't compile
|
||||||
b = e // won't compile
|
b = e // won't compile
|
||||||
b = byte(e) // ok
|
b = byte(e) // ok
|
||||||
e = E(b) // ok
|
e = E(b) // ok
|
||||||
|
|
||||||
|
array a[E] // E is plain, array has size 2
|
||||||
|
a[0] // won't compile
|
||||||
|
a[EB] // ok
|
||||||
|
|
||||||
|
|
||||||
Plain enumerations have their variants equal to `byte(0)` to `byte(<name>.count - 1)`.
|
Plain enumerations have their variants equal to `byte(0)` to `byte(<name>.count - 1)`.
|
||||||
|
|
||||||
Tip: You can use an enumeration with no variants as a strongly checked alternative byte type,
|
Tip: You can use an enumeration with no variants as a strongly checked alternative byte type,
|
||||||
|
Loading…
Reference in New Issue
Block a user