Skip to content

Commit 8b76a3e

Browse files
Add ETDump profiling to the Apple frameworks and SwiftPM package (pytorch#22205)
## Summary This adds **ETDump profiling** to the ExecuTorch SwiftPM package and Apple frameworks. An ETDump is the profiling trace that records which operators ran and how long they took. Before this, collecting one was only possible from the pip wheel; now a Swift or C++ app can do it directly. ## Design **A separate framework.** ETDump ships as its own `ExecuTorchETDump` framework rather than being folded into the core `executorch` framework. That keeps the profiler and its `flatcc` serialization dependency out of the runtime for apps that do not profile. It is built only when the runtime is compiled with the tracing hooks on (`EXECUTORCH_BUILD_DEVTOOLS` + `EXECUTORCH_ENABLE_EVENT_TRACER`), which the Apple presets now enable. **The tracer seam.** The profiler needs its tracer installed when the model is constructed. The C++ `Module` takes its tracer at construction, but an Objective-C category cannot add a designated initializer (doing so makes the compiler treat the public initializers as convenience ones that fail to chain). So an internal class method on `ExecuTorchModule` builds a module with a tracer attached, leaving the public initializers untouched. The `ETDump` object owns the module and reads the trace back through it, so the tracer lives exactly as long as the module. ## Usage ```swift let etdump = try ETDump(filePath: "model.pte") _ = try etdump.module.forward([input]) let data = try etdump.takeData() // the trace, ready to save // or straight to disk: try etdump.takeData(toFile: "trace.etdump") ``` `ETDump.isAvailable` reports whether the build included the profiler. ## What changed - `extension/apple/etdump/`: the new `ExecuTorchETDump` framework (public `ETDump` API + error enum) and its CMake. - `extension/apple/ExecuTorch/Internal/ExecuTorchModule+Internal.h` + `ExecuTorchModule.mm`: the internal class-method seam that attaches a tracer; public API unchanged. - `tools/cmake/preset/default.cmake`: the `EXECUTORCH_BUILD_EXTENSION_ETDUMP_APPLE` option, requiring the devtools and event-tracer options. - `tools/cmake/preset/apple_common.cmake`: enable the profiler and the extension for Apple builds. - `scripts/build_apple_frameworks.sh` + `.github/workflows/apple.yml`: build and publish the framework. - `Package.swift`: the `executorch_etdump` product. A companion change to the package template branch adds the product to the published manifest. ## Test plan - Compiled the module seam and the wrapper against the runtime headers: zero errors and no new warnings, in particular none of the designated-initializer warnings the category approach produced. - Confirmed the SwiftPM manifest parses with the `executorch_etdump` product depending on `executorch`. - Verified the build option requires the devtools and event-tracer options and fails fast without them. - Device and simulator builds are exercised by the Apple CI jobs this adds the framework to. --------- Co-authored-by: PyTorch Bot <pytorchbot@users.noreply.github.com>
1 parent 16d3b9f commit 8b76a3e

25 files changed

Lines changed: 1220 additions & 205 deletions

‎.Package.swift/executorch_dump/dummy.swift‎

Whitespace-only changes.

‎.Package.swift/executorch_dump_debug/dummy.swift‎

Whitespace-only changes.

‎.github/workflows/apple.yml‎

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ on:
1616
- scripts/build_apple_frameworks.sh
1717
- scripts/build_apple_llm_demo.sh
1818
- scripts/create_frameworks.sh
19+
- Package.swift
1920
- .ci/scripts/test_ios_ci.sh
2021
- extension/apple/**
2122
- extension/benchmark/apple/**
@@ -191,6 +192,7 @@ jobs:
191192
FRAMEWORKS=(
192193
"executorch"
193194
"executorch_llm"
195+
"executorch_dump"
194196
"backend_coreml"
195197
"backend_mlx"
196198
"backend_xnnpack"
@@ -298,7 +300,15 @@ jobs:
298300
git checkout -b "${BRANCH}"
299301
fi
300302
301-
[[ -f Package.swift ]] || mv Package.swift.template Package.swift
303+
# Always substitute from the template on the swiftpm branch, never from
304+
# a Package.swift left behind by an earlier run for this same version.
305+
# Nightly versions carry a date, so two runs in one day land on the same
306+
# branch, and a release re-run reuses the version exactly; reusing the
307+
# old file there would publish a manifest missing whatever the template
308+
# gained since, and the failure surfaces as a product that is built but
309+
# has no entry, with nothing pointing at the stale file.
310+
git checkout swiftpm -- Package.swift.template
311+
mv -f Package.swift.template Package.swift
302312
303313
sed -i "s/__VERSION__/${VERSION}/g" Package.swift
304314
@@ -354,7 +364,11 @@ jobs:
354364
# above are text greps, the swiftpm branch has no CI of its own, and a
355365
# .template is not a manifest. Resolve it here so a Swift-level defect
356366
# fails this run rather than every consumer of the published branch.
357-
if ! swift package dump-package > /dev/null; then
367+
# Use describe, not dump-package: dump-package parses the manifest but
368+
# returns 0 even when a target's directory is absent, while describe
369+
# loads the package and fails, which is the case that reaches
370+
# consumers when a stub directory is missed.
371+
if ! swift package describe > /dev/null; then
358372
echo "::error::the substituted Package.swift does not evaluate"
359373
exit 1
360374
fi

‎CMakeLists.txt‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1172,9 +1172,12 @@ if(EXECUTORCH_BUILD_KERNELS_TORCHAO)
11721172
endif()
11731173

11741174
# The shared build ships the profiler as one of its libraries, and the Python
1175-
# extension records a hard dependency on it, so the target has to exist whenever
1176-
# either of those is being built rather than only when devtools is asked for.
1177-
if((EXECUTORCH_BUILD_PYBIND OR EXECUTORCH_BUILD_SHARED)
1175+
# extension records a hard dependency on it, and the Apple ETDump extension
1176+
# links it, so the target has to exist whenever any of those is being built
1177+
# rather than only when devtools is asked for.
1178+
if((EXECUTORCH_BUILD_PYBIND
1179+
OR EXECUTORCH_BUILD_SHARED
1180+
OR EXECUTORCH_BUILD_EXTENSION_ETDUMP_APPLE)
11781181
AND NOT EXECUTORCH_BUILD_DEVTOOLS
11791182
)
11801183
add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/devtools)
@@ -1536,6 +1539,10 @@ if(EXECUTORCH_BUILD_EXTENSION_ASR_RUNNER)
15361539
list(APPEND _executorch_extensions extension_asr_runner)
15371540
endif()
15381541

1542+
if(EXECUTORCH_BUILD_EXTENSION_ETDUMP_APPLE)
1543+
add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/extension/apple/dump)
1544+
endif()
1545+
15391546
if(EXECUTORCH_BUILD_EXTENSION_LLM_APPLE)
15401547
add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/extension/llm/apple)
15411548
endif()

‎Package.swift‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,11 @@ let products = deliverables([
7070
"c++",
7171
],
7272
],
73+
"executorch_dump": [
74+
"targets": [
75+
"executorch",
76+
],
77+
],
7378
"executorch_llm": [
7479
"targets": [
7580
"executorch",
@@ -189,6 +194,11 @@ if FileManager.default.fileExists(atPath: "\(objcTestsDir)/add_mul_coreml.pte")
189194
objcTestResources.append(.copy("add_mul_coreml.pte"))
190195
}
191196

197+
// The dump test fixture is committed under the target, the way the sibling tests
198+
// target's fixture is, so the test bundle always ships it and SwiftPM synthesizes
199+
// Bundle.module.
200+
let dumpTestResources: [Resource] = [.copy("resources/add.pte")]
201+
192202
let testLinkerSettings: [LinkerSetting] = [
193203
// The test targets depend on the executorch binary target directly, which
194204
// carries no linker settings, rather than the with-dependencies target that
@@ -238,6 +248,17 @@ let package = Package(
238248
exclude: [".gitignore"],
239249
resources: objcTestResources,
240250
linkerSettings: testLinkerSettings
251+
),
252+
.testTarget(
253+
name: "dump_tests",
254+
dependencies: [
255+
.target(name: "executorch_dump\(debug_suffix)\(dependencies_suffix)"),
256+
.target(name: "kernels_optimized\(dependencies_suffix)"),
257+
.target(name: "backend_coreml\(dependencies_suffix)"),
258+
],
259+
path: "extension/apple/dump/ExecuTorchDump/__tests__",
260+
resources: dumpTestResources,
261+
linkerSettings: testLinkerSettings
241262
)
242263
]
243264
)

‎docs/source/using-executorch-ios.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ ExecuTorch supports both iOS and macOS via Objective-C, Swift, and C++. ExecuTor
77
The ExecuTorch Runtime for iOS and macOS (ARM64) is distributed as a collection of prebuilt [.xcframework](https://developer.apple.com/documentation/xcode/creating-a-multi-platform-binary-framework-bundle) binary targets. These targets are compatible with both iOS and macOS devices and simulators and are available in both release and debug modes:
88

99
* `executorch` - Core runtime components
10+
* `executorch_dump` - ETDump profiling
1011
* `executorch_llm` - LLM-specific runtime components
1112
* `backend_coreml` - Core ML backend
1213
* `backend_mlx` - MLX backend

‎extension/apple/ExecuTorch/Exported/ExecuTorch.h‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
#import "ExecuTorchBackendOption.h"
1010
#import "ExecuTorchBackendOptionsMap.h"
1111
#import "ExecuTorchError.h"
12+
#import "ExecuTorchEventTracer.h"
1213
#import "ExecuTorchImageProcessor.h"
1314
#import "ExecuTorchLog.h"
1415
#import "ExecuTorchModule.h"
Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
/*
2+
* Copyright (c) Meta Platforms, Inc. and affiliates.
3+
* All rights reserved.
4+
*
5+
* This source code is licensed under the BSD-style license found in the
6+
* LICENSE file in the root directory of this source tree.
7+
*/
8+
9+
#import <Foundation/Foundation.h>
10+
11+
NS_ASSUME_NONNULL_BEGIN
12+
13+
/**
14+
* An opaque handle to a runtime event tracer.
15+
*
16+
* A tracer records what a model does while it runs. This base class carries no
17+
* behavior of its own: a concrete tracer, such as the one the ExecuTorchDump
18+
* framework provides, subclasses it and supplies the underlying implementation.
19+
* Pass an instance to a `Module` at creation to have that module record through
20+
* it.
21+
*
22+
* # Lifetime
23+
* A tracer is single-use: creating a `Module` with it hands the underlying
24+
* implementation to that module, which owns it from then on. Do not pass the
25+
* same instance to a second module.
26+
*/
27+
NS_SWIFT_NAME(EventTracer)
28+
@interface ExecuTorchEventTracer : NSObject
29+
30+
+ (instancetype)new NS_UNAVAILABLE;
31+
- (instancetype)init NS_UNAVAILABLE;
32+
33+
@end
34+
35+
NS_ASSUME_NONNULL_END
Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
/*
2+
* Copyright (c) Meta Platforms, Inc. and affiliates.
3+
* All rights reserved.
4+
*
5+
* This source code is licensed under the BSD-style license found in the
6+
* LICENSE file in the root directory of this source tree.
7+
*/
8+
9+
#import "ExecuTorchEventTracer.h"
10+
11+
#import <executorch/extension/apple/ExecuTorch/Internal/ExecuTorchEventTracer+Internal.h>
12+
13+
using executorch::runtime::EventTracer;
14+
15+
@implementation ExecuTorchEventTracer {
16+
std::unique_ptr<EventTracer> _tracer;
17+
}
18+
19+
- (instancetype)initWithCppTracer:(std::unique_ptr<EventTracer>)tracer {
20+
self = [super init];
21+
if (self) {
22+
_tracer = std::move(tracer);
23+
}
24+
return self;
25+
}
26+
27+
- (std::unique_ptr<EventTracer>)takeCppTracer {
28+
return std::move(_tracer);
29+
}
30+
31+
@end

0 commit comments

Comments
 (0)