zephyr: Deprecate blocking read sensor APIs

Introduction

The introduction of the asynchronous sensor read and stream APIs have resolved a lot of the previous issues involved with sensors. Though at the current state of things, there are 2 different ways for applications to read sensor data. The redundancy becomes the burden of the driver authors. In order to alleviate this, we propose that after the upcoming 3.7 LTS release, we deprecate the following functions:

  • sensor_sample_fetch()
  • sensor_sample_fetch_chan()
  • sensor_channel_get()

The first two functions can be replaced by the asynchronous sensor_read() functionality, while the latter is replaced by the decoder API. In order to deprecate these, the following conditions must be met:

Hard requirements:

  • Update the samples (at the time of writing there are 19 sensor samples)
  • Update sensor documentation
  • Provide a blocking alternative to sensor_read(). This function (sensor_read_blocking() will allow developers to migrate more easily by effectively fetching, waiting, and decoding). We should also have a backwards compatibility function to convert the new q31_t values to the legacy sensor_value struct such that apps have the easiest time migrating to the new APIs.
  • Fix the sensor clock (RFC# TBD). I haven’t formalized this yet, but effectively, we need a chosen node for a clock which would default to the system one if none were selected. Then all sensor time will be measured off this one clock (which may be an external counter).

Soft requirements:

The above are considered “soft” requirements, because they’re only hard requirements for streaming implementations. We could deprecate the existing fetch/get paths without them.

Enhancements:

  • Allow specifying channels and attributes in devicetree

About this issue

  • Original URL
  • State: open
  • Created 3 years ago
  • Comments: 23 (21 by maintainers)

Most upvoted comments

I’d like to present the following to the Architecture WG as a first step Sensor async API migration.pdf

(this might not be the final slide deck, just the current draft. I’ll post here any updates.)

I’m really becoming a fan of the read_and_decode APIs. Nevertheless, I’m trying to get deeper into this migration stuff, as I own a huge amount of device drivers and I need to understand carefully what the impact will be at my side.

I’ll try to summarize what I understood from the pdf:

There will be two phases: deprecation and migration.

In the deprecation phase the fetch and get APIs will disappears at sample level BUT, if I got it right, the driver inner mechanism will remain the same, which means no need to provide:

  • a RTIO submit routine
  • a decode function
  • other read_and_decode mechanism related stuff

At least this is what I get from the “Driver fetch/get functions will NOT be deprecated” statement in this phase description. I’m also assuming that the new sensor_read_blocking() API will take care of the q31_t translation from sensor_val.

The migration phase will be more time consuming, as the read_and_decode approach should be made available for all sensor drivers. Probably I would need to drop some of the ST old drivers and migrate the rest. The rest of the drivers not necessarily will support the streaming functionality.

Moreover, as of today, I’m working on new drivers. For these drivers, I will ONLY implement read_and_decode mechanism.

@yperess can you confirm I got it right? Especially the deprecation phase. Thx!

Sensor WG:

  • Luis/Yuval: Note the memory ownership making it difficult to provide an implementation of fetch/get with async + decoder in the RFC
  • Yuval: BMA4xx driver only implements new API… shim-less application with a single sensor vs existing API for ram/rom usage
  • Maureen: There will be an interim period with shimmed drivers with increased ram/rom usage from those
  • Yuval: No fetch/get removal until shim is gone (marked deprecated until then).
  • Tom: There’s going to be some ROM increase, likely RAM decrease, and more correct behavior. Not much effort has been put to ROM optimization.
  • Yuval/Maureen: We need to quantify, to some ballpark estimate, what is the cost (~1k rom/X ram, etc)
  • Tom: Quantify which use cases, one temp sensor? Many sensors?
  • Maureen: We need to quantify the simplest case
  • Yuval: Single accelerometer sample, take it, convert it, and measure it.
  • Luis: What are the benefits of this new API, why do we want it?
  • Tom: link issues about why this API is being deprecated
  • Yuval: when do we want to start the deprecation path? We can meet with arch wg before 3.7, April do architecture review (prior to 3.7) to get feedback.
  • Maureen: Bring it to the arch wg soon, ZDS in April. How and when will the driver be migrated?
  • Tom: I think breaking down the maintainership of sensors by vendor helps break down the problem.
  • Yuval: Find/ask authors to update drivers, if not then maintainers would need to work towards doing it.
  • Tom: Exactly, why I want to break down sensors by vendor (tdk/bosch/st/analog)
  • Maureen: Thinking of backporting changes is important. Thinking of deprecating the existing API, when do we stop accepting new drivers using the old API?
  • Yuval: Any non-inflight PRs after the deprecation using the old API shouldn’t be accepted

Another question on new sensor drivers to be submitted. I’m guessing that .trigger_set() API is also going to disappear, as triggers are declared in a different way and will be processed as events and not thru a callback. For the same reason triggers thread are now useless and can be removed.

Do you all agree on that @yperess and @teburd ?

That’s correct, we can drop trigger_set

Another question on new sensor drivers to be submitted. I’m guessing that .trigger_set() API is also going to disappear, as triggers are declared in a different way and will be processed as events and not thru a callback. For the same reason triggers thread are now useless and can be removed.

Do you all agree on that @yperess and @teburd ?

@avisconti you got it 100%

Can we keep the user-facing fetch/get, implementing it using the new async API, instead of deprecating/removing it?

What about adding #77100 as another soft requirement?

I think that’s appropriate for a phase 2. At first we just want to deprecate the static functions exposed in sensor.h so we get users off the API. The migration off the sensor driver API struct will likely include #77100

@yperess I have a few questions on the legacy sensor API deprecation proposal:

  • What does legacy API deprecation mean? Does it mean that these APIs will be eventually removed in Zephyr?
  • How about legacy Zephyr sensor device drivers? Are we going to upgrade them, or we implement shim for them, or we simply deprecate them, or we review them one by one and decide case by case?
  • If we are going to upgrade them, who is going to do it, and is there a timeline?
  • If we are going to add shim to them for now, then later are we going to remove shim?
  • I agree that mixing the new API with legacy API is confusing, instead of deprecate the legacy API, will it be better to simply separate the new API out (like put it to sensor_async.h)? Meaning that we keep the legacy API and sensor device drivers as is, and introduce the new async API (in separate header) and new async sensor device drivers (in separate folder).
  • For the new API naming like sensor_stream_xxx, will it be better to be renamed? Streaming sensor and event sensor are two different terminologies in sensor world, conceptual wise, using sensor_stream_xxx for event based sensor looks a bit weird, and can easily create confusion.
  • I am not sure the overhead of new API on the simplest sensor device driver, like HALL sensor, basically it does not use any new feature introduced by the new API. Do we have any comparison data?

If you have one application that has blocking read, and convert that to this new async. method, can you list the RAM and flash usages for both of these so the 2 can be compared?