Skip to content

Commit cf7d962

Browse files
dpgeorgedpgeorge
committed
docs/reference/mpyfiles: Update .mpy description to match latest format.
Signed-off-by: Damien George <damien@micropython.org>
1 parent 1f1afae commit cf7d962

1 file changed

Lines changed: 45 additions & 17 deletions

File tree

‎docs/reference/mpyfiles.rst‎

Lines changed: 45 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,8 @@ and .mpy version.
8080
=================== ============
8181
MicroPython release .mpy version
8282
=================== ============
83-
v1.12 and up 5
83+
v1.19 and up 6
84+
v1.12 - v1.18 5
8485
v1.11 4
8586
v1.9.3 - v1.10 3
8687
v1.9 - v1.9.2 2
@@ -93,6 +94,7 @@ MicroPython repository at which the .mpy version was changed.
9394
=================== ========================================
9495
.mpy version change Git commit
9596
=================== ========================================
97+
5 to 6 f2040bfc7ee033e48acef9f289790f3b4e6b74e5
9698
4 to 5 5716c5cf65e9b2cb46c2906f40302401bdd27517
9799
3 to 4 9a5f92ea72754c01cc03e5efcdfe94021120531e
98100
2 to 3 ff93fd4f50321c6190e1659b19e64fef3045a484
@@ -104,21 +106,31 @@ initial version 0 d8c834c95d506db979ec871417de90b7951edc30
104106
Binary encoding of .mpy files
105107
-----------------------------
106108

107-
MicroPython .mpy files are a binary container format with code objects
108-
stored internally in a nested hierarchy. To keep files small while still
109+
MicroPython .mpy files are a binary container format with code objects (bytecode
110+
and native machine code) stored internally in a nested hierarchy. The code for
111+
the outer module is stored first, and then its children follow. Each child may
112+
have further children, for example in the case of a class having methods, or a
113+
function defining a lambda or comprehension. To keep files small while still
109114
providing a large range of possible values it uses the concept of a
110115
variably-encoded-unsigned-integer (vuint) in many places. Similar to utf-8
111116
encoding, this encoding stores 7 bits per byte with the 8th bit (MSB) set
112117
if one or more bytes follow. The bits of the unsigned integer are stored
113118
in the vuint in LSB form.
114119

115-
The top-level of an .mpy file consists of two parts:
120+
The top-level of an .mpy file consists of three parts:
116121

117122
* The header.
118123

124+
* The global qstr and constant tables.
125+
119126
* The raw-code for the outer scope of the module.
120127
This outer scope is executed when the .mpy file is imported.
121128

129+
You can inspect the contents of a .mpy file by using ``mpy-tool.py``, for
130+
example (run from the root of the main MicroPython repository)::
131+
132+
$ ./tools/mpy-tool.py -xd myfile.mpy
133+
122134
The header
123135
~~~~~~~~~~
124136

@@ -131,7 +143,26 @@ byte value 0x4d (ASCII 'M')
131143
byte .mpy version number
132144
byte feature flags
133145
byte number of bits in a small int
134-
vuint size of qstr window
146+
====== ================================
147+
148+
The global qstr and constant tables
149+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
150+
151+
An .mpy file contains a single qstr table, and a single constant object table.
152+
These are global to the .mpy file, they are referenced by all nested raw-code
153+
objects. The qstr table maps internal qstr number (internal to the .mpy file)
154+
to the resolved qstr number of the runtime that the .mpy file is imported into.
155+
This links the .mpy file with the rest of the system that it executes within.
156+
The constant object table is populated with references to all constant objects
157+
that the .mpy file needs.
158+
159+
====== ================================
160+
size field
161+
====== ================================
162+
vuint number of qstrs
163+
vuint number of constant objects
164+
... qstr data
165+
... encoded constant objects
135166
====== ================================
136167

137168
Raw code elements
@@ -143,24 +174,21 @@ contents are:
143174
====== ================================
144175
size field
145176
====== ================================
146-
vuint type and size
177+
vuint type, size and whether there are sub-raw-code elements
147178
... code (bytecode or machine code)
148-
vuint number of constant objects
149-
vuint number of sub-raw-code elements
150-
... constant objects
179+
vuint number of sub-raw-code elements (only if non-zero)
151180
... sub-raw-code elements
152181
====== ================================
153182

154183
The first vuint in a raw-code element encodes the type of code stored in this
155-
element (the two least-significant bits), and the decompressed length of the code
156-
(the amount of RAM to allocate for it).
157-
158-
Following the vuint comes the code itself. In the case of bytecode it also contains
159-
compressed qstr values.
184+
element (the two least-significant bits), whether this raw-code has any
185+
children (the third least-significant bit), and the length of the code that
186+
follows (the amount of RAM to allocate for it).
160187

161-
Following the code comes a vuint counting the number of constant objects, and
162-
another vuint counting the number of sub-raw-code elements.
188+
Following the vuint comes the code itself. Unless the code type is viper code
189+
with relocations, this code is constant data and does not need to be modified.
163190

164-
The constant objects are then stored next.
191+
If this raw-code has any children (as indicated by a bit in the first vuint),
192+
following the code comes a vuint counting the number of sub-raw-code elements.
165193

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

0 commit comments

Comments
 (0)