xref: /aosp_15_r20/external/executorch/examples/devtools/README.md (revision 523fa7a60841cd1ecfb9cc4201f1ca8b03ed023a)

# Developer Tools Examples
This directory contains examples of BundledProgram and ETDump generation.

## Directory structure
```bash
examples/devtools
├── scripts                           # Python scripts to illustrate export workflow of bundled program.
├── executor_runner                   # Contains an example for both BundledProgram to verify ExecuTorch model, and generate ETDump for runtime results.
├── CMakeLists.txt                    # Example CMakeLists.txt for building executor_runner with Developer Tools support.
├── build_example_runner.sh           # A convenient shell script to build the example_runner.
├── test_example_runner.sh            # A convenient shell script to run the example_runner.
└── README.md                         # Current file
```

## BundledProgram

We 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.


1. Sets up the basic development environment for ExecuTorch by [Setting up ExecuTorch from GitHub](https://pytorch.org/executorch/stable/getting-started-setup).

2. 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.

```bash
cd executorch # To the top level dir

# To get a list of example models
python3 -m examples.devtools.scripts.export_bundled_program -h

# To generate a specific `.bpte` model
python3 -m examples.devtools.scripts.export_bundled_program -m mv2 # for MobileNetv2

# This should generate ./mv2_bundled.bpte file, if successful.
```

3. 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).

```bash
   cd executorch
   ./examples/devtools/build_example_runner.sh
   ./cmake-out/examples/devtools/example_runner --bundled_program_path mv2_bundled.bpte --output_verification
   ```


## ETDump

### Getting Started

After 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.
We offer an example runner that accepts a `BundledProgram` (`.bpte`) and runs a single iteration over the first method defined.

Running the program will generate an `ETDump` file (`.etdp`) at the location specified by `--etdump_path`.

```bash
   ./cmake-out/examples/devtools/example_runner --bundled_program_path mv2_bundled.bpte --etdump_path mv2_etdump.etdp
   ```

### Parsing ETDump

Once 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.

```bash
   python3 -m devtools.inspector.inspector_cli --etdump_path mv2_etdump.etdp
   ```
### ETDump C++ API

ETDump 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.

```cpp
   executorch::etdump::ETDumpGen etdump_gen;
   Result<Method> method =
      program->load_method(method_name, &memory_manager, &etdump_gen);
   ```

Since the `EventTracer` hooks are embedded within the runtime, profiling and debug data will be automatically recorded.

Once execution has completed, finalize the ETDump buffer. This returns an `etdump_result`, a struct with the finalized buffer and its size.

```cpp
   etdump_result result = etdump_gen.get_etdump_data();
   if (result.buf != nullptr && result.size > 0) {
    FILE* f = fopen(FLAGS_etdump_path.c_str(), "w+");
    fwrite((uint8_t*)result.buf, 1, result.size, f);
    fclose(f);
    free(result.buf);
  }
   ```