The open source OpenXR runtime
doc: Update driver writing documentation
+79
-31
+1
-1
doc/mainpage.md
+1
-1
doc/mainpage.md
+76
-9
doc/writing-a-new-driver.md
+76
-9
doc/writing-a-new-driver.md
···
1
1
# Writing a new driver {#writing-driver}
2
2
3
3
<!--
4
-
Copyright 2018-2020, Collabora, Ltd. and the Monado contributors
4
+
Copyright 2018-2021, Collabora, Ltd. and the Monado contributors
5
5
SPDX-License-Identifier: BSL-1.0
6
6
-->
7
7
8
-
This document will tell you in broad strokes what you need to do to create a
9
-
driver in Monado. Like the many ones already in there @ref drv. It is not a step
10
-
by step guide to making a driver. Also what you need to do can vary a lot
11
-
depending on the type of hardware you are adding a driver for and the level of
12
-
features you want.
8
+
The easiest way to begin writing a driver is to start from a working example.
9
+
The @ref drv_sample driver is provided explicitly for this purpose: it creates
10
+
an HMD device, with a custom @ref xrt_auto_prober implementation for hardware
11
+
discovery, and some simple display parameters that should be easy to modify.
12
+
13
+
Copy that directory and rename the files in it. Then, use the following `sed`
14
+
command to perform some bulk renames before you begin actually writing code. The
15
+
command as written assumes your new device type is called `my_device` or `md`
16
+
for short, and your auto-prober is called `my_device_auto_prober` or `mdap` for
17
+
short: change the replacement side of each pattern to match the real names you
18
+
are using.
19
+
20
+
```sh
21
+
# First pattern is for renaming device types,
22
+
# second is for renaming device variables,
23
+
# third is for renaming device macros.
24
+
# Fourth and fifth are for renaming auto prober types and variables, respectively.
25
+
# The last two are for renaming the environment variable and function name
26
+
# for the environment variable logging config.
27
+
sed -r -e 's/sample_hmd/my_device/g' \
28
+
-e 's/\bsh\b/md/g' \
29
+
-e 's/sample_auto_prober/my_device_auto_prober/g' \
30
+
-e 's/\bsap\b/mdap/g' \
31
+
-e 's/\bSH_/MD_/g' \
32
+
-e 's/sample/my_device/g' \
33
+
-e 's/SAMPLE/MY_DEVICE/g' \
34
+
-i *.c *.h
35
+
```
36
+
37
+
You will want to go through each function of the sample code you started from,
38
+
implement any missing functionality, and adapt any existing functionality to
39
+
match your device. Refer to other @ref drv for additional guidance. Most drivers
40
+
are fairly simple, as large or complex functionality in drivers is often
41
+
factored out into separate auxiliary libraries.
42
+
43
+
## What to Implement
44
+
45
+
You will definitely make at least one implementation of @ref xrt_device. If your
46
+
driver can talk to e.g. both a headset and corresponding controllers, you can
47
+
choose to expose all those through a single xrt_device implementation, or
48
+
through multiple implementations that may share some underlying component (by
49
+
convention called `..._system`). Both are valid choices, and the right one to
50
+
choose depends on which maps better to your underlying device or API you are
51
+
connecting to. It is more common to have one xrt_device per piece of hardware,
52
+
however. @ref hydra_device serves as a nice example of two controllers that are
53
+
enumerated as a single overall USB HID device but expose two separate xrt_device
54
+
instances.
55
+
56
+
Depending on whether your device can be created from a detected USB HID device,
57
+
you will also need to implement either @ref xrt_auto_prober or a function
58
+
matching the prototype for @ref xrt_prober_entry::found. See below for more details.
13
59
14
-
## Map
60
+
## Other Relevant Components
15
61
16
-
The first components you will be interacting with is @ref st_prober find the
62
+
The components you will be interacting with is @ref st_prober to find the
17
63
hardware devices and setup a working system, along with the @ref aux code that
18
-
provides various helpers. You can look at other @ref drv on how to start.
64
+
provides various helpers. It is convention in Monado for interfaces to allow
65
+
full, complete control of anything a device might want to modify/control, and to
66
+
provide helper functionality in @ref aux to simplify implementation of the most
67
+
common cases.
19
68
20
69
## Probing
21
70
···
23
72
too hard: you use the auto prober interface when the basic USB VID/PID-based
24
73
interface is not sufficient for you to detect presence/absence of your device,
25
74
or if you don't want to use the built-in HID support for some reason.
75
+
76
+
If you can use built-in HID, you might consider looking at @ref hdk_found, which
77
+
is a nice example of how to implement detection of an HMD based on the USB HID
78
+
for its IMU.
79
+
80
+
Either way, your device's detection details will need to be added to a list used
81
+
by the prober at @ref xrt_instance startup time. The stock lists for mainline
82
+
Monado are in `src/xrt/targets/common/target_lists.c`. These are shared by the
83
+
various targets (OpenXR runtime shared library, service executable, utility
84
+
executables) also found in `src/xrt/targets`. If you're using Monado as a
85
+
toolkit or component rather than as a standalone runtime and service, you can
86
+
replicate whatever portions of the target lists in your own target, or just
87
+
directly implement the @ref xrt_instance interface more directly, linking in
88
+
only those drivers and components you need. **Note**, however, that Monado is
89
+
intended to not expose any external API other than the OpenXR API: the @ref
90
+
xrt_iface are subject to change as required so those writing drivers or other
91
+
software on those interfaces are encouraged to upstream as much as possible to
92
+
minimize maintenance burden.
+2
-21
src/xrt/drivers/sample/sample_interface.h
+2
-21
src/xrt/drivers/sample/sample_interface.h
···
21
21
* @brief Simple do-nothing sample driver, that cannot be detected by USB VID/PID
22
22
* and thus exposes an "auto-prober" to explicitly discover the device.
23
23
*
24
+
* See @ref writing-driver for additional information.
25
+
*
24
26
* This device has an implementation of @ref xrt_auto_prober to perform hardware
25
27
* detection, as well as an implementation of @ref xrt_device for the actual device.
26
28
*
···
28
30
* you can skip the @ref xrt_auto_prober implementation, and instead implement a
29
31
* "found" function that matches the signature expected by xrt_prober_entry::found.
30
32
* See for example @ref hdk_found.
31
-
*
32
-
* After you copy and rename these files, you can customize them with the following,
33
-
* assuming your new device type is called `struct my_device` or `md` for short, and
34
-
* your auto-prober is called `struct my_device_auto_prober` or `mdap` for short:
35
-
*
36
-
* ```sh
37
-
* # First pattern is for renaming device types,
38
-
* # second is for renaming device variables,
39
-
* # third is for renaming device macros.
40
-
* # Fourth and fifth are for renaming auto prober types and variables, respectively.
41
-
* # The last two are for renaming the environment variable and function name
42
-
* # for the environment variable logging config.
43
-
* sed -r -e 's/sample_hmd/my_device/g' \
44
-
* -e 's/\bsh\b/md/g' \
45
-
* -e 's/sample_auto_prober/my_device_auto_prober/g' \
46
-
* -e 's/\bsap\b/mdap/g' \
47
-
* -e 's/\bSH_/MD_/g' \
48
-
* -e 's/sample/my_device/g' \
49
-
* -e 's/SAMPLE/MY_DEVICE/g' \
50
-
* -i *.c *.h
51
-
* ```
52
33
*/
53
34
54
35
/*!