Create global memory which can be shared with the esp32.

Author: Molorius

README.md

@@ -31,6 +31,8 @@ Copyright 2024 Blake Felt [email protected]
 # Contents
 * [Building ulp-forth](#building-ulp-forth)
 * [Using ulp-forth](#using-ulp-forth)
+* [Sharing memory](#sharing-memory)
+* [Threading models](#threading-models)
 * [Assembly words](#assembly-words)
 * [System words](#system-words)
 * [Clock words](#clock-words)
@@ -40,7 +42,7 @@ Copyright 2024 Blake Felt [email protected]
 * [Standard Core words](#standard-core-words)
 * [Standard Core Extension words](#standard-core-extension-words)
 * [Standard Double words](#standard-double-words)
-# [Optimizations](#optimizations)
+* [Optimizations](#optimizations)
 
 # Building ulp-forth
 
@@ -68,21 +70,65 @@ The cross compiler can be run with `ulp-forth build`. The user should pass in th
 * `--reserved` Number of reserved bytes for the ULP, for use with --assembly flag (default 8176). Note that the Espressif linker has a bug so has 12 less total bytes. Any space not used by code or data is used for the stacks.
 * `--subroutine` Use the subroutine threading model, see the [threading models](#threading-models) section.
 
+
+# Sharing memory
+
+There are words that can be used to share memory with the esp32. When compiled with the `--custom_assembly` or `--assembly` flags, the output assembly will include the `.global` directive for the associated memory. This memory will not be optimized away.
+
+| Shared word        | Equivalent word |
+| ------------------ | --------------- |
+| `GLOBAL-VARIABLE`  | `VARIABLE`      |
+| `GLOBAL-2VARIABLE` | `2VARIABLE`     |
+| `GLOBAL-ALLOCATE`  | `ALLOCATE`      |
+
+Access should be done while holding the mutex, see the [System words](#system-words) section.
+
+Example:
+
+```forth
+global-variable example \ create a global variable named "example"
+
+\ read an address while holding the mutex
+: global-@ ( address -- n )
+    mutex.take \ take ownership of the mutex
+    @ \ read the value at the address
+    mutex.give \ release the mutex
+;
+
+\ write to an address while holding the mutex
+: global-! ( n address -- )
+    mutex.take \ take ownership of the mutex
+    ! \ write the value to the address
+    mutex.give \ release the mutex
+;
+
+\ get the value at "example"
+: get-example ( -- )
+    example \ put the address of the memory onto the stack
+    global-@ \ read it
+;
+
+\ set the value at "example"
+: set-example ( n -- )
+    example \ put the address of the memory onto the stack
+    global-! \ write to it
+;
+```
+
 # Threading models
 
-There are two threading models for the output ULP code. This is forth definition of "threading" and is not the same as multithreading in other languages. It can be thought of as the execution environment.
+There are two threading models for the output ULP code. This is the forth definition of "threading" and is not the same as multithreading in other languages. It can be thought of as the execution environment.
 
-Token threading is usually smaller and subroutine threading is usually bigger, but this can vary based on the program and optimizations.
+Token threading is usually smaller and subroutine threading is usually faster, but this can vary based on the program and optimizations.
 
 ## Token threading (default)
-
-This is the default threading model. This uses a lightweight virtual machine to execute all forth words. This allows for some very compact code, but there is a speed penalty for the virtual machine.
+This uses a lightweight virtual machine to execute all forth words. This allows for some very compact code, but there is a speed penalty for the virtual machine.
 
 Code using this is roughly 20% smaller than subroutine threaded code.
 
 ## Subroutine threading
 
-This can be enabled with the `--subroutine` flag. It copmiles all forth words into assembly subroutines. This is very fast while executing, but there is a size penalty.
+This can be enabled with the `--subroutine` flag. It compiles all forth words into assembly subroutines. This is very fast while executing, but there is a size penalty.
 
 Code using this is roughly 20% faster than token threaded code.
 

pkg/forth/builtin/02_core.f

@@ -10,17 +10,51 @@
 \ Immediate.
 : RECURSE ( -- ) LAST COMPILE, ; IMMEDIATE
 
+: ALLOCATE ( n -- address ok )
+    FALSE \ mark as not global
+    [ 'A' WORD A ] LITERAL \ put an empty string as the name
+    --ALLOCATE
+;
+
+: GLOBAL-ALLOCATE ( n "\<spaces\>name" -- address ok )
+    TRUE \ mark as global
+    BL WORD \ parse the name
+    --ALLOCATE
+;
+
 \ Parse the next word delimited by a space. Allocate n cells. Create
 \ a definition for the word that places the address of the allocated
 \ memory onto the stack.
-: BUFFER: ( n -- )
+: BUFFER: ( n "\<spaces\>name" -- )
     ALLOCATE DROP \ allocate n words, drop the superfluous "ok" indicator but keep address
     : \ parse the next input, create a word with that name
     POSTPONE LITERAL \ compile the allocated address literal
     POSTPONE ; \ end the definition
 ;
 
-: VARIABLE 1 BUFFER: ;
+\ Parse the next word delimited by a space. Allocate n cells. Create
+\ a definition for the word that places the address of the allocated
+\ memory onto the stack. The allocated memory will be output to assembly
+\ with the same name and with the .global assembly tag.
+: GLOBAL-BUFFER: ( n "\<spaces\>name" -- )
+    BL WORD \ ( n name ) get the name we want to create
+    SWAP 1 PICK \ ( name n name ) copy the name
+    TRUE SWAP \ ( name n true name ) prepare for allocation
+    --ALLOCATE DROP SWAP \ ( address name ) allocate the memory, drop the "ok"
+    --CREATE-FORTH \ ( address ) create the new forth word
+    POSTPONE LITERAL \ ( ) compile the address
+    POSTPONE EXIT \ compile an exit
+;
+
+\ create a variable only visible to the ulp
+: VARIABLE ( "\<spaces\>name" -- )
+    1 BUFFER:
+;
+
+\ create a variable that can be shared with the esp32
+: GLOBAL-VARIABLE ( "\<spaces\>name" -- )
+    1 GLOBAL-BUFFER:
+;
 
 : DEFER
     1 ALLOCATE DROP \ allocate 1 word

pkg/forth/builtin/03_double.f

@@ -77,3 +77,4 @@
 ;
 
 : 2VARIABLE 2 BUFFER: ;
+: GLOBAL-2VARIABLE 2 GLOBAL-BUFFER: ;

pkg/forth/flag.go

@@ -9,9 +9,10 @@ package forth
 
 // Flags associated with each word
 type Flag struct {
-	Hidden    bool // This word is hidden from being found.
-	Immediate bool // This word should be executed immediately.
-	Data      bool // This Forth word is data and should not be optimized.
+	Hidden     bool // This word is hidden from being found.
+	Immediate  bool // This word should be executed immediately.
+	Data       bool // This Forth word is data and should not be optimized.
+	GlobalData bool // This data word should be marked as .global in the output.
 
 	addedToList bool // This word is already added to the output list.
 	recursive   bool // This Forth word is recursive.

pkg/forth/primitive.go

@@ -599,9 +599,29 @@ func PrimitiveSetup(vm *VirtualMachine) error {
 			},
 		},
 		{
-			name: "ALLOCATE",
+			name: "--ALLOCATE", // ( size global name -- address success )
 			goFunc: func(vm *VirtualMachine, entry *DictionaryEntry) error {
-				n, err := vm.Stack.PopNumber()
+				// get name
+				cell, err := vm.Stack.Pop()
+				if err != nil {
+					return JoinEntryError(err, entry, "could not pop name")
+				}
+				cellAddr, ok := cell.(CellAddress)
+				if !ok {
+					return EntryError(entry, "requires a name")
+				}
+				name, err := cellsToString(cellAddr.Entry.Word.(*WordForth).Cells)
+				if err != nil {
+					return JoinEntryError(err, entry, "could not parse name")
+				}
+				// get global
+				nGlobal, err := vm.Stack.PopNumber()
+				if err != nil {
+					return PopError(err, entry)
+				}
+				global := nGlobal != 0
+				// get size
+				n, err := vm.Stack.PopNumber() // the number of inputs
 				if err != nil {
 					return PopError(err, entry)
 				}
@@ -614,14 +634,18 @@ func PrimitiveSetup(vm *VirtualMachine) error {
 					w.Cells[i] = CellNumber{0}
 				}
 				de = DictionaryEntry{
+					Name: string(name),
 					Word: &w,
-					Flag: Flag{Data: true},
+					Flag: Flag{
+						Data:       true,
+						GlobalData: global,
+					},
 				}
-				cell := CellAddress{
+				newCell := CellAddress{
 					Offset: 0,
 					Entry:  &de,
 				}
-				err = vm.Stack.Push(cell)
+				err = vm.Stack.Push(newCell)
 				if err != nil {
 					return PushError(err, entry)
 				}

pkg/forth/ulpBuild.go

@@ -250,6 +250,11 @@ func (u *Ulp) buildDataWords() (string, error) {
 		if err != nil {
 			return "", err
 		}
+		if word.Entry.Flag.GlobalData {
+			label := word.Entry.ulpName
+			global := ".global " + label + "\r\n"
+			asm = global + asm
+		}
 		output[i] = asm
 	}
 	return strings.Join(output, "\r\n"), nil