This is an automated email from the ASF dual-hosted git repository. xiaoxiang781216 pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit 68f4dff0992c553788c9434e3d6d0646a4fabc02 Author: Felipe Moura <[email protected]> AuthorDate: Sat Aug 29 13:24:08 2026 -0300 Documentation/lsm6ds3trc: document FIFO mode and its quirks Adds a section covering CONFIG_SENSORS_LSM6DS3TRC_FIFO: what it changes (one interrupt/I2C read per watermark instead of per sample) and its three limitations while it's on -- both sub-sensors forced to the same ODR, temperature no longer per-sample (one read per drain applied to the whole batch), and both sub-sensors must stay physically enabled regardless of subscription, since the chip's FIFO write trigger needs both running -- plus the watermark/ORB-buffer-size relationship callers need to respect. Also documents a related chip quirk found during bench testing: diff_words reads 0 at the exact moment a real FIFO overrun occurs, even though the FIFO is still completely full of valid, retained data (a forced read past that point recovers real samples, not garbage). This isn't a bug in this driver: ST's own engineers confirm the same behavior for this chip family on their community forum (thread "LSM6DS3 FIFO status clarification", td-p/184022), and the mainline Linux st_lsm6dsx driver doesn't attempt to recover from it either -- it only special-cases an empty FIFO, not an overrun one. Documenting this in a comment rather than adding recovery logic: with the small watermark this driver uses, reaching a real overrun at all means the drain has already fallen many seconds behind, and ST's own guidance for this condition is to avoid it via watermark sizing rather than recover from it. Signed-off-by: Felipe Moura <[email protected]> --- .../drivers/special/sensors/lsm6ds3trc.rst | 36 ++++++++++++++++++++++ drivers/sensors/lsm6ds3trc_uorb.c | 18 +++++++++++ 2 files changed, 54 insertions(+) diff --git a/Documentation/components/drivers/special/sensors/lsm6ds3trc.rst b/Documentation/components/drivers/special/sensors/lsm6ds3trc.rst index 8d770c8a892..ad0f0dba90a 100644 --- a/Documentation/components/drivers/special/sensors/lsm6ds3trc.rst +++ b/Documentation/components/drivers/special/sensors/lsm6ds3trc.rst @@ -132,6 +132,42 @@ sensor, read in the same burst transaction as whichever sub-sensor's sample triggered it -- it does not have an independent output data rate of its own in this driver. +FIFO mode +========= + +Setting ``CONFIG_SENSORS_LSM6DS3TRC_FIFO=y`` switches interrupt-driven +delivery from one uORB event per data-ready interrupt to draining the +chip's hardware FIFO on a watermark interrupt instead -- one interrupt and +one I2C burst read per +``CONFIG_SENSORS_LSM6DS3TRC_FIFO_WATERMARK`` samples, rather than per +sample. This cuts interrupt and I2C-wakeup frequency roughly by the +watermark size, at the cost of three limitations while it's on: + +- Both the accelerometer and gyroscope are forced to the same output + data rate. Whichever sub-sensor activates first sets it; a second + subscriber joins that rate instead of using its own. +- Per-sample temperature isn't available -- the FIFO pattern doesn't + include it. One direct temperature read happens per drain and is + applied to every sample in that batch instead. +- The chip's FIFO write trigger only fires while both the accelerometer + and the gyroscope are physically running, even if only one of them is + actually subscribed. This driver forces the unsubscribed sub-sensor + on at the shared rate to make the FIFO work at all -- it's still left + out of the FIFO pattern itself, so this doesn't cost extra I2C + bandwidth on drain, but it does mean FIFO mode cannot power down the + unused sub-sensor the way non-FIFO interrupt-driven mode can. + +.. warning:: + ``CONFIG_SENSORS_LSM6DS3TRC_FIFO_WATERMARK`` is in samples, not raw + FIFO words, but it must not exceed + ``CONFIG_SENSORS_LSM6DS3TRC_ACCEL_ORB_BUFSIZE`` or + ``CONFIG_SENSORS_LSM6DS3TRC_GYRO_ORB_BUFSIZE`` -- a single drain can + push that many events into each topic's uORB ring buffer at once, and + a smaller buffer drops the oldest ones. + +FIFO mode only takes effect in interrupt-driven mode (a real ``attach()`` +in ``lsm6ds3trc_config_s``); it's silently unused in kthread polling mode. + This sensor also has an additional command for gaining access to extra functionality. diff --git a/drivers/sensors/lsm6ds3trc_uorb.c b/drivers/sensors/lsm6ds3trc_uorb.c index 7a9558652e9..86f2b78f0eb 100644 --- a/drivers/sensors/lsm6ds3trc_uorb.c +++ b/drivers/sensors/lsm6ds3trc_uorb.c @@ -874,6 +874,24 @@ static void lsm6ds3trc_fifo_worker(FAR void *arg) if (status[1] & BIT_FIFO_STATUS2_OVER_RUN) { snerr("WARNING: LSM6DS3TR-C FIFO overrun, some samples were lost\n"); + + /* diff_words reads 0 here, not the FIFO's actual (still full) + * content -- confirmed on hardware (a forced read past this point + * recovers real, valid samples) and independently confirmed by + * ST's own engineers for this chip family: once Continuous mode + * genuinely overruns, DIFF_FIFO resets to 0 while OVER_RUN/WaterM/ + * FIFO_FULL_SMART stay set (see ST's community forum, thread + * "LSM6DS3 FIFO status clarification", td-p/184022). + * Recovering the still-present data would mean assuming the + * FIFO is at capacity rather than trusting diff_words -- skipped + * here on purpose: with the small watermark this driver uses, + * reaching a real overrun at all means the drain has already + * fallen many seconds behind, and ST's own guidance for this + * condition is to avoid it via watermark sizing rather than + * recover from it. The mainline Linux st_lsm6dsx driver, for the + * same chip family, doesn't attempt recovery here either -- it + * only special-cases an empty FIFO, not an overrun one. + */ } /* Round down to a whole number of pattern chunks -- never split one
