diff options
author | Yuval Peress <peress@google.com> | 2022-02-12 23:19:22 -0700 |
---|---|---|
committer | Commit Bot <commit-bot@chromium.org> | 2022-02-18 06:10:27 +0000 |
commit | 94bded51c57db4ea51dbc473914127eb62a23a5f (patch) | |
tree | 35e8ad9bc3be11fd71ffe8ff94295b6a83201317 | |
parent | bf490a7129e65808be6e35f15e537bd0875bf884 (diff) | |
download | chrome-ec-94bded51c57db4ea51dbc473914127eb62a23a5f.tar.gz |
docs: zephyr: Add more information about motionsense
Add details about the various devicetree nodes and configuration needed
for Zephyr motionsense initialization.
BRANCH=none
BUG=b:208437221
TEST=none
Signed-off-by: Yuval Peress <peress@google.com>
Change-Id: Id2b0b7622bfc387119a3977069adf673f6943e68
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/3459942
Reviewed-by: Keith Short <keithshort@chromium.org>
-rw-r--r-- | docs/zephyr/zephyr_motionsense.md | 52 |
1 files changed, 49 insertions, 3 deletions
diff --git a/docs/zephyr/zephyr_motionsense.md b/docs/zephyr/zephyr_motionsense.md index e140876310..5c2a90d93f 100644 --- a/docs/zephyr/zephyr_motionsense.md +++ b/docs/zephyr/zephyr_motionsense.md @@ -72,10 +72,56 @@ Kconfig sub-option | Default | Documentation ## Devicetree Nodes -*Detail the devicetree nodes that configure the feature.* +Initiating the devicetree nodes for motionsense requires a bit of internal +knowledge of the drivers' +[bindings](https://source.chromium.org/chromium/chromiumos/platform/ec/+/HEAD:zephyr/dts/bindings/motionsense/). -*Note - avoid documenting node properties here. Point to the relevant `.yaml` -file instead, which contains the authoritative definition.* +### Sensor mutex + +Some drivers, such as the BMI260, which combine 2 sensors (accelerometer and +gyroscope) will require a mutex to be defined. The individual nodes in the +devicetree will accept a `phandle` pointing to the mutex +[here](https://source.chromium.org/chromium/chromiumos/platform/ec/+/HEAD:zephyr/dts/bindings/motionsense/motionsense-sensor-base.yaml;l=37;drc=67e0b58c17177858595001baa1aa607b54b18d11). +It is important for both nodes of these sensors to point to the same mutex ( +see example below). + +### Location and orientation + +The location of the sensor is dictated in an enum property +[location](https://source.chromium.org/chromium/chromiumos/platform/ec/+/HEAD:zephyr/dts/bindings/motionsense/motionsense-sensor-base.yaml;l=29;drc=67e0b58c17177858595001baa1aa607b54b18d11). +It is important to note that sensors which are combined in a single chip (such +as the BMI260) should have the same value for both nodes. +This property allows the distinction between sensors location at the following: + +* "base" - the base of the laptop (where the keyboard is). +* "lid" - the screen surface of the laptop. +* "camera" - an explicit location for the camera. + +In addition to the location, each sensor node should also include a reference +to a [rotation matrix](https://source.chromium.org/chromium/chromiumos/platform/ec/+/HEAD:zephyr/dts/bindings/motionsense/motionsense-sensor-base.yaml;l=45;drc=67e0b58c17177858595001baa1aa607b54b18d11). +This will be used to orient the sensor data according to the standardised screen +coordinates. + +### Internal sensor data + +Internal sensor data nodes can be found [here](https://source.chromium.org/chromium/chromiumos/platform/ec/+/HEAD:zephyr/dts/bindings/motionsense/drvdata/). +These are required, one per physical sensor, in order to instantiate the +internal data structures. It is important to check the required properties of +each binding to ensure proper instantiation. + +### Motion sensor nodes + +All motion sensor nodes (accel, gyro, and mag) should be declared inside the +`motionsense-sensor` node. This will in-turn create the `motion_sensors` array +required for the sensor logic. + +### Additional sensor meta-data + +Additional information about sensors can be provided by the +[motionsense-sensor-info](https://source.chromium.org/chromium/chromiumos/platform/ec/+/HEAD:zephyr/dts/bindings/motionsense/cros-ec,motionsense-sensor-info.yaml). +This node provides information about the ALS (ambient light sensor) list, the +various interrupts, and sensors which are placed in force mode (motionsense will +directly query these sensors instead of waiting for an interrupt). ## Board Specific Code |