Re: Counter API ambiguity.

Tseng, Kuo-Lang <kuo-lang.tseng@...>


From: zephyr-devel-bounces@... [mailto:zephyr-devel-
bounces@...] On Behalf Of Michal Kruszewski via Zephyr-devel
Sent: Monday, August 28, 2017 1:51 AM
To: zephyr-devel@...
Subject: [Zephyr-devel] Counter API ambiguity.

In the counter API we can find following function with its description:

* @brief Set an alarm.
* @param dev Pointer to the device structure for the driver instance.
* @param callback Pointer to the callback function. if this is NULL,
*                 this function unsets the alarm.
* @param count Number of counter ticks.
* @param user_data Pointer to user data.
* @retval 0 If successful.
* @retval -ENOTSUP if the counter was not started yet.
* @retval -ENODEV if the device doesn't support interrupt (e.g. free
*                        running counters).
* @retval Negative errno code if failure.
static inline int counter_set_alarm(struct device *dev,
    counter_callback_t callback,
    u32_t count, void *user_data)
const struct counter_driver_api *api = dev->driver_api;

return api->set_alarm(dev, callback, count, user_data); }

Description: * @param count Number of counter ticks is misleading because it is
not explicitly defined if it is relative count (relative to current counter value) or
absolute counter count value.
Baohong can correct me. I believe this is the number of counter ticks for the counter to send a notification. User would not need to know what current counter value is; when the API is called, the counter would start counting this number of ticks and when it reaches to that many ticks, it would generate a notification, i.e. the callback will be invoked.

Can anyone clarify it and can we make PR to add that information to API so that
application developers do not interpret it in wrong way?

Michał Kruszewski

Sent with ProtonMail Secure Email.

Join to automatically receive all group messages.