@micropython.native and @micropython.viper

A viper function on a Pico that multiplies its two int arguments returns 1,410,065,408 for 100,000 × 100,000. Its integers are 32-bit machine words, so the arithmetic wraps modulo 2³², the price viper pays for running integer and buffer code much faster than bytecode.

The native and viper emitters compile a Python function into the processor’s own instructions. Below: what each does, which builds have it, how viper’s words and pointers behave, and how to test viper code on a computer.

Three emitters compile the same function three ways

By default MicroPython compiles a function to bytecode, which its virtual machine runs one instruction at a time. Two decorators choose another emitter for one function, @micropython.native and @micropython.viper, and the compiler reads them itself, so they need no import:

• @micropython.native: the native emitternative emitter: The part of MicroPython's compiler that turns a function decorated with @micropython.native into the processor's own instructions. The code does the same object operations as bytecode, so it behaves the same and runs roughly twice as fast. writes machine code that does the same object operations as the bytecode would. MicroPython’s speed guide puts it at roughly twice as fast as bytecode, with larger code and a few limits: raise needs an argument, and scheduled callbacks do not run while native code runs.
• @micropython.viper: the viper emitterviper emitter: The compiler's second machine-code emitter, used for @micropython.viper functions. It adds types of its own, machine-word integers and pointers into buffers, and runs integer and buffer code much faster than bytecode, at the cost of Python's exact integers. adds types of its own, machine-word integers and pointers into buffers, and optimises further. The guide calls it not fully compliant: it gains most on integer maths and bit operations, takes no default argument values and does not optimise floats.

A native function behaves as before, within those limits, only faster; a viper function may give different integer results, as the next section shows. Each build has the emitter of its own processor or none: x86 and x64, 32-bit ARM including the Thumb code of the RP2040, Xtensa on the ESP32, and since 1.24 RISC-V on chips such as the ESP32-C3. The unix port has no emitter for 64-bit ARM, so on an Apple Silicon Mac or a 64-bit Raspberry Pi system both decorators stop the module at compile time with SyntaxError: invalid micropython decorator. Answer for a hot function of your own:

Viper integers are machine words

A viper int is a machine wordmachine word: The number of bits a processor handles in one step: 32 on the RP2040 and the ESP32, 64 on an x86-64 computer. Viper's integers are machine words, so their arithmetic wraps when a result needs more bits.: 32 bits on rp2 and esp32, 64 bits on an x64 build. The speed guide is explicit: on 32-bit hardware, viper’s arithmetic wraps modulo 2³². This program works out what each build returns for the same operations on a viper function’s int arguments, with the board’s word kept by masking:

"""Viper's integers are machine words: what Python, a 32-bit board and a 64-bit build give for the same operations.

The operands are a viper function's int arguments, so the board computes on them at run time.
Written as literals, an expression such as 100000 * 100000 is worked out by the compiler first.
"""


def word(value, bits):
    """value as a signed machine word of this many bits, the way viper's int keeps it."""
    value &= (1 << bits) - 1
    return value - (1 << bits) if value >> (bits - 1) else value


def uword(value, bits):
    """value as an unsigned machine word: viper's uint, seen by Python on return."""
    return value & ((1 << bits) - 1)


CASES = [
    ("a << b, a = 1, b = 31", 1 << 31, word),
    ("a * b, a = b = 100000", 100000 * 100000, word),
    ("a + 1, a = 2**31 - 1", (1 << 31) - 1 + 1, word),
    ("-1, returned as int", -1, word),
    ("-1, returned as uint", -1, uword),
]
print("%-22s %20s %13s %20s" % ("operation", "Python", "rp2, esp32", "unix x64"))
for text, exact, kind in CASES:
    print("%-22s %20d %13d %20d" % (text, exact, kind(exact, 32), kind(exact, 64)))

operation                            Python    rp2, esp32             unix x64
a << b, a = 1, b = 31            2147483648   -2147483648           2147483648
a * b, a = b = 100000           10000000000    1410065408          10000000000
a + 1, a = 2**31 - 1             2147483648   -2147483648           2147483648
-1, returned as int                      -1            -1                   -1
-1, returned as uint                     -1    4294967295 18446744073709551615

Shifting 1 left by 31 sets the top bit of a 32-bit word, which a signed word reads as −2,147,483,648, and 100,000 × 100,000 keeps only its low 32 bits. The 64-bit build keeps the products and sums exact, which is why code tested on a computer’s unix build can still be wrong on a Pico. Literals would not show it: the compiler works out 100000 * 100000 itself, before the function runs, so the values come in as arguments. The return type decides how the caller sees the word: -1 returned as int stays −1, while a function declared -> uint returns 4,294,967,295 on the board.

Viper’s other types are named for what they point at. ptr8, ptr16 and ptr32 read and write 8, 16 and 32-bit values in a buffer such as a bytearray, by index; ptr points to objects; and the casts int(), uint() and bool() turn a Python object into a native value. No pointer checks its index against the buffer’s length.

Check yourself

Bytecode, native and viper, one question at a time.

Viper's types and pointers, tested on a computer before the board Pro: opens with a Pro, Premium or Ultimate pass

Where viper's machine words bite: constants, comparisons and code size Pro: opens with a Pro, Premium or Ultimate pass

Interview questions

Warm-up (fresher): What is the difference between @micropython.native and @micropython.viper?

Both compile a function to machine code instead of bytecode. Native code does the same object operations as bytecode, so the function behaves as before and runs roughly twice as fast. Viper adds its own types, machine-word integers and pointers into buffers, and runs integer and buffer code much faster, but its integers wrap at the machine word, so it is not fully compatible with Python.

Key takeaways

• @micropython.native keeps Python’s behaviour and runs roughly twice as fast; @micropython.viper adds machine-word types and pointers and runs integer code much faster, at the cost of exact integers.
• Each build has the emitter of its own processor or none, and a build without one refuses the decorators at compile time.
• Viper integers wrap at the machine word, 32 bits on rp2 and esp32, so code that is right on a 64-bit build can be wrong on a Pico.