Commit Graph

79 Commits

Author SHA1 Message Date
Damien George d6564a3159 tools/mpremote: Add "umount" command.
Signed-off-by: Damien George <damien@micropython.org>
2022-02-25 13:10:45 +11:00
Damien George ad1f523e7e tools/mpremote: Add "resume" and "soft-reset" commands.
This makes the auto soft-reset behaviour of mpremote more logical, and now
configurable via these new commands.

Signed-off-by: Damien George <damien@micropython.org>
2022-02-25 13:09:28 +11:00
Peter Hinch 80b81acea5 docs/reference/isr_rules.rst: Describe uasyncio-IRQ interface. 2022-02-04 12:27:16 +11:00
Luiz Brandao ddda959e57 docs/reference/isr_rules.rst: Fix inconsistent variable name in example.
Fixed to be conistent with the code example above it.
2022-02-04 11:20:15 +11:00
Damien George d9d67adef1 docs: Remove trailing spaces and convert tabs to spaces.
Signed-off-by: Damien George <damien@micropython.org>
2021-12-15 11:49:22 +11:00
Damien George 01f1c3aac2 docs/reference/filesystem.rst: Add detail on how to use littlefs fuse.
Without the --block_count option the fuse will fail.

Signed-off-by: Damien George <damien@micropython.org>
2021-11-19 15:13:05 +11:00
NitiKaur e87b2e8bfa docs/reference/manifest.rst: Add docs for manifest.py files. 2021-10-14 14:03:03 +11:00
NitiKaur 135339ce3a docs/reference/mpremote.rst: Add docs for mpremote. 2021-10-14 13:09:51 +11:00
Jim Mussared b326edf68c all: Remove MICROPY_OPT_CACHE_MAP_LOOKUP_IN_BYTECODE.
This commit removes all parts of code associated with the existing
MICROPY_OPT_CACHE_MAP_LOOKUP_IN_BYTECODE optimisation option, including the
-mcache-lookup-bc option to mpy-cross.

This feature originally provided a significant performance boost for Unix,
but wasn't able to be enabled for MCU targets (due to frozen bytecode), and
added significant extra complexity to generating and distributing .mpy
files.

The equivalent performance gain is now provided by the combination of
MICROPY_OPT_LOAD_ATTR_FAST_PATH and MICROPY_OPT_MAP_LOOKUP_CACHE (which has
been enabled on the unix port in the previous commit).

It's hard to provide precise performance numbers, but tests have been run
on a wide variety of architectures (x86-64, ARM Cortex, Aarch64, RISC-V,
xtensa) and they all generally agree on the qualitative improvements seen
by the combination of MICROPY_OPT_LOAD_ATTR_FAST_PATH and
MICROPY_OPT_MAP_LOOKUP_CACHE.

For example, on a "quiet" Linux x64 environment (i3-5010U @ 2.10GHz) the
change from CACHE_MAP_LOOKUP_IN_BYTECODE, to LOAD_ATTR_FAST_PATH combined
with MAP_LOOKUP_CACHE is:

diff of scores (higher is better)
N=2000 M=2000       bccache -> attrmapcache      diff      diff% (error%)
bm_chaos.py        13742.56 ->   13905.67 :   +163.11 =  +1.187% (+/-3.75%)
bm_fannkuch.py        60.13 ->      61.34 :     +1.21 =  +2.012% (+/-2.11%)
bm_fft.py         113083.20 ->  114793.68 :  +1710.48 =  +1.513% (+/-1.57%)
bm_float.py       256552.80 ->  243908.29 : -12644.51 =  -4.929% (+/-1.90%)
bm_hexiom.py         521.93 ->     625.41 :   +103.48 = +19.826% (+/-0.40%)
bm_nqueens.py     197544.25 ->  217713.12 : +20168.87 = +10.210% (+/-3.01%)
bm_pidigits.py      8072.98 ->    8198.75 :   +125.77 =  +1.558% (+/-3.22%)
misc_aes.py        17283.45 ->   16480.52 :   -802.93 =  -4.646% (+/-0.82%)
misc_mandel.py     99083.99 ->  128939.84 : +29855.85 = +30.132% (+/-5.88%)
misc_pystone.py    83860.10 ->   82592.56 :  -1267.54 =  -1.511% (+/-2.27%)
misc_raytrace.py   21490.40 ->   22227.23 :   +736.83 =  +3.429% (+/-1.88%)

