diff --git a/doc/images/in-process.drawio b/doc/images/in-process.drawio new file mode 100644 index 000000000..f2b2f738b --- /dev/null +++ b/doc/images/in-process.drawio @@ -0,0 +1 @@ +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 \ No newline at end of file diff --git a/doc/images/in-process.svg b/doc/images/in-process.svg new file mode 100644 index 000000000..fff438d59 --- /dev/null +++ b/doc/images/in-process.svg @@ -0,0 +1,3 @@ + + +
then creates
then creates
calls
calls
xrt_instance_create
(full implementation in targets/common/target_instance.c)
[Not supported by viewer]
With XRT_FEATURE_SERVICE disabled
With XRT_FEATURE_SERVICE disabled

in libopenxr_monado.so

This library is loaded by the OpenXR loader and provides the entry points for that API. The entire runtime exists in this library, within the process space of the application. Built in xrt/targets/openxr
[Not supported by viewer]
xrCreateInstance
(in state_trackers/oxr/oxr_instance.c)
[Not supported by viewer]
calls
calls
t_instance
which implements xrt_instance with functions that access hardware
[Not supported by viewer]t_instanceselect = t_instance_selectcreate_fd_compositor = t_instance_create_fd_compositorget_prober = t_instance_get_proberdestroy = t_instance_destroy
«interface»
xrt_instance
[Not supported by viewer]
a real xrt_prober_create
(in targets/openxr/target.c)
[Not supported by viewer] \ No newline at end of file diff --git a/doc/images/out-of-proc.drawio b/doc/images/out-of-proc.drawio new file mode 100644 index 000000000..941b63498 --- /dev/null +++ b/doc/images/out-of-proc.drawio @@ -0,0 +1 @@ +7VtZc9s4DP41nk0fmtHhK4+xc2xm0zaTpNv2ycNItM2GElWKju3++gUpUrePJnKcdj3TSUXwBj6AAEi33GGwuOQomn5gPqYtx/IXLfes5Ti2bTnwn6QsNcWyrIQy4cTXtIxwR35i01BTZ8THcaGhYIwKEhWJHgtD7IkCDXHO5sVmY0aLs0ZogiuEOw/RKvUL8cU03ZiVVfyNyWSqp+53dEWATGNNiKfIZ/McyT1vuUPOmEi+gsUQU8k9w5ek38WK2nRhHIdimw5fL++cj5fvxcnH+4/dOfnnR/T9+n0nGeUJ0ZnesJjiUPKTYySA8cnSxdLwA/vAHl1kXEzZhIWInmfUAWez0MdyUgtKHguIp7+z9teMRUC0gfgdC7HUckczwYA0FQHVtdVN6n3HbMY9vGZnGngC8QkW69q5SUO5sdwMmoeXmAVY8CU04JgiQZ6KuEAaXpO0XSYB+NBCqBfIadtzvcv5/ArbvS+Lwd34c++TWXZOIIBF+nI5PIP3eEHEV91dfn/L0c8WuYqzpSmEwALV5bhjit/ydVk3VTL9aiXQmNhr+fxaQl63yJyQW06XwnIHYwYbBjOF9Ca7P2bSPgyGsG+COVR9xPOMDF8T+f+CixEJY4FCD48S1TUjPnDTyFBgyck0CfloPEtWHEQUB8BwYACTJoCEKSMBfxegyYGkXySkdL5j710VnZSCgZYonE+JwHdRsp85HBJb6vcT5gIv1iqkru252sDqI8Y50UZtntnr1AhPc6b6xNqVeK2KfL8QWIpjfb29H12cn95/vj0f3Z3f/ns1PJfAD9EDBU0tcxEYIAUUC84e8ZBRxoEeslDydUwoLZFybJXy1XrttE1ZDyzrJXcJGJZTSiYh0ALi+8poIE3wQB4At0YE1O4XBWSO9px80uM0L5/2zuRjV+RjdGNqG7VQ6KfkgUU4XPARQB+O7+OY5bQoa2yIkSHcT0mc9OdI8SIpMiQtsmM9SBKctPD3E4z/9dZUSg1HoWwScfakXB/TUJlMWcFIKBUSfBmuKpG0GKc3V8fSOjDpbBEuXSHgJuL+HEQnB/U8HKvB0KMaNKJSJx3rKMSATTVxMiBIGtZBwgl8h4ri4yei2pIwmgnQdut90hrGTvbDntQAVzdDtenwUc0k1xJjrjsHzJ9RLBc5mBEqjIEB05XaFGlmEn7nuBxlTK7Xjxzut1WVGAyS3KF71slK9+pclNpbb7bkJsdUuXBT0Bdwk8qHbAPKUtKVXlVX3HaNrtj2zpRl9WFVUpZERd6nEv8FPYkwj0kssDr8MsgAGVAWxEUoE2makKdPqURb8CJiscL1eBaqKrBkYlmGpoJkok58FgoSyK+7T3nVTE491QRF0V9xoopSeTZCt7rz/xd2u1uAt+4gTq1/4+Bdbeif7WgNlXd1pZ2fFT5V1fk6UoiBTgKPBKD3ERAvrZ00dfLvm3Gn7JI7ZferUqx1p/q7EmL3Fb3lzXIE4QURgzMOV11kc3Zpm7B3UXaLonStGs+r+5qi7FVE2Ux0u7csg0lJbcoyaAy/fpKhdjX9pjWKRN7zNUopEYwALeU4HiUghnS4t6VCbXdLFdrdmXbyp+lQd0sd6r8pHbKrtsxg2ydPZbi/QK9K+rBBr4BcM32OBDrjyVREmu6RHm6DB+rK9YHKqBxIsp/ErV4scx57vGoPJWAXYbvBBuwioWE7RaPQOalxkeqitN7O/Nyqo/vbJ/D7W5oFo4hvxC6Y+4Sd2oU/yBzktN/kstJcVRb0/x6GoffmDEPbrnDplQ0AwICLU3kTK5lNURwT735KQlN1QeSO9KWQbxrqXAdQcvU+iqdqWatup6xju9Nurb2hgsIN5gS4K4VevrXqFa6t7NY211bPuqVqb2nc3MaNm+56I7PIGXI7JycF5PatTnGIZEu6VwmU6TJeYDXbFauZtyElCMdzElCUJMhyNxsKrVNC/Wu0ZDPJVujvPZrSYMo4+QntUQGb5p6k26q/VUk73cnB9DQcx9DtxojeLpE+oEWh4TWKRapOlKIoJg/pZUwAICDhgAnBgk3I+oVknNMpSLRbY4vSaKYQubhrjJGe7hZ7IJkJxa2Vtzy9mkjppGY6p1ucDVHQzBBcl4G0QvFOwFaNf2NMkysTVbRy+SFTU5+/3TZpa04biseyW/n+TUhjanK516rNWTuj3Gp2SVJ9JlcggR5SJdBXRLDQzgD+AdeH8ka+AwsfQtnOyvBPNudiCCew4IgovGGA6xzHohaJ6/V3Mz6XRblvgmMZH805atW3L4nPPBr7Izj0IhYToe6/ZOXQaZ1albRhuekBJM2CpOPsGyTV5LN8+wCh6wPmdeYiX3tAQ7No6PX3jYZqzsfHUp7LOiikVQccNIsD22rvGQgmhttfWGXCH/Ntwp/u+vAnC3WcXwp1dhnFleOx54dV7rbXMc2HVS+Ck1tN39Vmfg9h0C+HQYcoaCXonPVRkPJ4a2B4iIi2Otbc7aH6ViIit5q63hQR1eHjEBq9Blr2Hhq51ZRdJTRaiZFDmLQ7ZOw9THKrmZVimLQSFoeQaUeY2H/I5Na8l5A4GKjnvOqKEYqDmgdCKWXD/eLDyovBZt8ElX28Trvq49l1LyQ7a1zKl4WjVVP8Jt4E5UJBHTO+KLxr6yNv82/6Wm8pujPLbvC5XUjECAR89O7Zr+zkW3XMR+Zp+75/w9Uphml2zdPxlNb0S9XVvw8syAwpwCDZs4H3EYnzs+mtpHVUemGc/sTgIoDTowGxVWRUI8mVYuuULGHt68iGxAbF7LfSSQyc/eTcPf8P \ No newline at end of file diff --git a/doc/images/out-of-proc.svg b/doc/images/out-of-proc.svg new file mode 100644 index 000000000..061cdd7f4 --- /dev/null +++ b/doc/images/out-of-proc.svg @@ -0,0 +1,3 @@ + + +
then creates
then creates
calls
calls
xrt_instance_create
(full implementation in targets/common/target_instance.c)
[Not supported by viewer]
With XRT_FEATURE_SERVICE enabled
With XRT_FEATURE_SERVICE enabled

