Prog8 Documentation Release 1.50-dev Irmen de Jong Aug 05, 2019 Contents of this manual: 1 What is Prog8? 3 2 Code examples 5 3 Design principles and features9 4 Required tools 11 4.1 Target system specification........................................ 11 4.2 Writing and building a program..................................... 14 4.3 Programming in Prog8.......................................... 16 4.4 Syntax Reference............................................. 28 4.5 TODO.................................................. 39 5 Index 41 Index 43 i ii Prog8 Documentation, Release 1.50-dev Contents of this manual: 1 Prog8 Documentation, Release 1.50-dev 2 Contents of this manual: CHAPTER 1 What is Prog8? This is an experimental compiled programming language targeting the 8-bit 6502/ 6510 microprocessor. This CPU is from the late 1970’s and early 1980’s and was used in many home computers from that era, such as the Commodore- 64. The language aims to provide many conveniences over raw assembly code (even when using a macro assembler), while still being low level enough to create high performance programs. Prog8 is copyright © Irmen de Jong ([email protected]| http://www.razorvine.net). The project is on github: https://github.com/irmen/prog8.git This software is licensed under the GNU GPL 3.0, see https://www.gnu.org/licenses/gpl.html 3 Prog8 Documentation, Release 1.50-dev 4 Chapter 1. What is Prog8? CHAPTER 2 Code examples This code calculates prime numbers using the Sieve of Eratosthenes algorithm: %import c64utils %zeropage basicsafe main { ubyte[256] sieve ubyte candidate_prime = 2 sub start() { memset(sieve, 256, false) c64scr.print("prime numbers up to 255:\n\n") ubyte amount=0 while true { ubyte prime = find_next_prime() if prime==0 break c64scr.print_ub(prime) c64scr.print(", ") amount++ } c64.CHROUT('\n') c64scr.print("number of primes (expected 54): ") c64scr.print_ub(amount) c64.CHROUT('\n') } sub find_next_prime() -> ubyte { while sieve[candidate_prime] { candidate_prime++ (continues on next page) 5 Prog8 Documentation, Release 1.50-dev (continued from previous page) if candidate_prime==0 return 0 } sieve[candidate_prime] = true uword multiple = candidate_prime while multiple < len(sieve) { sieve[lsb(multiple)] = true multiple += candidate_prime } return candidate_prime } } when compiled an ran on a C-64 you get this: The following programs shows a use of the high level struct type: %import c64utils %zeropage basicsafe main { struct Color { ubyte red ubyte green ubyte blue } sub start() { Color purple = {255, 0, 255} Color other other = purple other.red /= 2 other.green = 10 + other.green / 2 other.blue = 99 c64scr.print_ub(other.red) c64.CHROUT(',') c64scr.print_ub(other.green) c64.CHROUT(',') (continues on next page) 6 Chapter 2. Code examples Prog8 Documentation, Release 1.50-dev (continued from previous page) c64scr.print_ub(other.blue) c64.CHROUT('\n') } } when compiled and ran, it prints 127,10,99 on the screen. 7 Prog8 Documentation, Release 1.50-dev 8 Chapter 2. Code examples CHAPTER 3 Design principles and features • It is a cross-compiler running on modern machines (Linux, MacOS, Windows, . ) The generated output is a machine code program runnable on actual 8-bit 6502 hardware. • Usable on most operating systems. • Based on simple and familiar imperative structured programming paradigm. • ‘One statement per line’ code style, resulting in clear readable programs. • Modular programming and scoping via modules, code blocks, and subroutines. • Provide high level programming constructs but stay close to the metal; still able to directly use memory ad- dresses, CPU registers and ROM subroutines • Arbitrary number of subroutine parameters (constrained only by available memory) • Complex nested expressions are possible • Values are typed. Types supported include signed and unsigned bytes and words, arrays, strings and floats. • No dynamic memory allocation or sizing! All variables stay fixed size as determined at compile time. • Provide various quality of life language features and library subroutines specifically for the target platform. • Provide a very convenient edit/compile/run cycle by being able to directly launch the compiled program in an emulator and provide debugging information to the emulator. • The compiler outputs a regular 6502 assembly source code file, but doesn’t assemble this itself. The (separate) ‘64tass’ cross-assembler tool is used for that. • Goto is usually considered harmful, but not here: arbitrary control flow jumps and branches are possible, and will usually translate directly into the appropriate single 6502 jump/branch instruction. • There are no complicated built-in error handling or overflow checks, you’ll have to take care of this yourself if required. This keeps the language and code simple and efficient. • The compiler tries to optimize the program and generated code, but hand-tuning of the performance or space- critical parts will likely still be required. This is supported by the ability to easily write embedded assembly code directly in the program source code. 9 Prog8 Documentation, Release 1.50-dev 10 Chapter 3. Design principles and features CHAPTER 4 Required tools 64tass - cross assembler. Install this on your shell path. A recent .exe version of this tool for Windows can be obtained from my clone of this project. For other platforms it is very easy to compile it yourself (make ; make install). A Java runtime (jre or jdk), version 8 or newer is required to run the packaged compiler. If you’re scared of Oracle’s licensing terms, most Linux distributions ship OpenJDK instead and for Windows it’s possible to get that as well. Check out AdoptOpenJDK for downloads. Finally: a C-64 emulator (or a real C-64 ofcourse) to run the programs on. The compiler assumes the presence of the Vice emulator. Important: Building the compiler itself: (Only needed if you have not downloaded a pre-built ‘fat-jar’) (re)building the compiler itself requires a recent Kotlin SDK. The compiler is developed using the IntelliJ IDEA IDE from Jetbrains, with the Kotlin plugin (free community edition of this IDE is available). But a bare Kotlin SDK installation should work just as well. Instructions on how to obtain a working compiler are in First, getting a working compiler. 4.1 Target system specification Prog8 targets the following hardware: • 8 bit MOS 6502/6510 CPU • 64 Kb addressable memory (RAM or ROM) • memory mapped I/O registers The main target machine is the Commodore-64, which is an example of this. This chapter explains the relevant system details of such a machine. 11 Prog8 Documentation, Release 1.50-dev 4.1.1 Memory Model Physical address space layout The 6502 CPU can address 64 kilobyte of memory. Most of the 64 kilobyte address space can be used by Prog8 programs. This is a hard limit: there is no built-in support for RAM expansions or bank switching. memory area type note $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 A few of these memory addresses are reserved and cannot be used for arbitrary data. They have a special hardware function, or are reserved for internal use in the code generated by the compiler: reserved address in use for $00 data direction (CPU hw) $01 bank select (CPU hw) $02 internal scratch variable $03 internal scratch variable $fb - $fc internal scratch variable $fd - $fe internal scratch variable $fffa - $fffb NMI vector (CPU hw) $fffc - $fffd RESET vector (CPU hw) $fffe - $ffff IRQ vector (CPU hw) The actual machine will often have many other special addresses as well, For example, the Commodore-64 has: • ROMs installed in the machine: BASIC, kernal and character roms. Occupying $a000–$bfff and $e000–$ffff. • memory-mapped I/O registers, for the video and sound chips, and the CIA’s. Occupying $d000–$dfff. • RAM areas that are used for screen graphics and sprite data: usually at $0400–$07ff. Prog8 programs can access all of those special memory locations but it will have a special meaning. ZeroPage (“ZP”) 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 follwoing limitations: • several addresses ($02, $03, $fb - $fc, $fd - $fe) are reserved for internal use • most other addresses will already be in use by the machine’s operating system or kernal, and overwriting them will probably crash the machine. It is possible to use all of these yourself, but only if the program takes over the entire system (and seizes control from the regular kernal). This means it can no longer use (most) BASIC and kernal routines from ROM. • it’s more convenient and safe to let the compiler allocate these addresses for you and just use symbolic names in the program code. Prog8 knows what addresses are safe to use in the various ZP handling configurations. 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. 12 Chapter 4. Required tools Prog8 Documentation, Release 1.50-dev 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. It’s possible to claim the whole ZP as well (by disabling the operating system or kernal). If you want, it’s also possible to be more restricive and stay clear of the addresses used by BASIC routines too.