RFC: API: Counter: counter_read() has no way of indicating failure

[henrikbrixandersen]

Introduction

The counter API has a method for reading the current counter value with the following function prototype:

u32_t counter_read(struct device *dev);

This API function does not allow any standard way of indicating a "read failure" since the return value is just the raw, 32-bit counter value.

Problem description

Counters, like most other devices, may be connected to the SoC/MCU using an external bus (I2C, SPI, ...) where communication errors can occur. Our current counter API allows indicating failures from all other API functions than the counter_read() function.

Proposed change

I suggest introducing a new counter API function for reading the counter value with the current function prototype:

int counter_get_value(struct device *dev, u32_t *ticks);

This new API function will effectively replace counter_read(), which can then be deprecated. During the deprecation period, counter_read() can be implemented using the newly introduced counter_get_value() API function and return 0 if counter_get_value() returned a negative error code.

Detailed RFC

• Introduce counter_get_value() counter API syscall and handler
• Deprecate counter_read() counter API syscall and handler and reimplement it using counter_get_value()
• Introduce counter_api_get_value() typedef to replace existing counter_api_get_value()
• Update all in-tree counter drivers to match the new counter driver API (most will just return a value of zero)

Proposed change (Detailed)

See above.

Dependencies

This change will require users updating any out-of-tree counter drivers, but the application API can remain the same during the deprecation period.

Concerns and Unresolved Questions

None so far.

Alternatives

None so far.

[nordic-krch]

Sounds ok. Counter API was initially created for internal peripherals thus direct readout but as it fits external devices then it should be extended.

[henrikbrixandersen]

Great. Thanks for your feedback. What is the next step here? Should I create a pull request?

[carlescufi]

Great. Thanks for your feedback. What is the next step here? Should I create a pull request?

Yes, and you can also deprecate counter_read() in the same PR. Since this is not a Stable API change (without deprecation) you don't need to do anything extra in this case.

EDIT: @henrikbrixandersen I was wrong, this is listed as an unstable API so the only thing you need to do is to change the API call directly (no need to rename it, just change the signature) and then add a small note in the release notes.

[henrikbrixandersen]

PR creation is awaiting #22030.

[andrewboie]

+1 to this proposal