Skip to content

Commit 92e8584

Browse files
committed
Update PAL override docs
1 parent 7b39a0c commit 92e8584

File tree

1 file changed

+41
-1
lines changed

1 file changed

+41
-1
lines changed

docs/source/using-executorch-runtime-integration.md

Lines changed: 41 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,47 @@ For non-POSIX-compliant systems, a minimal no-op PAL implementation is provided.
2424

2525
### Overriding the PAL
2626

27-
Overriding the default PAL implementation is commonly done to route logs to a user-specified destination or to provide PAL functionality on embedded systems. To override one or more PAL methods, take the following steps:
27+
Overriding the default PAL implementation is commonly done to route logs to a user-specified destination or to provide PAL functionality on embedded systems. The PAL can be overriden usinn runtime APIs or at link time. Prefer the runtime API unless you specifically need link-time overrides.
28+
29+
### Runtime PAL Registration
30+
31+
To register a custom PAL implementation, take the following steps:
32+
33+
- Include
34+
[`executorch/runtime/platform/platform.h`](https://github.com/pytorch/executorch/blob/main/runtime/platform/platform.h)
35+
in one of your application's `.c` or `.cpp` files.
36+
- Create an instance of the [PalImpl](https://github.com/pytorch/executorch/blob/7b39a0ce63bfb5124d4d29cfb6c8af85a3c580ba/runtime/platform/platform.h#L163) struct.
37+
- Set one or more fields to custom PAL function implementations. Leave fields as null to use the default platform implementation.
38+
- The PalImpl struct provides a [create](https://github.com/pytorch/executorch/blob/7b39a0ce63bfb5124d4d29cfb6c8af85a3c580ba/runtime/platform/platform.h#L168) method for this purpose.
39+
- Call `executorch::platform::register_pal(pal_impl)` to register the implementation.
40+
- This can be done from a static context, as in the example below.
41+
42+
Here is a complete example from [pybindings.cpp](https://github.com/pytorch/executorch/blob/7b39a0ce63bfb5124d4d29cfb6c8af85a3c580ba/extension/pybindings/pybindings.cpp#L4), where logs are redirected to show up properly in a Python notebook environment.
43+
44+
```cpp
45+
void emit_log_message(
46+
et_timestamp_t timestamp,
47+
et_pal_log_level_t level,
48+
const char* filename,
49+
ET_UNUSED const char* function,
50+
size_t line,
51+
const char* message,
52+
ET_UNUSED size_t length) {
53+
std::cerr << "[" << filename << ":" << line << "] " << message << std::endl;
54+
}
55+
56+
runtime::PalImpl build_pal() {
57+
return runtime::PalImpl::create(emit_log_message, __FILE__);
58+
}
59+
60+
// Update PAL to redirect logs.
61+
ET_UNUSED bool registration_result = runtime::register_pal(build_pal());
62+
```
63+
64+
### Weak Symbol Override
65+
ExecuTorch also provides a link-time method to override the PAL using weak symbols. This method is primarily maintained for backwards compatability.
66+
67+
To override one or more PAL methods, take the following steps:
2868
2969
- Include
3070
[`executorch/runtime/platform/platform.h`](https://github.com/pytorch/executorch/blob/main/runtime/platform/platform.h)

0 commit comments

Comments
 (0)