Home | History | Annotate | Download | only in include
      1 /**
      2  * \file include/timer.h
      3  * \brief Application interface library for the ALSA driver
      4  * \author Jaroslav Kysela <perex (at) perex.cz>
      5  * \author Abramo Bagnara <abramo (at) alsa-project.org>
      6  * \author Takashi Iwai <tiwai (at) suse.de>
      7  * \date 1998-2001
      8  *
      9  * Application interface library for the ALSA driver
     10  */
     11 /*
     12  *   This library is free software; you can redistribute it and/or modify
     13  *   it under the terms of the GNU Lesser General Public License as
     14  *   published by the Free Software Foundation; either version 2.1 of
     15  *   the License, or (at your option) any later version.
     16  *
     17  *   This program is distributed in the hope that it will be useful,
     18  *   but WITHOUT ANY WARRANTY; without even the implied warranty of
     19  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     20  *   GNU Lesser General Public License for more details.
     21  *
     22  *   You should have received a copy of the GNU Lesser General Public
     23  *   License along with this library; if not, write to the Free Software
     24  *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
     25  *
     26  */
     27 
     28 #ifndef __ALSA_TIMER_H
     29 #define __ALSA_TIMER_H
     30 
     31 #ifdef __cplusplus
     32 extern "C" {
     33 #endif
     34 
     35 /**
     36  *  \defgroup Timer Timer Interface
     37  *  Timer Interface. See \ref timer page for more details.
     38  *  \{
     39  */
     40 
     41 /** dlsym version for interface entry callback */
     42 #define SND_TIMER_DLSYM_VERSION		_dlsym_timer_001
     43 /** dlsym version for interface entry callback */
     44 #define SND_TIMER_QUERY_DLSYM_VERSION	_dlsym_timer_query_001
     45 
     46 /** timer identification structure */
     47 typedef struct _snd_timer_id snd_timer_id_t;
     48 /** timer global info structure */
     49 typedef struct _snd_timer_ginfo snd_timer_ginfo_t;
     50 /** timer global params structure */
     51 typedef struct _snd_timer_gparams snd_timer_gparams_t;
     52 /** timer global status structure */
     53 typedef struct _snd_timer_gstatus snd_timer_gstatus_t;
     54 /** timer info structure */
     55 typedef struct _snd_timer_info snd_timer_info_t;
     56 /** timer params structure */
     57 typedef struct _snd_timer_params snd_timer_params_t;
     58 /** timer status structure */
     59 typedef struct _snd_timer_status snd_timer_status_t;
     60 /** timer master class */
     61 typedef enum _snd_timer_class {
     62 	SND_TIMER_CLASS_NONE = -1,	/**< invalid */
     63 	SND_TIMER_CLASS_SLAVE = 0,	/**< slave timer */
     64 	SND_TIMER_CLASS_GLOBAL,		/**< global timer */
     65 	SND_TIMER_CLASS_CARD,		/**< card timer */
     66 	SND_TIMER_CLASS_PCM,		/**< PCM timer */
     67 	SND_TIMER_CLASS_LAST = SND_TIMER_CLASS_PCM	/**< last timer */
     68 } snd_timer_class_t;
     69 
     70 /** timer slave class */
     71 typedef enum _snd_timer_slave_class {
     72 	SND_TIMER_SCLASS_NONE = 0,		/**< none */
     73 	SND_TIMER_SCLASS_APPLICATION,		/**< for internal use */
     74 	SND_TIMER_SCLASS_SEQUENCER,		/**< sequencer timer */
     75 	SND_TIMER_SCLASS_OSS_SEQUENCER,		/**< OSS sequencer timer */
     76 	SND_TIMER_SCLASS_LAST = SND_TIMER_SCLASS_OSS_SEQUENCER	/**< last slave timer */
     77 } snd_timer_slave_class_t;
     78 
     79 /** timer read event identification */
     80 typedef enum _snd_timer_event {
     81 	SND_TIMER_EVENT_RESOLUTION = 0,	/* val = resolution in ns */
     82 	SND_TIMER_EVENT_TICK,		/* val = ticks */
     83 	SND_TIMER_EVENT_START,		/* val = resolution in ns */
     84 	SND_TIMER_EVENT_STOP,		/* val = 0 */
     85 	SND_TIMER_EVENT_CONTINUE,	/* val = resolution in ns */
     86 	SND_TIMER_EVENT_PAUSE,		/* val = 0 */
     87 	SND_TIMER_EVENT_EARLY,		/* val = 0 */
     88 	SND_TIMER_EVENT_SUSPEND,	/* val = 0 */
     89 	SND_TIMER_EVENT_RESUME,		/* val = resolution in ns */
     90 	/* master timer events for slave timer instances */
     91 	SND_TIMER_EVENT_MSTART = SND_TIMER_EVENT_START + 10,
     92 	SND_TIMER_EVENT_MSTOP = SND_TIMER_EVENT_STOP + 10,
     93 	SND_TIMER_EVENT_MCONTINUE = SND_TIMER_EVENT_CONTINUE + 10,
     94 	SND_TIMER_EVENT_MPAUSE = SND_TIMER_EVENT_PAUSE + 10,
     95 	SND_TIMER_EVENT_MSUSPEND = SND_TIMER_EVENT_SUSPEND + 10,
     96 	SND_TIMER_EVENT_MRESUME = SND_TIMER_EVENT_RESUME + 10
     97 } snd_timer_event_t;
     98 
     99 /** timer read structure */
    100 typedef struct _snd_timer_read {
    101 	unsigned int resolution;	/**< tick resolution in nanoseconds */
    102         unsigned int ticks;		/**< count of happened ticks */
    103 } snd_timer_read_t;
    104 
    105 /** timer tstamp + event read structure */
    106 typedef struct _snd_timer_tread {
    107 	snd_timer_event_t event;	/**< Timer event */
    108 	snd_htimestamp_t tstamp;	/**< Time stamp of each event */
    109 	unsigned int val;		/**< Event value */
    110 } snd_timer_tread_t;
    111 
    112 /** global timer - system */
    113 #define SND_TIMER_GLOBAL_SYSTEM 0
    114 /** global timer - RTC */
    115 #define SND_TIMER_GLOBAL_RTC 	1
    116 /** global timer - HPET */
    117 #define SND_TIMER_GLOBAL_HPET	2
    118 
    119 /** timer open mode flag - non-blocking behaviour */
    120 #define SND_TIMER_OPEN_NONBLOCK		(1<<0)
    121 /** use timestamps and event notification - enhanced read */
    122 #define SND_TIMER_OPEN_TREAD		(1<<1)
    123 
    124 /** timer handle type */
    125 typedef enum _snd_timer_type {
    126 	/** Kernel level HwDep */
    127 	SND_TIMER_TYPE_HW = 0,
    128 	/** Shared memory client timer (not yet implemented) */
    129 	SND_TIMER_TYPE_SHM,
    130 	/** INET client timer (not yet implemented) */
    131 	SND_TIMER_TYPE_INET
    132 } snd_timer_type_t;
    133 
    134 /** timer query handle */
    135 typedef struct _snd_timer_query snd_timer_query_t;
    136 /** timer handle */
    137 typedef struct _snd_timer snd_timer_t;
    138 
    139 
    140 int snd_timer_query_open(snd_timer_query_t **handle, const char *name, int mode);
    141 int snd_timer_query_open_lconf(snd_timer_query_t **handle, const char *name, int mode, snd_config_t *lconf);
    142 int snd_timer_query_close(snd_timer_query_t *handle);
    143 int snd_timer_query_next_device(snd_timer_query_t *handle, snd_timer_id_t *tid);
    144 int snd_timer_query_info(snd_timer_query_t *handle, snd_timer_ginfo_t *info);
    145 int snd_timer_query_params(snd_timer_query_t *handle, snd_timer_gparams_t *params);
    146 int snd_timer_query_status(snd_timer_query_t *handle, snd_timer_gstatus_t *status);
    147 
    148 int snd_timer_open(snd_timer_t **handle, const char *name, int mode);
    149 int snd_timer_open_lconf(snd_timer_t **handle, const char *name, int mode, snd_config_t *lconf);
    150 int snd_timer_close(snd_timer_t *handle);
    151 int snd_async_add_timer_handler(snd_async_handler_t **handler, snd_timer_t *timer,
    152 				snd_async_callback_t callback, void *private_data);
    153 snd_timer_t *snd_async_handler_get_timer(snd_async_handler_t *handler);
    154 int snd_timer_poll_descriptors_count(snd_timer_t *handle);
    155 int snd_timer_poll_descriptors(snd_timer_t *handle, struct pollfd *pfds, unsigned int space);
    156 int snd_timer_poll_descriptors_revents(snd_timer_t *timer, struct pollfd *pfds, unsigned int nfds, unsigned short *revents);
    157 int snd_timer_info(snd_timer_t *handle, snd_timer_info_t *timer);
    158 int snd_timer_params(snd_timer_t *handle, snd_timer_params_t *params);
    159 int snd_timer_status(snd_timer_t *handle, snd_timer_status_t *status);
    160 int snd_timer_start(snd_timer_t *handle);
    161 int snd_timer_stop(snd_timer_t *handle);
    162 int snd_timer_continue(snd_timer_t *handle);
    163 ssize_t snd_timer_read(snd_timer_t *handle, void *buffer, size_t size);
    164 
    165 size_t snd_timer_id_sizeof(void);
    166 /** allocate #snd_timer_id_t container on stack */
    167 #define snd_timer_id_alloca(ptr) __snd_alloca(ptr, snd_timer_id)
    168 int snd_timer_id_malloc(snd_timer_id_t **ptr);
    169 void snd_timer_id_free(snd_timer_id_t *obj);
    170 void snd_timer_id_copy(snd_timer_id_t *dst, const snd_timer_id_t *src);
    171 
    172 void snd_timer_id_set_class(snd_timer_id_t *id, int dev_class);
    173 int snd_timer_id_get_class(snd_timer_id_t *id);
    174 void snd_timer_id_set_sclass(snd_timer_id_t *id, int dev_sclass);
    175 int snd_timer_id_get_sclass(snd_timer_id_t *id);
    176 void snd_timer_id_set_card(snd_timer_id_t *id, int card);
    177 int snd_timer_id_get_card(snd_timer_id_t *id);
    178 void snd_timer_id_set_device(snd_timer_id_t *id, int device);
    179 int snd_timer_id_get_device(snd_timer_id_t *id);
    180 void snd_timer_id_set_subdevice(snd_timer_id_t *id, int subdevice);
    181 int snd_timer_id_get_subdevice(snd_timer_id_t *id);
    182 
    183 size_t snd_timer_ginfo_sizeof(void);
    184 /** allocate #snd_timer_ginfo_t container on stack */
    185 #define snd_timer_ginfo_alloca(ptr) __snd_alloca(ptr, snd_timer_ginfo)
    186 int snd_timer_ginfo_malloc(snd_timer_ginfo_t **ptr);
    187 void snd_timer_ginfo_free(snd_timer_ginfo_t *obj);
    188 void snd_timer_ginfo_copy(snd_timer_ginfo_t *dst, const snd_timer_ginfo_t *src);
    189 
    190 int snd_timer_ginfo_set_tid(snd_timer_ginfo_t *obj, snd_timer_id_t *tid);
    191 snd_timer_id_t *snd_timer_ginfo_get_tid(snd_timer_ginfo_t *obj);
    192 unsigned int snd_timer_ginfo_get_flags(snd_timer_ginfo_t *obj);
    193 int snd_timer_ginfo_get_card(snd_timer_ginfo_t *obj);
    194 char *snd_timer_ginfo_get_id(snd_timer_ginfo_t *obj);
    195 char *snd_timer_ginfo_get_name(snd_timer_ginfo_t *obj);
    196 unsigned long snd_timer_ginfo_get_resolution(snd_timer_ginfo_t *obj);
    197 unsigned long snd_timer_ginfo_get_resolution_min(snd_timer_ginfo_t *obj);
    198 unsigned long snd_timer_ginfo_get_resolution_max(snd_timer_ginfo_t *obj);
    199 unsigned int snd_timer_ginfo_get_clients(snd_timer_ginfo_t *obj);
    200 
    201 size_t snd_timer_info_sizeof(void);
    202 /** allocate #snd_timer_info_t container on stack */
    203 #define snd_timer_info_alloca(ptr) __snd_alloca(ptr, snd_timer_info)
    204 int snd_timer_info_malloc(snd_timer_info_t **ptr);
    205 void snd_timer_info_free(snd_timer_info_t *obj);
    206 void snd_timer_info_copy(snd_timer_info_t *dst, const snd_timer_info_t *src);
    207 
    208 int snd_timer_info_is_slave(snd_timer_info_t * info);
    209 int snd_timer_info_get_card(snd_timer_info_t * info);
    210 const char *snd_timer_info_get_id(snd_timer_info_t * info);
    211 const char *snd_timer_info_get_name(snd_timer_info_t * info);
    212 long snd_timer_info_get_resolution(snd_timer_info_t * info);
    213 
    214 size_t snd_timer_params_sizeof(void);
    215 /** allocate #snd_timer_params_t container on stack */
    216 #define snd_timer_params_alloca(ptr) __snd_alloca(ptr, snd_timer_params)
    217 int snd_timer_params_malloc(snd_timer_params_t **ptr);
    218 void snd_timer_params_free(snd_timer_params_t *obj);
    219 void snd_timer_params_copy(snd_timer_params_t *dst, const snd_timer_params_t *src);
    220 
    221 int snd_timer_params_set_auto_start(snd_timer_params_t * params, int auto_start);
    222 int snd_timer_params_get_auto_start(snd_timer_params_t * params);
    223 int snd_timer_params_set_exclusive(snd_timer_params_t * params, int exclusive);
    224 int snd_timer_params_get_exclusive(snd_timer_params_t * params);
    225 int snd_timer_params_set_early_event(snd_timer_params_t * params, int early_event);
    226 int snd_timer_params_get_early_event(snd_timer_params_t * params);
    227 void snd_timer_params_set_ticks(snd_timer_params_t * params, long ticks);
    228 long snd_timer_params_get_ticks(snd_timer_params_t * params);
    229 void snd_timer_params_set_queue_size(snd_timer_params_t * params, long queue_size);
    230 long snd_timer_params_get_queue_size(snd_timer_params_t * params);
    231 void snd_timer_params_set_filter(snd_timer_params_t * params, unsigned int filter);
    232 unsigned int snd_timer_params_get_filter(snd_timer_params_t * params);
    233 
    234 size_t snd_timer_status_sizeof(void);
    235 /** allocate #snd_timer_status_t container on stack */
    236 #define snd_timer_status_alloca(ptr) __snd_alloca(ptr, snd_timer_status)
    237 int snd_timer_status_malloc(snd_timer_status_t **ptr);
    238 void snd_timer_status_free(snd_timer_status_t *obj);
    239 void snd_timer_status_copy(snd_timer_status_t *dst, const snd_timer_status_t *src);
    240 
    241 snd_htimestamp_t snd_timer_status_get_timestamp(snd_timer_status_t * status);
    242 long snd_timer_status_get_resolution(snd_timer_status_t * status);
    243 long snd_timer_status_get_lost(snd_timer_status_t * status);
    244 long snd_timer_status_get_overrun(snd_timer_status_t * status);
    245 long snd_timer_status_get_queue(snd_timer_status_t * status);
    246 
    247 /* deprecated functions, for compatibility */
    248 long snd_timer_info_get_ticks(snd_timer_info_t * info);
    249 
    250 /** \} */
    251 
    252 #ifdef __cplusplus
    253 }
    254 #endif
    255 
    256 #endif /** __ALSA_TIMER_H */
    257 
    258