mirror of
https://github.com/irmen/prog8.git
synced 2024-11-26 11:49:22 +00:00
BASIC, VICE, C64, zeropage spelling
This commit is contained in:
Irmen de Jong
parent
db8912a735
commit
e951340033
@ -138,7 +138,7 @@ One or more .p8 module files
|
||||
|
||||
``-noreinit``
|
||||
Don't create code to reinitialize the global (block level) variables on every run of the program.
|
||||
Also means that all such variables are no longer placed in the zero page.
|
||||
Also means that all such variables are no longer placed in the zeropage.
|
||||
Sometimes the program will be a lot shorter when using this, but sometimes the opposite happens.
|
||||
When using this option, it is no longer be possible to run the program correctly more than once!
|
||||
*Experimental feature*: still has some problems!
|
||||
@ -210,26 +210,26 @@ the ``srcdirs`` command line option.
|
||||
|
||||
.. _debugging:
|
||||
|
||||
Debugging (with Vice)
|
||||
Debugging (with VICE)
|
||||
---------------------
|
||||
|
||||
There's support for using the monitor and debugging capabilities of the rather excellent
|
||||
`Vice emulator <http://vice-emu.sourceforge.net/>`_.
|
||||
`VICE emulator <http://vice-emu.sourceforge.net/>`_.
|
||||
|
||||
The ``%breakpoint`` directive (see :ref:`directives`) in the source code instructs the compiler to put
|
||||
a *breakpoint* at that position. Some systems use a BRK instruction for this, but
|
||||
this will usually halt the machine altogether instead of just suspending execution.
|
||||
Prog8 issues a NOP instruction instead and creates a 'virtual' breakpoint at this position.
|
||||
All breakpoints are then written to a file called "programname.vice-mon-list",
|
||||
which is meant to be used by the Vice emulator.
|
||||
It contains a series of commands for Vice's monitor, including source labels and the breakpoint settings.
|
||||
which is meant to be used by the VICE emulator.
|
||||
It contains a series of commands for VICE's monitor, including source labels and the breakpoint settings.
|
||||
If you use the emulator autostart feature of the compiler, it will take care of this for you.
|
||||
If you launch Vice manually, you'll have to use a command line option to load this file:
|
||||
If you launch VICE manually, you'll have to use a command line option to load this file:
|
||||
|
||||
``$ x64 -moncommands programname.vice-mon-list``
|
||||
|
||||
Vice will then use the label names in memory disassembly, and will activate any breakpoints as well.
|
||||
If your running program hits one of the breakpoints, Vice will halt execution and drop you into the monitor.
|
||||
VICE will then use the label names in memory disassembly, and will activate any breakpoints as well.
|
||||
If your running program hits one of the breakpoints, VICE will halt execution and drop you into the monitor.
|
||||
|
||||
|
||||
Troubleshooting
|
||||
|
||||
@ -140,11 +140,11 @@ This code calculates prime numbers using the Sieve of Eratosthenes algorithm::
|
||||
}
|
||||
|
||||
|
||||
when compiled an ran on a C-64 you get this:
|
||||
when compiled an ran on a C64 you get this:
|
||||
|
||||
.. image:: _static/primes_example.png
|
||||
:align: center
|
||||
:alt: result when run on C-64
|
||||
:alt: result when run on C64
|
||||
|
||||
when the exact same program is compiled for the Commander X16 target, and run on the emulator, you get this:
|
||||
|
||||
@ -170,7 +170,7 @@ Required additional tools
|
||||
It's very easy to compile yourself.
|
||||
A recent precompiled .exe (only for Windows) can be obtained from my `clone <https://github.com/irmen/64tass/releases>`_ of this project.
|
||||
*You need at least version 1.55.2257 of this assembler to correctly use the breakpoints feature.*
|
||||
It's possible to use older versions, but it is very likely that the automatic Vice breakpoints won't work with them.
|
||||
It's possible to use older versions, but it is very likely that the automatic VICE breakpoints won't work with them.
|
||||
|
||||
A **Java runtime (jre or jdk), version 11 or newer** is required to run the prog8 compiler itself.
|
||||
If you're scared of Oracle's licensing terms, most Linux distributions ship OpenJDK in their packages repository instead.
|
||||
@ -178,7 +178,7 @@ For Windows it's possible to get that as well; check out `AdoptOpenJDK <https://
|
||||
For MacOS you can use the Homebrew system to install a recent version of OpenJDK.
|
||||
|
||||
Finally: an **emulator** (or a real machine of course) to test and run your programs on.
|
||||
In C64 mode, the compiler assumes the presence of the `Vice emulator <http://vice-emu.sourceforge.net/>`_.
|
||||
In C64 mode, the compiler assumes the presence of the `VICE emulator <http://vice-emu.sourceforge.net/>`_.
|
||||
If you're targeting the Commander X16 instead, there's a choice of the official `x16emu <https://github.com/commanderx16/x16-emulator>`_
|
||||
and the unofficial `box16 <https://github.com/indigodarkwolf/box16>`_ (you can select which one you want to launch
|
||||
using the ``-emu`` or ``-emu2`` command line options)
|
||||
|
||||
@ -105,7 +105,7 @@ sys (part of syslib)
|
||||
note: a more accurate way to do this is by using a raster irq handler instead.
|
||||
|
||||
``reset_system()``
|
||||
Soft-reset the system back to initial power-on Basic prompt.
|
||||
Soft-reset the system back to initial power-on BASIC prompt.
|
||||
(called automatically by Prog8 when the main subroutine returns and the program is not using basicsafe zeropage option)
|
||||
|
||||
|
||||
@ -358,7 +358,7 @@ palette (cx16 only)
|
||||
Available for the Cx16 target. Various routines to set the display color palette.
|
||||
There are also a few better looking Commodore 64 color palettes available here,
|
||||
because the Commander X16's default colors for this (the first 16 colors) are too saturated
|
||||
and are quite different than how they looked on a VIC-II chip in a C-64.
|
||||
and are quite different than how they looked on a VIC-II chip in a C64.
|
||||
|
||||
|
||||
cx16diskio (cx16 only)
|
||||
|
||||
@ -17,15 +17,15 @@ CPU
|
||||
Memory Map
|
||||
----------
|
||||
|
||||
Zero page
|
||||
zeropage
|
||||
=========
|
||||
#. *Absolute requirement:* Provide three times 2 consecutive bytes (i.e. three 16-bit pointers) in the Zero page that are free to use at all times.
|
||||
#. Provide list of any additional free Zero page locations for a normal running system (basic + Kernal enabled)
|
||||
#. Provide list of any additional free Zero page locations when basic is off, but floating point routines should still work
|
||||
#. Provide list of any additional free Zero page locations when only the Kernal remains enabled
|
||||
#. *Absolute requirement:* Provide three times 2 consecutive bytes (i.e. three 16-bit pointers) in the zeropage that are free to use at all times.
|
||||
#. Provide list of any additional free zeropage locations for a normal running system (BASIC + Kernal enabled)
|
||||
#. Provide list of any additional free zeropage locations when BASIC is off, but floating point routines should still work
|
||||
#. Provide list of any additional free zeropage locations when only the Kernal remains enabled
|
||||
|
||||
Only the three 16-bit pointers are absolutely required to be able to use prog8 on the system.
|
||||
But more known available Zero page locations mean smaller and faster programs.
|
||||
But more known available zeropage locations mean smaller and faster programs.
|
||||
|
||||
|
||||
RAM, ROM, I/O
|
||||
|
||||
@ -201,12 +201,12 @@ Values will usually be part of an expression or assignment statement::
|
||||
|
||||
*putting a variable in zeropage:*
|
||||
If you add the ``@zp`` tag to the variable declaration, the compiler will prioritize this variable
|
||||
when selecting variables to put into zero page (but no guarantees). If there are enough free locations in the zeropage,
|
||||
when selecting variables to put into zeropage (but no guarantees). If there are enough free locations in the zeropage,
|
||||
it will try to fill it with as much other variables as possible (before they will be put in regular memory pages).
|
||||
Use ``@requirezp`` tag to *force* the variable into zeropage, but if there is no more free space the compilation will fail.
|
||||
It's possible to put strings, arrays and floats into zeropage too, however because Zp space is really scarce
|
||||
this is not advised as they will eat up the available space very quickly. It's best to only put byte or word
|
||||
variables in Zeropage.
|
||||
variables in zeropage.
|
||||
|
||||
Example::
|
||||
|
||||
@ -261,8 +261,8 @@ Floating point numbers
|
||||
|
||||
Floats are stored in the 5-byte 'MFLPT' format that is used on CBM machines,
|
||||
and currently all floating point operations are specific to the Commodore 64.
|
||||
This is because routines in the C-64 BASIC and Kernal ROMs are used for that.
|
||||
So floating point operations will only work if the C-64 BASIC ROM (and Kernal ROM)
|
||||
This is because routines in the C64 BASIC and Kernal ROMs are used for that.
|
||||
So floating point operations will only work if the C64 BASIC ROM (and Kernal ROM)
|
||||
are banked in.
|
||||
|
||||
Also your code needs to import the ``floats`` library to enable floating point support
|
||||
@ -889,7 +889,7 @@ ror2(x)
|
||||
sizeof(name)
|
||||
Number of bytes that the object 'name' occupies in memory. This is a constant determined by the data type of
|
||||
the object. For instance, for a variable of type uword, the sizeof is 2.
|
||||
For an 10 element array of floats, it is 50 (on the C-64, where a float is 5 bytes).
|
||||
For an 10 element array of floats, it is 50 (on the C64, where a float is 5 bytes).
|
||||
Note: usually you will be interested in the number of elements in an array, use len() for that.
|
||||
|
||||
memory(name, size, alignment)
|
||||
|
||||
@ -54,7 +54,7 @@ Directives
|
||||
.. data:: %zeropage <style>
|
||||
|
||||
Level: module.
|
||||
Global setting, select ZeroPage handling style. Defaults to ``kernalsafe``.
|
||||
Global setting, select zeropage handling style. Defaults to ``kernalsafe``.
|
||||
|
||||
- style ``kernalsafe`` -- use the part of the ZP that is 'free' or only used by BASIC routines,
|
||||
and don't change anything else. This allows full use of Kernal ROM routines (but not BASIC routines),
|
||||
@ -84,7 +84,7 @@ Directives
|
||||
16 virtual registers cx16.r0...cx16.r15 from the Commander X16 into the zeropage as well
|
||||
(but not on the same locations). They are relocated automatically by the compiler.
|
||||
The other options need those locations for other things so those virtual registers have
|
||||
to be put into memory elsewhere (outside of the zeropage). Trying to use them as zero page
|
||||
to be put into memory elsewhere (outside of the zeropage). Trying to use them as zeropage
|
||||
variables or pointers etc. will be a lot slower in those cases!
|
||||
On the Commander X16 the registers are always in zeropage. On other targets, for now, they
|
||||
are always outside of the zeropage.
|
||||
@ -100,8 +100,8 @@ Directives
|
||||
|
||||
Level: module.
|
||||
Global setting, set the program's start memory address. It's usually fixed at ``$0801`` because the
|
||||
default launcher type is a CBM-basic program. But you have to specify this address yourself when
|
||||
you don't use a CBM-basic launcher.
|
||||
default launcher type is a CBM-BASIC program. But you have to specify this address yourself when
|
||||
you don't use a CBM-BASIC launcher.
|
||||
|
||||
|
||||
.. data:: %import <name>
|
||||
@ -295,7 +295,7 @@ Various examples::
|
||||
byte[5] values = 255 ; initialize with five 255 bytes
|
||||
|
||||
word @zp zpword = 9999 ; prioritize this when selecting vars for zeropage storage
|
||||
uword @requirezp zpaddr = $3000 ; we require this variable in Zeropage
|
||||
uword @requirezp zpaddr = $3000 ; we require this variable in zeropage
|
||||
word @shared asmvar ; variable is used in assembly code but not elsewhere
|
||||
|
||||
|
||||
|
||||
@ -39,7 +39,7 @@ This is a hard limit: there is no built-in support for RAM expansions or bank sw
|
||||
====================== ================== ========
|
||||
memory area type note
|
||||
====================== ================== ========
|
||||
``$00``--``$ff`` ZeroPage contains many sensitive system variables
|
||||
``$00``--``$ff`` zeropage contains many sensitive system variables
|
||||
``$100``--``$1ff`` Hardware stack used by the CPU, normally not accessed directly
|
||||
``$0200``--``$ffff`` Free RAM or ROM free to use memory area, often a mix of RAM and ROM
|
||||
====================== ================== ========
|
||||
@ -75,10 +75,10 @@ Prog8 programs can access all of those special memory locations but it will have
|
||||
|
||||
.. _zeropage:
|
||||
|
||||
ZeroPage ("ZP")
|
||||
Zeropage ("ZP")
|
||||
---------------
|
||||
|
||||
The ZeroPage memory block ``$02``--``$ff`` can be regarded as 254 CPU 'registers', because
|
||||
The zeropage memory block ``$02``--``$ff`` can be regarded as 254 CPU 'registers', because
|
||||
they take less clock cycles to access and need fewer instruction bytes than accessing other memory locations outside of the ZP.
|
||||
Theoretically they can all be used in a program, with the following limitations:
|
||||
|
||||
@ -95,7 +95,7 @@ It will use the free ZP addresses to place its ZP variables in,
|
||||
until they're all used up. If instructed to output a program that takes over the entire
|
||||
machine, (almost) all of the ZP addresses are suddenly available and will be used.
|
||||
|
||||
**ZeroPage handling is configurable:**
|
||||
**zeropage handling is configurable:**
|
||||
There's a global program directive to specify the way the compiler
|
||||
treats the ZP for the program. The default is to be reasonably restrictive to use the
|
||||
part of the ZP that is not used by the C64's Kernal routines.
|
||||
@ -104,10 +104,10 @@ If you want, it's also possible to be more restrictive and stay clear of the add
|
||||
This allows the program to exit cleanly back to a BASIC ready prompt - something that is not possible in the other modes.
|
||||
|
||||
|
||||
IRQs and the ZeroPage
|
||||
IRQs and the zeropage
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The normal IRQ routine in the C-64's Kernal will read and write several addresses in the ZP
|
||||
The normal IRQ routine in the C64's Kernal will read and write several addresses in the ZP
|
||||
(such as the system's software jiffy clock which sits in ``$a0 - $a2``):
|
||||
|
||||
``$a0 - $a2``; ``$91``; ``$c0``; ``$c5``; ``$cb``; ``$f5 - $f6``
|
||||
@ -144,7 +144,7 @@ IRQ Handling
|
||||
|
||||
Normally, the system's default IRQ handling is not interfered with.
|
||||
You can however install your own IRQ handler (for clean separation, it is advised to define it inside its own block).
|
||||
There are a few library routines available to make setting up C-64 60hz IRQs and Raster IRQs a lot easier (no assembly code required).
|
||||
There are a few library routines available to make setting up C64 60hz IRQs and Raster IRQs a lot easier (no assembly code required).
|
||||
|
||||
For the C64 these routines are::
|
||||
|
||||
|
||||
@ -24,7 +24,7 @@ directly into the target variable, register, or memory location.
|
||||
The software stack is implemented as follows:
|
||||
|
||||
- 2 pages of memory are allocated for this, exact locations vary per machine target.
|
||||
For the C-64 they are set at $ce00 and $cf00 (so $ce00-$cfff is reserved).
|
||||
For the C64 they are set at $ce00 and $cf00 (so $ce00-$cfff is reserved).
|
||||
For the Commander X16 they are set at $0400 and $0500 (so $0400-$05ff are reserved).
|
||||
This default location can be overridden using the `-esa` command line option.
|
||||
- these are the high and low bytes of the values on the stack (it's a 'split 16 bit word stack')
|
||||
@ -73,7 +73,7 @@ regular subroutines
|
||||
- the return value is passed back to the caller via cpu register(s):
|
||||
Byte values will be put in ``A`` .
|
||||
Word values will be put in ``A`` + ``Y`` register pair.
|
||||
Float values will be put in the ``FAC1`` float 'register' (Basic allocated this somewhere in ram).
|
||||
Float values will be put in the ``FAC1`` float 'register' (BASIC allocated this somewhere in ram).
|
||||
|
||||
|
||||
Calls to builtin functions are treated in a special way:
|
||||
|
||||
Loading…
Reference in New Issue
Block a user