README.md
1# Developer Tools Examples
2This directory contains examples of BundledProgram and ETDump generation.
3
4## Directory structure
5```bash
6examples/devtools
7├── scripts # Python scripts to illustrate export workflow of bundled program.
8├── executor_runner # Contains an example for both BundledProgram to verify ExecuTorch model, and generate ETDump for runtime results.
9├── CMakeLists.txt # Example CMakeLists.txt for building executor_runner with Developer Tools support.
10├── build_example_runner.sh # A convenient shell script to build the example_runner.
11├── test_example_runner.sh # A convenient shell script to run the example_runner.
12└── README.md # Current file
13```
14
15## BundledProgram
16
17We will use an example model (in `torch.nn.Module`) and its representative inputs, both from [`models/`](../models) directory, to generate a [BundledProgram(`.bpte`)](../../docs/source/bundled-io.md) file using the [script](scripts/export_bundled_program.py). Then we will use [devtools/example_runner](example_runner/example_runner.cpp) to execute the `.bpte` model on the ExecuTorch runtime and verify the model on BundledProgram API.
18
19
201. Sets up the basic development environment for ExecuTorch by [Setting up ExecuTorch from GitHub](https://pytorch.org/executorch/stable/getting-started-setup).
21
222. Using the [script](scripts/export_bundled_program.py) to generate a BundledProgram binary file by retreiving a `torch.nn.Module` model and its representative inputs from the list of available models in the [`models/`](../models) dir.
23
24```bash
25cd executorch # To the top level dir
26
27# To get a list of example models
28python3 -m examples.devtools.scripts.export_bundled_program -h
29
30# To generate a specific `.bpte` model
31python3 -m examples.devtools.scripts.export_bundled_program -m mv2 # for MobileNetv2
32
33# This should generate ./mv2_bundled.bpte file, if successful.
34```
35
363. Once we have the BundledProgram binary (`.bpte`) file, then let's run and verify it with ExecuTorch runtime and BundledProgram APIs using the [devtools/example_runner](example_runner/example_runner.cpp).
37
38```bash
39 cd executorch
40 ./examples/devtools/build_example_runner.sh
41 ./cmake-out/examples/devtools/example_runner --bundled_program_path mv2_bundled.bpte --output_verification
42 ```
43
44
45## ETDump
46
47### Getting Started
48
49After exporting a `BundledProgram`, runtime profiling and debug data can be collected in an ``ETDump``. An ``ETDump`` is a buffer containing data generated by hooks within the ExecuTorch runtime.
50We offer an example runner that accepts a `BundledProgram` (`.bpte`) and runs a single iteration over the first method defined.
51
52Running the program will generate an `ETDump` file (`.etdp`) at the location specified by `--etdump_path`.
53
54```bash
55 ./cmake-out/examples/devtools/example_runner --bundled_program_path mv2_bundled.bpte --etdump_path mv2_etdump.etdp
56 ```
57
58### Parsing ETDump
59
60Once an `ETDump` has been generated, it can be viewed using the CLI inspector. This will print a tabular view of the data recorded in the ETDump.
61
62```bash
63 python3 -m devtools.inspector.inspector_cli --etdump_path mv2_etdump.etdp
64 ```
65### ETDump C++ API
66
67ETDump profiling can also be used in a custom C++ program. `ETDumpGen` is an implementation of the abstract `EventTracer` class. Include the header file located at `devtools/etdump/etdump_flatcc.h`. To initialize the ETDump generator, construct it before loading the method from the program.
68
69```cpp
70 executorch::etdump::ETDumpGen etdump_gen;
71 Result<Method> method =
72 program->load_method(method_name, &memory_manager, &etdump_gen);
73 ```
74
75Since the `EventTracer` hooks are embedded within the runtime, profiling and debug data will be automatically recorded.
76
77Once execution has completed, finalize the ETDump buffer. This returns an `etdump_result`, a struct with the finalized buffer and its size.
78
79```cpp
80 etdump_result result = etdump_gen.get_etdump_data();
81 if (result.buf != nullptr && result.size > 0) {
82 FILE* f = fopen(FLAGS_etdump_path.c_str(), "w+");
83 fwrite((uint8_t*)result.buf, 1, result.size, f);
84 fclose(f);
85 free(result.buf);
86 }
87 ```
88