From 0bfc54dfc8e6e7c79a9262aa21161de141ddbc34 Mon Sep 17 00:00:00 2001 From: Mikhail Efimov Date: Mon, 14 Oct 2024 16:41:20 +0300 Subject: [PATCH 1/3] gh-119786: move bytecode interpreter doc to InternalDocs --- InternalDocs/README.md | 3 +++ .../bytecode_interpreter.md | 17 ++++++++--------- Tools/cases_generator/README.md | 2 +- 3 files changed, 12 insertions(+), 10 deletions(-) rename Tools/cases_generator/interpreter_definition.md => InternalDocs/bytecode_interpreter.md (95%) diff --git a/InternalDocs/README.md b/InternalDocs/README.md index 805e2f97937e1e..6b30a3a1947e69 100644 --- a/InternalDocs/README.md +++ b/InternalDocs/README.md @@ -11,6 +11,7 @@ The core dev team attempts to keep this documentation up to date. If it is not, please report that through the [issue tracker](https://github.com/python/cpython/issues). +List of topics: [Guide to the parser](parser.md) @@ -18,6 +19,8 @@ it is not, please report that through the [Frames](frames.md) +[Bytecode Interpreter](bytecode_interpreter.md) + [Adaptive Instruction Families](adaptive.md) [The Source Code Locations Table](locations.md) diff --git a/Tools/cases_generator/interpreter_definition.md b/InternalDocs/bytecode_interpreter.md similarity index 95% rename from Tools/cases_generator/interpreter_definition.md rename to InternalDocs/bytecode_interpreter.md index ba09931c541646..494d837516c477 100644 --- a/Tools/cases_generator/interpreter_definition.md +++ b/InternalDocs/bytecode_interpreter.md @@ -32,8 +32,7 @@ The presence of these macros and the nature of bytecode interpreters means that the interpreter is effectively defined in a domain specific language (DSL). Rather than using an ad-hoc DSL embedded in the C code for the interpreter, -a custom DSL should be defined and the semantics of the bytecode instructions, -and the instructions defined in that DSL. +a custom DSL is defined. This DSL defines the semantics of the bytecode instructions. Generating the interpreter decouples low-level details of dispatching and error handling from the semantics of the instructions, resulting @@ -53,11 +52,10 @@ to be written. One way to mitigate this is through the use of code generators. Code generators decouple the debugging of the code (the generator) from checking the correctness (the DSL input). -For example, we are likely to want a new interpreter for the tier 2 optimizer -to be added in 3.12. That interpreter will have a different API, a different -set of instructions and potentially different dispatching mechanism. -But the instructions it will interpret will be built from the same building -blocks as the instructions for the tier 1 (PEP 659) interpreter. +New interpreter for the tier 2 optimizer is added in CPython 3.13. +That interpreter have a different API, a different set of instructions and +different dispatching mechanism. But the instructions it interpret are built +from the same building blocks as the instructions for the tier 1 (PEP 659) interpreter. Rewriting all the instructions is tedious and error-prone, and changing the instructions is a maintenance headache as both versions need to be kept in sync. @@ -74,7 +72,7 @@ We update it as the need arises. ### Syntax Each op definition has a kind, a name, a stack and instruction stream effect, -and a piece of C code describing its semantics:: +and a piece of C code describing its semantics: ``` file: @@ -245,7 +243,8 @@ The same is true for all members of a pseudo instruction ## Examples -(Another source of examples can be found in the [tests](test_generator.py).) +(Another source of examples can be found in the +[tests](https://github.com/python/cpython/blob/main/Lib/test/test_generated_cases.py).) Some examples: diff --git a/Tools/cases_generator/README.md b/Tools/cases_generator/README.md index fb512c4646b851..8c37f67a096dca 100644 --- a/Tools/cases_generator/README.md +++ b/Tools/cases_generator/README.md @@ -1,7 +1,7 @@ # Tooling to generate interpreters Documentation for the instruction definitions in `Python/bytecodes.c` -("the DSL") is [here](interpreter_definition.md). +("the DSL") is [here](https://github.com/python/cpython/blob/main/InternalDocs/bytecode_interpreter.md). What's currently here: From 748b53cbca06b58c138f56895fdee055283958f9 Mon Sep 17 00:00:00 2001 From: Mikhail Efimov Date: Mon, 14 Oct 2024 20:05:46 +0300 Subject: [PATCH 2/3] File interpreter_definition.md moved back --- InternalDocs/README.md | 2 -- Tools/cases_generator/README.md | 2 +- .../cases_generator/interpreter_definition.md | 12 +++++++----- 3 files changed, 8 insertions(+), 8 deletions(-) rename InternalDocs/bytecode_interpreter.md => Tools/cases_generator/interpreter_definition.md (96%) diff --git a/InternalDocs/README.md b/InternalDocs/README.md index 6b30a3a1947e69..ecca37a17b7c04 100644 --- a/InternalDocs/README.md +++ b/InternalDocs/README.md @@ -19,8 +19,6 @@ List of topics: [Frames](frames.md) -[Bytecode Interpreter](bytecode_interpreter.md) - [Adaptive Instruction Families](adaptive.md) [The Source Code Locations Table](locations.md) diff --git a/Tools/cases_generator/README.md b/Tools/cases_generator/README.md index 8c37f67a096dca..fb512c4646b851 100644 --- a/Tools/cases_generator/README.md +++ b/Tools/cases_generator/README.md @@ -1,7 +1,7 @@ # Tooling to generate interpreters Documentation for the instruction definitions in `Python/bytecodes.c` -("the DSL") is [here](https://github.com/python/cpython/blob/main/InternalDocs/bytecode_interpreter.md). +("the DSL") is [here](interpreter_definition.md). What's currently here: diff --git a/InternalDocs/bytecode_interpreter.md b/Tools/cases_generator/interpreter_definition.md similarity index 96% rename from InternalDocs/bytecode_interpreter.md rename to Tools/cases_generator/interpreter_definition.md index 494d837516c477..6cf36f343d5fa7 100644 --- a/InternalDocs/bytecode_interpreter.md +++ b/Tools/cases_generator/interpreter_definition.md @@ -32,7 +32,8 @@ The presence of these macros and the nature of bytecode interpreters means that the interpreter is effectively defined in a domain specific language (DSL). Rather than using an ad-hoc DSL embedded in the C code for the interpreter, -a custom DSL is defined. This DSL defines the semantics of the bytecode instructions. +a custom DSL should be defined and the semantics of the bytecode instructions, +and the instructions defined in that DSL. Generating the interpreter decouples low-level details of dispatching and error handling from the semantics of the instructions, resulting @@ -52,10 +53,11 @@ to be written. One way to mitigate this is through the use of code generators. Code generators decouple the debugging of the code (the generator) from checking the correctness (the DSL input). -New interpreter for the tier 2 optimizer is added in CPython 3.13. -That interpreter have a different API, a different set of instructions and -different dispatching mechanism. But the instructions it interpret are built -from the same building blocks as the instructions for the tier 1 (PEP 659) interpreter. +For example, we are likely to want a new interpreter for the tier 2 optimizer +to be added in 3.12. That interpreter will have a different API, a different +set of instructions and potentially different dispatching mechanism. +But the instructions it will interpret will be built from the same building +blocks as the instructions for the tier 1 (PEP 659) interpreter. Rewriting all the instructions is tedious and error-prone, and changing the instructions is a maintenance headache as both versions need to be kept in sync. From 83c7b9557b803cc3d14ce7793116a38e2088bb65 Mon Sep 17 00:00:00 2001 From: Irit Katriel <1055913+iritkatriel@users.noreply.github.com> Date: Mon, 14 Oct 2024 18:15:46 +0100 Subject: [PATCH 3/3] Update InternalDocs/README.md --- InternalDocs/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/InternalDocs/README.md b/InternalDocs/README.md index ecca37a17b7c04..0a6ecf899458ed 100644 --- a/InternalDocs/README.md +++ b/InternalDocs/README.md @@ -11,7 +11,8 @@ The core dev team attempts to keep this documentation up to date. If it is not, please report that through the [issue tracker](https://github.com/python/cpython/issues). -List of topics: +Index: +----- [Guide to the parser](parser.md)