-----Original Message-----
From: Dirk Brandewie [mailto:dirk.j.brandewie(a)intel.com]
Sent: Tuesday, March 01, 2016 10:33 AM
To: Tseng, Kuo-Lang <kuo-lang.tseng(a)intel.com>; devel(a)lists.zephyrproject.org
Cc: Brandewie, Dirk J <dirk.j.brandewie(a)intel.com>
Subject: Re: [devel] RFC: Counter driver API



On 02/26/2016 12:29 PM, Tseng, Kuo-Lang wrote:

Hi,

As per suggestion from Gerrit comment, moving the discussion to mailing list.

Background
--------------

On Quark (SE and D2000), there are Always On Counter (free running) and Always

ON Periodic Timer devices. A counter|timer driver is to be added for supporting
these devices. At same time, the goal is to create an API that is generic enough for
not just these two specific devices.

Proposal:
-----------

Generic counter driver API:
-------------------------------
We will have 3 routines - start, stop, and read, which takes in the device pointer -

which identifies the timer. The driver header, counter.h, is under /include folder:

I think it might be useful to add a function to retrieve the timebase of the counter.
ATM the developer just needs to *know* what is being counted.

A function to set the timebase may be needed in the future for IP blocks that don't
have a fixed timebase/tick rate.

/**
* @brief Set up counter configuration and start it.
* @param dev Pointer to the device structure for the driver instance.
* @param config Pointer to counter configuration structure
*
* @retval DEV_OK If successful.
* @retval DEV_* Code otherwise.
*/
int counter_start(struct device *dev, counter_input *config);

/**
* @brief Stop the counter.
* @param dev Pointer to the device structure for the driver instance.
*
* @retval DEV_OK If successful.
* @retval DEV_* Code otherwise.
*/
int counter_stop(struct device *dev);

/**
* @brief Read current counter value
* @param dev Pointer to the device structure for the driver instance.
*
* @return 32-bit value
*/
uint32_t counter_read(struct device *dev)

Do we need a write() function for future proofing?

For write, current API counter_start is the API; the initial_value field in the counter_input data structure can be re-configured whenever a new value needs to be re-loaded to the periodic timer.

The counter_input structure can be something like below:

/**
* @brief Counter configuration.
*
* Acceptable setting in the configuration structure is hardware-specific.
*
* initial_value - Initial value to load to the counter or timer.
* callback - Callback function when timer expires.
*/
struct counter_input {

counter_init?

uint32_t initial_value;

countdown_value?

void (*callback)(void);

void (*callback)(void *context);
void *context;
lets the app pass in their context if needed.

};

Note - Using structure, tomorrow we can add more fields for a counter with more

features.

For the Free Running counter in Quark, these fields would be null as it does not

support interrupt or callback notification.

The hardware-specific driver implementation:
-----------------------------------

This can be implemented in /drivers directory. For example, for Quark SE and

D2000, we can have below file which implements the API functionality using the
AON Counter and AON Periodic Timer:

drivers/quark_aon_counter.c

Comment, feedback welcome.