1 /** 2 * \file include/pcm_ioplug.h 3 * \brief External I/O-Plugin SDK 4 * \author Takashi Iwai <tiwai@suse.de> 5 * \date 2005 6 * 7 * External I/O-Plugin SDK 8 */ 9 10 /* 11 * ALSA external PCM plugin SDK 12 * 13 * Copyright (c) 2005 Takashi Iwai <tiwai@suse.de> 14 * 15 * This library is free software; you can redistribute it and/or modify 16 * it under the terms of the GNU Lesser General Public License as 17 * published by the Free Software Foundation; either version 2.1 of 18 * the License, or (at your option) any later version. 19 * 20 * This program is distributed in the hope that it will be useful, 21 * but WITHOUT ANY WARRANTY; without even the implied warranty of 22 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 23 * GNU Lesser General Public License for more details. 24 * 25 * You should have received a copy of the GNU Lesser General Public 26 * License along with this library; if not, write to the Free Software 27 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA 28 * 29 */ 30 31 #ifndef __ALSA_PCM_IOPLUG_H 32 #define __ALSA_PCM_IOPLUG_H 33 34 /** 35 * \defgroup PCM_IOPlug External I/O plugin SDK 36 * \ingroup Plugin_SDK 37 * See the \ref pcm page for more details. 38 * \{ 39 */ 40 41 /** hw constraints for ioplug */ 42 enum { 43 SND_PCM_IOPLUG_HW_ACCESS = 0, /**< access type */ 44 SND_PCM_IOPLUG_HW_FORMAT, /**< format */ 45 SND_PCM_IOPLUG_HW_CHANNELS, /**< channels */ 46 SND_PCM_IOPLUG_HW_RATE, /**< rate */ 47 SND_PCM_IOPLUG_HW_PERIOD_BYTES, /**< period bytes */ 48 SND_PCM_IOPLUG_HW_BUFFER_BYTES, /**< buffer bytes */ 49 SND_PCM_IOPLUG_HW_PERIODS, /**< number of periods */ 50 SND_PCM_IOPLUG_HW_PARAMS /**< max number of hw constraints */ 51 }; 52 53 /** I/O plugin handle */ 54 typedef struct snd_pcm_ioplug snd_pcm_ioplug_t; 55 /** Callback table of ioplug */ 56 typedef struct snd_pcm_ioplug_callback snd_pcm_ioplug_callback_t; 57 #ifdef DOC_HIDDEN 58 /* redefine typedefs for stupid doxygen */ 59 typedef snd_pcm_ioplug snd_pcm_ioplug_t; 60 typedef snd_pcm_ioplug_callback snd_pcm_ioplug_callback_t; 61 #endif 62 63 /* 64 * bit flags for additional conditions 65 */ 66 #define SND_PCM_IOPLUG_FLAG_LISTED (1<<0) /**< list up this PCM */ 67 #define SND_PCM_IOPLUG_FLAG_MONOTONIC (1<<1) /**< monotonic timestamps */ 68 /** hw pointer wrap around at boundary instead of buffer_size */ 69 #define SND_PCM_IOPLUG_FLAG_BOUNDARY_WA (1<<2) 70 71 /* 72 * Protocol version 73 */ 74 #define SND_PCM_IOPLUG_VERSION_MAJOR 1 /**< Protocol major version */ 75 #define SND_PCM_IOPLUG_VERSION_MINOR 0 /**< Protocol minor version */ 76 #define SND_PCM_IOPLUG_VERSION_TINY 2 /**< Protocol tiny version */ 77 /** 78 * IO-plugin protocol version 79 */ 80 #define SND_PCM_IOPLUG_VERSION ((SND_PCM_IOPLUG_VERSION_MAJOR<<16) |\ 81 (SND_PCM_IOPLUG_VERSION_MINOR<<8) |\ 82 (SND_PCM_IOPLUG_VERSION_TINY)) 83 84 /** Handle of ioplug */ 85 struct snd_pcm_ioplug { 86 /** 87 * protocol version; #SND_PCM_IOPLUG_VERSION must be filled here 88 * before calling #snd_pcm_ioplug_create() 89 */ 90 unsigned int version; 91 /** 92 * name of this plugin; must be filled before calling #snd_pcm_ioplug_create() 93 */ 94 const char *name; 95 unsigned int flags; /**< SND_PCM_IOPLUG_FLAG_XXX */ 96 int poll_fd; /**< poll file descriptor */ 97 unsigned int poll_events; /**< poll events */ 98 unsigned int mmap_rw; /**< pseudo mmap mode */ 99 /** 100 * callbacks of this plugin; must be filled before calling #snd_pcm_ioplug_create() 101 */ 102 const snd_pcm_ioplug_callback_t *callback; 103 /** 104 * private data, which can be used freely in the driver callbacks 105 */ 106 void *private_data; 107 /** 108 * PCM handle filled by #snd_pcm_ioplug_create() 109 */ 110 snd_pcm_t *pcm; 111 112 snd_pcm_stream_t stream; /**< stream direcion; read-only */ 113 snd_pcm_state_t state; /**< current PCM state; read-only */ 114 volatile snd_pcm_uframes_t appl_ptr; /**< application pointer; read-only */ 115 volatile snd_pcm_uframes_t hw_ptr; /**< hw pointer; read-only */ 116 int nonblock; /**< non-block mode; read-only */ 117 118 snd_pcm_access_t access; /**< access type; filled after hw_params is called */ 119 snd_pcm_format_t format; /**< PCM format; filled after hw_params is called */ 120 unsigned int channels; /**< number of channels; filled after hw_params is called */ 121 unsigned int rate; /**< rate; filled after hw_params is called */ 122 snd_pcm_uframes_t period_size; /**< period size; filled after hw_params is called */ 123 snd_pcm_uframes_t buffer_size; /**< buffer size; filled after hw_params is called */ 124 }; 125 126 /** Callback table of ioplug */ 127 struct snd_pcm_ioplug_callback { 128 /** 129 * start the PCM; required, called inside mutex lock 130 */ 131 int (*start)(snd_pcm_ioplug_t *io); 132 /** 133 * stop the PCM; required, called inside mutex lock 134 */ 135 int (*stop)(snd_pcm_ioplug_t *io); 136 /** 137 * get the current DMA position; required, called inside mutex lock 138 * \return buffer position up to buffer_size or 139 * when #SND_PCM_IOPLUG_FLAG_BOUNDARY_WA flag is set up to boundary or 140 * a negative error code for Xrun 141 */ 142 snd_pcm_sframes_t (*pointer)(snd_pcm_ioplug_t *io); 143 /** 144 * transfer the data; optional, called inside mutex lock 145 */ 146 snd_pcm_sframes_t (*transfer)(snd_pcm_ioplug_t *io, 147 const snd_pcm_channel_area_t *areas, 148 snd_pcm_uframes_t offset, 149 snd_pcm_uframes_t size); 150 /** 151 * close the PCM; optional 152 */ 153 int (*close)(snd_pcm_ioplug_t *io); 154 /** 155 * hw_params; optional 156 */ 157 int (*hw_params)(snd_pcm_ioplug_t *io, snd_pcm_hw_params_t *params); 158 /** 159 * hw_free; optional 160 */ 161 int (*hw_free)(snd_pcm_ioplug_t *io); 162 /** 163 * sw_params; optional 164 */ 165 int (*sw_params)(snd_pcm_ioplug_t *io, snd_pcm_sw_params_t *params); 166 /** 167 * prepare; optional 168 */ 169 int (*prepare)(snd_pcm_ioplug_t *io); 170 /** 171 * drain; optional 172 */ 173 int (*drain)(snd_pcm_ioplug_t *io); 174 /** 175 * toggle pause; optional, called inside mutex lock 176 */ 177 int (*pause)(snd_pcm_ioplug_t *io, int enable); 178 /** 179 * resume; optional 180 */ 181 int (*resume)(snd_pcm_ioplug_t *io); 182 /** 183 * poll descriptors count; optional 184 */ 185 int (*poll_descriptors_count)(snd_pcm_ioplug_t *io); 186 /** 187 * poll descriptors; optional 188 */ 189 int (*poll_descriptors)(snd_pcm_ioplug_t *io, struct pollfd *pfd, unsigned int space); 190 /** 191 * mangle poll events; optional 192 */ 193 int (*poll_revents)(snd_pcm_ioplug_t *io, struct pollfd *pfd, unsigned int nfds, unsigned short *revents); 194 /** 195 * dump; optional 196 */ 197 void (*dump)(snd_pcm_ioplug_t *io, snd_output_t *out); 198 /** 199 * get the delay for the running PCM; optional; since v1.0.1 200 */ 201 int (*delay)(snd_pcm_ioplug_t *io, snd_pcm_sframes_t *delayp); 202 /** 203 * query the channel maps; optional; since v1.0.2 204 */ 205 snd_pcm_chmap_query_t **(*query_chmaps)(snd_pcm_ioplug_t *io); 206 /** 207 * get the channel map; optional; since v1.0.2 208 */ 209 snd_pcm_chmap_t *(*get_chmap)(snd_pcm_ioplug_t *io); 210 /** 211 * set the channel map; optional; since v1.0.2 212 */ 213 int (*set_chmap)(snd_pcm_ioplug_t *io, const snd_pcm_chmap_t *map); 214 }; 215 216 217 int snd_pcm_ioplug_create(snd_pcm_ioplug_t *io, const char *name, 218 snd_pcm_stream_t stream, int mode); 219 int snd_pcm_ioplug_delete(snd_pcm_ioplug_t *io); 220 221 /* update poll_fd and mmap_rw */ 222 int snd_pcm_ioplug_reinit_status(snd_pcm_ioplug_t *ioplug); 223 224 /* get a mmap area (for mmap_rw only) */ 225 const snd_pcm_channel_area_t *snd_pcm_ioplug_mmap_areas(snd_pcm_ioplug_t *ioplug); 226 227 /* clear hw_parameter setting */ 228 void snd_pcm_ioplug_params_reset(snd_pcm_ioplug_t *io); 229 230 /* hw_parameter setting */ 231 int snd_pcm_ioplug_set_param_minmax(snd_pcm_ioplug_t *io, int type, unsigned int min, unsigned int max); 232 int snd_pcm_ioplug_set_param_list(snd_pcm_ioplug_t *io, int type, unsigned int num_list, const unsigned int *list); 233 234 /* change PCM status */ 235 int snd_pcm_ioplug_set_state(snd_pcm_ioplug_t *ioplug, snd_pcm_state_t state); 236 237 /* calucalte the available frames */ 238 snd_pcm_uframes_t snd_pcm_ioplug_avail(const snd_pcm_ioplug_t * const ioplug, 239 const snd_pcm_uframes_t hw_ptr, 240 const snd_pcm_uframes_t appl_ptr); 241 snd_pcm_uframes_t snd_pcm_ioplug_hw_avail(const snd_pcm_ioplug_t * const ioplug, 242 const snd_pcm_uframes_t hw_ptr, 243 const snd_pcm_uframes_t appl_ptr); 244 245 /** \} */ 246 247 #endif /* __ALSA_PCM_IOPLUG_H */ 248