From 5522a573fe00438b75c322c2382ea9f33e9b7992 Mon Sep 17 00:00:00 2001
From: Adam Shamblin <adam@vexingworkshop.com>
Date: Mon, 18 Jul 2022 19:48:34 -0600
Subject: [PATCH] move rng function to its own file, update Makefile and README
 for hwfc

---
 .gitignore    |  1 +
 Makefile      | 10 +++++++++-
 README.md     | 16 ++++++++++++++++
 src/rng.fs    | 11 +++++++++++
 src/uart.fs   |  6 ++++++
 src/wordle.fs | 13 ++-----------
 6 files changed, 45 insertions(+), 12 deletions(-)
 create mode 100644 .gitignore
 create mode 100644 src/rng.fs

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..c10d187
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1 @@
+project/
diff --git a/Makefile b/Makefile
index f5f0db4..ec57a30 100644
--- a/Makefile
+++ b/Makefile
@@ -1,7 +1,15 @@
 # As recommended by the Mecrisp-Stellaris unofficial docs
 # @ https://mecrisp-stellaris-folkdoc.sourceforge.io/serial-terminals.html
+
+HW_FLOW_CONTROL ?= 1
+LINESPEED = ""
+
+ifeq ($(HW_FLOW_CONTROL), 0)
+	LINESPEED = "-l200"
+endif
+
 connect:
 	picocom -b 115200 -f h /dev/ttyUSB0 \
 		--imap lfcrlf,crcrlf \
 		--omap delbs,crlf \
-		--send-cmd "ascii-xfr -s"
+		--send-cmd "ascii-xfr -s $(LINESPEED)"
diff --git a/README.md b/README.md
index 45b621c..170b95d 100644
--- a/README.md
+++ b/README.md
@@ -14,6 +14,22 @@ out of an rp2040, while learning practical programming using the Forth language.
 
 [Documentation](doc/README.md)
 
+## Connecting
+
+To connect to the system relying on hardware flow control:
+
+```shell
+make connect
+```
+
+Or, when hardware flow control may not be present:
+
+```shell
+HW_FLOW_CONTROL=0 make connect
+```
+
+This will add a 200ms end-of-line delay. Enabling hardware flow control comes
+highly recommended, as developer workflow improves tremendously.
 
 ## TODO
 
diff --git a/src/rng.fs b/src/rng.fs
new file mode 100644
index 0000000..78ee204
--- /dev/null
+++ b/src/rng.fs
@@ -0,0 +1,11 @@
+\ Random number generation words
+\ Relies upon the rp2040 ring oscillator
+
+$40060000       constant ROSC_BASE
+ROSC_BASE $1c + constant RANDOMBIT
+
+\ Given a size in bits, return a random number
+: random ( bits -- n )
+  0 SWAP 0 DO
+    RANDOMBIT @ I lshift OR
+  LOOP ;
diff --git a/src/uart.fs b/src/uart.fs
index 36078f7..1b8cd9c 100644
--- a/src/uart.fs
+++ b/src/uart.fs
@@ -22,12 +22,18 @@ UART1_BASE UARTCR + constant UART1_CR
 : transmit-enabled? ( addr -- flag ) @ 1 8 lshift AND 0 > ;
 
 \ Hardware Flow Control
+\ Given the address of a UART control register, check if rts or cts is enabled
+\ example: UART0 rts-enabled?
 : rts-enabled? ( addr -- flag ) @ 1 14 lshift AND 0 > ;
 : cts-enabled? ( addr -- flag ) @ 1 15 lshift AND 0 > ;
 
+\ Given the address of a UART control register, toggle rts or cts
+\ example: UART0 rts-toggle
 : rts-toggle ( addr -- ) DUP @ 1 14 lshift XOR SWAP ! ;
 : cts-toggle ( addr -- ) DUP @ 1 15 lshift XOR SWAP ! ;
 
+\ Given the address of a UART control register, enable rts or cts
+\ example: UART0 rts-enable
 : rts-enable ( addr -- ) DUP @ 1 14 lshift OR SWAP ! ;
 : cts-enable ( addr -- ) DUP @ 1 15 lshift OR SWAP ! ;
 
diff --git a/src/wordle.fs b/src/wordle.fs
index b0dccc5..a148d01 100644
--- a/src/wordle.fs
+++ b/src/wordle.fs
@@ -1,20 +1,11 @@
 \ The hit game, Wordle
 
+\ requires rng.fs, terminal.fs
+
 \ QOL words
 : ? @ . ;
 : R? R@ . ;
 
-\ Random number generator
-\ relies on the rp2040 Ring Oscillator
-$40060000       constant ROSC_BASE
-ROSC_BASE $1c + constant RANDOMBIT
-
-\ Given a size in bits, return a random number
-: random ( bits -- n )
-  0 SWAP 0 DO
-    RANDOMBIT @ I lshift OR
-  LOOP ;
-
 \ Lexicon
 5 constant WORDSIZE
 20 WORDSIZE * constant SIZE
-- 
2.39.5