Skip to content

Commit c0d948a

Browse files
authored
update etdump doc for better clearance
Differential Revision: D91245299 Pull Request resolved: pytorch#16793
1 parent 8e8058d commit c0d948a

1 file changed

Lines changed: 88 additions & 5 deletions

File tree

‎docs/source/etdump.md‎

Lines changed: 88 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,28 @@ ETDump (ExecuTorch Dump) is one of the core components of the ExecuTorch Develop
77

88
Generating an ETDump is a relatively straightforward process. Users can follow the steps detailed below to integrate it into their application that uses ExecuTorch.
99

10+
### Build Configuration
11+
12+
To enable ETDump support, you need to configure your CMake build with the following options:
13+
14+
**Required CMake options:**
15+
```cmake
16+
-DEXECUTORCH_BUILD_DEVTOOLS=ON # Builds the devtools library including ETDump
17+
-DEXECUTORCH_ENABLE_EVENT_TRACER=ON # Enables event tracing in the runtime
18+
```
19+
20+
**Required CMake targets to link:**
21+
```cmake
22+
target_link_libraries(your_binary
23+
etdump # ETDump library
24+
# ... other ExecuTorch libraries
25+
)
26+
```
27+
28+
The `EXECUTORCH_ENABLE_EVENT_TRACER=ON` option automatically sets the `ET_EVENT_TRACER_ENABLED` preprocessor flag for the ExecuTorch runtime and all operator libraries.
29+
30+
### Using the Low-Level Runtime API
31+
1032
1. ***Include*** the ETDump header in your code.
1133
```C++
1234
#include <executorch/devtools/etdump/etdump_flatcc.h>
@@ -34,15 +56,76 @@ if (result.buf != nullptr && result.size > 0) {
3456
}
3557
```
3658

37-
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:
59+
### Using the Module API (C++)
60+
61+
For applications using the higher-level [Module API](extension-module.md), ETDump integration is simpler. Create an `ETDumpGen` instance and pass it to the `Module` constructor:
62+
63+
```cpp
64+
#include <fstream>
65+
#include <memory>
66+
67+
#include <executorch/extension/module/module.h>
68+
#include <executorch/devtools/etdump/etdump_flatcc.h>
69+
70+
using namespace ::executorch::extension;
71+
72+
Module module("/path/to/model.pte", Module::LoadMode::Mmap, std::make_unique<ETDumpGen>());
73+
74+
// Execute a method, e.g., module.forward(...); or module.execute("my_method", ...);
75+
76+
if (auto* etdump = dynamic_cast<ETDumpGen*>(module.event_tracer())) {
77+
const auto trace = etdump->get_etdump_data();
78+
79+
if (trace.buf && trace.size > 0) {
80+
std::unique_ptr<void, decltype(&free)> guard(trace.buf, free);
81+
std::ofstream file("/path/to/trace.etdump", std::ios::binary);
82+
83+
if (file) {
84+
file.write(static_cast<const char*>(trace.buf), trace.size);
85+
}
86+
}
87+
}
3888
```
39-
target_compile_options(executorch INTERFACE -DET_EVENT_TRACER_ENABLED)
40-
target_compile_options(portable_ops_lib INTERFACE -DET_EVENT_TRACER_ENABLED)
89+
90+
### Using the Python Runtime API
91+
92+
For Python applications using the [Python Runtime API](runtime-python-api-reference.rst), you can enable ETDump when loading a program:
93+
94+
```python
95+
from pathlib import Path
96+
import os
97+
98+
import torch
99+
from executorch.runtime import Runtime, Program, Method
100+
101+
# Create program with etdump generation enabled
102+
et_runtime: Runtime = Runtime.get()
103+
program: Program = et_runtime.load_program(
104+
Path("/tmp/program.pte"),
105+
enable_etdump=True,
106+
debug_buffer_size=int(1e7), # 10MB buffer to capture all debug info
107+
)
108+
109+
# Load method and execute
110+
forward: Method = program.load_method("forward")
111+
inputs = (torch.ones(2, 2), torch.ones(2, 2))
112+
outputs = forward.execute(inputs)
113+
114+
# Write etdump result to file
115+
etdump_file = "/tmp/etdump_output.etdp"
116+
debug_file = "/tmp/debug_output.bin"
117+
program.write_etdump_result_to_file(etdump_file, debug_file)
118+
119+
# Check that files were created
120+
print(f"ETDump file created: {os.path.exists(etdump_file)}")
121+
print(f"Debug file created: {os.path.exists(debug_file)}")
41122
```
42123

43-
### Make sure ET_EVENT_TRACER_ENABLED flag is enabled or ETDump will be empty.
124+
**Note:** The Python Runtime API requires ExecuTorch to be built with event tracing enabled (`EXECUTORCH_ENABLE_EVENT_TRACER=ON`).
125+
126+
### Troubleshooting: Empty ETDump
44127

45-
If the binary is not compiled with the `ET_EVENT_TRACER_ENABLED` preprocessor flag, no trace events will be recorded and the ETDump will be empty.
128+
If the binary is not compiled with the `ET_EVENT_TRACER_ENABLED` preprocessor flag (either by setting `EXECUTORCH_ENABLE_EVENT_TRACER=ON` in CMake or manually adding `-DET_EVENT_TRACER_ENABLED`), no trace events will be recorded and the ETDump will be empty.
46129

47130
When this flag is missing, the following code:
48131

0 commit comments

Comments
 (0)