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

dpgeorge · dpgeorge · commit d9d56931e4bb · 2020-11-30T11:49:00.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,81 @@ 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:
+
+#. Enter raw REPL as usual via ctrl-A.
+
+#. Write 3 bytes: ``b"\x05A\x01"`` (ie ctrl-E then "A" then ctrl-A).
+
+#. Read 2 bytes to determine if the device entered raw-paste mode:
+
+   * If the result is ``b"R\x00"`` then the device understands the command but
+     doesn't support raw paste.
+
+   * If the result is ``b"R\x01"`` then the device does support raw paste and
+     has entered this mode.
+
+   * 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.
+
+#. If the device is in raw-paste mode then continue, otherwise fallback to
+   standard raw mode.
+
+#. 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.
+
+#. Write out the code to the device:
+
+   * While there are bytes to send, write up to the remaining window size.
+
+   * If the window size is 0, or there is a byte waiting to read, read 1 byte.
+     If this byte is ``b"\x01"`` then increase the remaining window size by the
+     window size from step 5.  If this byte is ``b"\x04"`` then the device wants
+     to end the data reception, and ``b"\x04"`` should be written to the device
+     and no more code sent after that.
+
+#. When all code has been written to the device, write ``b"\x04"`` to indicate
+   end-of-data.
+
+#. Read from the device until ``b"\x04"`` is received.  At this point the device
+   has received and compiled all of the code that was sent and is executing it.
+
+#. The device outputs any characters produced by the executing code.  When (if)
+   the code finishes ``b"\x04"`` will be output, followed by any exception that
+   was uncaught, followed again by ``b"\x04"``.  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.
