From 82bc7ebb1f91ccbab60a81f4858f8ca9b0e07c7c Mon Sep 17 00:00:00 2001 From: dschmenk Date: Sat, 6 Jan 2024 15:28:58 -0800 Subject: [PATCH] Preliminary doc for PLFORTH --- README.md | 152 +++++++++++++++++++++++++------------------------ doc/PLFORTH.md | 101 ++++++++++++++++++++++++++++++++ 2 files changed, 180 insertions(+), 73 deletions(-) create mode 100644 doc/PLFORTH.md diff --git a/README.md b/README.md index 5e010ad..b733a3c 100755 --- a/README.md +++ b/README.md @@ -1,3 +1,5 @@ +[Get a preview of FORTH coming to PLASMA 2.1](https://github.com/dschmenk/PLASMA/blob/master/doc/PLFORTH.md) + # 3/24/2023 PLASMA 2.0 Available! Only 5 years in the making! @@ -26,86 +28,90 @@ Different projects have led to the architecture of PLASMA, most notably Apple Pa +- [3/24/2023 PLASMA 2.0 Available!](#3242023-plasma-20-available) +- [4/29/2018 PLASMA 1.2 Available!](#4292018-plasma-12-available) +- [The PLASMA Programming Language](#the-plasma-programming-language) + - [Contents](#contents) - [Build Environment](#build-environment) + - [PLASMA Cross-Compiler](#plasma-cross-compiler) - [acme Cross-Assembler](#acme-cross-assembler) - [PLASMA Source](#plasma-source) - - [Portable VM](#portable-vm) - - [Target VM](#target-vm) + - [Portable VM](#portable-vm) + - [Target VM](#target-vm) + - [PLASMA Target Hosted Compiler](#plasma-target-hosted-compiler) - [Tutorial](#tutorial) - - [PLASMA Compiler/Assembler](#plasma-compilerassembler) - - [PLASMA Modules](#plasma-modules) - - [Data Types](#data-types) - - [Obligatory 'Hello World'](#obligatory-hello-world) - - [Character Case](#character-case) - - [Comments](#comments) - - [Numbers](#numbers) - - [Characters](#characters) - - [Strings](#strings) - - [Organization of a PLASMA Source File](#organization-of-a-plasma-source-file) - - [Module Dependencies](#module-dependencies) - - [File Inclusion](#file-inclusion) - - [Predefined Functions](#predefined-functions) - - [Constant Declarations](#constant-declarations) - - [Structure Declarations](#structure-declarations) - - [Global Data & Variables Declarations](#global-data-variables-declarations) - - [Function Definitions](#function-definitions) - - [Statements and Expressions](#statements-and-expressions) - - [Exported Declarations](#exported-declarations) - - [Module Main Initialization Function](#module-main-initialization-function) - - [Module Done](#module-done) - - [Runtime](#runtime) -- [Reference](#reference) - - [Decimal and Hexadecimal Numbers](#decimal-and-hexadecimal-numbers) - - [Character and String Literals](#character-and-string-literals) - - [In-line String Literals](#in-line-string-literals) - - [Words](#words) - - [Bytes](#bytes) - - [Addresses](#addresses) - - [Arrays](#arrays) - - [Type Overrides](#type-overrides) - - [Multi-Dimensional Arrays](#multi-dimensional-arrays) - - [Offsets (Structure Elements)](#offsets-structure-elements) - - [Defining Structures](#defining-structures) - - [Pointers](#pointers) - - [Pointer Dereferencing](#pointer-dereferencing) - - [Addresses of Data/Code](#addresses-of-datacode) - - [Function Pointers](#function-pointers) + - [PLASMA Compiler/Assembler](#plasma-compilerassembler) + - [PLASMA Modules](#plasma-modules) + - [Data Types](#data-types) + - [Obligatory 'Hello World'](#obligatory-hello-world) + - [Character Case](#character-case) + - [Comments](#comments) + - [Numbers](#numbers) + - [Characters](#characters) + - [Strings](#strings) + - [Organization of a PLASMA Source File](#organization-of-a-plasma-source-file) + - [Module Dependencies](#module-dependencies) + - [File Inclusion](#file-inclusion) + - [Predefined Functions](#predefined-functions) + - [Constant Declarations](#constant-declarations) + - [Structure Declarations](#structure-declarations) + - [Global Data \& Variables Declarations](#global-data--variables-declarations) - [Function Definitions](#function-definitions) - - [Expressions and Statements](#expressions-and-statements) - - [Address Operators](#address-operators) - - [Arithmetic, Bitwise, and Logical Operators](#arithmetic-bitwise-and-logical-operators) - - [Assignment](#assignment) - - [Empty Assignments](#empty-assignments) - - [Increment and Decrement](#increment-and-decrement) - - [Lambda (Anonymous) Functions](#lambda-functions) - - [Control Flow](#control-flow) - - [CALL](#call) - - [RETURN](#return) - - [IF/[ELSIF]/[ELSE]/FIN](#ifelsifelsefin) - - [WHEN/IS/[OTHERWISE]/WEND](#whenisotherwisewend) - - [FOR \ [STEP]/NEXT](#for-todownto-stepnext) - - [WHILE/LOOP](#whileloop) - - [REPEAT/UNTIL](#repeatuntil) - - [CONTINUE](#continue) - - [BREAK](#break) + - [Statements and Expressions](#statements-and-expressions) + - [Exported Declarations](#exported-declarations) + - [Module Main Initialization Function](#module-main-initialization-function) + - [Module Done](#module-done) + - [Runtime](#runtime) +- [Reference](#reference) + - [Decimal and Hexadecimal Numbers](#decimal-and-hexadecimal-numbers) + - [Character and String Literals](#character-and-string-literals) + - [In-line String Literals](#in-line-string-literals) + - [Words](#words) + - [Bytes](#bytes) + - [Addresses](#addresses) + - [Arrays](#arrays) + - [Type Overrides](#type-overrides) + - [Multi-Dimensional Arrays](#multi-dimensional-arrays) + - [Offsets (Structure Elements)](#offsets-structure-elements) + - [Defining Structures](#defining-structures) + - [Pointers](#pointers) + - [Pointer Dereferencing](#pointer-dereferencing) + - [Addresses of Data/Code](#addresses-of-datacode) + - [Function Pointers](#function-pointers) + - [Function Definitions](#function-definitions-1) + - [Expressions and Statements](#expressions-and-statements) + - [Address Operators](#address-operators) + - [Arithmetic, Bitwise, and Logical Operators](#arithmetic-bitwise-and-logical-operators) + - [Assignment](#assignment) + - [Empty Assignments](#empty-assignments) + - [Increment and Decrement](#increment-and-decrement) + - [Lambda Functions](#lambda-functions) + - [Control Flow](#control-flow) + - [CALL](#call) + - [RETURN](#return) + - [IF/\[ELSIF\]/\[ELSE\]/FIN](#ifelsifelsefin) + - [WHEN/IS/\[OTHERWISE\]/WEND](#whenisotherwisewend) + - [FOR \ \[STEP\]/NEXT](#for-todownto-stepnext) + - [WHILE/LOOP](#whileloop) + - [REPEAT/UNTIL](#repeatuntil) + - [CONTINUE](#continue) + - [BREAK](#break) - [Advanced Topics](#advanced-topics) - - [Code Optimizations](#code-optimizations) - - [Functions Without Parameters Or Local Variables](#functions-without-parameters-or-local-variables) - - [Return Values](#return-values) - - [Native Assembly Functions](#native-assembly-functions) -- [Libraries and Sample Code](https://github.com/dschmenk/PLASMA/wiki) + - [Code Optimizations](#code-optimizations) + - [Functions Without Parameters Or Local Variables](#functions-without-parameters-or-local-variables) + - [Return Values](#return-values) + - [Native Assembly Functions](#native-assembly-functions) - [Implementation](#implementation) - - [A New Approach](#a-new-approach) - - [The Virtual Machine](#the-virtual-machine) - - [The Stacks](#the-stacks) - - [Evaluation Stack](#evaluation-stack) - - [Call Stack](#call-stack) - - [Local Frame Stack](#local-frame-stack) - - [Local String Pool](#local-string-pool) - - [The Bytecodes](https://github.com/dschmenk/PLASMA/wiki/PLASMA-Byte-Codes) - - [Apple 1 PLASMA](#apple-1-plasma) - - [Apple II PLASMA](#apple-ii-plasma) - - [Apple /// PLASMA](#apple--plasma) + - [A New Approach](#a-new-approach) + - [The Virtual Machine](#the-virtual-machine) + - [The Stacks](#the-stacks) + - [Evaluation Stack](#evaluation-stack) + - [Call Stack](#call-stack) + - [Local Frame Stack](#local-frame-stack) + - [Local String Pool](#local-string-pool) + - [Apple 1 PLASMA](#apple-1-plasma) + - [Apple II PLASMA](#apple-ii-plasma) + - [Apple /// PLASMA](#apple--plasma) - [Links](#links) diff --git a/doc/PLFORTH.md b/doc/PLFORTH.md new file mode 100644 index 0000000..f4ccb36 --- /dev/null +++ b/doc/PLFORTH.md @@ -0,0 +1,101 @@ +# FORTH PLASMA + PLFORTH ! + +PLFORTH represents a REPL and scripting language for the PLASMA environment. Or, what I did over the Holiday break. + +The goals of PLFORTH are pretty straight forward: +**Interactivity** and **debugging**. + +PLFORTH is a PLASMA module written in PLASMA itself. As a first class citizen of the PLASMA environment, it has instant access to all the PLASMA modules, from floating point to high-res graphics libraries and everything in between. + +## Missing words in PLFORTH + +There are quite a few missing word that a standard FORTH would have. Mostly due to deliberately keeping PLFORTH as minimal as possible to reduce the memory footpring and load time. Most of the missing words can be synthesized using existing PLASMA modules and some glue words. The double word have mostly been made avialable through PLASMA's 32 bit integer module, `INT32` by way of the `int32.4th` script. You can always petition to get your favorite FORTH word included in the default vocabulary. Speaking of `VOCABULARY`, PLFORTH only has one. + +## PLFORTH specific words + +### Words for looking at internal structures: + +`SHOW xxxx`: Displays the decompiled words making up the definition of `xxxx` + +`SHOWSTACK`: Displays the data stack + +`SHOWRSTACK`: Displays the return stack. Note: PLFORTH uses a software defined return stack, this is not the hardware stack + +`SHOWHASH`: Display the hash table depth counts. Used to debug the efficacy of the hash algorithm + +### Words for tracing and single stepping execution: + +`TRON`: Turn tracing on + +`TROFF`: Tirn tracing off (will also turn off single stepping if enabled) + +`STEPON`: Turn single stepping on + +`STEPOFF`: Turn single stepping off + +While running code, `` will toggle tracing on and off as well + +### Words for breakpoints: + +`BRK`: Used inside compiled word to effect a runtime break + +`BRKON xxxx`: Enable breakpoint whenever word `xxxx` is executed + +`BRKOFF`: Disable the breakpoint. Note: only one breakpoint is currently supported + +While running code, `` will break out and return to the interpreter. + +`CONT`: Continue running from the last break point + +### Words for PLASMA linkage: + +`LOOKUP yyyy`: Lookup symbol `yyyy` in PLASMA symbol table and return its address + +`PLASMA zzzz`: Create word `zzzz` with code address from `LOOKUP` + +### Word to run a script: + +`SRC" ssss"`: Source file `ssss` as input. Can be nested + +### Word for compiler modes: + +`PBC`: Compile into PLASMA Byte Code + +`ITC`: Compile into Indirect Threaded Code + +## Debugging vs Performance + +PLFORTH defaults to compiling using ITC (Indirect Threaded Code). This supports a list of inspection and debugging features while developing programs and scripts. However, the compiler can easily switch to PBC (PLASMA Byte Code) to greatly improve performance, but most of the debugging tools are lost. ITC compiled words and PBC compiled words can be intermingled and call each other seemlessly. PLASMA Byte Code is a direct match to many low-level FORTH constructs. + +## Hi-Res Graphics +Due to the way the Apple II implements Hi-Res graphics, a stub loader is required to reserve the pages used. + +`HRFORTH`: Reserve HGR page 1 before launching PLFORTH + +`HR2FORTH`: Reserve HGR pages 1 and 2 before launching PLFORTH + +## Scripts + +There are a few useful scripts located in the `scripts` directory. By far the most useful is `plasma.4th` + +### plasma.4th useful words + +`CAT`: Display files in current ProDOS directory + +`CAT" pppp"`: Display files in `pppp` ProDOS directory + +`PFX" pppp"`: Set current ProDOS prefix to `pppp` + +`PFX.`: Display current ProDOS prefix + +`EDIT" ssss"`: Edit file `ssss` + +## Caveats + +This is definitely a Work-In-Progress. There are still a few places where I'm unsure about the proper implementation of some words, especially the more esoteric compiler constructs. It also looks suspiciously like an early '80s wordset, as that is what I'm most familiar with. + +## Links + +Here is a (worse than usual) video running through some examples: https://youtu.be/picPyXAk77I?si=Td2En5Z3oxVTzh0z + +A pre-configures ProDOS floppy image barely able to run PLFORTH is available here: https://github.com/dschmenk/PLASMA/blob/master/images/apple/PLFORTH.PO