From ecbcc277b83d6dd9133ca78946dd232f8c0d4f11 Mon Sep 17 00:00:00 2001 From: Irmen de Jong Date: Thu, 10 Aug 2023 00:17:50 +0200 Subject: [PATCH] improve -varshigh documentation --- compiler/src/prog8/CompilerMain.kt | 2 +- docs/source/compiling.rst | 19 +++++++++---------- 2 files changed, 10 insertions(+), 11 deletions(-) diff --git a/compiler/src/prog8/CompilerMain.kt b/compiler/src/prog8/CompilerMain.kt index 1376166c8..7203226d2 100644 --- a/compiler/src/prog8/CompilerMain.kt +++ b/compiler/src/prog8/CompilerMain.kt @@ -51,7 +51,7 @@ private fun compileMain(args: Array): Boolean { val compilationTarget by cli.option(ArgType.String, fullName = "target", description = "target output of the compiler (one of '${C64Target.NAME}', '${C128Target.NAME}', '${Cx16Target.NAME}', '${AtariTarget.NAME}', '${VMTarget.NAME}') (required)") val startVm by cli.option(ArgType.Boolean, fullName = "vm", description = "load and run a .p8ir IR source file in the VM") val watchMode by cli.option(ArgType.Boolean, fullName = "watch", description = "continuous compilation mode (watch for file changes)") - val varsHighBank by cli.option(ArgType.Int, fullName = "varshigh", description = "put uninitialized variables in high memory area instead of at the end of the program. On the cx16 target the value specifies the HiRAM bank (0=keep active), on other systems it is ignored.") + val varsHighBank by cli.option(ArgType.Int, fullName = "varshigh", description = "put uninitialized variables in high memory area instead of at the end of the program. On the cx16 target the value specifies the HiRAM bank to use, on other systems this value is ignored.") val moduleFiles by cli.argument(ArgType.String, fullName = "modules", description = "main module file(s) to compile").multiple(999) try { diff --git a/docs/source/compiling.rst b/docs/source/compiling.rst index fb7668e2e..a909a6d3e 100644 --- a/docs/source/compiling.rst +++ b/docs/source/compiling.rst @@ -178,21 +178,20 @@ One or more .p8 module files Can be repeated to define multiple symbols. ``-varshigh `` - Places the non-zeropage variables in a separate high memory area, instead of inside the program itself. - This results in an increase of the amount of system ram available for the program - itself. The amount of ram saved depends on the amount and types of variables in the program, - but can be several hundreds of bytes or more. - The new memory location of the variables depends on the compilation target machine: + Places uninitialized non-zeropage variables in a separate memory area, instead of inside the program itself. + This increases the amount of system ram available for program code. + The size of the increase depends on the program but can be several hundreds of bytes or more. + The location of the memory area for these variables depends on the compilation target machine: - c64: $C000 - $CEFF (specified rambank number is ignored) + c64: $C000 - $CFFF ; 4 kB, and the specified rambank number is ignored - cx16: $A000 - $BFFF in the given HiRAM bank (note: you must make sure that this HiRAM bank is mapped in when accessing variables! The bank should be 1 or up. Choose 1 if unsure.) + cx16: $A000 - $BFFF ; 8 kB in the specified HiRAM bank (note: no auto bank switching is done, you must make sure yourself that this HiRAM bank is active when accessing these variables!) If you use this option, you can no longer use the part of the above memory area that is - now alotted to the variables for your own purposes. The output of the 64tass assembler step at the + alotted to the variables, for your own purposes. The output of the 64tass assembler step at the end of compilation shows precise details of where and how much memory is used by the variables - (it's called 'BSS' section or Gap). Compilation (or rather, assembling) will fail if there are too - many variables to fit in the high ram block. + (it's called 'BSS' section or Gap at the address mentioned above). + Assembling the program will fail if there are too many variables to fit in a single high ram bank. Module source code files