From c71af26989df7f08f883b9170605e43f7bf3db83 Mon Sep 17 00:00:00 2001 From: Karol Stasiak Date: Mon, 4 Jun 2018 16:24:18 +0200 Subject: [PATCH] Documentation updates --- CHANGELOG.md | 10 +++++++++- docs/abi/undefined-behaviour.md | 2 +- docs/api/command-line.md | 2 +- docs/api/getting-started.md | 4 ++-- docs/lang/assembly.md | 5 +---- docs/lang/functions.md | 4 ++-- src/main/scala/millfork/Main.scala | 6 +++--- 7 files changed, 19 insertions(+), 14 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e6f3bcab..fe396b96 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,7 +10,15 @@ * Added character literals. -* Fixed several bugs, most importantly invalid offsets for branching instructions. +* Added 24-bit `farword` type. + +* Fixed invalid offsets for branching instructions. + +* Fixed incorrectly overlapping local variables. + +* Fixed broken `downto` loops. + +* Fixed several other bugs. * Other improvements. diff --git a/docs/abi/undefined-behaviour.md b/docs/abi/undefined-behaviour.md index 18c678e2..ee49e1f7 100644 --- a/docs/abi/undefined-behaviour.md +++ b/docs/abi/undefined-behaviour.md @@ -24,7 +24,7 @@ even up to hardware damage. * on ROM-based platforms: writing to arrays -* on ROM-based platforms: using global variables with an initial value +* on ROM-based platforms: using global variables with an initial value (they will not be initialized!) * violating the [safe assembly rules](../lang/assembly.md) diff --git a/docs/api/command-line.md b/docs/api/command-line.md index 1c94c2e3..57be176f 100644 --- a/docs/api/command-line.md +++ b/docs/api/command-line.md @@ -83,7 +83,7 @@ This may cause problems if the parameter table is stored next to a hardware regi * `-O0` – Disable all optimizations. -* `-O`, `-O2`, `-O3` – Optimize code, various levels. +* `-O`, `-O2` ... `-O8` – Optimize code, various levels. For most code, anything above `-O4` doesn't improve it anymore. * `-O9` – Optimize code using superoptimizer (experimental). Computationally expensive, decent results. diff --git a/docs/api/getting-started.md b/docs/api/getting-started.md index 01ba62f3..55a2ff0e 100644 --- a/docs/api/getting-started.md +++ b/docs/api/getting-started.md @@ -33,7 +33,7 @@ x64 hello_world.prg 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) +* `-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, `inf` for BBC file metadata) * `-I DIR;DIR;DIR;...` – specifies the paths to directories with modules to include. @@ -41,7 +41,7 @@ The following options are crucial when compiling your sources: You may be also interested in the following: -* `-O`, `-O2`, `-O3` – enable optimization (various levels) +* `-O`, `-O2`, `-O3`, `-O4` – enable optimization (various levels) * `--inline` – automatically inline functions for better optimization diff --git a/docs/lang/assembly.md b/docs/lang/assembly.md index f7b230cc..af110d20 100644 --- a/docs/lang/assembly.md +++ b/docs/lang/assembly.md @@ -31,9 +31,6 @@ Label names have to start with a letter and can contain digits, underscores and This means than they cannot start with a period like in many other assemblers. Similarly, anonymous labels designated with `+` or `-` are also not supported -Labels are global, -which means that they live in the same namespace as functions, types and global variables. - Assembly can refer to variables and constants defined in Millfork, but you need to be careful with using absolute vs immediate addressing: @@ -173,7 +170,7 @@ it should abide to the following rules: * do not change the data page register (keep an eye at the `PLD`, `MVN`, `MVP` instructions) - * explicitly use 16-bit immediate operands when appropriate; the assembler doesn't track flags and assumes 8-bit immediates by default + * explicitly use 16-bit immediate operands when appropriate; the assembler doesn't track flags and assumes 8-bit immediates by default (TODO: actually implement the 16-bit inline assembly correctly) * use far jumps unless you're sure that the called function returns with an `RTS` diff --git a/docs/lang/functions.md b/docs/lang/functions.md index 3eb32d28..88beeedb 100644 --- a/docs/lang/functions.md +++ b/docs/lang/functions.md @@ -25,13 +25,13 @@ Syntax: * `interrupt` – the function is a hardware interrupt handler. You are not allowed to call such functions directly. - The function cannot have parameters and the retrn type should be `void`. + The function cannot have parameters and the return type should be `void`. * `kernal_interrupt` – the function is an interrupt handler called from a generic vendor-provider hardware interrupt handler. The hardware instruction handler is assumed to have preserved the CPU registers, 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. - Unline 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. * `` is a valid return type, see [Types](./types.md) diff --git a/src/main/scala/millfork/Main.scala b/src/main/scala/millfork/Main.scala index 91a8ea48..a0024964 100644 --- a/src/main/scala/millfork/Main.scala +++ b/src/main/scala/millfork/Main.scala @@ -194,7 +194,7 @@ object Main { parameter("-t", "--target").placeholder("").action { (p, c) => assertNone(c.platform, "Platform already defined") c.copy(platform = Some(p)) - }.description("Target platform, any of: c64, c16, plus4, vic20, vic20_3k, vic20_8k, pet, c128, a8.") + }.description("Target platform, any of: c64, c16, plus4, vic20, vic20_3k, vic20_8k, pet, c128, a8, bbc, apple2, nes_mmc4, nes_small, c64_scpu, c64_scpu16, vcs.") parameter("-I", "--include-dir").repeatable().placeholder(";;...").action { (paths, c) => val n = paths.split(";") @@ -242,11 +242,11 @@ object Main { c.changeFlag(CompilationFlag.EmitEmulation65816Opcodes, b = true) c.changeFlag(CompilationFlag.EmitNative65816Opcodes, b = false) c.changeFlag(CompilationFlag.ReturnWordsViaAccumulator, b = false) - }.description("Emit 65816 opcodes (experimental).") + }.description("Emit 65816 opcodes in emulation mode (experimental).") flag("-fnative-65816-ops").action { c => c.changeFlag(CompilationFlag.EmitEmulation65816Opcodes, b = true) c.changeFlag(CompilationFlag.EmitNative65816Opcodes, b = true) - }.description("Emit 65816 opcodes (experimental).") + }.description("Emit 65816 opcodes in native mode (very experimental and buggy).") boolean("-flarge-code", "-fsmall-code").action { (c, v) => c.changeFlag(CompilationFlag.LargeCode, v) }.description("Whether should use 24-bit or 16-bit jumps to subroutines (not yet implemented).").hidden()