Improve the documentation of custom op build

[iseeyuan]

📚 The doc issue

Based on feedback in https://blacksamorez.substack.com/p/aqlm-executorch-android, it would be great to improve our documentation page, https://pytorch.org/executorch/stable/kernel-library-custom-aten-kernel.html.

Suggest a potential alternative/fix

No response

[larryliu0820]

https://github.com/BlackSamorez/executorch/pull/1/files is the code - cc @kimishpatel

[BlackSamorez]

Hi everyone, thanks for inviting me to provide feedback and propose documentation changes!

TLDR: proposition: create an editable template with placeholder custom op to edit step-by-step to integrate one's kernel.

In general, I feel like the process of fully integrating custom kernels takes a lot of steps:

1. Writing an implementation that operates with torch::executor primitives.
2. Configuring CMake to link Executorch and compile a dynamic lib.
3. Writing a torch binding and library declaration.
4. Configuring CMake to compile a separate library.
5. Load it into PyTorch and export the model with this custom OP.
6. Force-link the custom op library to the executable with target_link_options_shared_lib which is a function from build/Utils.cmake. As such, I was only able to do it from withing the Executorch CMake tree, having to make my kernels part of the same tree.

To get any feedback on whether what you're writing works you need to either:

1. Do steps 1-5 to use the OP from pytorch.
2. Do steps 1-2 and 7 to to test that the kernel is being properly linked to the runtime.

It's a lot of steps to take with virtually no feedback. As such, I believe it would make sense to construct a demo with all of those steps implemented for a placeholder function, model and clear instructions on what to edit to replace them with one's custom ops.

That way, people will be able to integrate their solution one step at a time (first editing the kernel code, then linking additional libraries, then changing signatures, then editing the Python level code) with clear feedback on what change caused things to stop working end-to-end. This would make debugging and error interpretation much easier than just a bunch of text describing what needs to be done from scratch.

From my experience, I spent a lot of time backtracking because I didn't realize that some things were meant to be written, compiled or linked in a specific manner from the very start, and a preexisting template would seemingly solve that problem.

[larryliu0820]

@BlackSamorez Thanks for providing the detailed feedback! Definitely agree that ExecuTorch should provide good examples for users to follow. We have a custom ops example folder https://github.com/pytorch/executorch/blob/main/examples/portable/custom_ops/README.md but it was using old yaml based API. We will definitely add a new example for EXECUTORCH_LIBRARY. We can also think about ways to generate or automate a lot of the steps you mentioned.

[iseeyuan]

Thanks for the great feedback @BlackSamorez ! Just to call out that contribution to ExecuTorch code base is more than welcome. Feel free to submit PRs for improvements!

[larryliu0820]

@BlackSamorez #5297 is merged. Can you take a look and let us know if this is helpful?

[iseeyuan]

Closing this issue as #5297 been landed.
It's contiguous work to improve documentations. Feel free to submit new issues, or help directly on documentation improvement!