docs: zephyr: Provide example of motionsense DTS

Add an example of the various devicetree compontents of initializing
motionsense.

BRANCH=none
BUG=b:208437221
TEST=none

Signed-off-by: Yuval Peress <peress@google.com>
Change-Id: Ie2be39bd378ff8c6ccd868d916cc10a6a410e098
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/3459249
Reviewed-by: Keith Short <keithshort@chromium.org>

1 files changed, 101 insertions, 6 deletions

diff --git a/docs/zephyr/zephyr_motionsense.md b/docs/zephyr/zephyr_motionsense.md
index dc55825125..4a305537fe 100644
--- a/docs/zephyr/zephyr_motionsense.md
+++ b/docs/zephyr/zephyr_motionsense.md
@@ -164,13 +164,108 @@ Properly debugging the sensor framework generally involves one of the following:
 
 ## Example
 
-*Provide code snippets from a working board to walk the user through
-all code that must be created to enable this feature.*
+### Create the mutex
+
+The mutexes are created as child nodes of the `cros-ec,motionsense-mutex`
+compatible string.
+
+```
+motionsense-mutex {
+  compatible = "cros-ec,motionsense-mutex";
+  lid_mutex: lid-mutex {
+    label = "LID_MUTEX";
+  };
+};
+```
+
+### Create the rotation reference
+
+The rotation references are created as child nodes of the
+`cros-ec,motionsense-rotation-ref` compatible string.
+
+```
+motionsense-rotation-ref {
+  compatible = "cros-ec,motionsense-rotation-ref";
+  lid_rot_ref: lid-rotation-ref {
+    mat33 = <1 0 0
+             0 1 0
+             0 0 1>;
+  };
+};
+```
+
+### Create the sensor data
+
+Data structures are iterated by their compatible string and do not need to be
+clustered under a parent node (though they usually are).
+
+```
+bmi260_data: bmi260-drv-data {
+  compatible = "cros-ec,drvdata-bmi260";
+  status = "okay";
+};
+```
+
+### Create the sensor list
+
+The sensor list is created from the child nodes of the `motionsense-sensor`
+node.
+
+```
+motionsense-sensor {
+  lid_accel: lid-accel {
+    compatible = "cros-ec,bmi260-accel";
+    status = "okay";
+    label = "Lid Accel";
+    /* Set the active mask so this sensor will be on in both S0 and S3 */
+    active-mask = "SENSOR_ACTIVE_S0_S3";
+    /* Set the location of the sensor */
+    location = "MOTIONSENSE_LOC_LID";
+    /* Set the mutex (must be the same as the gyro) */
+    mutex = <&lid_mutex>;
+    /* Set the rotation reference */
+    rot-standard-ref = <&lid_rot_ref>;
+    /* Set the data for the driver (must be the same as the gyro) */
+    drv-data = <&bmi260_data>;
+  };
+  lid_gyro: lid-gyro {
+    compatible = "cros-ec,bmi260-gyro";
+    status = "okay";
+    label = "Lid Gyro";
+    active-mask = "SENSOR_ACTIVE_S0_S3";
+    location = "MOTIONSENSE_LOC_LID";
+    mutex = <&lid_mutex>;
+    rot-standard-ref = <&lid_rot_ref>;
+    drv-data = <&bmi260_data>;
+  };
+};
+```
+
+### Configuring the sensor
+
+Some additional configurations can be provided to the first node of a sensor.
+For example, in the above, the `lid_accel` can include a `configs` section which
+will allow the EC to automatically re-configure the sensor on various power
+levels. For example, the following will enable the lid accelerometer in both
+`S0` and `S3` and set the `ODR` to 10,000mHz or the nearest higher sample rate.
+
+```
+lid_accel: lid-accel {
+  ...
+  configs {
+    compatible = "cros-ec,motionsense-sensor-config";
+    ec-s0 {
+      label = "SENSOR_CONFIG_EC_S0";
+      odr = <(10000 | ROUND_UP_FLAG)>;
+    };
+    ec-s3 {
+      label = "SENSOR_CONFIG_EC_S3";
+      odr = <(10000 | ROUND_UP_FLAG)>;
+    };
+  };
+};
+```
 
-<!--
-The following demonstrates linking to a code search result for a Kconfig option.
-Reference this link in your text by matching the text in brackets exactly.
--->
 [MOTIONSENSE]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig.motionsense;?q="config%20PLATFORM_EC_MOTIONSENSE"&ss=chromiumos
 [ACCEL FIFO]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig.motionsense;?q="config%20PLATFORM_EC_ACCEL_FIFO"&ss=chromiumos
 [TIGHT TIMESTAMPS]: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/ec/zephyr/Kconfig.motionsense;?q="config%20PLATFORM_EC_SENSOR_TIGHT_TIMESTAMPS"&ss=chromiumos