From faf198929656bbb440dd5390b870279affc3c320 Mon Sep 17 00:00:00 2001 From: Brad Nelson Date: Sun, 10 Jan 2021 19:44:04 -0800 Subject: [PATCH] Adding more docs. --- ueforth/arduino/arduino.template.ino | 3 +- ueforth/plan.txt | 56 ---- ueforth/site/index.html | 378 ++++++++++++++++++++++++++- 3 files changed, 365 insertions(+), 72 deletions(-) delete mode 100644 ueforth/plan.txt diff --git a/ueforth/arduino/arduino.template.ino b/ueforth/arduino/arduino.template.ino index 6c23d3a..228967a 100644 --- a/ueforth/arduino/arduino.template.ino +++ b/ueforth/arduino/arduino.template.ino @@ -1,6 +1,5 @@ {{opcodes}} - #include #include #include @@ -82,7 +81,7 @@ tos = (cell_t) st.st_size; PUSH(w < 0 ? errno : 0)) \ /* WiFi */ \ X("WiFi.config", WIFI_CONFIG, \ - WiFi.config(ToIP(sp[-1]), ToIP(*sp), ToIP(tos)); sp -= 2; DROP) \ + WiFi.config(ToIP(sp[-2], ToIP(sp[-1]), ToIP(*sp), ToIP(tos)); sp -= 3; DROP) \ X("WiFi.begin", WIFI_BEGIN, \ WiFi.begin((const char *) *sp, (const char *) tos); --sp; DROP) \ X("WiFi.disconnect", WIFI_DISCONNECT, WiFi.disconnect()) \ diff --git a/ueforth/plan.txt b/ueforth/plan.txt deleted file mode 100644 index a815e03..0000000 --- a/ueforth/plan.txt +++ /dev/null @@ -1,56 +0,0 @@ -POSSIBLE PLAN -------------- - -* Support many platform variants - - Linux & Windows - * Expose dlsym / LoadLibrary/GetAddress, build from there - * Load Forth bootstraping from command line and well known locations - - exe relative boot.fs - - exe relative linux.fs - - provide facility to find exe relative, provide more libraries: - * x11 / GDI - * simplified graphics - * console / ide - * Build distributable zip w/ main exe, boot files - - Maybe installer too? - - ESP32/8266 - * Expose key features via built-in words: - - Wi-Fi - - BLE - - GPIO - - Raw Flash - - FAT - - SPI - - Clock and Timers - * Load Core bootstrap from embedded code - * Load User program from internal flash, followed by external - * Multiple Build Configurations: - - Single .ino file for Arduino install (generated from c source) - - ESP-SDK built raw hex & FAT image - - Web - * Expose CALL opcode taking and returning sp, call item from an array. - - Prepopulate array with method to eval and store into same array. - * Load js relative Forth bootstrapping: - - js relative boot.fs - - js relative web.fs: - * canvas graphics - * simplified graphics - * DOM interaction - * console / ide - * Build distributable js, boot files -* Publish built downloadables to gh-pages -* Support cross built by providing built binaries with others. - -CORE ----- - -0= 0< + UM/MOD */MOD -AND OR XOR -DUP SWAP OVER DROP -@ L@ C@ ! L! C! FILL MOVE -SP@ SP! RP@ RP! >R R> R@ -EXECUTE BRANCH 0BRANCH DONEXT DOLIT -ALITERAL CELL -FIND PARSE S>NUMBER? -CREATE DOES> IMMEDIATE 'SYS -: EVAL1 EXIT ; diff --git a/ueforth/site/index.html b/ueforth/site/index.html index 486f88c..cb3156c 100644 --- a/ueforth/site/index.html +++ b/ueforth/site/index.html @@ -1,6 +1,31 @@ - EForth +EForth +

EForth

@@ -10,31 +35,357 @@ EForth is a delightfully minimalist approach to Forth originated by Bill Muench

-In its original form metacompilation is avoided. +In its original form, meta-compilation is avoided.

-

Download

+

Downloads

+ +

µEforth

+

-Version of uEforth - A reduced cross-platform EForth version (RECOMMENDED) +A reduced cross-platform EForth version +

+ +

+http://github.com/flagxor/eforth + - Complete Source Code (under ueforth) +

+ +

µEforth

+ +

+µEforth (micro-Eforth) simplifies EForth even futher, by building just enough +of the core of the system in C to allow the rest to be be built in proper Forth.

-esp32Forth, Version 6.3 for NodeMCU ESP32S - Tweaked for the Web +A handful of "tricky" words that involve internal loops or many steps are built in their own +functions: +

