document responsiveness trade-off

1 files changed, 27 insertions, 34 deletions

diff --git a/shell/README.md b/shell/README.md
index e2a38702..12dbdfc4 100644
--- a/shell/README.md
+++ b/shell/README.md
@@ -1,61 +1,52 @@
 ### A prototype shell for the Mu computer
 
-Currently runs a tiny subset of Lisp. Steps to run it from the top-level:
+Currently runs a tiny dialect of Lisp. Steps to run it from the top-level:
 
 1. Build it:
 ```sh
 $ ./translate shell/*.mu      # generates code.img
 ```
 
-2. Run it:
+You can now already run it:
 ```sh
-$ qemu-system-i386 -m 2G code.img
-```
-or:
-```
-$ bochs -f bochsrc            # _much_ slower
-```
-
-To save typing in a large s-expression, create a secondary disk for data:
-```sh
-$ dd if=/dev/zero of=data.img count=20160
+$ qemu-system-i386 code.img
 ```
 
-Load an s-expression into it:
-```sh
-$ echo '(+ 1 1)' |dd of=data.img conv=notrunc
-```
+But let's add some more 'meat' to play with.
 
-You can also try one of the files of definitions in this directory (`*.limg`).
+2. Create a data disk with a library of functions.
 
 ```sh
-$ cat data.limg |dd of=data.img conv=notrunc
+$ dd if=/dev/zero of=data.img count=20160
+$ cat shell/data.limg |dd of=data.img conv=notrunc
 ```
 
-Now run with both code and data disks:
+Run with data disk (and 2GB of RAM):
 ```sh
 $ qemu-system-i386 -m 2G -hda code.img -hdb data.img
 ```
-or:
-```
-$ bochs -f bochsrc.2disks
-```
-
-You can type in expressions, hit `ctrl-s` to see their results, and hit
-`ctrl-m` to focus on the `...` below and browse how the results were computed.
-[Here's a demo.](https://archive.org/details/akkartik-2min-2021-02-24) The
-bottom of the screen shows context-dependent keyboard shortcuts (there's no
-mouse in the Mu computer at the moment).
 
-*Improvements*
+Try typing in some expressions and hitting `ctrl-s` to see their results.
+Hit `ctrl-m` to focus on the `...` after a run, and browse how the results
+were computed. [Here's a demo.](https://archive.org/details/akkartik-2min-2021-02-24)
+The bottom of the screen shows context-dependent keyboard shortcuts.
 
-If your Qemu installation supports them, one of these commandline arguments
-may speed up emulation:
+3. If your Qemu installation supports them, one of these commandline arguments
+   may speed up emulation:
 
 - `-enable-kvm`
 - `-accel ___` (run with `-accel help` for a list of available options)
 
-As a complete example, here's the command I typically use on Linux:
+If you do this, I recommend also adjusting the `responsiveness` mask in
+shell/evaluate.mu, which controls how frequently the fake screen updates.
+Smaller values will seem more responsive, larger values will leave more time
+to run your programs. I like to see the screen update about once a second.
+Some suggested values depending on how fast your Qemu is running:
+
+- `-enable-kvm` on a T420s running Linux: `0xffff/responsiveness=64k`
+- `-accel tcg` on a 2019 Mac: `0xfff/responsiveness=4k`
+
+Putting it all together, here's the command I typically use on Linux:
 
 ```
 $ qemu-system-i386 -m 2G -enable-kvm -hda code.img -hdb data.img
@@ -63,10 +54,12 @@ $ qemu-system-i386 -m 2G -enable-kvm -hda code.img -hdb data.img
 
 *Known issues*
 
+* No mouse support.
+
 * Don't press keys too quickly (such as by holding down a key). The Mu
   computer will crash (and often Qemu will segfault).
 
-* Mu currently assumes access to 2GB of RAM. To change that, modify the
+* Mu currently assumes access to 2GB of RAM. To increase that, modify the
   definition of `Heap` in 120allocate.subx, and then modify the `-m 2G`
   argument in the Qemu commands above. Mu currently has no virtual
   memory. If your Heap is too large for RAM, allocating past the end of RAM