Updated the interpreters.md with the how to add a new bytecode specia…

…lization steps
python · faizanoor3001 · Mar 4, 2025 · Mar 4, 2025 · Mar 4, 2025 · Mar 4, 2025
commit 3bf2baf0790ce1dd86f59b196e51a7be2e600647
diff --git a/InternalDocs/interpreter.md b/InternalDocs/interpreter.md
@@ -505,6 +505,62 @@ After the last `DEOPT_IF` has passed, a hit should be recorded with
 `STAT_INC(BASE_INSTRUCTION, hit)`.
 After an optimization has been deferred in the adaptive instruction,
 that should be recorded with `STAT_INC(BASE_INSTRUCTION, deferred)`.
+## How to add a new bytecode specialization
-## How to add a new bytecode specialization
+
+## How to add a new bytecode specialization
-## How to add a new bytecode specialization
+
+## How to add a new bytecode specialization
+
+Assuming you found an instruction that serves as a good specialization candidate. 
+Let's use the example of [`CONTAINS_OP`](../Doc/library/dis.rst#contains_op):
-Assuming you found an instruction that serves as a good specialization candidate. 
-Let's use the example of [`CONTAINS_OP`](../Doc/library/dis.rst#contains_op):
+Let's say you found an instruction that serves as a good specialization candidate, such as [`CONTAINS_OP`](../Doc/library/dis.rst#contains_op):
-Assuming you found an instruction that serves as a good specialization candidate. 
-Let's use the example of [`CONTAINS_OP`](../Doc/library/dis.rst#contains_op):
+Let's say you found an instruction that serves as a good specialization candidate, such as [`CONTAINS_OP`](../Doc/library/dis.rst#contains_op):
+
+1. Update below in [Python/bytecodes.c](../Python/bytecodes.c)
-1. Update below in [Python/bytecodes.c](../Python/bytecodes.c)
+1. Make necessary changes to the instruction in [Python/bytecodes.c](../Python/bytecodes.c)
-1. Update below in [Python/bytecodes.c](../Python/bytecodes.c)
+1. Make necessary changes to the instruction in [Python/bytecodes.c](../Python/bytecodes.c)
+
+- Convert `CONTAINS_OP` to a micro-operation (uop) by renaming
+     it to `_CONTAINS_OP` and changing the instruction definition
+     from `inst` to `op`.
- Convert `CONTAINS_OP` to a micro-operation (uop) by renaming
-     it to `_CONTAINS_OP` and changing the instruction definition
-     from `inst` to `op`.
+- Convert the instruction (`CONTAINS_OP`, in our example) to a micro-operation (uop, formally μop) by renaming it to `_INSTRUCTION_NAME` (e.g., `_CONTAINS_OP`) and changing the instruction definition
+from `inst` to `op`.
- Convert `CONTAINS_OP` to a micro-operation (uop) by renaming
-     it to `_CONTAINS_OP` and changing the instruction definition
-     from `inst` to `op`.
+- Convert the instruction (`CONTAINS_OP`, in our example) to a micro-operation (uop, formally μop) by renaming it to `_INSTRUCTION_NAME` (e.g., `_CONTAINS_OP`) and changing the instruction definition
+from `inst` to `op`.
+
+  ```c
+        // Before
+        inst(CONTAINS_OP, ...);
+
+        // After
+        op(_CONTAINS_OP, ...);
+  ```
+
+- Add a uop that calls the specializing function `_SPECIALIZE_CONTAINS_OP`. 
+  For example.
- Add a uop that calls the specializing function `_SPECIALIZE_CONTAINS_OP`. 
-  For example.
+- Add a uop that calls the specializing function:
- Add a uop that calls the specializing function `_SPECIALIZE_CONTAINS_OP`. 
-  For example.
+- Add a uop that calls the specializing function:
+
+  ```c
+        specializing op(_SPECIALIZE_CONTAINS_OP, (counter/1, left, right -- left, right)) {
+            #if ENABLE_SPECIALIZATION
+            if (ADAPTIVE_COUNTER_IS_ZERO(counter)) {
+                next_instr = this_instr;
+                _Py_Specialize_ContainsOp(right, next_instr);
-                _Py_Specialize_ContainsOp(right, next_instr);
+                _Py_Specialize_ContainsOp(left, right, next_instr);
-                _Py_Specialize_ContainsOp(right, next_instr);
+                _Py_Specialize_ContainsOp(left, right, next_instr);
+                DISPATCH_SAME_OPARG();
+            }
+            STAT_INC(CONTAINS_OP, deferred);
+            DECREMENT_ADAPTIVE_COUNTER(this_instr[1].cache);
+            #endif  /* ENABLE_SPECIALIZATION */
+        }
+  ```
+
+- The original `CONTAINS_OP` is now a new macro consisting of
+      `_SPECIALIZE_CONTAINS_OP` and `_CONTAINS_OP`.
+
+2. Define the cache structure in [Include/internal/pycore_code.h](../Include/internal/pycore_code.h),
+at the very least, a 16-bit counter is needed.
-2. Define the cache structure in [Include/internal/pycore_code.h](../Include/internal/pycore_code.h),
-at the very least, a 16-bit counter is needed.
+2. Define the cache structure in [Include/internal/pycore_code.h](../Include/internal/pycore_code.h). It needs to have at least a 16-bit counter field.
-2. Define the cache structure in [Include/internal/pycore_code.h](../Include/internal/pycore_code.h),
-at the very least, a 16-bit counter is needed.
+2. Define the cache structure in [Include/internal/pycore_code.h](../Include/internal/pycore_code.h). It needs to have at least a 16-bit counter field.
+
+    ```c
+        typedef struct {
+            uint16_t counter;
+        } _PyContainsOpCache;
+    ```      
+
+3. Write the specializing function itself in [Python/specialize.c ](../Python/specialize.c). 
+   Refer to any other function in that file for the format.
+4. Remember to update operation stats by calling add_stat_dict in 
-4. Remember to update operation stats by calling add_stat_dict in 
+4. Remember to update operation stats by calling `add_stat_dict` in 
-4. Remember to update operation stats by calling add_stat_dict in 
+4. Remember to update operation stats by calling `add_stat_dict` in 
+   [Python/specialize.c ](../Python/specialize.c).
+5. Add the cache layout in [Lib/opcode.py](../Lib/opcode.py) so that Python's 
+   dis module will know how to represent it properly.
+6. Bump magic number in  [Include/core/pycore_magic_number.h](../Include/internal/pycore_magic_number.h).
-6. Bump magic number in  [Include/core/pycore_magic_number.h](../Include/internal/pycore_magic_number.h).
+6. Bump magic number in [Include/core/pycore_magic_number.h](../Include/internal/pycore_magic_number.h).
-6. Bump magic number in  [Include/core/pycore_magic_number.h](../Include/internal/pycore_magic_number.h).
+6. Bump magic number in [Include/core/pycore_magic_number.h](../Include/internal/pycore_magic_number.h).
+7. Run ``make regen-all`` on `*nix` or `build.bat --regen` on Windows.


 Additional resources