From 8b3e51f0db19daa5fe72c258598f73a3db3e7c42 Mon Sep 17 00:00:00 2001
From: Adam Shamblin <adam@vexingworkshop.com>
Date: Sun, 10 Jul 2022 16:46:49 -0600
Subject: [PATCH] Begin instructions to enable hardware flow control on a
 turnkey system

---
 doc/README.md | 29 +++++++++++++++++++++++++++++
 src/init.fs   |  2 ++
 src/uart.fs   |  2 ++
 3 files changed, 33 insertions(+)
 create mode 100644 src/init.fs

diff --git a/doc/README.md b/doc/README.md
index a6ad8b0..b98bdeb 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -1,5 +1,8 @@
 ---
 title: Documentation
+keywords:
+- docs
+- system
 ---
 
 # Documentation
@@ -11,3 +14,29 @@ available using the `forthdeck` project.
 * [Terminal](terminal.md)
 * [UART](uart.md)
 * [Wordle](wordle.fs)
+
+## System
+
+A certain number of words may be loaded into the system to greatly improve
+quality of life when using `forthdeck` interactively. These words may be
+compiled to flash and saved in the first image stored to the MCU.
+
+At the time of this writing I have chosen to include the [GPIO](gpio.md) and
+[UART](uart.md) collections in the first image of my own system and to enable
+hardware flow control.
+
+### Enabling Hardware Flow Control
+
+In order to enable hardware flow control and to increase the speed of serial
+uploads **greatly**, I have chosen to include the [GPIO](gpio.md),
+[UART](uart.md) and [INIT](init.md) collections in the first image of my own
+system.
+
+```forth
+compiletoflash
+\...ctrl-a ctrl-s, load files...
+save
+```
+
+`init.fs` contains an `INIT` word that will be run on system startup, and that
+includes code to enable hardware flow control on UART0.
diff --git a/src/init.fs b/src/init.fs
new file mode 100644
index 0000000..c6ee60f
--- /dev/null
+++ b/src/init.fs
@@ -0,0 +1,2 @@
+\ Init function for turnkey system
+: INIT UART0 hfc-enable ;
diff --git a/src/uart.fs b/src/uart.fs
index c74e4c6..36078f7 100644
--- a/src/uart.fs
+++ b/src/uart.fs
@@ -35,6 +35,8 @@ UART1_BASE UARTCR + constant UART1_CR
 : loopback-enable ( addr -- ) DUP @ 1 7 lshift OR SWAP ! ;
 
 \ Enable hardware flow control
+\ Given the address of a UART control register, enable hardware flow control
+\ example: UART0 hfc-enable
 : hfc-enable ( addr -- )
   2 pin UART funcsel! DUP cts-enable
   3 pin UART funcsel! rts-enable ;
-- 
2.39.5