diff --git a/backends/apple/mps/setup.md b/backends/apple/mps/setup.md index 697d93ea65..7cd4c240a4 100644 --- a/backends/apple/mps/setup.md +++ b/backends/apple/mps/setup.md @@ -116,7 +116,7 @@ python3 -m examples.apple.mps.scripts.mps_example --model_name="mv3" --no-use_fp cd executorch python3 -m examples.apple.mps.scripts.mps_example --model_name="mv3" --generate_etrecord -b ``` -2. Run your Program on the ExecuTorch runtime and generate an [ETDump](./sdk-etdump.md). +2. Run your Program on the ExecuTorch runtime and generate an [ETDump](./etdump.md). ``` ./cmake-out/examples/apple/mps/mps_executor_runner --model_path mv3_mps_bundled_fp16.pte --bundled_program --dump-outputs ``` diff --git a/docs/source/build-run-coreml.md b/docs/source/build-run-coreml.md index 6e0cc802df..51b64f8ea9 100644 --- a/docs/source/build-run-coreml.md +++ b/docs/source/build-run-coreml.md @@ -100,7 +100,7 @@ python3 -m examples.apple.coreml.scripts.export --model_name mv3 --generate_etre # Builds `coreml_executor_runner`. ./examples/apple/coreml/scripts/build_executor_runner.sh ``` -3. Run and generate an [ETDump](./sdk-etdump.md). +3. Run and generate an [ETDump](./etdump.md). ```bash cd executorch @@ -108,7 +108,7 @@ cd executorch ./coreml_executor_runner --model_path mv3_coreml_all.pte --profile_model --etdump_path etdump.etdp ``` -4. Create an instance of the [Inspector API](./sdk-inspector.rst) by passing in the [ETDump](./sdk-etdump.md) you have sourced from the runtime along with the optionally generated [ETRecord](./etrecord.rst) from step 1 or execute the following command in your terminal to display the profiling data table. +4. Create an instance of the [Inspector API](./sdk-inspector.rst) by passing in the [ETDump](./etdump.md) you have sourced from the runtime along with the optionally generated [ETRecord](./etrecord.rst) from step 1 or execute the following command in your terminal to display the profiling data table. ```bash python examples/apple/coreml/scripts/inspector_cli.py --etdump_path etdump.etdp --etrecord_path mv3_coreml.bin ``` diff --git a/docs/source/devtools-overview.md b/docs/source/devtools-overview.md index e18b7f16c6..222040a0f4 100644 --- a/docs/source/devtools-overview.md +++ b/docs/source/devtools-overview.md @@ -36,7 +36,7 @@ ETDump (ExecuTorch Dump) is the binary blob that is generated by the runtime aft If you only care about looking at the raw performance data without linking back to source code and other extensive features, an ETDump alone will be enough to leverage the basic features of the Developer Tools. For the full experience, it is recommended that the users also generate an ETRecord. ``` -More details are available in the [ETDump documentation](sdk-etdump.md) on how to generate and store an ETDump from the runtime. +More details are available in the [ETDump documentation](etdump.md) on how to generate and store an ETDump from the runtime. ### Inspector APIs diff --git a/docs/source/etdump.md b/docs/source/etdump.md new file mode 100644 index 0000000000..c58efb40de --- /dev/null +++ b/docs/source/etdump.md @@ -0,0 +1,44 @@ +# Prerequisite | ETDump - ExecuTorch Dump + +ETDump (ExecuTorch Dump) is one of the core components of the ExecuTorch Developer Tools. It is the mechanism through which all forms of profiling and debugging data is extracted from the runtime. Users can't parse ETDump directly; instead, they should pass it into the Inspector API, which deserializes the data, offering interfaces for flexible analysis and debugging. + + +## Generating an ETDump + +Generating an ETDump is a relatively straightforward process. Users can follow the steps detailed below to integrate it into their application that uses ExecuTorch. + +1. ***Include*** the ETDump header in your code. +```C++ +#include +``` + +2. ***Create*** an Instance of the ETDumpGen class and pass it into the `load_method` call that is invoked in the runtime. + +```C++ +torch::executor::ETDumpGen etdump_gen = torch::executor::ETDumpGen(); +Result method = + program->load_method(method_name, &memory_manager, &etdump_gen); +``` + +3. ***Dump Out the ETDump Buffer*** - after the inference iterations have been completed, users can dump out the ETDump buffer. If users are on a device which has a filesystem, they could just write it out to the filesystem. For more constrained embedded devices, users will have to extract the ETDump buffer from the device through a mechanism that best suits them (e.g. UART, JTAG etc.) + +```C++ +etdump_result result = etdump_gen.get_etdump_data(); +if (result.buf != nullptr && result.size > 0) { + // On a device with a file system users can just write it out + // to the file-system. + FILE* f = fopen(FLAGS_etdump_path.c_str(), "w+"); + fwrite((uint8_t*)result.buf, 1, result.size, f); + fclose(f); + free(result.buf); + } +``` + +4. ***Compile*** your binary using CMake with the `ET_EVENT_TRACER_ENABLED` pre-processor flag to enable events to be traced and logged into ETDump inside the ExecuTorch runtime. This flag needs to be added to the ExecuTorch library and any operator library that you are compiling into your binary. For reference, you can take a look at `examples/sdk/CMakeLists.txt`. The lines of interest are: +``` +target_compile_options(executorch INTERFACE -DET_EVENT_TRACER_ENABLED) +target_compile_options(portable_ops_lib INTERFACE -DET_EVENT_TRACER_ENABLED) +``` +## Using an ETDump + +Pass this ETDump into the [Inspector API](./sdk-inspector.rst) to access this data and do post-run analysis. diff --git a/docs/source/extension-module.md b/docs/source/extension-module.md index af269d9bb3..6e2e45bfdc 100644 --- a/docs/source/extension-module.md +++ b/docs/source/extension-module.md @@ -134,7 +134,7 @@ Most of the ExecuTorch APIs, including those described above, return either `Res ### Profile the Module -Use [ExecuTorch Dump](sdk-etdump.md) to trace model execution. Create an instance of the `ETDumpGen` class and pass it to the `Module` constructor. After executing a method, save the `ETDump` to a file for further analysis. You can capture multiple executions in a single trace if desired. +Use [ExecuTorch Dump](etdump.md) to trace model execution. Create an instance of the `ETDumpGen` class and pass it to the `Module` constructor. After executing a method, save the `ETDump` to a file for further analysis. You can capture multiple executions in a single trace if desired. ```cpp #include diff --git a/docs/source/index.rst b/docs/source/index.rst index 9620093804..a96c0db1c2 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -203,7 +203,7 @@ Topics in this section will help you get started with ExecuTorch. devtools-overview bundled-io etrecord - sdk-etdump + etdump sdk-profiling model-debugging sdk-inspector diff --git a/docs/source/llm/getting-started.md b/docs/source/llm/getting-started.md index 04ff220df1..bf51630326 100644 --- a/docs/source/llm/getting-started.md +++ b/docs/source/llm/getting-started.md @@ -774,7 +774,7 @@ Run the export script and the ETRecord will be generated as `etrecord.bin`. ##### ETDump generation -An ETDump is an artifact generated at runtime containing a trace of the model execution. For more information, see [the ETDump docs](../sdk-etdump.md). +An ETDump is an artifact generated at runtime containing a trace of the model execution. For more information, see [the ETDump docs](../etdump.md). Include the ETDump header in your code. ```cpp diff --git a/docs/source/model-debugging.md b/docs/source/model-debugging.md index 80358fe99a..ac8e993f02 100644 --- a/docs/source/model-debugging.md +++ b/docs/source/model-debugging.md @@ -14,7 +14,7 @@ Currently, ExecuTorch supports the following debugging flows: For a real example reflecting the steps below, please refer to [example_runner.cpp](https://github.com/pytorch/executorch/blob/main/examples/devtools/example_runner/example_runner.cpp). 1. [Optional] Generate an [ETRecord](./etrecord.rst) while exporting your model. When provided, this enables users to link profiling information back to the eager model source code (with stack traces and module hierarchy). -2. Integrate [ETDump generation](./sdk-etdump.md) into the runtime and set the debugging level by configuring the `ETDumpGen` object. Then, provide an additional buffer to which intermediate outputs and program outputs will be written. Currently we support two levels of debugging: +2. Integrate [ETDump generation](./etdump.md) into the runtime and set the debugging level by configuring the `ETDumpGen` object. Then, provide an additional buffer to which intermediate outputs and program outputs will be written. Currently we support two levels of debugging: - Program level outputs ```C++ Span buffer((uint8_t*)debug_buffer, debug_buffer_size); @@ -30,8 +30,8 @@ For a real example reflecting the steps below, please refer to [example_runner.c etdump_gen.set_event_tracer_debug_level( EventTracerDebugLogLevel::kIntermediateOutputs); ``` -3. Build the runtime with the pre-processor flag that enables tracking of debug events. Instructions are in the [ETDump documentation](./sdk-etdump.md). -4. Run your model and dump out the ETDump buffer as described [here](./sdk-etdump.md). (Do so similarly for the debug buffer if configured above) +3. Build the runtime with the pre-processor flag that enables tracking of debug events. Instructions are in the [ETDump documentation](./etdump.md). +4. Run your model and dump out the ETDump buffer as described [here](./etdump.md). (Do so similarly for the debug buffer if configured above) ### Accessing the debug outputs post run using the Inspector API's diff --git a/docs/source/sdk-etdump.md b/docs/source/sdk-etdump.md index c58efb40de..a765d4cf1b 100644 --- a/docs/source/sdk-etdump.md +++ b/docs/source/sdk-etdump.md @@ -1,44 +1,3 @@ # Prerequisite | ETDump - ExecuTorch Dump -ETDump (ExecuTorch Dump) is one of the core components of the ExecuTorch Developer Tools. It is the mechanism through which all forms of profiling and debugging data is extracted from the runtime. Users can't parse ETDump directly; instead, they should pass it into the Inspector API, which deserializes the data, offering interfaces for flexible analysis and debugging. - - -## Generating an ETDump - -Generating an ETDump is a relatively straightforward process. Users can follow the steps detailed below to integrate it into their application that uses ExecuTorch. - -1. ***Include*** the ETDump header in your code. -```C++ -#include -``` - -2. ***Create*** an Instance of the ETDumpGen class and pass it into the `load_method` call that is invoked in the runtime. - -```C++ -torch::executor::ETDumpGen etdump_gen = torch::executor::ETDumpGen(); -Result method = - program->load_method(method_name, &memory_manager, &etdump_gen); -``` - -3. ***Dump Out the ETDump Buffer*** - after the inference iterations have been completed, users can dump out the ETDump buffer. If users are on a device which has a filesystem, they could just write it out to the filesystem. For more constrained embedded devices, users will have to extract the ETDump buffer from the device through a mechanism that best suits them (e.g. UART, JTAG etc.) - -```C++ -etdump_result result = etdump_gen.get_etdump_data(); -if (result.buf != nullptr && result.size > 0) { - // On a device with a file system users can just write it out - // to the file-system. - FILE* f = fopen(FLAGS_etdump_path.c_str(), "w+"); - fwrite((uint8_t*)result.buf, 1, result.size, f); - fclose(f); - free(result.buf); - } -``` - -4. ***Compile*** your binary using CMake with the `ET_EVENT_TRACER_ENABLED` pre-processor flag to enable events to be traced and logged into ETDump inside the ExecuTorch runtime. This flag needs to be added to the ExecuTorch library and any operator library that you are compiling into your binary. For reference, you can take a look at `examples/sdk/CMakeLists.txt`. The lines of interest are: -``` -target_compile_options(executorch INTERFACE -DET_EVENT_TRACER_ENABLED) -target_compile_options(portable_ops_lib INTERFACE -DET_EVENT_TRACER_ENABLED) -``` -## Using an ETDump - -Pass this ETDump into the [Inspector API](./sdk-inspector.rst) to access this data and do post-run analysis. +Please update your link to . This URL will be deleted after v0.4.0. diff --git a/docs/source/sdk-inspector.rst b/docs/source/sdk-inspector.rst index 4d46915a8a..d80a8960b1 100644 --- a/docs/source/sdk-inspector.rst +++ b/docs/source/sdk-inspector.rst @@ -6,7 +6,7 @@ Overview The Inspector APIs provide a convenient interface for analyzing the contents of `ETRecord `__ and -`ETDump `__, helping developers get insights about model +`ETDump `__, helping developers get insights about model architecture and performance statistics. It’s built on top of the `EventBlock Class <#eventblock-class>`__ data structure, which organizes a group of `Event <#event-class>`__\ s for easy access to details of profiling events. diff --git a/docs/source/sdk-profiling.md b/docs/source/sdk-profiling.md index b618dbf8f1..dda71345cd 100644 --- a/docs/source/sdk-profiling.md +++ b/docs/source/sdk-profiling.md @@ -14,8 +14,8 @@ We provide access to all the profiling data via the Python [Inspector API](./sdk ## Steps to Profile a Model in ExecuTorch 1. [Optional] Generate an [ETRecord](./etrecord.rst) while you're exporting your model. If provided this will enable users to link back profiling details to eager model source code (with stack traces and module hierarchy). -2. Build the runtime with the pre-processor flags that enable profiling. Detailed in the [ETDump documentation](./sdk-etdump.md). -3. Run your Program on the ExecuTorch runtime and generate an [ETDump](./sdk-etdump.md). +2. Build the runtime with the pre-processor flags that enable profiling. Detailed in the [ETDump documentation](./etdump.md). +3. Run your Program on the ExecuTorch runtime and generate an [ETDump](./etdump.md). 4. Create an instance of the [Inspector API](./sdk-inspector.rst) by passing in the ETDump you have sourced from the runtime along with the optionally generated ETRecord from step 1. - Through the Inspector API, users can do a wide range of analysis varying from printing out performance details to doing more finer granular calculation on module level. diff --git a/docs/source/tutorials_source/devtools-integration-tutorial.py b/docs/source/tutorials_source/devtools-integration-tutorial.py index 92d8e32600..dea306a03d 100644 --- a/docs/source/tutorials_source/devtools-integration-tutorial.py +++ b/docs/source/tutorials_source/devtools-integration-tutorial.py @@ -20,7 +20,7 @@ # This tutorial will show a full end-to-end flow of how to utilize the Developer Tools to profile a model. # Specifically, it will: # -# 1. Generate the artifacts consumed by the Developer Tools (`ETRecord <../etrecord.html>`__, `ETDump <../sdk-etdump.html>`__). +# 1. Generate the artifacts consumed by the Developer Tools (`ETRecord <../etrecord.html>`__, `ETDump <../etdump.html>`__). # 2. Create an Inspector class consuming these artifacts. # 3. Utilize the Inspector class to analyze the model profiling result. @@ -297,5 +297,5 @@ def forward(self, x): # # - `ExecuTorch Developer Tools Overview <../devtools-overview.html>`__ # - `ETRecord <../etrecord.html>`__ -# - `ETDump <../sdk-etdump.html>`__ +# - `ETDump <../etdump.html>`__ # - `Inspector <../sdk-inspector.html>`__ diff --git a/extension/pybindings/pybindings.pyi b/extension/pybindings/pybindings.pyi index 307c5e1d76..14e8ec13e1 100644 --- a/extension/pybindings/pybindings.pyi +++ b/extension/pybindings/pybindings.pyi @@ -67,7 +67,7 @@ def _load_for_executorch( Args: path: File path to the ExecuTorch program as a string. enable_etdump: If true, enables an ETDump which can store profiling information. - See documentation at https://pytorch.org/executorch/stable/sdk-etdump.html + See documentation at https://pytorch.org/executorch/stable/etdump.html for how to use it. debug_buffer_size: If non-zero, enables a debug buffer which can store intermediate results of each instruction in the ExecuTorch program.