circuitpython/lib
Damien George bb24c69b90 lib/utils/pyexec: Add stdin-reader on raw REPL with flow control.
Background: the friendly/normal REPL is intended for human use whereas the
raw REPL is for computer use/automation.  Raw REPL is used for things like
pyboard.py script_to_run.py.  The normal REPL has built-in flow control
because it echos back the characters.  That's not so with raw REPL and flow
control is just implemented by rate limiting the amount of data that goes
in.  Currently it's fixed at 256 byte chunks every 10ms.  This is sometimes
too fast for slow MCUs or systems with small stdin buffers.  It's also too
slow for a lot of higher-end MCUs, ie it could be a lot faster.

This commit adds a new raw REPL mode which includes flow control: the
device will echo back a character after a certain number of bytes are sent
to the host, and the host can use this to regulate the data going out to
the device.  The amount of characters is controlled by the device and sent
to the host before communication starts.  This flow control allows getting
the maximum speed out of a serial link, regardless of the link or the
device at the other end.

Also, this new raw REPL mode parses and compiles the incoming data as it
comes in.  It does this by creating a "stdin reader" object which is then
passed to the lexer.  The lexer requests bytes from this "stdin reader"
which retrieves bytes from the host, and does flow control.  What this
means is that no memory is used to store the script (in the existing raw
REPL mode the device needs a big buffer to read in the script before it can
pass it on to the lexer/parser/compiler).  The only memory needed on the
device is enough to parse and compile.

Finally, it would be possible to extend this new raw REPL to allow bytecode
(.mpy files) to be sent as well as text mode scripts (but that's not done
in this commit).

Some results follow. The test was to send a large 33k script that contains
mostly comments and then prints out the heap, run via pyboard.py large.py.

On PYBD-SF6, prior to this PR:

$ ./pyboard.py large.py
stack: 524 out of 23552
GC: total: 392192, used: 34464, free: 357728
 No. of 1-blocks: 12, 2-blocks: 2, max blk sz: 2075, max free sz: 22345
GC memory layout; from 2001a3f0:
00000: h=hhhh=======================================hhBShShh==h=======h
00400: =====hh=B........h==h===========================================
00800: ================================================================
00c00: ================================================================
01000: ================================================================
01400: ================================================================
01800: ================================================================
01c00: ================================================================
02000: ================================================================
02400: ================================================================
02800: ================================================================
02c00: ================================================================
03000: ================================================================
03400: ================================================================
03800: ================================================================
03c00: ================================================================
04000: ================================================================
04400: ================================================================
04800: ================================================================
04c00: ================================================================
05000: ================================================================
05400: ================================================================
05800: ================================================================
05c00: ================================================================
06000: ================================================================
06400: ================================================================
06800: ================================================================
06c00: ================================================================
07000: ================================================================
07400: ================================================================
07800: ================================================================
07c00: ================================================================
08000: ================================================================
08400: ===============================================.....h==.........
       (349 lines all free)

(the big blob of used memory is the large script).

Same but with this PR:

$ ./pyboard.py large.py
stack: 524 out of 23552
GC: total: 392192, used: 1296, free: 390896
 No. of 1-blocks: 12, 2-blocks: 3, max blk sz: 40, max free sz: 24420
GC memory layout; from 2001a3f0:
00000: h=hhhh=======================================hhBShShh==h=======h
00400: =====hh=h=B......h==.....h==....................................
       (381 lines all free)

The only thing in RAM is the compiled script (and some other unrelated
items).

Time to download before this PR: 1438ms, data rate: 230,799 bits/sec.

Time to download with this PR: 119ms, data rate: 2,788,991 bits/sec.

So it's more than 10 times faster, and uses significantly less RAM.

Results are similar on other boards. On an stm32 board that connects via
UART only at 115200 baud, the data rate goes from 80kbit/sec to
113kbit/sec, so gets close to saturating the UART link without loss of
data.

The new raw REPL mode also supports a single ctrl-C to break out of this
flow-control mode, so that a ctrl-C can always get back to a known state.
It's also backwards compatible with the original raw REPL mode, which is
still supported with the same sequence of commands.  The new raw REPL
mode is activated by ctrl-E, which gives an error on devices that do not
support the new mode.

Signed-off-by: Damien George <damien@micropython.org>
2020-11-30 11:37:44 +11:00
..
asf4@d270f79aa1 lib: Add asf4 as a submodule. 2019-07-01 17:18:44 +10:00
axtls@43a6e6bd3b axtls: Update, exposes AES functions to implement ECB chiper mode. 2017-11-05 11:37:05 +02:00
berkeley-db-1.xx@35aaec4418 berkeley-db-1.xx: Update, allow to override MINCACHE, DEFPSIZE. 2017-09-10 13:51:51 +03:00
btstack@c8b9823f68 lib/btstack: Update to c8b9823 for USB HCI reset timeout fix. 2020-04-29 16:54:12 +10:00
cmsis/inc lib/cmsis: Upgrade to CMSIS 5.5.1. 2019-06-03 14:40:57 +10:00
embed py/stream: Remove mp_stream_errno and use system errno instead. 2020-04-27 23:58:46 +10:00
libc lib/libc: Fix string0's implementation of strncpy. 2020-07-22 16:29:54 +10:00
libffi@e9de7e35f2 lib/libffi: Add libffi as a submodule. 2015-10-17 15:52:35 +03:00
libm lib/libm: Reduce size of static two_over_pi array. 2020-09-04 00:45:56 +10:00
libm_dbl lib/libm_dbl: Add round.c source code. 2020-07-21 11:07:19 +10:00
littlefs lib/littlefs: Update littlefs2 to v2.2.0. 2020-04-09 15:59:28 +10:00
lwip@159e31b689 lib/lwip: Update lwIP to v2.1.2, tag STABLE-2_1_2_RELEASE. 2019-07-04 10:36:23 +10:00
mbedtls@3f8d78411a lib: Add new submodule for mbedtls, currently at v2.17.0. 2019-06-05 15:21:40 +10:00
mbedtls_errors lib/mbedtls_errors: Add code to patch mbedtls for shortened error strs. 2020-07-20 23:53:27 +10:00
memzip lib/memzip: Make lexer constructor raise exception when file not found. 2017-03-14 11:52:05 +11:00
mp-readline lib/mp-readline: Add word-based move/delete EMACS key sequences. 2020-01-12 13:09:27 +11:00
mynewt-nimble@97ce3eacaa lib/mynewt-nimble: Update submodule to NimBLE release 1.3.0. 2020-04-27 22:50:42 +10:00
netutils all: Use MP_ERROR_TEXT for all error messages. 2020-04-05 15:02:06 +10:00
nrfx@7a4c9d946c lib/nrfx: Upgrade to nrfx v2.0.0. 2020-05-15 15:06:02 +10:00
nxp_driver@b618cb1d52 mimxrt: Add new, minimal port to NXP i.MX RT series CPUs. 2020-03-11 15:34:13 +11:00
oofatfs lib/oofatfs: Update oofatfs library to fix issue with logic not. 2019-03-07 15:03:09 +11:00
stm32lib@58fee7c92b lib/stm32lib: Update library for H7 v1.6.0 and WB v1.6.0. 2020-07-21 01:02:58 +10:00
timeutils all: Rename absolute time-based functions to include "epoch". 2020-09-18 17:20:34 +10:00
tinytest Revert "lib/tinytest: Clean up test reporting in the presence of std..." 2019-12-19 17:53:46 +11:00
tinyusb@a6b916ba85 lib/tinyusb: Update to a6b916ba for i.MX support. 2020-03-11 15:32:55 +11:00
upytesthelper py: Add global default_emit_opt variable to make emit kind persistent. 2019-08-28 12:47:58 +10:00
utils lib/utils/pyexec: Add stdin-reader on raw REPL with flow control. 2020-11-30 11:37:44 +11:00
README.md lib: Add basic README. 2014-09-18 00:13:03 +01:00

README.md

This directory contains standard, low-level C libraries with emphasis on being independent and efficient. They can be used by any port.