alx/ueforth
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Adding more docs.

Browse Source
This commit is contained in:
Brad Nelson
2021-01-10 19:44:04 -08:00
parent 043c9634d1
commit faf1989296
3 changed files with 365 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
ueforth/arduino/arduino.template.ino
View File

@ -1,6 +1,5 @@
{{opcodes}}
#include <WiFi.h>
#include <WiFiClient.h>
#include <WebServer.h>
@ -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()) \

56
ueforth/plan.txt
View File

@ -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 ;

378
ueforth/site/index.html
View File

@ -1,6 +1,31 @@
<!DOCTYPE html>
<head>
<title>EForth</title>
<title>EForth</title>
<style>
body {
max-width: 800px;
}
h1 {
border-top: 3px solid #777;
background-color: #111;
color: #eee;
padding: 10px;
margin-top: 0;
}
h2 {
border-top: 2px solid #777;
background-color: #ccc;
padding: 10px;
}
h3 {
border-top: 1px solid #777;
background-color: #eee;
padding: 10px;
}
h5 {
margin: 2px;
}
</style>
</head>
<body>
<h1>EForth</h1>
@ -10,31 +35,357 @@ EForth is a delightfully minimalist approach to Forth originated by Bill Muench
</p>
<p>
In its original form metacompilation is avoided.
In its original form, meta-compilation is avoided.
</p>
<h2>Download</h2>
<h2>Downloads</h2>
<h3>µEforth</h3>
<p>
Version of uEforth - A reduced cross-platform EForth version (RECOMMENDED)
A reduced cross-platform EForth version
</p>
<ul>
<li><a href="static/ueforth-arduino-esp32.zip">ueforth-arduino-esp32.zip</a>
- Arudino Source Code</li>
<li><a href="static/uEforth32.exe">uEforth32.exe</a> - Window 32-bit EXE uEforth</li>
<li><a href="static/uEforth64.exe">uEforth64.exe</a> - Window 64-bit EXE uEforth</li>
<li><a href="static/ueforth.linux">ueforth.linux</a> - Linux 64-bit Executable uEforth</li>
<li><a href="https://github.com/flagxor/eforth" target="_blank">http://github.com/flagxor/eforth</a>
- Complete Source Code (under ueforth)</li>
- <b>Arduino ESP32</b> Source Code <b>&larr; SVFIG & Forth2020 folks start here!</b></li>
<li><a href="static/uEforth32.exe">uEforth32.exe</a> - Window 32-bit EXE µEforth</li>
<li><a href="static/uEforth64.exe">uEforth64.exe</a> - Window 64-bit EXE µEforth</li>
<li><a href="static/ueforth.linux">ueforth.linux</a> - Linux 64-bit Executable µEforth</li>
</ul>
<p>
<a href="https://github.com/flagxor/eforth" target="_blank">http://github.com/flagxor/eforth</a>
- Complete Source Code (under ueforth)
</p>
<h2>µEforth</h2>
<p>
µ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.
</p>
<p>
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:
</p>
<pre>
FIND ( a n -- xt | 0 )
PARSE ( ch -- a n )
S&gt;NUMBER? ( a n -- n f | 0 )
CREATE ( "name" -- )
EVALUATE1 ( -- )
</pre>
<p>
This includes <code>EVALUATE1</code> which parses a single word and
interprets or compiles it (reusing <code>PARSE</code>,
<code>FIND</code>, and <code>S&gt;NUMBER?</code>).
</p>
<p>
See <a href="https://github.com/flagxor/eforth/blob/main/ueforth/common/core.h">core.h</a>.
</p>
<p>
A few global variables connect parsing and compilation state between
C and Forth (by way of a memory region accessed via <code>'SYS</code>):
</p>
<pre>
'TIB --- Pointer to the Translation Input Buffer
#TIB --- Length of the Translation Input Buffer
&gt;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
</pre>
<p>
Error handling is routed via a deferred callback in <code>'NOTFOUND</code>
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.
</p>
<p>
<a href="https://en.wikipedia.org/wiki/X_Macro">X-Macros</a>
are then used to build up a small set of core opcodes defined in 1-3 lines each:
</p>
<pre>
0= 0&lt; + U/MOD */MOD AND OR XOR
DUP SWAP OVER DROP @ L@ C@ ! L! C!
SP@ SP! RP@ RP! &gt;R R&gt; R@ : ; EXIT
EXECUTE BRANCH 0BRANCH DONEXT DOLIT
ALITERAL CELL DOES&gt; IMMEDIATE 'SYS
</pre>
<p>
See <a href="https://github.com/flagxor/eforth/blob/main/ueforth/common/opcodes.h">opcodes.h</a>.
</p>
<p>
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
<code>Z"</code>, <code>Z&gt;S</code>, and <code>S&gt;Z</code>.
</p>
<h3>Arduino</h3>
<h4>Arduino Opcodes</h4>
<p>
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.
</p>
<p>
See <a href="https://github.com/flagxor/eforth/blob/main/ueforth/arduino/arduino.template.ino">arduino.template.ino</a>.
</p>
<h5>Allocation</h5>
<pre>
MALLOC ( n -- a | 0 ) System malloc
SYSFREE ( a -- ) System free
REALLOC ( a n -- a | 0 ) System realloc
</pre>
<h5>Serial</h5>
<pre>
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
</pre>
<h5>GPIO</h5>
<pre>
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 )
</pre>
<h5>System</h5>
<pre>
MS ( n -- )
TERMINATE ( n -- ) Call system exit
</pre>
<h5>Files</h5>
<pre>
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 )
</pre>
<h5>WiFi</h5>
<pre>
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
</pre>
<h5>mDNS</h5>
<pre>
MDNS.begin ( name-z -- ) Start multicast dns
</pre>
<h5>SPIFFS</h5>
<pre>
SPIFFS.begin ( format-on-fail path-z max-files -- f )
SPIFFS.end ( -- )
SPIFFS.format ( -- f )
SPIFFS.totalBytes ( -- n )
SPIFFS.usedBytes ( -- n )
</pre>
<h5>WebServer</h5>
<pre>
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.
</pre>
<h4>Arduino ESP32 WebUI</h4>
<p>
A terminal over the web can be activated.
Contact at port printed or via mDNS <a href="http://ueforth/">http://ueforth/</a>.
</p>
<pre>
webui ( network-z password-z -- )
</pre>
<p>
See <a href="https://github.com/flagxor/eforth/blob/main/ueforth/arduino/arduino_server.fs">arduino_server.fs</a>.
</p>
<h3>Windows</h3>
<h4>Windows Opcodes</h4>
<p>
The wealth of Windows .DLL and system functionality can be
accessed via the dynamic loading interface.
A handle to a library is obtained with <code>LOADLIBRARYA</code>,
and then individual symbols are accessed with <code>GETPROCADDRESS</code>.
</p>
<pre>
LOADLIBRARYA ( dllname-z -- module )
GETPROCADDRESS ( module name-z -- fn )
</pre>
<p>
And assembly version of <code>*/MOD</code> is provided to allow the EXE to build without
including MSVCRT.
</p>
<p>
See <a href="https://github.com/flagxor/eforth/blob/main/ueforth/windows/windows_main.c">windows_main.c</a>.
</p>
<p>
Native functions all called with CALL(n) (see Windows &amp; Linux Calling below).
</p>
<h4>Windows Imports</h4>
<p>
Various Win32 calls are imported in
<a href="https://github.com/flagxor/eforth/blob/main/ueforth/windows/windows.fs">windows.fs</a>.
In addition, a terminal that responds to ANSI escape codes is created and connected to
<code>TYPE</code> and <code>KEY</code>.
</p>
<h3>Linux</h3>
<h4>Linux Opcodes</h4>
<p>
Linux libraries and the operating system can be accessed via the use
of the <code>DLSYM</code> 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 (<code>dlopen</code>)
to be loaded from Forth.
</p>
<pre>
DLSYM ( module name-z -- fn )
</pre>
<p>
See <a href="https://github.com/flagxor/eforth/blob/main/ueforth/posix/posix_main.c">posix_main.c</a>.
</p>
<p>
Native functions all called with CALL(n) (see Windows &amp; Linux Calling below).
</p>
<h4>Linux Imports</h4>
<p>
Various Linux calls including Xlib are imported in
<a href="https://github.com/flagxor/eforth/blob/main/ueforth/posix/posix.fs">posix.fs</a> and
<a href="https://github.com/flagxor/eforth/blob/main/ueforth/posix/xlib.fs">xlib.fs</a>.
In addition, <code>TYPE</code> and <code>KEY</code> are connected to
<code>stdin</code> and <code>stdout</code>.
</p>
<h3>Windows &amp; Linux Calling</h3>
<p>
As unfortunately both Windows and Linux have system and library calls with
as many as 10 parameters (for example <code>XCreateImage</code>),
a collection of calling thunks is required.
A single varidic thunk would be ideal, but is hard to do without per platform
assembly language.
</p>
<pre>
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 )
</pre>
<p>
See <a href="https://github.com/flagxor/eforth/blob/main/ueforth/common/calling.h">calling.h</a>.
</p>
<h3>Web</h3>
<font style="font-size: 18pt; color: #C00;">Work in Progress - Coming Soon</font>
<h2>Classic esp32Forth</h2>
<p>
esp32Forth - Version 6.3 for NodeMCU ESP32S - Tweaked for the Web
</p>
<ul>
<li><a href="static/espforth.ino">espforth.ino</a>
</ul>
</p>
<h2>EForth Quirks</h2>
<h3>Classic EForth Quirks</h3>
<p>
EForth uses <code>FOR..NEXT</code> in favor of <code>DO..LOOP</code>.
@ -65,4 +416,3 @@ The even more enigmatic <code>FOR..WHILE..NEXT..ELSE..THEN</code>
is used in place of <code>DO..LEAVE..LOOP</code>.
It allows a while condition to early out of a counted loop.
</p>