2  * \file timer/timer.c
3  * \brief Timer Interface
7  * Timer Interface is designed to access timers.
8  * See \ref timer page for more details.
11  *  Timer Interface - main file
31 /*! \page timer Timer interface
33 <P> Timer interface is designed to use internal timers in sound hardware, but
34 it can be driven with any timer.
38 The timer implementation uses ring buffer to store information about timing
44 Timer devices can be opened in two ways. When #SND_TIMER_OPEN_NONBLOCK flag
58 \par Simple timer test program
61 This example shows opening a timer device and reading of timer events.
66  * \example ../test/timer.c
74 static int snd_timer_open_conf(snd_timer_t **timer,  in snd_timer_open_conf()  argument
92 			SNDERR("Invalid type for TIMER %s definition", name);  in snd_timer_open_conf()
94 			SNDERR("Invalid type for TIMER definition");  in snd_timer_open_conf()
115 			SNDERR("Invalid type for TIMER type %s definition", str);  in snd_timer_open_conf()
169 		err = open_func(timer, name, timer_root, timer_conf, mode);  in snd_timer_open_conf()
173 			(*timer)->dl_handle = h;  in snd_timer_open_conf()
178 static int snd_timer_open_noupdate(snd_timer_t **timer, snd_config_t *root, const char *name, int m…  in snd_timer_open_noupdate()  argument
182 	err = snd_config_search_definition(root, "timer", name, &timer_conf);  in snd_timer_open_noupdate()
184 		SNDERR("Unknown timer %s", name);  in snd_timer_open_noupdate()
187 	err = snd_timer_open_conf(timer, name, root, timer_conf, mode);  in snd_timer_open_noupdate()
193  * \brief Opens a new connection to the timer interface.
194  * \param timer Returned handle (NULL if not wanted)
195  * \param name ASCII identifier of the timer handle
199  * Opens a new connection to the timer interface specified with
202 int snd_timer_open(snd_timer_t **timer, const char *name, int mode)  in snd_timer_open()  argument
207 	assert(timer && name);  in snd_timer_open()
217 	err = snd_timer_open_noupdate(timer, top, name, mode);  in snd_timer_open()
223  * \brief Opens a new connection to the timer interface using local configuration
224  * \param timer Returned handle (NULL if not wanted)
225  * \param name ASCII identifier of the timer handle
230  * Opens a new connection to the timer interface specified with
233 int snd_timer_open_lconf(snd_timer_t **timer, const char *name,  in snd_timer_open_lconf()  argument
236 	assert(timer && name && lconf);  in snd_timer_open_lconf()
237 	return snd_timer_open_noupdate(timer, lconf, name, mode);  in snd_timer_open_lconf()
241  * \brief close timer handle
242  * \param timer timer handle
245  * Closes the specified timer handle and frees all associated
248 int snd_timer_close(snd_timer_t *timer)  in snd_timer_close()  argument
251   	assert(timer);  in snd_timer_close()
252 	while (!list_empty(&timer->async_handlers)) {  in snd_timer_close()
253 		snd_async_handler_t *h = list_entry(timer->async_handlers.next, snd_async_handler_t, hlist);  in snd_timer_close()
256 	err = timer->ops->close(timer);  in snd_timer_close()
257 	if (timer->dl_handle)  in snd_timer_close()
258 		snd_dlclose(timer->dl_handle);  in snd_timer_close()
259 	free(timer->name);  in snd_timer_close()
260 	free(timer);  in snd_timer_close()
265  * \brief get identifier of timer handle
266  * \param timer a timer handle
267  * \return ascii identifier of timer handle
269  * Returns the ASCII identifier of given timer handle. It's the same
272 const char *snd_timer_name(snd_timer_t *timer)  in snd_timer_name()  argument
274 	assert(timer);  in snd_timer_name()
275 	return timer->name;  in snd_timer_name()
279  * \brief get type of timer handle
280  * \param timer a timer handle
281  * \return type of timer handle
283  * Returns the type #snd_timer_type_t of given timer handle.
285 snd_timer_type_t snd_timer_type(snd_timer_t *timer)  in snd_timer_type()  argument
287 	assert(timer);  in snd_timer_type()
288 	return timer->type;  in snd_timer_type()
292  * \brief Add an async handler for a timer
294  * \param timer timer handle
299  * The asynchronous callback is called when new timer event occurs.
301 int snd_async_add_timer_handler(snd_async_handler_t **handler, snd_timer_t *timer,  in snd_async_add_timer_handler()  argument
307 	err = snd_async_add_handler(&h, timer->poll_fd,  in snd_async_add_timer_handler()
312 	h->u.timer = timer;  in snd_async_add_timer_handler()
313 	was_empty = list_empty(&timer->async_handlers);  in snd_async_add_timer_handler()
314 	list_add_tail(&h->hlist, &timer->async_handlers);  in snd_async_add_timer_handler()
316 		err = snd_timer_async(timer, snd_async_handler_get_signo(h), getpid());  in snd_async_add_timer_handler()
327  * \brief Return timer handle related to an async handler
329  * \return timer handle
337 	return handler->u.timer;  in snd_async_handler_get_timer()
341  * \brief get count of poll descriptors for timer handle
342  * \param timer timer handle
345 int snd_timer_poll_descriptors_count(snd_timer_t *timer)  in snd_timer_poll_descriptors_count()  argument
347 	assert(timer);  in snd_timer_poll_descriptors_count()
353  * \param timer timer handle
358 int snd_timer_poll_descriptors(snd_timer_t *timer, struct pollfd *pfds, unsigned int space)  in snd_timer_poll_descriptors()  argument
360 	assert(timer);  in snd_timer_poll_descriptors()
362 		pfds->fd = timer->poll_fd;  in snd_timer_poll_descriptors()
363 		switch (timer->mode & O_ACCMODE) {  in snd_timer_poll_descriptors()
383  * \param timer timer handle
389 int snd_timer_poll_descriptors_revents(snd_timer_t *timer, struct pollfd *pfds, unsigned int nfds, …  in snd_timer_poll_descriptors_revents()  argument
391         assert(timer && pfds && revents);  in snd_timer_poll_descriptors_revents()
401  * \param timer timer handle
405 int snd_timer_nonblock(snd_timer_t *timer, int nonblock)  in snd_timer_nonblock()  argument
408 	assert(timer);  in snd_timer_nonblock()
409 	if ((err = timer->ops->nonblock(timer, nonblock)) < 0)  in snd_timer_nonblock()
412 		timer->mode |= SND_TIMER_OPEN_NONBLOCK;  in snd_timer_nonblock()
414 		timer->mode &= ~SND_TIMER_OPEN_NONBLOCK;  in snd_timer_nonblock()
421  * \param timer timer handle
428 int snd_timer_async(snd_timer_t *timer, int sig, pid_t pid)  in snd_timer_async()  argument
430 	assert(timer);  in snd_timer_async()
435 	return timer->ops->async(timer, sig, pid);  in snd_timer_async()
490  * \brief determine, if timer is slave
492  * \return nonzero if timer is slave
501  * \brief get timer card
503  * \return timer card number
512  * \brief get timer id
514  * \return timer id
523  * \brief get timer name
525  * \return timer name
535  * \brief get timer resolution in us
537  * \return timer resolution
546  * \brief get information about timer handle
547  * \param timer timer handle
551 int snd_timer_info(snd_timer_t *timer, snd_timer_info_t * info)  in snd_timer_info()  argument
553 	assert(timer);  in snd_timer_info()
555 	return timer->ops->info(timer, info);  in snd_timer_info()
609  * \brief set timer auto start
624  * \brief determine if timer has auto start flag
626  * \return nonzero if timer has auto start flag
635  * \brief set timer exclusive use
655  * \brief determine if timer has exclusive flag
657  * \return nonzero if timer has exclusive flag
671  * \brief set timer early event
686  * \brief determine if timer has early event flag
688  * \return nonzero if timer has early event flag set
697  * \brief set timer ticks
708  * \brief get timer ticks
710  * \return timer ticks
719  * \brief set timer queue size (32-1024)
741  * \brief set timer event filter
757  * \brief get timer event filter
759  * \return timer event filter
773  * \brief set parameters for timer handle
774  * \param timer timer handle
778 int snd_timer_params(snd_timer_t *timer, snd_timer_params_t * params)  in snd_timer_params()  argument
780 	assert(timer);  in snd_timer_params()
782 	return timer->ops->params(timer, params);  in snd_timer_params()
893  * \brief get status from timer handle
894  * \param timer timer handle
898 int snd_timer_status(snd_timer_t *timer, snd_timer_status_t * status)  in snd_timer_status()  argument
900 	assert(timer);  in snd_timer_status()
902 	return timer->ops->status(timer, status);  in snd_timer_status()
906  * \brief start the timer
907  * \param timer timer handle
910 int snd_timer_start(snd_timer_t *timer)  in snd_timer_start()  argument
912 	assert(timer);  in snd_timer_start()
913 	return timer->ops->rt_start(timer);  in snd_timer_start()
917  * \brief stop the timer
918  * \param timer timer handle
921 int snd_timer_stop(snd_timer_t *timer)  in snd_timer_stop()  argument
923 	assert(timer);  in snd_timer_stop()
924 	return timer->ops->rt_stop(timer);  in snd_timer_stop()
928  * \brief continue the timer
929  * \param timer timer handle
932 int snd_timer_continue(snd_timer_t *timer)  in snd_timer_continue()  argument
934 	assert(timer);  in snd_timer_continue()
935 	return timer->ops->rt_continue(timer);  in snd_timer_continue()
939  * \brief read bytes using timer handle
940  * \param timer timer handle
944 ssize_t snd_timer_read(snd_timer_t *timer, void *buffer, size_t size)  in snd_timer_read()  argument
946 	assert(timer);  in snd_timer_read()
947 	assert(((timer->mode & O_ACCMODE) == O_RDONLY) || ((timer->mode & O_ACCMODE) == O_RDWR));  in snd_timer_read()
949 	return (timer->ops->read)(timer, buffer, size);  in snd_timer_read()
953  * \brief (DEPRECATED) get maximum timer ticks
955  * \return maximum timer ticks