Boot Linux faster!

Check our new training course

Boot Linux faster!

Check our new training course
and Creative Commons CC-BY-SA
lecture and lab materials

Bootlin logo

Elixir Cross Referencer

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
/*
 * Copyright (c) 2018 Nordic Semiconductor ASA
 * Copyright (c) 2016 Intel Corporation
 *
 * SPDX-License-Identifier: Apache-2.0
 */

/**
 * @file
 * @brief Public API for counter and timer drivers
 */

#ifndef ZEPHYR_INCLUDE_COUNTER_H_
#define ZEPHYR_INCLUDE_COUNTER_H_

/**
 * @brief Counter Interface
 * @defgroup counter_interface Counter Interface
 * @ingroup io_interfaces
 * @{
 */

#include <zephyr/types.h>
#include <stddef.h>
#include <device.h>
#include <stdbool.h>

#ifdef __cplusplus
extern "C" {
#endif

/** @brief Alarm callback
 *
 * @param dev       Pointer to the device structure for the driver instance.
 * @param chan_id   Channel ID.
 * @param ticks     Counter value that triggered the callback.
 * @param user_data User data.
 */
typedef void (*counter_alarm_callback_t)(struct device *dev,
					 u8_t chan_id, u32_t ticks,
					 void *user_data);

/** @brief Alarm callback structure.
 *
 * @param callback Callback called on alarm (cannot be NULL).
 * @param ticks Ticks that triggers the alarm. In case of absolute flag is set,
 *		maximal value that can be set equals top value
 *		(@ref counter_get_top_value). Otherwise
 *		@ref counter_get_max_relative_alarm() returns maximal value that
 *		can be set. If counter is clock driven then ticks can be
 *		converted to microseconds (see @ref counter_ticks_to_us).
 *		Alternatively, counter implementation may count asynchronous
 *		events.
 * @param user_data User data returned in callback.
 * @param absolute Ticks relation to counter value. If true ticks are treated as
 *		absolute value, else it is relative to the counter reading
 *		performed during the call.
 */
struct counter_alarm_cfg {
	counter_alarm_callback_t callback;
	u32_t ticks;
	void *user_data;
	bool absolute;
};

/** @brief Callback called when counter turns around.
 *
 * @param dev       Pointer to the device structure for the driver instance.
 * @param user_data User data provided in @ref counter_set_top_value.
 */
typedef void (*counter_top_callback_t)(struct device *dev, void *user_data);

/** @brief Structure with generic counter features.
 *
 * @param max_top_value Maximal (default) top value on which counter is reset
 *			(cleared or reloaded).
 * @param freq		Frequency of the source clock if synchronous events are
 *			counted.
 * @param count_up	Flag indicating direction of the counter. If true
 *			counter is counting up else counting down.
 * @param channels	Number of channels that can be used for setting alarm,
 *			see @ref counter_set_alarm.
 */
struct counter_config_info {
	u32_t max_top_value;
	u32_t freq;
	bool count_up;
	u8_t channels;
};

typedef int (*counter_api_start)(struct device *dev);
typedef int (*counter_api_stop)(struct device *dev);
typedef u32_t (*counter_api_read)(struct device *dev);
typedef int (*counter_api_set_alarm)(struct device *dev, u8_t chan_id,
				const struct counter_alarm_cfg *alarm_cfg);
typedef int (*counter_api_cancel_alarm)(struct device *dev, u8_t chan_id);
typedef int (*counter_api_set_top_value)(struct device *dev, u32_t ticks,
				    counter_top_callback_t callback,
				    void *user_data);
typedef u32_t (*counter_api_get_pending_int)(struct device *dev);
typedef u32_t (*counter_api_get_top_value)(struct device *dev);
typedef u32_t (*counter_api_get_max_relative_alarm)(struct device *dev);
typedef void *(*counter_api_get_user_data)(struct device *dev);

struct counter_driver_api {
	counter_api_start start;
	counter_api_stop stop;
	counter_api_read read;
	counter_api_set_alarm set_alarm;
	counter_api_cancel_alarm cancel_alarm;
	counter_api_set_top_value set_top_value;
	counter_api_get_pending_int get_pending_int;
	counter_api_get_top_value get_top_value;
	counter_api_get_max_relative_alarm get_max_relative_alarm;
	counter_api_get_user_data get_user_data;
};


/**
 * @brief Function to check if counter is counting up.
 *
 * @param[in]  dev    Pointer to the device structure for the driver instance.
 *
 * @retval true if counter is counting up.
 * @retval false if counter is counting down.
 */
static inline bool counter_is_counting_up(const struct device *dev)
{
	const struct counter_config_info *config =
			(struct counter_config_info *)dev->config->config_info;

	return config->count_up;
}

/**
 * @brief Function to get number of alarm channels.
 *
 * @param[in]  dev    Pointer to the device structure for the driver instance.
 *
 * @return Number of alarm channels.
 */
static inline u8_t counter_get_num_of_channels(const struct device *dev)
{
	const struct counter_config_info *config =
			(struct counter_config_info *)dev->config->config_info;

	return config->channels;
}

/**
 * @brief Function to get counter frequency.
 *
 * @param[in]  dev    Pointer to the device structure for the driver instance.
 *
 * @return Frequency of the counter in Hz, or zero if the counter does
 * not have a fixed frequency.
 */
static inline u32_t counter_get_frequency(const struct device *dev)
{
	const struct counter_config_info *config =
			(struct counter_config_info *)dev->config->config_info;

	return config->freq;
}

/**
 * @brief Function to convert microseconds to ticks.
 *
 * @param[in]  dev    Pointer to the device structure for the driver instance.
 * @param[in]  us     Microseconds.
 *
 * @return Converted ticks. Ticks will be saturated if exceed 32 bits.
 */
static inline u32_t counter_us_to_ticks(const struct device *dev, u64_t us)
{
	const struct counter_config_info *config =
			(struct counter_config_info *)dev->config->config_info;
	u64_t ticks = (us * config->freq) / USEC_PER_SEC;

	return (ticks > (u64_t)UINT32_MAX) ? UINT32_MAX : ticks;
}

/**
 * @brief Function to convert ticks to microseconds.
 *
 * @param[in]  dev    Pointer to the device structure for the driver instance.
 * @param[in]  ticks  Ticks.
 *
 * @return Converted microseconds.
 */
static inline u64_t counter_ticks_to_us(const struct device *dev, u32_t ticks)
{
	const struct counter_config_info *config =
			(struct counter_config_info *)dev->config->config_info;

	return ((u64_t)ticks * USEC_PER_SEC) / config->freq;
}

/**
 * @brief Function to retrieve maximum top value that can be set.
 *
 * @param[in]  dev    Pointer to the device structure for the driver instance.
 *
 * @return Max top value.
 */
static inline u32_t counter_get_max_top_value(const struct device *dev)
{
	const struct counter_config_info *config =
			(struct counter_config_info *)dev->config->config_info;

	return config->max_top_value;
}

/**
 * @brief Start counter device in free running mode.
 *
 * @param dev Pointer to the device structure for the driver instance.
 *
 * @retval 0 If successful.
 * @retval Negative errno code if failure.
 */
__syscall int counter_start(struct device *dev);

static inline int z_impl_counter_start(struct device *dev)
{
	const struct counter_driver_api *api =
				(struct counter_driver_api *)dev->driver_api;

	return api->start(dev);
}

/**
 * @brief Stop counter device.
 *
 * @param dev Pointer to the device structure for the driver instance.
 *
 * @retval 0 If successful.
 * @retval -ENOTSUP if the device doesn't support stopping the
 *                        counter.
 */
__syscall int counter_stop(struct device *dev);

static inline int z_impl_counter_stop(struct device *dev)
{
	const struct counter_driver_api *api =
				(struct counter_driver_api *)dev->driver_api;

	return api->stop(dev);
}

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

static inline u32_t z_impl_counter_read(struct device *dev)
{
	const struct counter_driver_api *api =
				(struct counter_driver_api *)dev->driver_api;

	return api->read(dev);
}

/**
 * @brief Set a single shot alarm on a channel.
 *
 * After expiration alarm can be set again, disabling is not needed. When alarm
 * expiration handler is called, channel is considered available and can be
 * set again in that context.
 *
 * @note API is not thread safe.
 *
 * @param dev		Pointer to the device structure for the driver instance.
 * @param chan_id	Channel ID.
 * @param alarm_cfg	Alarm configuration.
 *
 * @retval 0 If successful.
 * @retval -ENOTSUP if request is not supported (device does not support
 *		    interrupts or requested channel).
 * @retval -EINVAL if alarm settings are invalid.
 */
static inline int counter_set_channel_alarm(struct device *dev, u8_t chan_id,
				      const struct counter_alarm_cfg *alarm_cfg)
{
	const struct counter_driver_api *api =
				(struct counter_driver_api *)dev->driver_api;

	if (chan_id >= counter_get_num_of_channels(dev)) {
		return -ENOTSUP;
	}

	return api->set_alarm(dev, chan_id, alarm_cfg);
}

/**
 * @brief Cancel an alarm on a channel.
 *
 * @note API is not thread safe.
 *
 * @param dev		Pointer to the device structure for the driver instance.
 * @param chan_id	Channel ID.
 *
 * @retval 0 If successful.
 * @retval -ENOTSUP if request is not supported or the counter was not started
 *		    yet.
 */
static inline int counter_cancel_channel_alarm(struct device *dev,
						u8_t chan_id)
{
	const struct counter_driver_api *api =
				(struct counter_driver_api *)dev->driver_api;

	if (chan_id >= counter_get_num_of_channels(dev)) {
		return -ENOTSUP;
	}

	return api->cancel_alarm(dev, chan_id);
}

/**
 * @brief Set counter top value.
 *
 * Function sets top value and resets the counter to 0 or top value
 * depending on counter direction. On turnaround, counter is reset and optional
 * callback is periodically called. Top value can only be changed when there
 * is no active channel alarm.
 *
 * @param dev		Pointer to the device structure for the driver instance.
 * @param ticks		Top value.
 * @param callback	Callback function. Can be NULL.
 * @param user_data	User data passed to callback function. Not valid if
 *			callback is NULL.
 *
 * @retval 0 If successful.
 * @retval -ENOTSUP if request is not supported (e.g. top value cannot be
 *		    changed).
 * @retval -EBUSY if any alarm is active.
 */
static inline int counter_set_top_value(struct device *dev, u32_t ticks,
					counter_top_callback_t callback,
					void *user_data)
{
	const struct counter_driver_api *api =
				(struct counter_driver_api *)dev->driver_api;

	if (ticks > counter_get_max_top_value(dev)) {
		return -EINVAL;
	}

	return api->set_top_value(dev, ticks, callback, user_data);
}

/**
 * @brief Function to get pending interrupts
 *
 * The purpose of this function is to return the interrupt
 * status register for the device.
 * This is especially useful when waking up from
 * low power states to check the wake up source.
 *
 * @param dev Pointer to the device structure for the driver instance.
 *
 * @retval 1 if any counter interrupt is pending.
 * @retval 0 if no counter interrupt is pending.
 */
__syscall int counter_get_pending_int(struct device *dev);

static inline int z_impl_counter_get_pending_int(struct device *dev)
{
	const struct counter_driver_api *api =
				(struct counter_driver_api *)dev->driver_api;

	return api->get_pending_int(dev);
}

/**
 * @brief Function to retrieve current top value.
 *
 * @param[in]  dev    Pointer to the device structure for the driver instance.
 *
 * @return Top value.
 */
__syscall u32_t counter_get_top_value(struct device *dev);

static inline u32_t z_impl_counter_get_top_value(struct device *dev)
{
	const struct counter_driver_api *api =
				(struct counter_driver_api *)dev->driver_api;

	return api->get_top_value(dev);
}

/**
 * @brief Function to retrieve maximum relative value that can be set by
 *        counter_set_alarm.
 *
 * @param[in]  dev    Pointer to the device structure for the driver instance.
 *
 * @return Max alarm value.
 */
__syscall u32_t counter_get_max_relative_alarm(struct device *dev);

static inline u32_t z_impl_counter_get_max_relative_alarm(struct device *dev)
{
	const struct counter_driver_api *api =
				(struct counter_driver_api *)dev->driver_api;

	return api->get_max_relative_alarm(dev);
}

/* Deprecated counter callback. */
typedef void (*counter_callback_t)(struct device *dev, void *user_data);

/**
 * @brief Deprecated function.
 */
__deprecated static inline int counter_set_alarm(struct device *dev,
						 counter_callback_t callback,
						 u32_t count, void *user_data)
{
	return counter_set_top_value(dev, count, callback, user_data);
}

/**
 * @brief Get user data set for top alarm.
 *
 * @note Function intended to be used only by deprecated RTC driver API to
 * provide backward compatibility.
 *
 * @param dev Pointer to the device structure for the driver instance.
 *
 * @return User data.
 */
__deprecated static inline void *counter_get_user_data(struct device *dev)
{
	const struct counter_driver_api *api =
				(struct counter_driver_api *)dev->driver_api;

	if (api->get_user_data) {
		return api->get_user_data(dev);
	} else {
		return NULL;
	}
}

#ifdef __cplusplus
}
#endif

/**
 * @}
 */

#include <syscalls/counter.h>

#endif /* ZEPHYR_INCLUDE_COUNTER_H_ */