devguide
devguide copied to clipboard
Document how to add a bytecode specialization
How to add a new bytecode specialization is knowledge only a few of us remember right now. We should document this somewhere (devguide or CPython, I don't mind). Hopefully a new contributor can pick this up!
There reference is this PR: https://github.com/python/cpython/pull/116385/files
Assuming you found an instruction that serves as a good specialization candidate. Let's use the example of CONTAINS_OP
:
- Set the original
CONTAINS_OP
to a uop by changing it fromCONTAINS_OP
to_CONTAINS_OP
inPython/bytecodes.c
. The instruction definition should also change frominst
toop
. - Add the uop that calls a specializing function. In this case
_SPECIALIZE_CONTAINS_OP
. - The original
CONTAINS_OP
is now a new macro consisting of_SPECIALIZE_CONTAINS_OP + _CONTAINS_OP
. - Define the cache structure in
Include/internal/pycore_code.h
. At the very least, a 16-bit counter is needed. - Write the specializing function itself in
Python/specialize.c
. Refer to any other function in that file for the format. - Remember to update operation stats by calling
add_stat_dict
inPython/specialize.c
. - Add the cache layout in
Lib/opcode.py
so that Python'sdis
module will know how to represent it properly. - Bump magic number in
Include/internal/pycore_magic_number.h
. - Run
make regen-all
on *nix orbuild.bat --regen
on PC.