MicroPython .mpy files

MicroPython defines the concept of an .mpy file which is a binary container file format that holds precompiled code, and which can be imported like a normal .py module. The file foo.mpy can be imported via import foo, as long as foo.mpy can be found in the usual way by the import machinery. Usually, each directory listed in sys.path is searched in order. When searching a particular directory foo.py is looked for first and if that is not found then foo.mpy is looked for, then the search continues in the next directory if neither is found. As such, foo.py will take precedence over foo.mpy.

These .mpy files can contain bytecode which is usually generated from Python source files (.py files) via the mpy-cross program. For some architectures an .mpy file can also contain native machine code, which can be generated in a variety of ways, most notably from C source code.

Versioning and compatibility of .mpy files

A given .mpy file may or may not be compatible with a given MicroPython system. Compatibility is based on the following:

• Version of the .mpy file: the version of the file must match the version supported by the system loading it.
• Bytecode features used in the .mpy file: there are two bytecode features which must match between the file and the system: unicode support and inline caching of map lookups in the bytecode.
• Small integer bits: the .mpy file will require a minimum number of bits in a small integer and the system loading it must support at least this many bits.
• Qstr compression window size: the .mpy file will require a minimum window size for qstr decompression and the system loading it must have a window greater or equal to this size.
• Native architecture: if the .mpy file contains native machine code then it will specify the architecture of that machine code and the system loading it must support execution of that architecture's code.

If a MicroPython system supports importing .mpy files then the sys.implementation.mpy field will exist and return an integer which encodes the version (lower 8 bits), features and native architecture.

Trying to import an .mpy file that fails one of the first four tests will raise ValueError('incompatible .mpy file'). Trying to import an .mpy file that fails the native architecture test (if it contains native machine code) will raise ValueError('incompatible .mpy arch').

If importing an .mpy file fails then try the following:

• Determine the .mpy version and flags supported by your MicroPython system by executing:

  import sys
  sys_mpy = sys.implementation.mpy
  arch = [None, 'x86', 'x64',
   'armv6', 'armv6m', 'armv7m', 'armv7em', 'armv7emsp', 'armv7emdp',
   'xtensa', 'xtensawin'][sys_mpy >> 10]
  print('mpy version:', sys_mpy & 0xff)
  print('mpy flags:', end='')
  if arch:
   print(' -march=' + arch, end='')
  if sys_mpy & 0x100:
   print(' -mcache-lookup-bc', end='')
  if not sys_mpy & 0x200:
   print(' -mno-unicode', end='')
  print()
  

• Check the validity of the .mpy file by inspecting the first two bytes of the file. The first byte should be an uppercase 'M' and the second byte will be the version number, which should match the system version from above. If it doesn't match then rebuild the .mpy file.

• Check if the system .mpy version matches the version emitted by mpy-cross that was used to build the .mpy file, found by mpy-cross --version. If it doesn't match then recompile mpy-cross from the Git repository checked out at the tag (or hash) reported by mpy-cross --version.

• Make sure you are using the correct mpy-cross flags, found by the code above, or by inspecting the MPY_CROSS_FLAGS Makefile variable for the port that you are using.

The following table shows the correspondence between MicroPython release and .mpy version.

For completeness, the next table shows the Git commit of the main MicroPython repository at which the .mpy version was changed.

Binary encoding of .mpy files

MicroPython .mpy files are a binary container format with code objects stored internally in a nested hierarchy. To keep files small while still providing a large range of possible values it uses the concept of a variably-encoded-unsigned-integer (vuint) in many places. Similar to utf-8 encoding, this encoding stores 7 bits per byte with the 8th bit (MSB) set if one or more bytes follow. The bits of the unsigned integer are stored in the vuint in LSB form.

The top-level of an .mpy file consists of two parts:

• The header.
• The raw-code for the outer scope of the module. This outer scope is executed when the .mpy file is imported.

The header

The .mpy header is:

Raw code elements

A raw-code element contains code, either bytecode or native machine code. Its contents are:

The first vuint in a raw-code element encodes the type of code stored in this element (the two least-significant bits), and the decompressed length of the code (the amount of RAM to allocate for it).

Following the vuint comes the code itself. In the case of bytecode it also contains compressed qstr values.

Following the code comes a vuint counting the number of constant objects, and another vuint counting the number of sub-raw-code elements.

The constant objects are then stored next.

Finally any sub-raw-code elements are stored, recursively.

此处可能存在不合适展示的内容,页面不予展示。您可通过相关编辑功能自查并修改。

如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容,可点击提交进行申诉,我们将尽快为您处理。