+ +
+FIND ( a n -- xt | 0 )
+PARSE ( ch -- a n )
+S>NUMBER? ( a n -- n f | 0 )
+CREATE ( "name" -- )
+EVALUATE1 ( -- )
+
+ +

+This includes EVALUATE1 which parses a single word and +interprets or compiles it (reusing PARSE, +FIND, and S>NUMBER?). +

+ +

+See core.h. +

+ +

+A few global variables connect parsing and compilation state between +C and Forth (by way of a memory region accessed via 'SYS): +

+ +
+'TIB      --- Pointer to the Translation Input Buffer
+#TIB      --- Length of the Translation Input Buffer
+>IN       --- Number of characters consumed from TIB
+
+BASE      --- Numeric base for printing and parsing
+
+STATE     --- State of compiling, -1 for compiling, 0 for interpreting
+LAST      --- Execution token of last word defined
+
+'NOTFOUND --- Execution token of a handler to call on word not found
+
+ +

+Error handling is routed via a deferred callback in 'NOTFOUND +used when a word is absent from the dictionary. +This is eventually directed to an error routing that prints +a proper error, once I/O and exceptions are available. +

+ +

+X-Macros +are then used to build up a small set of core opcodes defined in 1-3 lines each: +

+ +
+0= 0< + U/MOD */MOD   AND OR XOR
+DUP SWAP OVER DROP    @ L@ C@ ! L! C!
+SP@ SP! RP@ RP!       >R R> R@   : ; EXIT
+EXECUTE BRANCH 0BRANCH DONEXT DOLIT
+ALITERAL CELL DOES> IMMEDIATE 'SYS
+
+ +

+See opcodes.h. +

+ +

+I/O and access to systems outside Forth are connected via a few per platform words. +Typically this set of words should be minimal, while still allowing relevant parts +of the host system to be available to Forth. +As null terminated strings are used by virtually all platforms, +their use is supported in Forth by way of +Z", Z>S, and S>Z. +

+ +

Arduino

+ +

Arduino Opcodes

+ +

+Because Arduino builds a statically linked image for flashing into ESP32 devices, +all C function bindings need to be explicitly added. +This is the current collection. +Typically to reduce confusion, function names have be preserved even through verbose. +In popular cases a shorted higher level name is provided. +

+ +

+See arduino.template.ino. +

+ +
Allocation
+
+MALLOC ( n -- a | 0 )   System malloc
+SYSFREE ( a -- )   System free
+REALLOC ( a n -- a | 0 )   System realloc
+
+ +
Serial
+
+Serial.begin ( baud -- )   Start serial port
+Serial.end ( -- )   End serial port
+Serial.available ( -- f )   Is serial data available
+Serial.readBytes ( a n -- n )   Read serial bytes, return number gotten
+Serial.write ( a n -- )   Write serial bytes
+
+ +
GPIO
+
+pinMode ( pin mode -- )   Set GPIO pin mode
+digitalWrite ( pin value -- )   Set GPIO pin state
+analogRead ( pin -- n )   Analog read from 0-4095
+ledcSetup ( channel freq resolution -- freq )
+ledcAttachPin ( pin channel -- )
+ledcDetachPin ( pin -- )
+ledcRead ( channel -- n )
+ledcReadFreq ( channel -- freq )   Get frequency (x 1,000,000)
+ledcWrite ( channel duty -- )
+ledcWriteTone ( channel freq )   Write tone frequency (x 1000)
+ledcWriteNote ( channel note octave -- freq )
+
+ +
System
+
+MS ( n -- )
+TERMINATE ( n -- ) Call system exit
+
+ +
Files
+
+R/O ( -- mode )
+R/W ( -- mode )
+W/O ( -- mode )
+BIN ( mode -- mode )
+CLOSE-FILE ( fh -- ior )
+OPEN-FILE ( a n mode -- fh ior )
+CREATE-FILE ( a n mode -- fh ior )
+DELETE-FILE ( a n -- ior )
+WRITE-FILE ( a n fh -- ior )
+READ-FILE ( a n fh -- n ior )
+FILE-POSITION ( fh -- n ior )
+REPOSITION-FILE ( n fh -- ior )
+FILE-SIZE ( fh -- n ior )
+
+ +
WiFi
+
+WiFi.config ( ip dns gateway subnet -- )   Packaged a.b.c.d little-endian
+Wifi.begin ( ssid-z password-z -- )
+Wifi.disconnect ( -- )
+WiFi.status ( -- n )
+WiFi.macAddress ( a -- )
+WiFi.localIP ( -- ip )
+WiFi.mode ( mode -- )
+WiFi.setTxPower ( powerx4 -- )   Set power x4
+WiFi.getTxPower ( -- powerx4 )   Get power x4
+
+ +
mDNS
+
+MDNS.begin ( name-z -- )   Start multicast dns
+
+ +
SPIFFS
+
+SPIFFS.begin ( format-on-fail path-z max-files -- f )
+SPIFFS.end ( -- )
+SPIFFS.format ( -- f )
+SPIFFS.totalBytes ( -- n )
+SPIFFS.usedBytes ( -- n )
+
+ +
WebServer
+
+WebServer.new ( port -- ws )   Allocate new webserver object
+WebServer.delete ( ws -- )   Delete webserver object
+WebServer.begin ( port ws -- )
+WebServer.stop ( ws -- )
+WebServer.on ( path-z xt ws -- ) Set up a web path handle callback
+WebServer.handleClient ( ws -- )   Handle one client request
+WebServer.hasArg ( z ws -- f )   By name
+WebServer.arg ( z ws -- z )   By name
+WebServer.argi ( n ws -- z )   By index
+WebServer.argName ( n ws -- z)   By index
+WebServer.args ( ws -- n )   Number of args
+WebServer.setContentLength ( n ws -- )
+WebServer.sendHeader ( name-z value-z fist ws -- )
+WebServer.send ( code mimetype data ws -- )
+WebServer.sendContent ( a n ws -- )
+WebServer.method ( ws -- n )   GET / POST etc.
+
+ +

Arduino ESP32 WebUI

+ +

+A terminal over the web can be activated. +Contact at port printed or via mDNS http://ueforth/. +

+ +
+webui ( network-z password-z -- )
+
+ +

+See arduino_server.fs. +

+ +

Windows

+ +

Windows Opcodes

+ +

+The wealth of Windows .DLL and system functionality can be +accessed via the dynamic loading interface. +A handle to a library is obtained with LOADLIBRARYA, +and then individual symbols are accessed with GETPROCADDRESS. +

+ +
+LOADLIBRARYA ( dllname-z -- module )
+GETPROCADDRESS ( module name-z -- fn )
+
+ +

+And assembly version of */MOD is provided to allow the EXE to build without +including MSVCRT. +

+ +

+See windows_main.c. +

+ +

+Native functions all called with CALL(n) (see Windows & Linux Calling below). +

+ +

Windows Imports

+ +

+Various Win32 calls are imported in +windows.fs. +In addition, a terminal that responds to ANSI escape codes is created and connected to +TYPE and KEY. +

+ +

Linux

+ +

Linux Opcodes

+ +

+Linux libraries and the operating system can be accessed via the use +of the DLSYM word. Functions can be requested by name from +particular modules. As the dynamic linking module is already loaded initially, +a 0 for the module allows the library loading function (dlopen) +to be loaded from Forth. +

+ +
+DLSYM ( module name-z -- fn )
+
+ +

+See posix_main.c. +

+ +

+Native functions all called with CALL(n) (see Windows & Linux Calling below). +

+ +

Linux Imports

+ +

+Various Linux calls including Xlib are imported in +posix.fs and +xlib.fs. +In addition, TYPE and KEY are connected to +stdin and stdout. +

+ +

Windows & Linux Calling

+ +

+As unfortunately both Windows and Linux have system and library calls with +as many as 10 parameters (for example XCreateImage), +a collection of calling thunks is required. +A single varidic thunk would be ideal, but is hard to do without per platform +assembly language. +

+ +
+CALL0 ( fn -- n )
+CALL1 ( n fn -- n )
+CALL2 ( n n fn -- n )
+CALL3 ( n n n fn -- n )
+CALL4 ( n n n n fn -- n )
+CALL5 ( n n n n n fn -- n )
+CALL6 ( n n n n n n fn -- n )
+CALL7 ( n n n n n n n fn -- n )
+CALL7 ( n n n n n n n n fn -- n )
+CALL9 ( n n n n n n n n n fn -- n )
+CALL10 ( n n n n n n n n n n fn -- n )
+
+ +

+See calling.h. +

+ +

Web

+ +Work in Progress - Coming Soon + +

Classic esp32Forth

+ +

+esp32Forth - Version 6.3 for NodeMCU ESP32S - Tweaked for the Web +

+ -

-

EForth Quirks

+

Classic EForth Quirks

EForth uses FOR..NEXT in favor of DO..LOOP. @@ -65,4 +416,3 @@ The even more enigmatic FOR..WHILE..NEXT..ELSE..THEN is used in place of DO..LEAVE..LOOP. It allows a while condition to early out of a counted loop.

-