in libopenxr_monado.so

This library is loaded by the OpenXR loader and provides the entry points for that API. No direct hardware access takes place (neither for rendering nor device input) - forwarded over IPC links to service module. Built in xrt/targets/openxr

[Not supported by viewer]

in monado-service

This persistent service performs hardware interaction and exposes functionality over IPC to the runtime SO loaded in the app's process. Built in xrt/targets/service

[Not supported by viewer]
xrCreateInstance
(in state_trackers/oxr/oxr_instance.c)
[Not supported by viewer]
xrt_instance_create
(trampoline in targets/openxr/target.c)
[Not supported by viewer]
calls
calls
ipc_instance_create
(in ipc/ipc_client_instance)
[Not supported by viewer]
calls
calls
ipc_client_instance
which implements xrt_instance with client proxy functions
[Not supported by viewer]
creates
creates
t_instance
which implements xrt_instance with functions that access hardware
[Not supported by viewer]t_instanceselect = t_instance_selectcreate_fd_compositor = t_instance_create_fd_compositorget_prober = t_instance_get_proberdestroy = t_instance_destroyipc_client_instanceselect = ipc_client_instance_selectcreate_fd_compositor = ipc_client_instance_create_fd_compositorget_prober = ipc_client_instance_get_proberdestroy = ipc_client_instance_destroy
«interface»
xrt_instance
[Not supported by viewer]
calls
calls
init_all()
(in ipc/ipc_server_process.c)
[Not supported by viewer]
a real xrt_prober_create (in targets/service/main.c)
[Not supported by viewer] \ No newline at end of file diff --git a/doc/mainpage.md b/doc/mainpage.md index 329146937..122a1d1ac 100644 --- a/doc/mainpage.md +++ b/doc/mainpage.md @@ -9,6 +9,7 @@ getting started information and general documentation. * @ref md_CHANGELOG - If this is the web version of the docs, the changelog also includes a section for changes that have not yet been in a tagged release. +* @ref md_targets * @ref md_writing-a-new-driver (**not complete**) ## Source layout diff --git a/doc/targets.md b/doc/targets.md new file mode 100644 index 000000000..4d3c3eeca --- /dev/null +++ b/doc/targets.md @@ -0,0 +1,73 @@ +# Understanding and Writing Targets + +Monado is designed to be a collection of related but independent modules. The +final build product that brings all the desired components together, potentially +with additional code, is called the "target". There are several targets included +in the Monado source tree (in `src/xrt/targets/`) including: + +- `cli` - builds `monado-cli` executable +- `openxr` - builds `libopenxr-monado.so` OpenXR runtime shared object +- `gui` - builds `monado-gui` executable +- `service` - builds `monado-service` executable (if `XRT_FEATURE_SERVICE` is + enabled) + +There is also a directory `common` which builds two static libraries. Because +the "target" is responsible for pulling in all the desired drivers, etc. it can +lead to some repetition if multiple targets want the same driver collection. For +this reason, the "all drivers" code shared between many targets is located here, +though you could consider it a part of the individual targets. + +## Requirements of a Target + +A target must first provide the entry point desired: `int main()` if it's an +executable, or the well-known symbol name if it's a shared library. In some +cases, the entry point might be provided by one of the modules being combined to +form the target. For instance, an OpenXR runtime must expose +`xrNegotiateLoaderRuntimeInterface`: this function is provided by the OpenXR +state tracker `st_oxr`, so the OpenXR runtime target just has to link the state +tracker in and ensure it is present in the final build product. + +Then, the target must provide access to the collection of devices desired. The +code is currently (26-May-2020) in the middle of a transition, from a +"prober"-centric interface to an "instance"-centric interface. + +- Target device access was historically done by implementing + `xrt_prober_create`, typically through a call to + `xrt_prober_create_with_lists`, often passing the target list defined in the + common `target_lists.c` shared file. This is currently still somewhat-required + but not as central as before, and will be removed soon. +- Target device access is now provided by implementing the `xrt_instance` + interface in your target and providing a definition of `xrt_instance_create` + that instantiates your implementation. + +All methods of `xrt_instance` are required, though the `get_prober` method may +output a null pointer if the instance is not using a prober. For more detailed +information on this interface, see the documentation for @ref xrt_instance + +## Sample Call Trees + +For clarity, call trees are included below for the OpenXR runtime in two general +cases: `XRT_FEATURE_SERVICE` disabled, and `XRT_FEATURE_SERVICE` enabled. Note +that even with `XRT_FEATURE_SERVICE` enabled, the other targets (cli, gui) more +closely resembler the `XRT_FEATURE_SERVICE` disabled diagram: they contain the +device drivers internally rather than contacting the service. + +### XRT_FEATURE_SERVICE disabled + +This is the simplest architecture. It is also the architecture used by the +various extra targets like `monado-cli` even when building with +`XRT_FEATURE_SERVICE` enabled. + +![In-process OpenXR runtime diagram](images/in-process.svg) + +### XRT_FEATURE_SERVICE enabled + +Note that in this case, there are two processes involved, which have different +`xrt_instance` implementations. + +- The runtime has a "stub" or "client proxy" implementation that delegates to + the service over the IPC. +- The service has a normal or complete instance implementation that actually + provides access to devices, etc. + +![Out-of-process OpenXR runtime diagram](images/out-of-proc.svg)