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