docs/reference/repl.rst: Add information about new raw-paste mode.

dpgeorge · dpgeorge · commit 528f4bf383c8 · 2020-11-30T11:37:44.000+11:00
Signed-off-by: Damien George &lt;damien@micropython.org&gt;
diff --git a/docs/reference/repl.rst b/docs/reference/repl.rst
@@ -196,17 +196,68 @@ So you can use the underscore to save the result in a variable. For example:
     15
     >>>
 
-Raw mode
---------
+Raw mode and raw-paste mode
+---------------------------
 
-Raw mode is not something that a person would normally use. It is intended for
-programmatic use. It essentially behaves like paste mode with echo turned off.
+Raw mode (also called raw REPL) is not something that a person would normally use.
+It is intended for programmatic use and essentially behaves like paste mode with
+echo turned off, and with optional flow control.
 
 Raw mode is entered using Ctrl-A. You then send your python code, followed by
 a Ctrl-D. The Ctrl-D will be acknowledged by 'OK' and then the python code will
 be compiled and executed. Any output (or errors) will be sent back. Entering
 Ctrl-B will leave raw mode and return the the regular (aka friendly) REPL.
 
-The ``tools/pyboard.py`` program uses the raw REPL to execute python files on the
-MicroPython board.
-
+Raw-paste mode is an additional mode within the raw REPL that includes flow control,
+and which compiles code as it receives it. This makes it more robust for high-speed
+transfer of code into the device, and it also uses less RAM when receiving because
+it does not need to store a verbatim copy of the code before compiling (unlike
+standard raw mode).
+
+Raw-paste mode uses the following protocol:
+1. Enter raw REPL as usual via ctrl-A.
+2. Write 3 bytes: b"\x05A\x01" (ie ctrl-E then "A" then ctrl-A).
+3. Read 2 bytes to determine if the device entered raw-paste mode:
+    - 3a: If the result is b"R\x00" then the device understands the command but
+      doesn't support raw paste.
+    - 3b: If the result is b"R\x01" then the device does support raw paste and has
+      entered this mode.
+    - 3c: Otherwise the result should be b"ra" and the device doesn't support raw
+      paste and the string b"w REPL; CTRL-B to exit\r\n>" should be read and
+      discarded.
+4. If the device is in raw-paste mode then continue, otherwise fallback to standard
+   raw mode.
+5. Read 2 bytes, this is the flow-control window size (in bytes) stored as a 16-bit
+   unsigned little endian integer.  The remaining window size should be set to this
+   number.
+6. Write out the code to the device:
+    - 6a. While there are bytes to send, write up to the remaining window size.
+    - 6b. If the window size is 0, or there is a byte waiting to read, read 1 byte.
+      If this byte is b"\x01" (ctrl-A) then increase the remaining window size
+      by the window size from step 5.  If this byte is b"\x04" (ctrl-D) then the
+      device wants to end the data reception, and b"\x04" (ctrl-D) should be
+      written to the device and no more code sent after that.
+7. When all code has been written to the device, write b"\x04" (ctrl-D) to
+   indicate end-of-data.
+8. Read from the device until b"\x04" (ctrl-D) is received.  At this point the
+   device has received and compiled all of the code that was sent and is executing
+   it.
+9. The device outputs any characters produced by the executing code.  When (if)
+   the code finishes b"\x04" (ctrl-D) will be output, followed by any exception
+   that was uncaught, followed again by b"\x04" (ctrl-D).  It then goes back to
+   the standard raw REPL and outputs b">".
+
+For example, starting at a new line at the normal (friendly) REPL, if you write:
+
+    b'\x01\x05A\x01print(123)\x04'
+
+Then the device will respond with something like:
+
+    b'\r\nraw REPL; CTRL-B to exit\r\n>R\x01\x80\x00\x01\x04123\r\n\x04\x04>'
+
+In this case the flow-control window size is 128 and there is a new window
+immediately available at the start (ie up to 256 bytes can be written to begin
+with before waiting or checking for more incoming flow-control characters).
+
+The ``tools/pyboard.py`` program uses the raw REPL, including raw-paste mode, to
+execute Python code on a MicroPython-enabled board.