This shows that the new optimisations are at least as good as the existing
inline-bytecode-caching, and are sometimes much better (because the new
ones apply caching to a wider variety of map lookups).

The new optimisations can also benefit code generated by the native
emitter, because they apply to the runtime rather than the generated code.
The improvement for the native emitter when LOAD_ATTR_FAST_PATH and
MAP_LOOKUP_CACHE are enabled is (same Linux environment as above):

diff of scores (higher is better)
N=2000 M=2000        native -> nat-attrmapcache  diff      diff% (error%)
bm_chaos.py        14130.62 ->   15464.68 :  +1334.06 =  +9.441% (+/-7.11%)
bm_fannkuch.py        74.96 ->      76.16 :     +1.20 =  +1.601% (+/-1.80%)
bm_fft.py         166682.99 ->  168221.86 :  +1538.87 =  +0.923% (+/-4.20%)
bm_float.py       233415.23 ->  265524.90 : +32109.67 = +13.756% (+/-2.57%)
bm_hexiom.py         628.59 ->     734.17 :   +105.58 = +16.796% (+/-1.39%)
bm_nqueens.py     225418.44 ->  232926.45 :  +7508.01 =  +3.331% (+/-3.10%)
bm_pidigits.py      6322.00 ->    6379.52 :    +57.52 =  +0.910% (+/-5.62%)
misc_aes.py        20670.10 ->   27223.18 :  +6553.08 = +31.703% (+/-1.56%)
misc_mandel.py    138221.11 ->  152014.01 : +13792.90 =  +9.979% (+/-2.46%)
misc_pystone.py    85032.14 ->  105681.44 : +20649.30 = +24.284% (+/-2.25%)
misc_raytrace.py   19800.01 ->   23350.73 :  +3550.72 = +17.933% (+/-2.79%)

In summary, compared to MICROPY_OPT_CACHE_MAP_LOOKUP_IN_BYTECODE, the new
MICROPY_OPT_LOAD_ATTR_FAST_PATH and MICROPY_OPT_MAP_LOOKUP_CACHE options:
- are simpler;
- take less code size;
- are faster (generally);
- work with code generated by the native emitter;
- can be used on embedded targets with a small and constant RAM overhead;
- allow the same .mpy bytecode to run on all targets.

See #7680 for further discussion.  And see also #7653 for a discussion
about simplifying mpy-cross options.

Signed-off-by: Jim Mussared <jim.mussared@gmail.com>
2021-09-16 16:04:03 +10:00
Peter Hinch 3720a570f2 docs/reference: Mention that slicing a memoryview causes allocation. 2021-08-30 23:55:29 +10:00
Jim Mussared d7fbc755dc docs/library/index.rst: Clarify module naming and purpose.
Adds section about extending built-in modules from Python.

Signed-off-by: Jim Mussared <jim.mussared@gmail.com>
2021-08-13 23:14:08 +10:00
Jim Mussared c737cde947 docs: Replace ufoo with foo in all docs.
Anywhere a module is mentioned, use its "non-u" name for consistency.

The "import module" vs "import umodule" is something of a FAQ, and this
commit intends to help clear that up.  As a first approximation MicroPython
is Python, and so imports should work the same as Python and use the same
name, to a first approximation.  The u-version of a module is a detail that
can be learned later on, when the user wants to understand more and have
finer control over importing.

Existing Python code should just work, as much as it is possible to do that
within the constraints of embedded systems, and the MicroPython
documentation should match the idiomatic way to write Python code.

With universal weak links for modules (via MICROPY_MODULE_WEAK_LINKS) users
can consistently use "import foo" across all ports (with the exception of
the minimal ports).  And the ability to override/extend via "foo.py"
continues to work well.

