Apple-2-SW/prog8
1
0
Fork 0
mirror of https://github.com/irmen/prog8.git synced 2025-02-18 20:30:43 +00:00
Code Issues Projects Releases Wiki Activity

BASIC, VICE, C64, zeropage spelling

Browse Source
This commit is contained in:
Irmen de Jong 2022-10-29 14:12:10 +02:00
parent db8912a735
commit e951340033
8 changed files with 39 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
docs/source/building.rst
View File

@ -210,26 +210,26 @@ the ``srcdirs`` command line option.
.. _debugging: .. _debugging:
Debugging (with Vice) Debugging (with VICE)
--------------------- ---------------------
There's support for using the monitor and debugging capabilities of the rather excellent 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 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 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. 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. 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", All breakpoints are then written to a file called "programname.vice-mon-list",
which is meant to be used by the Vice emulator. 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. 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 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`` ``$ x64 -moncommands programname.vice-mon-list``
Vice will then use the label names in memory disassembly, and will activate any breakpoints as well. 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. If your running program hits one of the breakpoints, VICE will halt execution and drop you into the monitor.
Troubleshooting Troubleshooting

8
docs/source/index.rst
View File

@ -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 .. image:: _static/primes_example.png
:align: center :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: 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. 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. 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.* *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. 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. 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. 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. 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>`_ 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 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) using the ``-emu`` or ``-emu2`` command line options)

4
docs/source/libraries.rst
View File

@ -105,7 +105,7 @@ sys (part of syslib)
note: a more accurate way to do this is by using a raster irq handler instead. note: a more accurate way to do this is by using a raster irq handler instead.
``reset_system()`` ``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) (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. 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, 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 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) cx16diskio (cx16 only)

12
docs/source/portingguide.rst
View File

@ -17,15 +17,15 @@ CPU
Memory Map 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. #. *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 Zero page locations for a normal running system (basic + Kernal enabled) #. Provide list of any additional free zeropage 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 zeropage 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 #. 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. 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 RAM, ROM, I/O

8
docs/source/programming.rst
View File

@ -206,7 +206,7 @@ it will try to fill it with as much other variables as possible (before they wil
Use ``@requirezp`` tag to *force* the variable into zeropage, but if there is no more free space the compilation will fail. 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 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 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:: Example::
@ -261,8 +261,8 @@ Floating point numbers
Floats are stored in the 5-byte 'MFLPT' format that is used on CBM machines, 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. 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. This is because routines in the C64 BASIC and Kernal ROMs are used for that.
So floating point operations will only work if the C-64 BASIC ROM (and Kernal ROM) So floating point operations will only work if the C64 BASIC ROM (and Kernal ROM)
are banked in. are banked in.
Also your code needs to import the ``floats`` library to enable floating point support Also your code needs to import the ``floats`` library to enable floating point support
@ -889,7 +889,7 @@ ror2(x)
sizeof(name) sizeof(name)
Number of bytes that the object 'name' occupies in memory. This is a constant determined by the data type of 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. 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. Note: usually you will be interested in the number of elements in an array, use len() for that.
memory(name, size, alignment) memory(name, size, alignment)

8
docs/source/syntaxreference.rst
View File

@ -54,7 +54,7 @@ Directives
.. data:: %zeropage <style> .. data:: %zeropage <style>
Level: module. 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, - 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), and don't change anything else. This allows full use of Kernal ROM routines (but not BASIC routines),
@ -100,8 +100,8 @@ Directives
Level: module. Level: module.
Global setting, set the program's start memory address. It's usually fixed at ``$0801`` because the 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 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. you don't use a CBM-BASIC launcher.
.. data:: %import <name> .. data:: %import <name>
@ -295,7 +295,7 @@ Various examples::
byte[5] values = 255 ; initialize with five 255 bytes byte[5] values = 255 ; initialize with five 255 bytes
word @zp zpword = 9999 ; prioritize this when selecting vars for zeropage storage 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 word @shared asmvar ; variable is used in assembly code but not elsewhere

14
docs/source/targetsystem.rst
View File

@ -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 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 ``$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 ``$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:
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. 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: 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 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. 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 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 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. 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. 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``): (such as the system's software jiffy clock which sits in ``$a0 - $a2``):
``$a0 - $a2``; ``$91``; ``$c0``; ``$c5``; ``$cb``; ``$f5 - $f6`` ``$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. 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). 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:: For the C64 these routines are::

4
docs/source/technical.rst
View File

@ -24,7 +24,7 @@ directly into the target variable, register, or memory location.
The software stack is implemented as follows: The software stack is implemented as follows:
- 2 pages of memory are allocated for this, exact locations vary per machine target. - 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). 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. 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') - 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): - the return value is passed back to the caller via cpu register(s):
Byte values will be put in ``A`` . Byte values will be put in ``A`` .
Word values will be put in ``A`` + ``Y`` register pair. 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: Calls to builtin functions are treated in a special way: