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)
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:
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:
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?
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:
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?