Signed-off-by: Jim Mussared <jim.mussared@gmail.com>
2021-08-13 22:53:29 +10:00
Brianna Laugher d128999938 tools: Add filesystem action examples to pyboard.py help.
Signed-off-by: Brianna Laugher <brianna.laugher@gmail.com>
2021-02-13 14:37:28 +11:00
Damien George a14ca31e85 docs/reference/repl.rst: Add information about new raw-paste mode.
Signed-off-by: Damien George <damien@micropython.org>
2020-12-01 22:35:13 +11:00
Kevin Thomas 6eebdbc495 docs/reference/glossary.rst: Fix minor grammar error, An -> A. 2020-10-22 15:40:11 +11:00
David Lechner ee7568ca8d docs/reference/packages.rst: Fix typo, remove duplicate "port".
Fixes #6485.
2020-09-30 23:32:24 +10:00
David Lechner 1e6d18c915 docs: Fix Sphinx 3.x warnings, and enable warnings-as-errors on build.
This enables warnings as errors and fixes all current errors, namely:

- reference to terms in the glossary must now be explicit (:term:)
- method overloads must not be declared as a separate method or must
  use :noindex:
- 2 cases where `` should have been used instead of `
2020-06-05 21:42:17 +10:00
Andrew Leech e54626f4c1 docs/reference: Add note about multiple exceptions when heap is locked. 2020-06-02 15:56:34 +10:00
Damien George e0905e85a7 esp8266: Change from FAT to littlefs v2 as default filesystem.
This commit changes the esp8266 boards to use littlefs v2 as the
filesystem, rather than FAT.  Since the esp8266 doesn't expose the
filesystem to the PC over USB there's no strong reason to keep it as FAT.
Littlefs is smaller in code size, is more efficient in use of flash to
store data, is resilient over power failure, and using it saves about 4k of
heap RAM, which can now be used for other things.

This is a backwards incompatible change because all existing esp8266 boards
will need to update their filesystem after installing new firmware (eg
backup old files, install firmware, restore files to new filesystem).

As part of this commit the memory layout of the default board (GENERIC) has
changed.  It now allocates all 1M of memory-mapped flash to the firmware,
so the filesystem area starts at the 2M point.  This is done to allow more
frozen bytecode to be stored in the 1M of memory-mapped flash.  This
requires an esp8266 module with 2M or more of flash to work, so a new board
called GENERIC_1M is added which has the old memory-mapping (but still
changed to use littlefs for the filesystem).

In summary there are now 3 esp8266 board definitions:
- GENERIC_512K: for 512k modules, doesn't have a filesystem.
- GENERIC_1M: for 1M modules, 572k for firmware+frozen code, 396k for
  filesystem (littlefs).
- GENERIC: for 2M (or greater) modules, 968k for firmware+frozen code,
  1M+ for filesystem (littlefs), FAT driver also included in firmware for
  use on, eg, external SD cards.
2020-04-04 16:30:36 +11:00
Lars Kellogg-Stedman 3a0f64fc7a tools/pyboard.py: Add -d as an alias for --device. 2020-03-30 11:37:32 +11:00
Lars Kellogg-Stedman 1cf994c48b tools/pyboard.py: Support setting device/baudrate from shell env vars.
Allow defaults for --device and --baudrate to be set in the environment
using PYBOARD_DEVICE and PYBOARD_BAUDRATE.
2020-03-30 11:37:32 +11:00
Jason Neal aec88ddf03 docs: More consistent capitalization and use of articles in headings.
See issue #3188.
2020-01-06 22:17:29 +11:00
Damien George e58c7ce3d6 docs/reference: Add documentation describing use of .mpy files.
Including information about .mpy versioning and how to debug failed imports
of .mpy files.
2019-12-19 17:06:27 +11:00
Damien George b310930dba docs/library/uos: Add notes and links about littlefs failures. 2019-12-10 16:58:53 +11:00
Damien George 381be9a745 docs/reference/filesystem: Add note and example about using filesystem. 2019-12-09 14:21:22 +11:00
Daniel Mizyrycki 50dc5f10a6 docs/reference/filesystem: Fix typo in block device code example. 2019-12-09 14:13:09 +11:00
Jim Mussared 9a849cc7ca docs: Add littlefs docs and a filesystem tutorial. 2019-12-04 23:18:23 +11:00
Jim Mussared d7dbd267e7 docs/reference: Add docs describing use of pyboard.py. 2019-12-04 23:18:03 +11:00
Damien George 90c524c114 docs: Remove spaces on lines that are empty. 2019-12-04 15:02:54 +11:00
Mike Causer a2c4cb484d docs: Fix spelling in various parts of the docs. 2019-10-16 14:08:28 +11:00
Jim Mussared a93495b66d docs/reference/glossary.rst: Add new terms and reduce complexity of old. 2019-10-15 16:36:02 +11:00
Paul m. p. P afc8596c15 docs/reference/speed_python: Add missing self to var caching example. 2019-08-28 12:55:41 +10:00
Peter Hinch 3a679eaf00 docs/reference/speed_python: Update that read-only buffers are accepted.
As allowed by recent cd35dd9d9a
2019-08-19 16:39:30 +10:00
Andrew Leech 89ff506513 py: Update and rework build system for including external C modules.
How to use this feature is documented in docs/develop/cmodules.rst.
2019-03-08 22:58:42 +11:00
Ayke van Laethem 2e516074da py: Implement a module system for external, user C modules.
This system makes it a lot easier to include external libraries as static,
native modules in MicroPython.  Simply pass USER_C_MODULES (like
FROZEN_MPY_DIR) as a make parameter.
2019-03-08 22:49:00 +11:00
Mike Causer 812969d615 all: Change PYB message prefix to MPY.
Replaces "PYB: soft reboot" with "MPY: soft reboot", etc.

Having a consistent prefix across ports reduces the difference between
ports, which is a general goal.  And this change won't break pyboard.py
because that tool only looks for "soft reboot".
2019-02-12 15:18:33 +11:00
Damien George 0ab8428995 docs/reference/index: Remove conditional for inline asm docs.
The heading of this section makes it clear it is for Thumb-2 architectures
only.
2018-07-20 15:51:06 +10:00
Damien George 0db49c37a4 docs: Fix some references and RST markup to eliminate Sphinx warnings. 2018-03-15 15:50:51 +11:00
Damien George 9cef2b03a7 docs/reference/repl.rst: Fix some minor errors in the REPL tutorial. 2018-03-09 16:14:58 +11:00
Paul Sokolovsky e37ccfe59b docs/packages: Explicitly recommend usage of setuptools instead of distutils. 2017-12-16 10:42:30 +02:00
Paul Sokolovsky 9251f1395e docs/packages: Use "install_dir/" in examples. 2017-12-16 10:37:36 +02:00
Paul Sokolovsky 448d93a04a docs/glossary: micropython-lib: Clarify wording. 2017-12-15 00:11:02 +02:00
Paul Sokolovsky bf73ee114f docs/packages: mpy_bin2res no longer required to create resources.
Everything happens automagically with overridden "sdist" from
sdist_upip.py.
2017-12-14 18:28:10 +02:00
Paul Sokolovsky 54cd6e3e4b docs/packages: Add quick "Creating distribution packages" section.
Needs more details.
2017-12-13 00:12:37 +02:00
Paul Sokolovsky c60fc670ea docs/reference/packages: Add chapter on distribution packages and deployment.
A long overdue overview of preparing packages, installing them with upip,
freezing, dealing with resources. Initial version, more iterations required.
2017-12-11 00:08:41 +02:00
Paul Sokolovsky ca8034d6b8 docs/glossary: Clarify wording for "baremetal". 2017-12-06 00:08:24 +02:00
Paul Sokolovsky 155ec21e49 docs/glossary: Describe string interning. 2017-12-04 01:01:03 +02:00
Paul Sokolovsky 8175f1608e docs/glossary: Describe "stream" term. 2017-12-03 18:56:18 +02:00
Paul Sokolovsky 4fee35a32c docs/glossary: Describe the callee-owned tuple concept. 2017-12-03 15:08:39 +02:00
Peter Hinch ec1e9a10a7 docs: Add notes on heap allocation caused by bound method refs. 2017-11-23 11:35:58 +11:00