conf/ucm: PAZ00: add Toshiba AC100/Dynabook AZ new config
[alsa-lib.git] / src / pcm / pcm.c
1 /**
2  * \file pcm/pcm.c
3  * \ingroup PCM
4  * \brief PCM Interface
5  * \author Jaroslav Kysela <perex@perex.cz>
6  * \author Abramo Bagnara <abramo@alsa-project.org>
7  * \date 2000-2001
8  *
9  * PCM Interface is designed to write or read digital audio frames. A
10  * frame is the data unit converted into/from sound in one time unit
11  * (1/rate seconds), by example if you set your playback PCM rate to
12  * 44100 you'll hear 44100 frames per second. The size in bytes of a
13  * frame may be obtained from bits needed to store a sample and
14  * channels count.
15  *
16  * See the \ref pcm page for more details.
17  */
18 /*
19  *  PCM Interface - main file
20  *  Copyright (c) 1998 by Jaroslav Kysela <perex@perex.cz>
21  *  Copyright (c) 2000 by Abramo Bagnara <abramo@alsa-project.org>
22  *
23  *   This library is free software; you can redistribute it and/or modify
24  *   it under the terms of the GNU Lesser General Public License as
25  *   published by the Free Software Foundation; either version 2.1 of
26  *   the License, or (at your option) any later version.
27  *
28  *   This program is distributed in the hope that it will be useful,
29  *   but WITHOUT ANY WARRANTY; without even the implied warranty of
30  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
31  *   GNU Lesser General Public License for more details.
32  *
33  *   You should have received a copy of the GNU Lesser General Public
34  *   License along with this library; if not, write to the Free Software
35  *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
36  *
37  */
38
39 /*! \page pcm PCM (digital audio) interface
40
41 <P>Although abbreviation PCM stands for Pulse Code Modulation, we are
42 understanding it as general digital audio processing with volume samples
43 generated in continuous time periods.</P>
44
45 <P>The analog signal is recorded via analog to digital converters (ADC).
46 The digital value (de-facto a volume at a specific time) obtained
47 from ADC can be further processed. The following picture shows a perfect
48 sinus waveform:</P>
49
50 <BR>
51 \image html wave1.gif
52
53 <P>Next image shows digitized representation:</P>
54
55 <BR>
56 \image html wave2.gif
57
58 <P>As you may see, the quality of digital audio signal depends on the time
59 (recording rate) and voltage resolution (usually in an linear integer
60 representation with basic unit one bit).</P>
61
62 <P>The stored digital signal can be converted back to voltage (analog)
63 representation via digital to analog converters (DAC).</P>
64
65 <P>One digital value is called sample. More samples are collected to frames
66 (frame is terminology for ALSA) depending on count of converters used at one
67 specific time. One frame might contain one sample (when only one converter is
68 used - mono) or more samples (for example: stereo has signals from two converters
69 recorded at same time). Digital audio stream contains collection of frames
70 recorded at boundaries of continuous time periods.</P>
71
72 \section pcm_general_overview General overview
73
74 ALSA uses the ring buffer to store outgoing (playback) and incoming (capture,
75 record) samples. There are two pointers being maintained to allow
76 a precise communication between application and device pointing to current
77 processed sample by hardware and last processed sample by application.
78 The modern audio chips allow to program the transfer time periods.
79 It means that the stream of samples is divided to small chunks. Device
80 acknowledges to application when the transfer of a chunk is complete.
81
82 \section pcm_transfer Transfer methods in UNIX environments
83
84 In the UNIX environment, data chunk acknowledges are received via standard I/O
85 calls or event waiting routines (poll or select function). To accomplish
86 this list, the asynchronous notification of acknowledges should be listed
87 here. The ALSA implementation for these methods is described in
88 the \ref alsa_transfers section.
89
90 \subsection pcm_transfer_io Standard I/O transfers
91
92 The standard I/O transfers are using the read (see 'man 2 read') and write
93 (see 'man 2 write') C functions. There are two basic behaviours of these
94 functions - blocked and non-blocked (see the O_NONBLOCK flag for the
95 standard C open function - see 'man 2 open'). In non-blocked behaviour,
96 these I/O functions never stops, they return -EAGAIN error code, when no
97 data can be transferred (the ring buffer is full in our case). In blocked
98 behaviour, these I/O functions stop and wait until there is a room in the
99 ring buffer (playback) or until there are a new samples (capture). The ALSA
100 implementation can be found in the \ref alsa_pcm_rw section.
101
102 \subsection pcm_transfer_event Event waiting routines
103
104 The poll or select functions (see 'man 2 poll' or 'man 2 select' for further
105 details) allows to receive requests/events from the device while
106 an application is waiting on events from other sources (like keyboard, screen,
107 network etc.), too. \ref snd_pcm_poll_descriptors can be used to get a file
108 descriptor to poll or select on. The implemented
109 transfer routines can be found in the \ref alsa_transfers section.
110
111 \subsection pcm_transfer_async Asynchronous notification
112
113 ALSA driver and library knows to handle the asynchronous notifications over
114 the SIGIO signal. This signal allows to interrupt application and transfer
115 data in the signal handler. For further details see the sigaction function
116 ('man 2 sigaction'). The section \ref pcm_async describes the ALSA API for
117 this extension. The implemented transfer routines can be found in the
118 \ref alsa_transfers section.
119
120 \section pcm_open_behaviour Blocked and non-blocked open
121
122 The ALSA PCM API uses a different behaviour when the device is opened
123 with blocked or non-blocked mode. The mode can be specified with
124 \a mode argument in #snd_pcm_open() function.
125 The blocked mode is the default (without #SND_PCM_NONBLOCK mode).
126 In this mode, the behaviour is that if the resources have already used
127 with another application, then it blocks the caller, until resources are
128 free. The non-blocked behaviour (with #SND_PCM_NONBLOCK)
129 doesn't block the caller in any way and returns -EBUSY error when the
130 resources are not available. Note that the mode also determines the
131 behaviour of standard I/O calls, returning -EAGAIN when non-blocked mode is
132 used and the ring buffer is full (playback) or empty (capture).
133 The operation mode for I/O calls can be changed later with
134 the #snd_pcm_nonblock() function.
135
136 \section pcm_async Asynchronous mode
137
138 There is also possibility to receive asynchronous notification after
139 specified time periods. You may see the #SND_PCM_ASYNC
140 mode for #snd_pcm_open() function and
141 #snd_async_add_pcm_handler() function for further details.
142
143 \section pcm_handshake Handshake between application and library
144
145 The ALSA PCM API design uses the states to determine the communication
146 phase between application and library. The actual state can be determined
147 using #snd_pcm_state() call. There are these states:
148
149 \par SND_PCM_STATE_OPEN
150 The PCM device is in the open state. After the #snd_pcm_open() open call,
151 the device is in this state. Also, when #snd_pcm_hw_params() call fails,
152 then this state is entered to force application calling 
153 #snd_pcm_hw_params() function to set right communication
154 parameters.
155
156 \par SND_PCM_STATE_SETUP
157 The PCM device has accepted communication parameters and it is waiting
158 for #snd_pcm_prepare() call to prepare the hardware for
159 selected operation (playback or capture).
160
161 \par SND_PCM_STATE_PREPARE
162 The PCM device is prepared for operation. Application can use
163 #snd_pcm_start() call, write or read data to start
164 the operation.
165
166 \par SND_PCM_STATE_RUNNING
167 The PCM device is running. It processes the samples. The stream can
168 be stopped using the #snd_pcm_drop() or
169 #snd_pcm_drain calls.
170
171 \par SND_PCM_STATE_XRUN
172 The PCM device reached overrun (capture) or underrun (playback).
173 You can use the -EPIPE return code from I/O functions
174 (#snd_pcm_writei(), #snd_pcm_writen(), #snd_pcm_readi(), #snd_pcm_readn())
175 to determine this state without checking
176 the actual state via #snd_pcm_state() call. You can recover from
177 this state with #snd_pcm_prepare(),
178 #snd_pcm_drop() or #snd_pcm_drain() calls.
179
180 \par SND_PCM_STATE_DRAINING
181 The device is in this state when application using the capture mode
182 called #snd_pcm_drain() function. Until all data are
183 read from the internal ring buffer using I/O routines
184 (#snd_pcm_readi(), #snd_pcm_readn()),
185 then the device stays in this state.
186
187 \par SND_PCM_STATE_PAUSED
188 The device is in this state when application called
189 the #snd_pcm_pause() function until the pause is released.
190 Not all hardware supports this feature. Application should check the
191 capability with the #snd_pcm_hw_params_can_pause().
192
193 \par SND_PCM_STATE_SUSPENDED
194 The device is in the suspend state provoked with the power management
195 system. The stream can be resumed using #snd_pcm_resume()
196 call, but not all hardware supports this feature. Application should check
197 the capability with the #snd_pcm_hw_params_can_resume().
198 In other case, the calls #snd_pcm_prepare(),
199 #snd_pcm_drop(), #snd_pcm_drain() can be used
200 to leave this state.
201
202 \par SND_PCM_STATE_DISCONNECTED
203 The device is physicaly disconnected. It does not accept any I/O calls in this state.
204
205 \section pcm_formats PCM formats
206
207 The full list of formats present the #snd_pcm_format_t type.
208 The 24-bit linear samples uses 32-bit physical space, but the sample is
209 stored in low three bits. Some hardware does not support processing of full
210 range, thus you may get the significant bits for linear samples via
211 #snd_pcm_hw_params_get_sbits() function. The example: ICE1712
212 chips support 32-bit sample processing, but low byte is ignored (playback)
213 or zero (capture). The function snd_pcm_hw_params_get_sbits()
214 returns 24 in the case.
215
216 \section alsa_transfers ALSA transfers
217
218 There are two methods to transfer samples in application. The first method
219 is the standard read / write one. The second method, uses the direct audio
220 buffer to communicate with the device while ALSA library manages this space
221 itself. You can find examples of all communication schemes for playback
222 in \ref example_test_pcm "Sine-wave generator example". To complete the
223 list, we should note that #snd_pcm_wait() function contains
224 embedded poll waiting implementation.
225
226 \subsection alsa_pcm_rw Read / Write transfer
227
228 There are two versions of read / write routines. The first expects the
229 interleaved samples at input (#SND_PCM_ACCESS_RW_INTERLEAVED access method),
230 and the second one expects non-interleaved (samples in separated buffers -
231 #SND_PCM_ACCESS_RW_NONINTERLEAVED access method) at input. There are these
232 functions for interleaved transfers: #snd_pcm_writei()
233 #snd_pcm_readi(). For non-interleaved transfers, there are
234 these functions: #snd_pcm_writen() and #snd_pcm_readn().
235
236 \subsection alsa_mmap_rw Direct Read / Write transfer (via mmap'ed areas)
237
238 Three kinds of organization of ring buffer memory areas exist in ALSA API.
239 Access #SND_PCM_ACCESS_MMAP_INTERLEAVED has interleaved samples. Access
240 #SND_PCM_ACCESS_MMAP_NONINTERLEAVED expects continous sample areas for
241 one channel. Access #SND_PCM_ACCESS_MMAP_COMPLEX does not fit to interleaved
242 and non-interleaved ring buffer organization.
243
244 There are two functions for this kind of transfer. Application can get an
245 access to memory areas via #snd_pcm_mmap_begin() function.
246 This function returns the areas (single area is equal to a channel)
247 containing the direct pointers to memory and sample position description
248 in #snd_pcm_channel_area_t structure. After application
249 transfers the data in the memory areas, then it must be acknowledged
250 the end of transfer via #snd_pcm_mmap_commit() function
251 to allow the ALSA library update the pointers to ring buffer. This kind of
252 communication is also called "zero-copy", because the device does not require
253 to copy the samples from application to another place in system memory.
254
255 If you like to use the compatibility functions in mmap mode, there are
256 read / write routines equaling to standard read / write transfers. Using
257 these functions discards the benefits of direct access to memory region.
258 See the #snd_pcm_mmap_readi(),
259 #snd_pcm_writei(), #snd_pcm_readn()
260 and #snd_pcm_writen() functions.
261
262 \section pcm_errors Error codes
263
264 \par -EPIPE
265
266 This error means xrun (underrun for playback or overrun for capture).
267 The underrun can happen when an application does not feed new samples
268 in time to alsa-lib (due CPU usage). The overrun can happen when
269 an application does not take new captured samples in time from alsa-lib.
270
271 \par -ESTRPIPE
272
273 This error means that system has suspended drivers. The application
274 should wait in loop when snd_pcm_resume() != -EAGAIN and then
275 call snd_pcm_prepare() when snd_pcm_resume() return an error code.
276 If snd_pcm_resume() does not fail (a zero value is returned), driver
277 supports resume and the snd_pcm_prepare() call can be ommited.
278
279 \par -EBADFD
280
281 This error means that the device is in a bad state. It means that
282 the handskahe between application and alsa-lib is corrupted.
283
284 \par -ENOTTY, -ENODEV
285
286 This error can happen when device is physically removed (for example
287 some hotplug devices like USB or PCMCIA, CardBus or ExpressCard
288 can be removed on the fly).
289
290 \section pcm_params Managing parameters
291
292 The ALSA PCM device uses two groups of PCM related parameters. The hardware
293 parameters contains the stream description like format, rate, count of
294 channels, ring buffer size etc. The software parameters contains the
295 software (driver) related parameters. The communication behaviour can be
296 controlled via these parameters, like automatic start, automatic stop,
297 interrupting (chunk acknowledge) etc. The software parameters can be
298 modified at any time (when valid hardware parameters are set). It includes
299 the running state as well.
300
301 \subsection pcm_hw_params Hardware related parameters
302
303 The ALSA PCM devices use the parameter refining system for hardware
304 parameters - #snd_pcm_hw_params_t. It means, that
305 application choose the full-range of configurations at first and then
306 application sets single parameters until all parameters are elementary
307 (definite).
308
309 \par Access modes
310
311 ALSA knows about five access modes. The first three can be used for direct
312 communication. The access mode #SND_PCM_ACCESS_MMAP_INTERLEAVED
313 determines the direct memory area and interleaved sample organization.
314 Interleaved organization means, that samples from channels are mixed together.
315 The access mode #SND_PCM_ACCESS_MMAP_NONINTERLEAVED
316 determines the direct memory area and non-interleaved sample organization.
317 Each channel has a separate buffer in the case. The complex direct memory
318 organization represents the #SND_PCM_ACCESS_MMAP_COMPLEX
319 access mode. The sample organization does not fit the interleaved or
320 non-interleaved access modes in the case. The last two access modes
321 describes the read / write access methods.
322 The #SND_PCM_ACCESS_RW_INTERLEAVED access represents the read /
323 write interleaved access and the #SND_PCM_ACCESS_RW_NONINTERLEAVED
324 represents the non-interleaved access.
325
326 \par Formats
327
328 The full list of formats is available in #snd_pcm_format_t
329 enumeration.
330
331 \subsection pcm_sw_params Software related parameters
332
333 These parameters - #snd_pcm_sw_params_t can be modified at
334 any time including the running state.
335
336 \par Minimum available count of samples
337
338 This parameter controls the wakeup point. If the count of available samples
339 is equal or greater than this value, then application will be activated.
340
341 \par Timestamp mode
342
343 The timestamp mode specifies, if timestamps are activated. Currently, only
344 #SND_PCM_TSTAMP_NONE and #SND_PCM_TSTAMP_MMAP
345 modes are known. The mmap mode means that timestamp is taken
346 on every period time boundary. Corresponding position in the ring buffer
347 assigned to timestamp can be obtained using #snd_pcm_htimestamp() function.
348
349 \par Transfer align
350
351 The read / write transfers can be aligned to this sample count. The modulo
352 is ignored by device. Usually, this value is set to one (no align).
353
354 \par Start threshold
355
356 The start threshold parameter is used to determine the start point in
357 stream. For playback, if samples in ring buffer is equal or greater than
358 the start threshold parameters and the stream is not running, the stream will
359 be started automatically from the device. For capture, if the application wants
360 to read count of samples equal or greater then the stream will be started.
361 If you want to use explicit start (#snd_pcm_start), you can
362 set this value greater than ring buffer size (in samples), but use the
363 constant MAXINT is not a bad idea.
364
365 \par Stop threshold
366
367 Similarly, the stop threshold parameter is used to automatically stop
368 the running stream, when the available samples crosses this boundary.
369 It means, for playback, the empty samples in ring buffer and for capture,
370 the filled (used) samples in ring buffer.
371
372 \par Silence threshold
373
374 The silence threshold specifies count of samples filled with silence
375 ahead of the current application pointer for playback. It is usable
376 for applications when an overrun is possible (like tasks depending on
377 network I/O etc.). If application wants to manage the ahead samples itself,
378 the #snd_pcm_rewind() function allows to forget the last
379 samples in the stream.
380
381 \section pcm_status Obtaining stream status
382
383 The stream status is stored in #snd_pcm_status_t structure.
384 These parameters can be obtained: the current stream state -
385 #snd_pcm_status_get_state(), timestamp of trigger -
386 #snd_pcm_status_get_trigger_tstamp(), timestamp of last
387 pointer update #snd_pcm_status_get_tstamp(), delay in samples -
388 #snd_pcm_status_get_delay(), available count in samples -
389 #snd_pcm_status_get_avail(), maximum available samples -
390 #snd_pcm_status_get_avail_max(), ADC over-range count in
391 samples - #snd_pcm_status_get_overrange(). The last two
392 parameters - avail_max and overrange are reset to zero after the status
393 call.
394
395 \subsection pcm_status_fast Obtaining stream state fast and update r/w pointer
396
397 <p>
398 The function #snd_pcm_avail_update() updates the current
399 available count of samples for writing (playback) or filled samples for
400 reading (capture). This call is mandatory for updating actual r/w pointer.
401 Using standalone, it is a light method to obtain current stream position,
402 because it does not require the user <-> kernel context switch, but the value
403 is less accurate, because ring buffer pointers are updated in kernel drivers
404 only when an interrupt occurs. If you want to get accurate stream state,
405 use functions #snd_pcm_avail(), #snd_pcm_delay() or #snd_pcm_avail_delay().
406 </p>
407 <p>
408 The function #snd_pcm_avail() reads the current hardware pointer
409 in the ring buffer from hardware and calls #snd_pcm_avail_update() then.
410 </p>
411 <p>
412 The function #snd_pcm_delay() returns the delay in samples.
413 For playback, it means count of samples in the ring buffer before
414 the next sample will be sent to DAC. For capture, it means count of samples
415 in the ring buffer before the next sample will be captured from ADC. It works
416 only when the stream is in the running or draining (playback only) state.
417 Note that this function does not update the current r/w pointer for applications,
418 so the function #snd_pcm_avail_update() must be called afterwards
419 before any read/write begin+commit operations.
420 </p>
421 <p>
422 The function #snd_pcm_avail_delay() combines #snd_pcm_avail() and
423 #snd_pcm_delay() and returns both values in sync.
424 </p>
425
426 \section pcm_action Managing the stream state
427
428 The following functions directly and indirectly affect the stream state:
429
430 \par snd_pcm_hw_params
431 The #snd_pcm_hw_params() function brings the stream state
432 to #SND_PCM_STATE_SETUP
433 if successfully finishes, otherwise the state #SND_PCM_STATE_OPEN
434 is entered.
435 When it is brought to SETUP state, this function automatically
436 calls #snd_pcm_prepare() function to bring to the PREPARE state
437 as below.
438
439 \par snd_pcm_prepare
440 The #snd_pcm_prepare() function enters from #SND_PCM_STATE_SETUP
441 to the #SND_PCM_STATE_PREPARED after a successful finish.
442
443 \par snd_pcm_start
444 The #snd_pcm_start() function enters
445 the #SND_PCM_STATE_RUNNING after a successful finish.
446
447 \par snd_pcm_drop
448 The #snd_pcm_drop() function enters the
449 #SND_PCM_STATE_SETUP state.
450
451 \par snd_pcm_drain
452 The #snd_pcm_drain() function enters the
453 #SND_PCM_STATE_DRAINING, if
454 the capture device has some samples in the ring buffer otherwise
455 #SND_PCM_STATE_SETUP state is entered.
456
457 \par snd_pcm_pause
458 The #snd_pcm_pause() function enters the
459 #SND_PCM_STATE_PAUSED or #SND_PCM_STATE_RUNNING.
460
461 \par snd_pcm_writei, snd_pcm_writen
462 The #snd_pcm_writei() and #snd_pcm_writen()
463 functions can conditionally start the stream -
464 #SND_PCM_STATE_RUNNING. They depend on the start threshold
465 software parameter.
466
467 \par snd_pcm_readi, snd_pcm_readn
468 The #snd_pcm_readi() and #snd_pcm_readn()
469 functions can conditionally start the stream -
470 #SND_PCM_STATE_RUNNING. They depend on the start threshold
471 software parameter.
472
473 \section pcm_sync Streams synchronization
474
475 There are two functions allowing link multiple streams together. In the
476 case, the linking means that all operations are synchronized. Because the
477 drivers cannot guarantee the synchronization (sample resolution) on hardware
478 lacking this feature, the #snd_pcm_info_get_sync() function
479 returns synchronization ID - #snd_pcm_sync_id_t, which is equal
480 for hardware synchronized streams. When the #snd_pcm_link()
481 function is called, all operations managing the stream state for these two
482 streams are joined. The opposite function is #snd_pcm_unlink().
483
484 \section pcm_dev_names PCM naming conventions
485
486 The ALSA library uses a generic string representation for names of devices.
487 The devices might be virtual, physical or a mix of both. The generic string
488 is passed to #snd_pcm_open() or #snd_pcm_open_lconf().
489 It contains two parts: device name and arguments. Devices and arguments are described
490 in configuration files. The usual place for default definitions is at /usr/share/alsa/alsa.conf.
491 For detailed descriptions about integrated PCM plugins look to \ref pcm_plugins.
492
493 \subsection pcm_dev_names_default Default device
494
495 The default device is equal to plug plugin with hw plugin as slave. The defaults are
496 used:
497
498 \code
499 defaults.pcm.card 0
500 defaults.pcm.device 0
501 defaults.pcm.subdevice -1
502 \endcode
503
504 These defaults can be freely overwritten in local configuration files.
505
506 Example:
507
508 \code
509 default
510 \endcode
511
512 \subsection pcm_dev_names_hw HW device
513
514 The hw device description uses the hw plugin. The three arguments (in order: CARD,DEV,SUBDEV)
515 specify card number or identifier, device number and subdevice number (-1 means any).
516
517 Example:
518
519 \code
520 hw
521 hw:0
522 hw:0,0
523 hw:supersonic,1
524 hw:soundwave,1,2
525 hw:DEV=1,CARD=soundwave,SUBDEV=2
526 \endcode
527
528 \subsection pcm_dev_names_plughw Plug->HW device
529
530 The plughw device description uses the plug plugin and hw plugin as slave. The arguments
531 are same as for hw device.
532
533 Example:
534
535 \code
536 plughw
537 plughw:0
538 plughw:0,0
539 plughw:supersonic,1
540 plughw:soundwave,1,2
541 plughw:DEV=1,CARD=soundwave,SUBDEV=2
542 \endcode
543
544 \subsection pcm_dev_names_plug Plug device
545
546 The plug device uses the plug plugin. The one SLAVE argument specifies the slave plugin.
547
548 Example:
549
550 \code
551 plug:mypcmdef
552 plug:hw
553 plug:'hw:0,0'
554 plug:SLAVE=hw
555 \endcode
556
557 \subsection pcm_dev_names_shm Shared memory device
558
559 The shm device uses the shm plugin. The two arguments (in order: SOCKET,PCM) specify
560 UNIX socket name (for example /tmp/alsa.socket) for server communication and server's PCM name.
561
562 Example:
563
564 \code
565 shm:'/tmp/alsa.sock',default
566 shm:SOCKET='/tmp/alsa.sock',PCM=default
567 \endcode
568
569 \subsection pcm_dev_names_tee Tee device
570
571 The tee device stores contents of a stream to given file plus transfers it to given slave plugin.
572 The three arguments (in order: SLAVE,FILE,FORMAT) specify slave plugin, filename and file format.
573
574 Example:
575
576 \code
577 tee:hw,'/tmp/out.raw',raw
578 \endcode
579
580 \subsection pcm_dev_names_file File device
581
582 The file device is file plugin with null plugin as slave. The arguments (in order: FILE,FORMAT)
583 specify filename and file format.
584
585 Example:
586
587 \code
588 file:'/tmp/out.raw',raw
589 \endcode
590
591 \subsection pcm_dev_names_null Null device
592
593 The null device is null plugin. This device has not any arguments.
594
595
596 \section pcm_examples Examples
597
598 The full featured examples with cross-links can be found in Examples section
599 (see top of page):
600
601 \anchor example_test_pcm
602 \par Sine-wave generator
603 \par
604 alsa-lib/test/pcm.c example shows various transfer methods for the playback direction.
605
606 \par Minimalistic PCM playback code
607 \par
608 alsa-lib/test/pcm_min.c example shows the minimal code to produce a sound.
609
610 \par Latency measuring tool
611 \par
612 alsa-lib/test/latency.c example shows the measuring of minimal latency between capture and
613 playback devices.
614
615 */
616
617 /**
618 \example ../../test/pcm.c
619 */
620 /**
621 \example ../../test/pcm_min.c
622 */
623 /**
624 \example ../../test/latency.c
625 */
626
627 #include <stdio.h>
628 #include <string.h>
629 #include <malloc.h>
630 #include <stdarg.h>
631 #include <signal.h>
632 #include <sys/poll.h>
633 #include <sys/shm.h>
634 #include <sys/mman.h>
635 #include <limits.h>
636 #include "pcm_local.h"
637
638 /**
639  * \brief get identifier of PCM handle
640  * \param pcm PCM handle
641  * \return ascii identifier of PCM handle
642  *
643  * Returns the ASCII identifier of given PCM handle. It's the same
644  * identifier specified in snd_pcm_open().
645  */
646 const char *snd_pcm_name(snd_pcm_t *pcm)
647 {
648         assert(pcm);
649         return pcm->name;
650 }
651
652 /**
653  * \brief get type of PCM handle
654  * \param pcm PCM handle
655  * \return type of PCM handle
656  *
657  * Returns the type #snd_pcm_type_t of given PCM handle.
658  */
659 snd_pcm_type_t snd_pcm_type(snd_pcm_t *pcm)
660 {
661         assert(pcm);
662         return pcm->type;
663 }
664
665 /**
666  * \brief get stream for a PCM handle
667  * \param pcm PCM handle
668  * \return stream of PCM handle
669  *
670  * Returns the type #snd_pcm_stream_t of given PCM handle.
671  */
672 snd_pcm_stream_t snd_pcm_stream(snd_pcm_t *pcm)
673 {
674         assert(pcm);
675         return pcm->stream;
676 }
677
678 /**
679  * \brief close PCM handle
680  * \param pcm PCM handle
681  * \return 0 on success otherwise a negative error code
682  *
683  * Closes the specified PCM handle and frees all associated
684  * resources.
685  */
686 int snd_pcm_close(snd_pcm_t *pcm)
687 {
688         int res = 0, err;
689         assert(pcm);
690         if (pcm->setup && !pcm->donot_close) {
691                 snd_pcm_drop(pcm);
692                 err = snd_pcm_hw_free(pcm);
693                 if (err < 0)
694                         res = err;
695         }
696         if (pcm->mmap_channels)
697                 snd_pcm_munmap(pcm);
698         while (!list_empty(&pcm->async_handlers)) {
699                 snd_async_handler_t *h = list_entry(pcm->async_handlers.next, snd_async_handler_t, hlist);
700                 snd_async_del_handler(h);
701         }
702         err = pcm->ops->close(pcm->op_arg);
703         if (err < 0)
704                 res = err;
705         err = snd_pcm_free(pcm);
706         if (err < 0)
707                 res = err;
708         return res;
709 }       
710
711 /**
712  * \brief set nonblock mode
713  * \param pcm PCM handle
714  * \param nonblock 0 = block, 1 = nonblock mode
715  * \return 0 on success otherwise a negative error code
716  */
717 int snd_pcm_nonblock(snd_pcm_t *pcm, int nonblock)
718 {
719         int err;
720         assert(pcm);
721         if ((err = pcm->ops->nonblock(pcm->op_arg, nonblock)) < 0)
722                 return err;
723         if (nonblock)
724                 pcm->mode |= SND_PCM_NONBLOCK;
725         else
726                 pcm->mode &= ~SND_PCM_NONBLOCK;
727         return 0;
728 }
729
730 #ifndef DOC_HIDDEN
731 /**
732  * \brief set async mode
733  * \param pcm PCM handle
734  * \param sig Signal to raise: < 0 disable, 0 default (SIGIO)
735  * \param pid Process ID to signal: 0 current
736  * \return 0 on success otherwise a negative error code
737  *
738  * A signal is raised every period.
739  */
740 int snd_pcm_async(snd_pcm_t *pcm, int sig, pid_t pid)
741 {
742         assert(pcm);
743         if (sig == 0)
744                 sig = SIGIO;
745         if (pid == 0)
746                 pid = getpid();
747         return pcm->ops->async(pcm->op_arg, sig, pid);
748 }
749 #endif
750
751 /**
752  * \brief Obtain general (static) information for PCM handle
753  * \param pcm PCM handle
754  * \param info Information container
755  * \return 0 on success otherwise a negative error code
756  */
757 int snd_pcm_info(snd_pcm_t *pcm, snd_pcm_info_t *info)
758 {
759         assert(pcm && info);
760         return pcm->ops->info(pcm->op_arg, info);
761 }
762
763 /** \brief Retreive current PCM hardware configuration chosen with #snd_pcm_hw_params
764  * \param pcm PCM handle
765  * \param params Configuration space definition container
766  * \return 0 on success otherwise a negative error code
767  */
768 int snd_pcm_hw_params_current(snd_pcm_t *pcm, snd_pcm_hw_params_t *params)
769 {
770         unsigned int frame_bits;
771
772         assert(pcm && params);
773         if (!pcm->setup)
774                 return -EBADFD;
775         memset(params, 0, snd_pcm_hw_params_sizeof());
776         params->flags = pcm->hw_flags;
777         snd_mask_set(&params->masks[SND_PCM_HW_PARAM_ACCESS - SND_PCM_HW_PARAM_FIRST_MASK], pcm->access);
778         snd_mask_set(&params->masks[SND_PCM_HW_PARAM_FORMAT - SND_PCM_HW_PARAM_FIRST_MASK], pcm->format);
779         snd_mask_set(&params->masks[SND_PCM_HW_PARAM_SUBFORMAT - SND_PCM_HW_PARAM_FIRST_MASK], pcm->subformat);
780         frame_bits = snd_pcm_format_physical_width(pcm->format) * pcm->channels;
781         snd_interval_set_value(&params->intervals[SND_PCM_HW_PARAM_FRAME_BITS - SND_PCM_HW_PARAM_FIRST_INTERVAL], frame_bits);
782         snd_interval_set_value(&params->intervals[SND_PCM_HW_PARAM_CHANNELS - SND_PCM_HW_PARAM_FIRST_INTERVAL], pcm->channels);
783         snd_interval_set_value(&params->intervals[SND_PCM_HW_PARAM_RATE - SND_PCM_HW_PARAM_FIRST_INTERVAL], pcm->rate);
784         snd_interval_set_value(&params->intervals[SND_PCM_HW_PARAM_PERIOD_TIME - SND_PCM_HW_PARAM_FIRST_INTERVAL], pcm->period_time);
785         snd_interval_set_value(&params->intervals[SND_PCM_HW_PARAM_PERIOD_SIZE - SND_PCM_HW_PARAM_FIRST_INTERVAL], pcm->period_size);
786         snd_interval_copy(&params->intervals[SND_PCM_HW_PARAM_PERIODS - SND_PCM_HW_PARAM_FIRST_INTERVAL], &pcm->periods);
787         snd_interval_copy(&params->intervals[SND_PCM_HW_PARAM_BUFFER_TIME - SND_PCM_HW_PARAM_FIRST_INTERVAL], &pcm->buffer_time);
788         snd_interval_set_value(&params->intervals[SND_PCM_HW_PARAM_BUFFER_SIZE - SND_PCM_HW_PARAM_FIRST_INTERVAL], pcm->buffer_size);
789         snd_interval_set_value(&params->intervals[SND_PCM_HW_PARAM_BUFFER_BYTES - SND_PCM_HW_PARAM_FIRST_INTERVAL], (pcm->buffer_size * frame_bits) / 8);
790         params->info = pcm->info;
791         params->msbits = pcm->msbits;
792         params->rate_num = pcm->rate_num;
793         params->rate_den = pcm->rate_den;
794         params->fifo_size = pcm->fifo_size;
795         return 0;
796
797
798 /** \brief Install one PCM hardware configuration chosen from a configuration space and #snd_pcm_prepare it
799  * \param pcm PCM handle
800  * \param params Configuration space definition container
801  * \return 0 on success otherwise a negative error code
802  *
803  * The configuration is chosen fixing single parameters in this order:
804  * first access, first format, first subformat, min channels, min rate, 
805  * min period time, max buffer size, min tick time
806  *
807  * After this call, #snd_pcm_prepare() is called automatically and
808  * the stream is brought to \c #SND_PCM_STATE_PREPARED state.
809  *
810  * The hardware parameters cannot be changed when the stream is
811  * running (active). The software parameters can be changed
812  * at any time.
813  */
814 int snd_pcm_hw_params(snd_pcm_t *pcm, snd_pcm_hw_params_t *params)
815 {
816         int err;
817         assert(pcm && params);
818         err = _snd_pcm_hw_params(pcm, params);
819         if (err < 0)
820                 return err;
821         err = snd_pcm_prepare(pcm);
822         return err;
823 }
824
825 /** \brief Remove PCM hardware configuration and free associated resources
826  * \param pcm PCM handle
827  * \return 0 on success otherwise a negative error code
828  */
829 int snd_pcm_hw_free(snd_pcm_t *pcm)
830 {
831         int err;
832         if (! pcm->setup)
833                 return 0;
834         if (pcm->mmap_channels) {
835                 err = snd_pcm_munmap(pcm);
836                 if (err < 0)
837                         return err;
838         }
839         // assert(snd_pcm_state(pcm) == SND_PCM_STATE_SETUP ||
840         //        snd_pcm_state(pcm) == SND_PCM_STATE_PREPARED);
841         err = pcm->ops->hw_free(pcm->op_arg);
842         pcm->setup = 0;
843         if (err < 0)
844                 return err;
845         return 0;
846 }
847
848 /** \brief Install PCM software configuration defined by params
849  * \param pcm PCM handle
850  * \param params Configuration container
851  * \return 0 on success otherwise a negative error code
852  *
853  * The software parameters can be changed at any time.
854  * The hardware parameters cannot be changed when the stream is
855  * running (active).
856  */
857 int snd_pcm_sw_params(snd_pcm_t *pcm, snd_pcm_sw_params_t *params)
858 {
859         int err;
860         /* the hw_params must be set at first!!! */
861         if (CHECK_SANITY(! pcm->setup)) {
862                 SNDMSG("PCM not set up");
863                 return -EIO;
864         }
865         if (! params->avail_min) {
866                 SNDMSG("params->avail_min is 0");
867                 return -EINVAL;
868         }
869 #if 0
870         /* disable the check below - it looks too restrictive
871          * (start_threshold is basically independent from avail_min)
872          */
873         if (params->start_threshold <= pcm->buffer_size &&
874             params->start_threshold > (pcm->buffer_size / params->avail_min) * params->avail_min) {
875                 SNDMSG("params->avail_min problem for start_threshold");
876                 return -EINVAL;
877         }
878 #endif
879         err = pcm->ops->sw_params(pcm->op_arg, params);
880         if (err < 0)
881                 return err;
882         pcm->tstamp_mode = params->tstamp_mode;
883         pcm->period_step = params->period_step;
884         pcm->avail_min = params->avail_min;
885         pcm->period_event = params->period_event;
886         pcm->start_threshold = params->start_threshold;
887         pcm->stop_threshold = params->stop_threshold;
888         pcm->silence_threshold = params->silence_threshold;
889         pcm->silence_size = params->silence_size;
890         pcm->boundary = params->boundary;
891         return 0;
892 }
893
894 /**
895  * \brief Obtain status (runtime) information for PCM handle
896  * \param pcm PCM handle
897  * \param status Status container
898  * \return 0 on success otherwise a negative error code
899  */
900 int snd_pcm_status(snd_pcm_t *pcm, snd_pcm_status_t *status)
901 {
902         assert(pcm && status);
903         return pcm->fast_ops->status(pcm->fast_op_arg, status);
904 }
905
906 /**
907  * \brief Return PCM state
908  * \param pcm PCM handle
909  * \return PCM state #snd_pcm_state_t of given PCM handle
910  *
911  * This is a faster way to obtain only the PCM state without calling
912  * \link ::snd_pcm_status() \endlink.
913  */
914 snd_pcm_state_t snd_pcm_state(snd_pcm_t *pcm)
915 {
916         assert(pcm);
917         return pcm->fast_ops->state(pcm->fast_op_arg);
918 }
919
920 /**
921  * \brief (DEPRECATED) Synchronize stream position with hardware
922  * \param pcm PCM handle
923  * \return 0 on success otherwise a negative error code
924  *
925  * Note this function does not update the actual r/w pointer
926  * for applications. The function #snd_pcm_avail_update()
927  * have to be called before any mmap begin+commit operation.
928  */
929 int snd_pcm_hwsync(snd_pcm_t *pcm)
930 {
931         assert(pcm);
932         if (CHECK_SANITY(! pcm->setup)) {
933                 SNDMSG("PCM not set up");
934                 return -EIO;
935         }
936         return pcm->fast_ops->hwsync(pcm->fast_op_arg);
937 }
938 #ifndef DOC_HIDDEN
939 link_warning(snd_pcm_hwsync, "Warning: snd_pcm_hwsync() is deprecated, consider to use snd_pcm_avail()");
940 #endif
941
942 /**
943  * \brief Obtain delay for a running PCM handle
944  * \param pcm PCM handle
945  * \param delayp Returned delay in frames
946  * \return 0 on success otherwise a negative error code
947  *
948  * For playback the delay is defined as the time that a frame that is written
949  * to the PCM stream shortly after this call will take to be actually
950  * audible. It is as such the overall latency from the write call to the final
951  * DAC.
952  *
953  * For capture the delay is defined as the time that a frame that was
954  * digitized by the audio device takes until it can be read from the PCM
955  * stream shortly after this call returns. It is as such the overall latency
956  * from the initial ADC to the read call.
957  *
958  * Please note that hence in case of a playback underrun this value will not
959  * necessarily got down to 0.
960  *
961  * If the application is interested in the fill level of the playback buffer
962  * of the device, it should use #snd_pcm_avail*() functions. The
963  * value returned by that call is not directly related to the delay, since the
964  * latter might include some additional, fixed latencies the former does not.
965  *
966  * Note this function does not update the actual r/w pointer
967  * for applications. The function #snd_pcm_avail_update()
968  * have to be called before any begin+commit operation.
969  */
970 int snd_pcm_delay(snd_pcm_t *pcm, snd_pcm_sframes_t *delayp)
971 {
972         assert(pcm);
973         if (CHECK_SANITY(! pcm->setup)) {
974                 SNDMSG("PCM not set up");
975                 return -EIO;
976         }
977         return pcm->fast_ops->delay(pcm->fast_op_arg, delayp);
978 }
979
980 /**
981  * \brief Resume from suspend, no samples are lost
982  * \param pcm PCM handle
983  * \return 0 on success otherwise a negative error code
984  * \retval -EAGAIN resume can't be proceed immediately (audio hardware is probably still suspended)
985  * \retval -ENOSYS hardware doesn't support this feature
986  *
987  * This function can be used when the stream is in the suspend state
988  * to do the fine resume from this state. Not all hardware supports
989  * this feature, when an -ENOSYS error is returned, use the \link ::snd_pcm_prepare() \endlink
990  * function to recovery.
991  */
992 int snd_pcm_resume(snd_pcm_t *pcm)
993 {
994         assert(pcm);
995         if (CHECK_SANITY(! pcm->setup)) {
996                 SNDMSG("PCM not set up");
997                 return -EIO;
998         }
999         return pcm->fast_ops->resume(pcm->fast_op_arg);
1000 }
1001
1002 /**
1003  * \brief Obtain last position update hi-res timestamp
1004  * \param pcm PCM handle
1005  * \param avail Number of available frames when timestamp was grabbed
1006  * \param tstamp Hi-res timestamp
1007  * \return 0 on success otherwise a negative error code
1008  *
1009  * Note this function does not update the actual r/w pointer
1010  * for applications.
1011  */
1012 int snd_pcm_htimestamp(snd_pcm_t *pcm, snd_pcm_uframes_t *avail, snd_htimestamp_t *tstamp)
1013 {
1014         assert(pcm);
1015         if (CHECK_SANITY(! pcm->setup)) {
1016                 SNDMSG("PCM not set up");
1017                 return -EIO;
1018         }
1019         return pcm->fast_ops->htimestamp(pcm->fast_op_arg, avail, tstamp);
1020 }
1021
1022 /**
1023  * \brief Prepare PCM for use
1024  * \param pcm PCM handle
1025  * \return 0 on success otherwise a negative error code
1026  */
1027 int snd_pcm_prepare(snd_pcm_t *pcm)
1028 {
1029         assert(pcm);
1030         if (CHECK_SANITY(! pcm->setup)) {
1031                 SNDMSG("PCM not set up");
1032                 return -EIO;
1033         }
1034         return pcm->fast_ops->prepare(pcm->fast_op_arg);
1035 }
1036
1037 /**
1038  * \brief Reset PCM position
1039  * \param pcm PCM handle
1040  * \return 0 on success otherwise a negative error code
1041  *
1042  * Reduce PCM delay to 0.
1043  */
1044 int snd_pcm_reset(snd_pcm_t *pcm)
1045 {
1046         assert(pcm);
1047         if (CHECK_SANITY(! pcm->setup)) {
1048                 SNDMSG("PCM not set up");
1049                 return -EIO;
1050         }
1051         return pcm->fast_ops->reset(pcm->fast_op_arg);
1052 }
1053
1054 /**
1055  * \brief Start a PCM
1056  * \param pcm PCM handle
1057  * \return 0 on success otherwise a negative error code
1058  */
1059 int snd_pcm_start(snd_pcm_t *pcm)
1060 {
1061         assert(pcm);
1062         if (CHECK_SANITY(! pcm->setup)) {
1063                 SNDMSG("PCM not set up");
1064                 return -EIO;
1065         }
1066         return pcm->fast_ops->start(pcm->fast_op_arg);
1067 }
1068
1069 /**
1070  * \brief Stop a PCM dropping pending frames
1071  * \param pcm PCM handle
1072  * \return 0 on success otherwise a negative error code
1073  *
1074  * This function stops the PCM <i>immediately</i>.
1075  * The pending samples on the buffer are ignored.
1076  *
1077  * For processing all pending samples, use \link ::snd_pcm_drain() \endlink
1078  * instead.
1079  */
1080 int snd_pcm_drop(snd_pcm_t *pcm)
1081 {
1082         assert(pcm);
1083         if (CHECK_SANITY(! pcm->setup)) {
1084                 SNDMSG("PCM not set up");
1085                 return -EIO;
1086         }
1087         return pcm->fast_ops->drop(pcm->fast_op_arg);
1088 }
1089
1090 /**
1091  * \brief Stop a PCM preserving pending frames
1092  * \param pcm PCM handle
1093  * \return 0 on success otherwise a negative error code
1094  * \retval -ESTRPIPE a suspend event occurred
1095  *
1096  * For playback wait for all pending frames to be played and then stop
1097  * the PCM.
1098  * For capture stop PCM permitting to retrieve residual frames.
1099  *
1100  * For stopping the PCM stream immediately, use \link ::snd_pcm_drop() \endlink
1101  * instead.
1102  */
1103 int snd_pcm_drain(snd_pcm_t *pcm)
1104 {
1105         assert(pcm);
1106         if (CHECK_SANITY(! pcm->setup)) {
1107                 SNDMSG("PCM not set up");
1108                 return -EIO;
1109         }
1110         return pcm->fast_ops->drain(pcm->fast_op_arg);
1111 }
1112
1113 /**
1114  * \brief Pause/resume PCM
1115  * \param pcm PCM handle
1116  * \param enable 0 = resume, 1 = pause
1117  * \return 0 on success otherwise a negative error code
1118  *
1119  * Note that this function works only on the hardware which supports
1120  * pause feature.  You can check it via \link ::snd_pcm_hw_params_can_pause() \endlink
1121  * function.
1122  */
1123 int snd_pcm_pause(snd_pcm_t *pcm, int enable)
1124 {
1125         assert(pcm);
1126         if (CHECK_SANITY(! pcm->setup)) {
1127                 SNDMSG("PCM not set up");
1128                 return -EIO;
1129         }
1130         return pcm->fast_ops->pause(pcm->fast_op_arg, enable);
1131 }
1132
1133 /**
1134  * \brief Get safe count of frames which can be rewinded
1135  * \param pcm PCM handle
1136  * \return a positive number of frames or negative error code
1137  *
1138  * Note: The snd_pcm_rewind() can accept bigger value than returned
1139  * by this function. But it is not guaranteed that output stream
1140  * will be consistent with bigger value.
1141  */
1142 snd_pcm_sframes_t snd_pcm_rewindable(snd_pcm_t *pcm)
1143 {
1144         assert(pcm);
1145         if (CHECK_SANITY(! pcm->setup)) {
1146                 SNDMSG("PCM not set up");
1147                 return -EIO;
1148         }
1149         return pcm->fast_ops->rewindable(pcm->fast_op_arg);
1150 }
1151
1152 /**
1153  * \brief Move application frame position backward
1154  * \param pcm PCM handle
1155  * \param frames wanted displacement in frames
1156  * \return a positive number for actual displacement otherwise a
1157  * negative error code
1158  */
1159 snd_pcm_sframes_t snd_pcm_rewind(snd_pcm_t *pcm, snd_pcm_uframes_t frames)
1160 {
1161         assert(pcm);
1162         if (CHECK_SANITY(! pcm->setup)) {
1163                 SNDMSG("PCM not set up");
1164                 return -EIO;
1165         }
1166         if (frames == 0)
1167                 return 0;
1168         return pcm->fast_ops->rewind(pcm->fast_op_arg, frames);
1169 }
1170
1171 /**
1172  * \brief Get safe count of frames which can be forwarded
1173  * \param pcm PCM handle
1174  * \return a positive number of frames or negative error code
1175  *
1176  * Note: The snd_pcm_forward() can accept bigger value than returned
1177  * by this function. But it is not guaranteed that output stream
1178  * will be consistent with bigger value.
1179  */
1180 snd_pcm_sframes_t snd_pcm_forwardable(snd_pcm_t *pcm)
1181 {
1182         assert(pcm);
1183         if (CHECK_SANITY(! pcm->setup)) {
1184                 SNDMSG("PCM not set up");
1185                 return -EIO;
1186         }
1187         return pcm->fast_ops->forwardable(pcm->fast_op_arg);
1188 }
1189
1190 /**
1191  * \brief Move application frame position forward
1192  * \param pcm PCM handle
1193  * \param frames wanted skip in frames
1194  * \return a positive number for actual skip otherwise a negative error code
1195  * \retval 0 means no action
1196  */
1197 #ifndef DOXYGEN
1198 snd_pcm_sframes_t INTERNAL(snd_pcm_forward)(snd_pcm_t *pcm, snd_pcm_uframes_t frames)
1199 #else
1200 snd_pcm_sframes_t snd_pcm_forward(snd_pcm_t *pcm, snd_pcm_uframes_t frames)
1201 #endif
1202 {
1203         assert(pcm);
1204         if (CHECK_SANITY(! pcm->setup)) {
1205                 SNDMSG("PCM not set up");
1206                 return -EIO;
1207         }
1208         if (frames == 0)
1209                 return 0;
1210         return pcm->fast_ops->forward(pcm->fast_op_arg, frames);
1211 }
1212 use_default_symbol_version(__snd_pcm_forward, snd_pcm_forward, ALSA_0.9.0rc8);
1213
1214 /**
1215  * \brief Write interleaved frames to a PCM
1216  * \param pcm PCM handle
1217  * \param buffer frames containing buffer
1218  * \param size frames to be written
1219  * \return a positive number of frames actually written otherwise a
1220  * negative error code
1221  * \retval -EBADFD PCM is not in the right state (#SND_PCM_STATE_PREPARED or #SND_PCM_STATE_RUNNING)
1222  * \retval -EPIPE an underrun occurred
1223  * \retval -ESTRPIPE a suspend event occurred (stream is suspended and waiting for an application recovery)
1224  *
1225  * If the blocking behaviour is selected, then routine waits until
1226  * all requested bytes are played or put to the playback ring buffer.
1227  * The count of bytes can be less only if a signal or underrun occurred.
1228  *
1229  * If the non-blocking behaviour is selected, then routine doesn't wait at all.
1230  */ 
1231 snd_pcm_sframes_t snd_pcm_writei(snd_pcm_t *pcm, const void *buffer, snd_pcm_uframes_t size)
1232 {
1233         assert(pcm);
1234         assert(size == 0 || buffer);
1235         if (CHECK_SANITY(! pcm->setup)) {
1236                 SNDMSG("PCM not set up");
1237                 return -EIO;
1238         }
1239         if (pcm->access != SND_PCM_ACCESS_RW_INTERLEAVED) {
1240                 SNDMSG("invalid access type %s", snd_pcm_access_name(pcm->access));
1241                 return -EINVAL;
1242         }
1243         return _snd_pcm_writei(pcm, buffer, size);
1244 }
1245
1246 /**
1247  * \brief Write non interleaved frames to a PCM
1248  * \param pcm PCM handle
1249  * \param bufs frames containing buffers (one for each channel)
1250  * \param size frames to be written
1251  * \return a positive number of frames actually written otherwise a
1252  * negative error code
1253  * \retval -EBADFD PCM is not in the right state (#SND_PCM_STATE_PREPARED or #SND_PCM_STATE_RUNNING)
1254  * \retval -EPIPE an underrun occurred
1255  * \retval -ESTRPIPE a suspend event occurred (stream is suspended and waiting for an application recovery)
1256  *
1257  * If the blocking behaviour is selected, then routine waits until
1258  * all requested bytes are played or put to the playback ring buffer.
1259  * The count of bytes can be less only if a signal or underrun occurred.
1260  *
1261  * If the non-blocking behaviour is selected, then routine doesn't wait at all.
1262  */ 
1263 snd_pcm_sframes_t snd_pcm_writen(snd_pcm_t *pcm, void **bufs, snd_pcm_uframes_t size)
1264 {
1265         assert(pcm);
1266         assert(size == 0 || bufs);
1267         if (CHECK_SANITY(! pcm->setup)) {
1268                 SNDMSG("PCM not set up");
1269                 return -EIO;
1270         }
1271         if (pcm->access != SND_PCM_ACCESS_RW_NONINTERLEAVED) {
1272                 SNDMSG("invalid access type %s", snd_pcm_access_name(pcm->access));
1273                 return -EINVAL;
1274         }
1275         return _snd_pcm_writen(pcm, bufs, size);
1276 }
1277
1278 /**
1279  * \brief Read interleaved frames from a PCM
1280  * \param pcm PCM handle
1281  * \param buffer frames containing buffer
1282  * \param size frames to be read
1283  * \return a positive number of frames actually read otherwise a
1284  * negative error code
1285  * \retval -EBADFD PCM is not in the right state (#SND_PCM_STATE_PREPARED or #SND_PCM_STATE_RUNNING)
1286  * \retval -EPIPE an overrun occurred
1287  * \retval -ESTRPIPE a suspend event occurred (stream is suspended and waiting for an application recovery)
1288  *
1289  * If the blocking behaviour was selected, then routine waits until
1290  * all requested bytes are filled. The count of bytes can be less only
1291  * if a signal or underrun occurred.
1292  *
1293  * If the non-blocking behaviour is selected, then routine doesn't wait at all.
1294  */ 
1295 snd_pcm_sframes_t snd_pcm_readi(snd_pcm_t *pcm, void *buffer, snd_pcm_uframes_t size)
1296 {
1297         assert(pcm);
1298         assert(size == 0 || buffer);
1299         if (CHECK_SANITY(! pcm->setup)) {
1300                 SNDMSG("PCM not set up");
1301                 return -EIO;
1302         }
1303         if (pcm->access != SND_PCM_ACCESS_RW_INTERLEAVED) {
1304                 SNDMSG("invalid access type %s", snd_pcm_access_name(pcm->access));
1305                 return -EINVAL;
1306         }
1307         return _snd_pcm_readi(pcm, buffer, size);
1308 }
1309
1310 /**
1311  * \brief Read non interleaved frames to a PCM
1312  * \param pcm PCM handle
1313  * \param bufs frames containing buffers (one for each channel)
1314  * \param size frames to be read
1315  * \return a positive number of frames actually read otherwise a
1316  * negative error code
1317  * \retval -EBADFD PCM is not in the right state (#SND_PCM_STATE_PREPARED or #SND_PCM_STATE_RUNNING)
1318  * \retval -EPIPE an overrun occurred
1319  * \retval -ESTRPIPE a suspend event occurred (stream is suspended and waiting for an application recovery)
1320  *
1321  * If the blocking behaviour was selected, then routine waits until
1322  * all requested bytes are filled. The count of bytes can be less only
1323  * if a signal or underrun occurred.
1324  *
1325  * If the non-blocking behaviour is selected, then routine doesn't wait at all.
1326  */ 
1327 snd_pcm_sframes_t snd_pcm_readn(snd_pcm_t *pcm, void **bufs, snd_pcm_uframes_t size)
1328 {
1329         assert(pcm);
1330         assert(size == 0 || bufs);
1331         if (CHECK_SANITY(! pcm->setup)) {
1332                 SNDMSG("PCM not set up");
1333                 return -EIO;
1334         }
1335         if (pcm->access != SND_PCM_ACCESS_RW_NONINTERLEAVED) {
1336                 SNDMSG("invalid access type %s", snd_pcm_access_name(pcm->access));
1337                 return -EINVAL;
1338         }
1339         return _snd_pcm_readn(pcm, bufs, size);
1340 }
1341
1342 /**
1343  * \brief Link two PCMs
1344  * \param pcm1 first PCM handle
1345  * \param pcm2 first PCM handle
1346  * \return 0 on success otherwise a negative error code
1347  *
1348  * The two PCMs will start/stop/prepare in sync.
1349  */ 
1350 int snd_pcm_link(snd_pcm_t *pcm1, snd_pcm_t *pcm2)
1351 {
1352         assert(pcm1);
1353         assert(pcm2);
1354         if (pcm1->fast_ops->link)
1355                 return pcm1->fast_ops->link(pcm1, pcm2);
1356         return -ENOSYS;
1357 }
1358
1359 /**
1360  * \brief Remove a PCM from a linked group
1361  * \param pcm PCM handle
1362  * \return 0 on success otherwise a negative error code
1363  */
1364 int snd_pcm_unlink(snd_pcm_t *pcm)
1365 {
1366         assert(pcm);
1367         if (pcm->fast_ops->unlink)
1368                 return pcm->fast_ops->unlink(pcm);
1369         return -ENOSYS;
1370 }
1371
1372 /**
1373  * \brief get count of poll descriptors for PCM handle
1374  * \param pcm PCM handle
1375  * \return count of poll descriptors
1376  */
1377 int snd_pcm_poll_descriptors_count(snd_pcm_t *pcm)
1378 {
1379         assert(pcm);
1380         if (pcm->fast_ops->poll_descriptors_count)
1381                 return pcm->fast_ops->poll_descriptors_count(pcm->fast_op_arg);
1382         return pcm->poll_fd_count;
1383 }
1384
1385
1386 /**
1387  * \brief get poll descriptors
1388  * \param pcm PCM handle
1389  * \param pfds array of poll descriptors
1390  * \param space space in the poll descriptor array
1391  * \return count of filled descriptors
1392  *
1393  * This function fills the given poll descriptor structs for the specified
1394  * PCM handle.  The poll desctiptor array should have the size returned by
1395  * \link ::snd_pcm_poll_descriptors_count() \endlink function.
1396  *
1397  * The result is intended for direct use with the poll() syscall.
1398  *
1399  * For reading the returned events of poll descriptor after poll() system
1400  * call, use \link ::snd_pcm_poll_descriptors_revents() \endlink function.
1401  * The field values in pollfd structs may be bogus regarding the stream
1402  * direction from the application perspective (POLLIN might not imply read
1403  * direction and POLLOUT might not imply write), but
1404  * the \link ::snd_pcm_poll_descriptors_revents() \endlink function
1405  * does the right "demangling".
1406  *
1407  * You can use output from this function as arguments for the select()
1408  * syscall, too.
1409  */
1410 int snd_pcm_poll_descriptors(snd_pcm_t *pcm, struct pollfd *pfds, unsigned int space)
1411 {
1412         assert(pcm && pfds);
1413         if (pcm->fast_ops->poll_descriptors)
1414                 return pcm->fast_ops->poll_descriptors(pcm->fast_op_arg, pfds, space);
1415         if (pcm->poll_fd < 0) {
1416                 SNDMSG("poll_fd < 0");
1417                 return -EIO;
1418         }
1419         if (space >= 1 && pfds) {
1420                 pfds->fd = pcm->poll_fd;
1421                 pfds->events = pcm->poll_events | POLLERR | POLLNVAL;
1422         } else {
1423                 return 0;
1424         }
1425         return 1;
1426 }
1427
1428 /**
1429  * \brief get returned events from poll descriptors
1430  * \param pcm PCM handle
1431  * \param pfds array of poll descriptors
1432  * \param nfds count of poll descriptors
1433  * \param revents returned events
1434  * \return zero if success, otherwise a negative error code
1435  *
1436  * This function does "demangling" of the revents mask returned from
1437  * the poll() syscall to correct semantics (POLLIN = read, POLLOUT = write).
1438  *
1439  * Note: The null event also exists. Even if poll() or select()
1440  * syscall returned that some events are waiting, this function might
1441  * return empty set of events. In this case, application should
1442  * do next event waiting using poll() or select().
1443  */
1444 int snd_pcm_poll_descriptors_revents(snd_pcm_t *pcm, struct pollfd *pfds, unsigned int nfds, unsigned short *revents)
1445 {
1446         assert(pcm && pfds && revents);
1447         if (pcm->fast_ops->poll_revents)
1448                 return pcm->fast_ops->poll_revents(pcm->fast_op_arg, pfds, nfds, revents);
1449         if (nfds == 1) {
1450                 *revents = pfds->revents;
1451                 return 0;
1452         }
1453         return -EINVAL;
1454 }
1455
1456 #ifndef DOC_HIDDEN
1457 #define PCMTYPE(v) [SND_PCM_TYPE_##v] = #v
1458 #define STATE(v) [SND_PCM_STATE_##v] = #v
1459 #define STREAM(v) [SND_PCM_STREAM_##v] = #v
1460 #define READY(v) [SND_PCM_READY_##v] = #v
1461 #define XRUN(v) [SND_PCM_XRUN_##v] = #v
1462 #define SILENCE(v) [SND_PCM_SILENCE_##v] = #v
1463 #define TSTAMP(v) [SND_PCM_TSTAMP_##v] = #v
1464 #define ACCESS(v) [SND_PCM_ACCESS_##v] = #v
1465 #define START(v) [SND_PCM_START_##v] = #v
1466 #define HW_PARAM(v) [SND_PCM_HW_PARAM_##v] = #v
1467 #define SW_PARAM(v) [SND_PCM_SW_PARAM_##v] = #v
1468 #define FORMAT(v) [SND_PCM_FORMAT_##v] = #v
1469 #define SUBFORMAT(v) [SND_PCM_SUBFORMAT_##v] = #v 
1470
1471 #define FORMATD(v, d) [SND_PCM_FORMAT_##v] = d
1472 #define SUBFORMATD(v, d) [SND_PCM_SUBFORMAT_##v] = d 
1473
1474
1475 static const char *const snd_pcm_stream_names[] = {
1476         STREAM(PLAYBACK),
1477         STREAM(CAPTURE),
1478 };
1479
1480 static const char *const snd_pcm_state_names[] = {
1481         STATE(OPEN),
1482         STATE(SETUP),
1483         STATE(PREPARED),
1484         STATE(RUNNING),
1485         STATE(XRUN),
1486         STATE(DRAINING),
1487         STATE(PAUSED),
1488         STATE(SUSPENDED),
1489         STATE(DISCONNECTED),
1490 };
1491
1492 static const char *const snd_pcm_access_names[] = {
1493         ACCESS(MMAP_INTERLEAVED), 
1494         ACCESS(MMAP_NONINTERLEAVED),
1495         ACCESS(MMAP_COMPLEX),
1496         ACCESS(RW_INTERLEAVED),
1497         ACCESS(RW_NONINTERLEAVED),
1498 };
1499
1500 static const char *const snd_pcm_format_names[] = {
1501         FORMAT(S8),
1502         FORMAT(U8),
1503         FORMAT(S16_LE),
1504         FORMAT(S16_BE),
1505         FORMAT(U16_LE),
1506         FORMAT(U16_BE),
1507         FORMAT(S24_LE),
1508         FORMAT(S24_BE),
1509         FORMAT(U24_LE),
1510         FORMAT(U24_BE),
1511         FORMAT(S32_LE),
1512         FORMAT(S32_BE),
1513         FORMAT(U32_LE),
1514         FORMAT(U32_BE),
1515         FORMAT(FLOAT_LE),
1516         FORMAT(FLOAT_BE),
1517         FORMAT(FLOAT64_LE),
1518         FORMAT(FLOAT64_BE),
1519         FORMAT(IEC958_SUBFRAME_LE),
1520         FORMAT(IEC958_SUBFRAME_BE),
1521         FORMAT(MU_LAW),
1522         FORMAT(A_LAW),
1523         FORMAT(IMA_ADPCM),
1524         FORMAT(MPEG),
1525         FORMAT(GSM),
1526         FORMAT(SPECIAL),
1527         FORMAT(S24_3LE),
1528         FORMAT(S24_3BE),
1529         FORMAT(U24_3LE),
1530         FORMAT(U24_3BE),
1531         FORMAT(S20_3LE),
1532         FORMAT(S20_3BE),
1533         FORMAT(U20_3LE),
1534         FORMAT(U20_3BE),
1535         FORMAT(S18_3LE),
1536         FORMAT(S18_3BE),
1537         FORMAT(U18_3LE),
1538         FORMAT(U18_3BE),
1539 };
1540
1541 static const char *const snd_pcm_format_aliases[SND_PCM_FORMAT_LAST+1] = {
1542         FORMAT(S16),
1543         FORMAT(U16),
1544         FORMAT(S24),
1545         FORMAT(U24),
1546         FORMAT(S32),
1547         FORMAT(U32),
1548         FORMAT(FLOAT),
1549         FORMAT(FLOAT64),
1550         FORMAT(IEC958_SUBFRAME),
1551 };
1552
1553 static const char *const snd_pcm_format_descriptions[] = {
1554         FORMATD(S8, "Signed 8 bit"), 
1555         FORMATD(U8, "Unsigned 8 bit"),
1556         FORMATD(S16_LE, "Signed 16 bit Little Endian"),
1557         FORMATD(S16_BE, "Signed 16 bit Big Endian"),
1558         FORMATD(U16_LE, "Unsigned 16 bit Little Endian"),
1559         FORMATD(U16_BE, "Unsigned 16 bit Big Endian"),
1560         FORMATD(S24_LE, "Signed 24 bit Little Endian"),
1561         FORMATD(S24_BE, "Signed 24 bit Big Endian"),
1562         FORMATD(U24_LE, "Unsigned 24 bit Little Endian"),
1563         FORMATD(U24_BE, "Unsigned 24 bit Big Endian"),
1564         FORMATD(S32_LE, "Signed 32 bit Little Endian"),
1565         FORMATD(S32_BE, "Signed 32 bit Big Endian"),
1566         FORMATD(U32_LE, "Unsigned 32 bit Little Endian"),
1567         FORMATD(U32_BE, "Unsigned 32 bit Big Endian"),
1568         FORMATD(FLOAT_LE, "Float 32 bit Little Endian"),
1569         FORMATD(FLOAT_BE, "Float 32 bit Big Endian"),
1570         FORMATD(FLOAT64_LE, "Float 64 bit Little Endian"),
1571         FORMATD(FLOAT64_BE, "Float 64 bit Big Endian"),
1572         FORMATD(IEC958_SUBFRAME_LE, "IEC-958 Little Endian"),
1573         FORMATD(IEC958_SUBFRAME_BE, "IEC-958 Big Endian"),
1574         FORMATD(MU_LAW, "Mu-Law"),
1575         FORMATD(A_LAW, "A-Law"),
1576         FORMATD(IMA_ADPCM, "Ima-ADPCM"),
1577         FORMATD(MPEG, "MPEG"),
1578         FORMATD(GSM, "GSM"),
1579         FORMATD(SPECIAL, "Special"),
1580         FORMATD(S24_3LE, "Signed 24 bit Little Endian in 3bytes"),
1581         FORMATD(S24_3BE, "Signed 24 bit Big Endian in 3bytes"),
1582         FORMATD(U24_3LE, "Unsigned 24 bit Little Endian in 3bytes"),
1583         FORMATD(U24_3BE, "Unsigned 24 bit Big Endian in 3bytes"),
1584         FORMATD(S20_3LE, "Signed 20 bit Little Endian in 3bytes"),
1585         FORMATD(S20_3BE, "Signed 20 bit Big Endian in 3bytes"),
1586         FORMATD(U20_3LE, "Unsigned 20 bit Little Endian in 3bytes"),
1587         FORMATD(U20_3BE, "Unsigned 20 bit Big Endian in 3bytes"),
1588         FORMATD(S18_3LE, "Signed 18 bit Little Endian in 3bytes"),
1589         FORMATD(S18_3BE, "Signed 18 bit Big Endian in 3bytes"),
1590         FORMATD(U18_3LE, "Unsigned 18 bit Little Endian in 3bytes"),
1591         FORMATD(U18_3BE, "Unsigned 18 bit Big Endian in 3bytes"),
1592 };
1593
1594 static const char *const snd_pcm_type_names[] = {
1595         PCMTYPE(HW), 
1596         PCMTYPE(HOOKS), 
1597         PCMTYPE(MULTI), 
1598         PCMTYPE(FILE), 
1599         PCMTYPE(NULL), 
1600         PCMTYPE(SHM), 
1601         PCMTYPE(INET), 
1602         PCMTYPE(COPY), 
1603         PCMTYPE(LINEAR), 
1604         PCMTYPE(ALAW), 
1605         PCMTYPE(MULAW), 
1606         PCMTYPE(ADPCM), 
1607         PCMTYPE(RATE), 
1608         PCMTYPE(ROUTE), 
1609         PCMTYPE(PLUG), 
1610         PCMTYPE(SHARE), 
1611         PCMTYPE(METER), 
1612         PCMTYPE(MIX), 
1613         PCMTYPE(DROUTE), 
1614         PCMTYPE(LBSERVER), 
1615         PCMTYPE(LINEAR_FLOAT), 
1616         PCMTYPE(LADSPA), 
1617         PCMTYPE(DMIX), 
1618         PCMTYPE(JACK),
1619         PCMTYPE(DSNOOP),
1620         PCMTYPE(IEC958),
1621         PCMTYPE(SOFTVOL),
1622         PCMTYPE(IOPLUG),
1623         PCMTYPE(EXTPLUG),
1624 };
1625
1626 static const char *const snd_pcm_subformat_names[] = {
1627         SUBFORMAT(STD), 
1628 };
1629
1630 static const char *const snd_pcm_subformat_descriptions[] = {
1631         SUBFORMATD(STD, "Standard"), 
1632 };
1633
1634 static const char *const snd_pcm_start_mode_names[] = {
1635         START(EXPLICIT),
1636         START(DATA),
1637 };
1638
1639 static const char *const snd_pcm_xrun_mode_names[] = {
1640         XRUN(NONE),
1641         XRUN(STOP),
1642 };
1643
1644 static const char *const snd_pcm_tstamp_mode_names[] = {
1645         TSTAMP(NONE),
1646         TSTAMP(ENABLE),
1647 };
1648 #endif
1649
1650 /**
1651  * \brief get name of PCM stream type
1652  * \param stream PCM stream type
1653  * \return ascii name of PCM stream type
1654  */
1655 const char *snd_pcm_stream_name(snd_pcm_stream_t stream)
1656 {
1657         if (stream > SND_PCM_STREAM_LAST)
1658                 return NULL;
1659         return snd_pcm_stream_names[stream];
1660 }
1661
1662 /**
1663  * \brief get name of PCM access type
1664  * \param acc PCM access type
1665  * \return ascii name of PCM access type
1666  */
1667 const char *snd_pcm_access_name(snd_pcm_access_t acc)
1668 {
1669         if (acc > SND_PCM_ACCESS_LAST)
1670                 return NULL;
1671         return snd_pcm_access_names[acc];
1672 }
1673
1674 /**
1675  * \brief get name of PCM sample format
1676  * \param format PCM sample format
1677  * \return ascii name of PCM sample format
1678  */
1679 const char *snd_pcm_format_name(snd_pcm_format_t format)
1680 {
1681         if (format > SND_PCM_FORMAT_LAST)
1682                 return NULL;
1683         return snd_pcm_format_names[format];
1684 }
1685
1686 /**
1687  * \brief get description of PCM sample format
1688  * \param format PCM sample format
1689  * \return ascii description of PCM sample format
1690  */
1691 const char *snd_pcm_format_description(snd_pcm_format_t format)
1692 {
1693         if (format > SND_PCM_FORMAT_LAST)
1694                 return NULL;
1695         return snd_pcm_format_descriptions[format];
1696 }
1697
1698 /**
1699  * \brief get PCM sample format from name
1700  * \param name PCM sample format name (case insensitive)
1701  * \return PCM sample format
1702  */
1703 snd_pcm_format_t snd_pcm_format_value(const char* name)
1704 {
1705         snd_pcm_format_t format;
1706         for (format = 0; format <= SND_PCM_FORMAT_LAST; format++) {
1707                 if (snd_pcm_format_names[format] &&
1708                     strcasecmp(name, snd_pcm_format_names[format]) == 0) {
1709                         return format;
1710                 }
1711                 if (snd_pcm_format_aliases[format] &&
1712                     strcasecmp(name, snd_pcm_format_aliases[format]) == 0) {
1713                         return format;
1714                 }
1715         }
1716         for (format = 0; format <= SND_PCM_FORMAT_LAST; format++) {
1717                 if (snd_pcm_format_descriptions[format] &&
1718                     strcasecmp(name, snd_pcm_format_descriptions[format]) == 0) {
1719                         return format;
1720                 }
1721         }
1722         return SND_PCM_FORMAT_UNKNOWN;
1723 }
1724
1725 /**
1726  * \brief get name of PCM sample subformat
1727  * \param subformat PCM sample subformat
1728  * \return ascii name of PCM sample subformat
1729  */
1730 const char *snd_pcm_subformat_name(snd_pcm_subformat_t subformat)
1731 {
1732         if (subformat > SND_PCM_SUBFORMAT_LAST)
1733                 return NULL;
1734         return snd_pcm_subformat_names[subformat];
1735 }
1736
1737 /**
1738  * \brief get description of PCM sample subformat
1739  * \param subformat PCM sample subformat
1740  * \return ascii description of PCM sample subformat
1741  */
1742 const char *snd_pcm_subformat_description(snd_pcm_subformat_t subformat)
1743 {
1744         if (subformat > SND_PCM_SUBFORMAT_LAST)
1745                 return NULL;
1746         return snd_pcm_subformat_descriptions[subformat];
1747 }
1748
1749 /**
1750  * \brief (DEPRECATED) get name of PCM start mode setting
1751  * \param mode PCM start mode
1752  * \return ascii name of PCM start mode setting
1753  */
1754 const char *snd_pcm_start_mode_name(snd_pcm_start_t mode)
1755 {
1756         if (mode > SND_PCM_START_LAST)
1757                 return NULL;
1758         return snd_pcm_start_mode_names[mode];
1759 }
1760
1761 #ifndef DOC_HIDDEN
1762 link_warning(snd_pcm_start_mode_name, "Warning: start_mode is deprecated, consider to use start_threshold");
1763 #endif
1764
1765 /**
1766  * \brief (DEPRECATED) get name of PCM xrun mode setting
1767  * \param mode PCM xrun mode
1768  * \return ascii name of PCM xrun mode setting
1769  */
1770 const char *snd_pcm_xrun_mode_name(snd_pcm_xrun_t mode)
1771 {
1772         if (mode > SND_PCM_XRUN_LAST)
1773                 return NULL;
1774         return snd_pcm_xrun_mode_names[mode];
1775 }
1776
1777 #ifndef DOC_HIDDEN
1778 link_warning(snd_pcm_xrun_mode_name, "Warning: xrun_mode is deprecated, consider to use stop_threshold");
1779 #endif
1780
1781 /**
1782  * \brief get name of PCM tstamp mode setting
1783  * \param mode PCM tstamp mode
1784  * \return ascii name of PCM tstamp mode setting
1785  */
1786 const char *snd_pcm_tstamp_mode_name(snd_pcm_tstamp_t mode)
1787 {
1788         if (mode > SND_PCM_TSTAMP_LAST)
1789                 return NULL;
1790         return snd_pcm_tstamp_mode_names[mode];
1791 }
1792
1793 /**
1794  * \brief get name of PCM state
1795  * \param state PCM state
1796  * \return ascii name of PCM state
1797  */
1798 const char *snd_pcm_state_name(snd_pcm_state_t state)
1799 {
1800         if (state > SND_PCM_STATE_LAST)
1801                 return NULL;
1802         return snd_pcm_state_names[state];
1803 }
1804
1805 /**
1806  * \brief get name of PCM type
1807  * \param type PCM type
1808  * \return ascii name of PCM type
1809  */
1810 #ifndef DOXYGEN
1811 const char *INTERNAL(snd_pcm_type_name)(snd_pcm_type_t type)
1812 #else
1813 const char *snd_pcm_type_name(snd_pcm_type_t type)
1814 #endif
1815 {
1816         if (type > SND_PCM_TYPE_LAST)
1817                 return NULL;
1818         return snd_pcm_type_names[type];
1819 }
1820 use_default_symbol_version(__snd_pcm_type_name, snd_pcm_type_name, ALSA_0.9.0);
1821
1822 /**
1823  * \brief Dump current hardware setup for PCM
1824  * \param pcm PCM handle
1825  * \param out Output handle
1826  * \return 0 on success otherwise a negative error code
1827  */
1828 int snd_pcm_dump_hw_setup(snd_pcm_t *pcm, snd_output_t *out)
1829 {
1830         assert(pcm);
1831         assert(out);
1832         if (CHECK_SANITY(! pcm->setup)) {
1833                 SNDMSG("PCM not set up");
1834                 return -EIO;
1835         }
1836         snd_output_printf(out, "  stream       : %s\n", snd_pcm_stream_name(pcm->stream));
1837         snd_output_printf(out, "  access       : %s\n", snd_pcm_access_name(pcm->access));
1838         snd_output_printf(out, "  format       : %s\n", snd_pcm_format_name(pcm->format));
1839         snd_output_printf(out, "  subformat    : %s\n", snd_pcm_subformat_name(pcm->subformat));
1840         snd_output_printf(out, "  channels     : %u\n", pcm->channels);
1841         snd_output_printf(out, "  rate         : %u\n", pcm->rate);
1842         snd_output_printf(out, "  exact rate   : %g (%u/%u)\n",
1843                           (pcm->rate_den ? ((double) pcm->rate_num / pcm->rate_den) : 0.0),
1844                           pcm->rate_num, pcm->rate_den);
1845         snd_output_printf(out, "  msbits       : %u\n", pcm->msbits);
1846         snd_output_printf(out, "  buffer_size  : %lu\n", pcm->buffer_size);
1847         snd_output_printf(out, "  period_size  : %lu\n", pcm->period_size);
1848         snd_output_printf(out, "  period_time  : %u\n", pcm->period_time);
1849         return 0;
1850 }
1851
1852 /**
1853  * \brief Dump current software setup for PCM
1854  * \param pcm PCM handle
1855  * \param out Output handle
1856  * \return 0 on success otherwise a negative error code
1857  */
1858 int snd_pcm_dump_sw_setup(snd_pcm_t *pcm, snd_output_t *out)
1859 {
1860         assert(pcm);
1861         assert(out);
1862         if (CHECK_SANITY(! pcm->setup)) {
1863                 SNDMSG("PCM not set up");
1864                 return -EIO;
1865         }
1866         snd_output_printf(out, "  tstamp_mode  : %s\n", snd_pcm_tstamp_mode_name(pcm->tstamp_mode));
1867         snd_output_printf(out, "  period_step  : %d\n", pcm->period_step);
1868         snd_output_printf(out, "  avail_min    : %ld\n", pcm->avail_min);
1869         snd_output_printf(out, "  period_event : %i\n", pcm->period_event);
1870         snd_output_printf(out, "  start_threshold  : %ld\n", pcm->start_threshold);
1871         snd_output_printf(out, "  stop_threshold   : %ld\n", pcm->stop_threshold);
1872         snd_output_printf(out, "  silence_threshold: %ld\n", pcm->silence_threshold);
1873         snd_output_printf(out, "  silence_size : %ld\n", pcm->silence_size);
1874         snd_output_printf(out, "  boundary     : %ld\n", pcm->boundary);
1875         return 0;
1876 }
1877
1878 /**
1879  * \brief Dump current setup (hardware and software) for PCM
1880  * \param pcm PCM handle
1881  * \param out Output handle
1882  * \return 0 on success otherwise a negative error code
1883  */
1884 int snd_pcm_dump_setup(snd_pcm_t *pcm, snd_output_t *out)
1885 {
1886         snd_pcm_dump_hw_setup(pcm, out);
1887         snd_pcm_dump_sw_setup(pcm, out);
1888         return 0;
1889 }
1890
1891 /**
1892  * \brief Dump status
1893  * \param status Status container
1894  * \param out Output handle
1895  * \return 0 on success otherwise a negative error code
1896  */
1897 int snd_pcm_status_dump(snd_pcm_status_t *status, snd_output_t *out)
1898 {
1899         assert(status);
1900         snd_output_printf(out, "  state       : %s\n", snd_pcm_state_name((snd_pcm_state_t) status->state));
1901         snd_output_printf(out, "  trigger_time: %ld.%06ld\n",
1902                 status->trigger_tstamp.tv_sec, status->trigger_tstamp.tv_nsec);
1903         snd_output_printf(out, "  tstamp      : %ld.%06ld\n",
1904                 status->tstamp.tv_sec, status->tstamp.tv_nsec);
1905         snd_output_printf(out, "  delay       : %ld\n", (long)status->delay);
1906         snd_output_printf(out, "  avail       : %ld\n", (long)status->avail);
1907         snd_output_printf(out, "  avail_max   : %ld\n", (long)status->avail_max);
1908         return 0;
1909 }
1910
1911 /**
1912  * \brief Dump PCM info
1913  * \param pcm PCM handle
1914  * \param out Output handle
1915  * \return 0 on success otherwise a negative error code
1916  */
1917 int snd_pcm_dump(snd_pcm_t *pcm, snd_output_t *out)
1918 {
1919         assert(pcm);
1920         assert(out);
1921         pcm->ops->dump(pcm->op_arg, out);
1922         return 0;
1923 }
1924
1925 /**
1926  * \brief Convert bytes in frames for a PCM
1927  * \param pcm PCM handle
1928  * \param bytes quantity in bytes
1929  * \return quantity expressed in frames
1930  */
1931 snd_pcm_sframes_t snd_pcm_bytes_to_frames(snd_pcm_t *pcm, ssize_t bytes)
1932 {
1933         assert(pcm);
1934         if (CHECK_SANITY(! pcm->setup)) {
1935                 SNDMSG("PCM not set up");
1936                 return -EIO;
1937         }
1938         return bytes * 8 / pcm->frame_bits;
1939 }
1940
1941 /**
1942  * \brief Convert frames in bytes for a PCM
1943  * \param pcm PCM handle
1944  * \param frames quantity in frames
1945  * \return quantity expressed in bytes
1946  */
1947 ssize_t snd_pcm_frames_to_bytes(snd_pcm_t *pcm, snd_pcm_sframes_t frames)
1948 {
1949         assert(pcm);
1950         if (CHECK_SANITY(! pcm->setup)) {
1951                 SNDMSG("PCM not set up");
1952                 return -EIO;
1953         }
1954         return frames * pcm->frame_bits / 8;
1955 }
1956
1957 /**
1958  * \brief Convert bytes in samples for a PCM
1959  * \param pcm PCM handle
1960  * \param bytes quantity in bytes
1961  * \return quantity expressed in samples
1962  */
1963 long snd_pcm_bytes_to_samples(snd_pcm_t *pcm, ssize_t bytes)
1964 {
1965         assert(pcm);
1966         if (CHECK_SANITY(! pcm->setup)) {
1967                 SNDMSG("PCM not set up");
1968                 return -EIO;
1969         }
1970         return bytes * 8 / pcm->sample_bits;
1971 }
1972
1973 /**
1974  * \brief Convert samples in bytes for a PCM
1975  * \param pcm PCM handle
1976  * \param samples quantity in samples
1977  * \return quantity expressed in bytes
1978  */
1979 ssize_t snd_pcm_samples_to_bytes(snd_pcm_t *pcm, long samples)
1980 {
1981         assert(pcm);
1982         if (CHECK_SANITY(! pcm->setup)) {
1983                 SNDMSG("PCM not set up");
1984                 return -EIO;
1985         }
1986         return samples * pcm->sample_bits / 8;
1987 }
1988
1989 /**
1990  * \brief Add an async handler for a PCM
1991  * \param handler Returned handler handle
1992  * \param pcm PCM handle
1993  * \param callback Callback function
1994  * \param private_data Callback private data
1995  * \return 0 otherwise a negative error code on failure
1996  *
1997  * The asynchronous callback is called when period boundary elapses.
1998  */
1999 int snd_async_add_pcm_handler(snd_async_handler_t **handler, snd_pcm_t *pcm, 
2000                               snd_async_callback_t callback, void *private_data)
2001 {
2002         int err;
2003         int was_empty;
2004         snd_async_handler_t *h;
2005         err = snd_async_add_handler(&h, _snd_pcm_async_descriptor(pcm),
2006                                     callback, private_data);
2007         if (err < 0)
2008                 return err;
2009         h->type = SND_ASYNC_HANDLER_PCM;
2010         h->u.pcm = pcm;
2011         was_empty = list_empty(&pcm->async_handlers);
2012         list_add_tail(&h->hlist, &pcm->async_handlers);
2013         if (was_empty) {
2014                 err = snd_pcm_async(pcm, snd_async_handler_get_signo(h), getpid());
2015                 if (err < 0) {
2016                         snd_async_del_handler(h);
2017                         return err;
2018                 }
2019         }
2020         *handler = h;
2021         return 0;
2022 }
2023
2024 /**
2025  * \brief Return PCM handle related to an async handler
2026  * \param handler Async handler handle
2027  * \return PCM handle
2028  */
2029 snd_pcm_t *snd_async_handler_get_pcm(snd_async_handler_t *handler)
2030 {
2031         if (handler->type != SND_ASYNC_HANDLER_PCM) {
2032                 SNDMSG("invalid handler type %d", handler->type);
2033                 return NULL;
2034         }
2035         return handler->u.pcm;
2036 }
2037
2038 static const char *const build_in_pcms[] = {
2039         "adpcm", "alaw", "copy", "dmix", "file", "hooks", "hw", "ladspa", "lfloat",
2040         "linear", "meter", "mulaw", "multi", "null", "empty", "plug", "rate", "route", "share",
2041         "shm", "dsnoop", "dshare", "asym", "iec958", "softvol", "mmap_emul",
2042         NULL
2043 };
2044
2045 static int snd_pcm_open_conf(snd_pcm_t **pcmp, const char *name,
2046                              snd_config_t *pcm_root, snd_config_t *pcm_conf,
2047                              snd_pcm_stream_t stream, int mode)
2048 {
2049         const char *str;
2050         char *buf = NULL, *buf1 = NULL;
2051         int err;
2052         snd_config_t *conf, *type_conf = NULL;
2053         snd_config_iterator_t i, next;
2054         const char *id;
2055         const char *lib = NULL, *open_name = NULL;
2056         int (*open_func)(snd_pcm_t **, const char *, 
2057                          snd_config_t *, snd_config_t *, 
2058                          snd_pcm_stream_t, int) = NULL;
2059 #ifndef PIC
2060         extern void *snd_pcm_open_symbols(void);
2061 #endif
2062         void *h = NULL;
2063         if (snd_config_get_type(pcm_conf) != SND_CONFIG_TYPE_COMPOUND) {
2064                 char *val;
2065                 id = NULL;
2066                 snd_config_get_id(pcm_conf, &id);
2067                 val = NULL;
2068                 snd_config_get_ascii(pcm_conf, &val);
2069                 SNDERR("Invalid type for PCM %s%sdefinition (id: %s, value: %s)", name ? name : "", name ? " " : "", id, val);
2070                 free(val);
2071                 return -EINVAL;
2072         }
2073         err = snd_config_search(pcm_conf, "type", &conf);
2074         if (err < 0) {
2075                 SNDERR("type is not defined");
2076                 return err;
2077         }
2078         err = snd_config_get_id(conf, &id);
2079         if (err < 0) {
2080                 SNDERR("unable to get id");
2081                 return err;
2082         }
2083         err = snd_config_get_string(conf, &str);
2084         if (err < 0) {
2085                 SNDERR("Invalid type for %s", id);
2086                 return err;
2087         }
2088         err = snd_config_search_definition(pcm_root, "pcm_type", str, &type_conf);
2089         if (err >= 0) {
2090                 if (snd_config_get_type(type_conf) != SND_CONFIG_TYPE_COMPOUND) {
2091                         SNDERR("Invalid type for PCM type %s definition", str);
2092                         goto _err;
2093                 }
2094                 snd_config_for_each(i, next, type_conf) {
2095                         snd_config_t *n = snd_config_iterator_entry(i);
2096                         const char *id;
2097                         if (snd_config_get_id(n, &id) < 0)
2098                                 continue;
2099                         if (strcmp(id, "comment") == 0)
2100                                 continue;
2101                         if (strcmp(id, "lib") == 0) {
2102                                 err = snd_config_get_string(n, &lib);
2103                                 if (err < 0) {
2104                                         SNDERR("Invalid type for %s", id);
2105                                         goto _err;
2106                                 }
2107                                 continue;
2108                         }
2109                         if (strcmp(id, "open") == 0) {
2110                                 err = snd_config_get_string(n, &open_name);
2111                                 if (err < 0) {
2112                                         SNDERR("Invalid type for %s", id);
2113                                         goto _err;
2114                                 }
2115                                 continue;
2116                         }
2117                         SNDERR("Unknown field %s", id);
2118                         err = -EINVAL;
2119                         goto _err;
2120                 }
2121         }
2122         if (!open_name) {
2123                 buf = malloc(strlen(str) + 32);
2124                 if (buf == NULL) {
2125                         err = -ENOMEM;
2126                         goto _err;
2127                 }
2128                 open_name = buf;
2129                 sprintf(buf, "_snd_pcm_%s_open", str);
2130         }
2131         if (!lib) {
2132                 const char *const *build_in = build_in_pcms;
2133                 while (*build_in) {
2134                         if (!strcmp(*build_in, str))
2135                                 break;
2136                         build_in++;
2137                 }
2138                 if (*build_in == NULL) {
2139                         buf1 = malloc(strlen(str) + sizeof(ALSA_PLUGIN_DIR) + 32);
2140                         if (buf1 == NULL) {
2141                                 err = -ENOMEM;
2142                                 goto _err;
2143                         }
2144                         lib = buf1;
2145                         sprintf(buf1, "%s/libasound_module_pcm_%s.so", ALSA_PLUGIN_DIR, str);
2146                 }
2147         }
2148 #ifndef PIC
2149         snd_pcm_open_symbols(); /* this call is for static linking only */
2150 #endif
2151         open_func = snd_dlobj_cache_lookup(open_name);
2152         if (open_func) {
2153                 err = 0;
2154                 goto _err;
2155         }
2156         h = snd_dlopen(lib, RTLD_NOW);
2157         if (h)
2158                 open_func = snd_dlsym(h, open_name, SND_DLSYM_VERSION(SND_PCM_DLSYM_VERSION));
2159         err = 0;
2160         if (!h) {
2161                 SNDERR("Cannot open shared library %s",
2162                        lib ? lib : "[builtin]");
2163                 err = -ENOENT;
2164         } else if (!open_func) {
2165                 SNDERR("symbol %s is not defined inside %s", open_name,
2166                        lib ? lib : "[builtin]");
2167                 snd_dlclose(h);
2168                 err = -ENXIO;
2169         }
2170        _err:
2171         if (err >= 0) {
2172                 err = open_func(pcmp, name, pcm_root, pcm_conf, stream, mode);
2173                 if (err >= 0) {
2174                         if (h /*&& (mode & SND_PCM_KEEP_ALIVE)*/) {
2175                                 snd_dlobj_cache_add(open_name, h, open_func);
2176                                 h = NULL;
2177                         }
2178                         (*pcmp)->dl_handle = h;
2179                         err = 0;
2180                 } else {
2181                         if (h)
2182                                 snd_dlclose(h);
2183                 }
2184         }
2185         if (type_conf)
2186                 snd_config_delete(type_conf);
2187         free(buf);
2188         free(buf1);
2189         return err;
2190 }
2191
2192 static int snd_pcm_open_noupdate(snd_pcm_t **pcmp, snd_config_t *root,
2193                                  const char *name, snd_pcm_stream_t stream,
2194                                  int mode, int hop)
2195 {
2196         int err;
2197         snd_config_t *pcm_conf;
2198         const char *str;
2199
2200         err = snd_config_search_definition(root, "pcm", name, &pcm_conf);
2201         if (err < 0) {
2202                 SNDERR("Unknown PCM %s", name);
2203                 return err;
2204         }
2205         if (snd_config_get_string(pcm_conf, &str) >= 0)
2206                 err = snd_pcm_open_noupdate(pcmp, root, str, stream, mode,
2207                                             hop + 1);
2208         else {
2209                 snd_config_set_hop(pcm_conf, hop);
2210                 err = snd_pcm_open_conf(pcmp, name, root, pcm_conf, stream, mode);
2211         }
2212         snd_config_delete(pcm_conf);
2213         return err;
2214 }
2215
2216 /**
2217  * \brief Opens a PCM
2218  * \param pcmp Returned PCM handle
2219  * \param name ASCII identifier of the PCM handle
2220  * \param stream Wanted stream
2221  * \param mode Open mode (see #SND_PCM_NONBLOCK, #SND_PCM_ASYNC)
2222  * \return 0 on success otherwise a negative error code
2223  */
2224 int snd_pcm_open(snd_pcm_t **pcmp, const char *name, 
2225                  snd_pcm_stream_t stream, int mode)
2226 {
2227         int err;
2228         assert(pcmp && name);
2229         err = snd_config_update();
2230         if (err < 0)
2231                 return err;
2232         return snd_pcm_open_noupdate(pcmp, snd_config, name, stream, mode, 0);
2233 }
2234
2235 /**
2236  * \brief Opens a PCM using local configuration
2237  * \param pcmp Returned PCM handle
2238  * \param name ASCII identifier of the PCM handle
2239  * \param stream Wanted stream
2240  * \param mode Open mode (see #SND_PCM_NONBLOCK, #SND_PCM_ASYNC)
2241  * \param lconf Local configuration
2242  * \return 0 on success otherwise a negative error code
2243  */
2244 int snd_pcm_open_lconf(snd_pcm_t **pcmp, const char *name, 
2245                        snd_pcm_stream_t stream, int mode,
2246                        snd_config_t *lconf)
2247 {
2248         assert(pcmp && name && lconf);
2249         return snd_pcm_open_noupdate(pcmp, lconf, name, stream, mode, 0);
2250 }
2251
2252 #ifndef DOC_HIDDEN
2253 int snd_pcm_new(snd_pcm_t **pcmp, snd_pcm_type_t type, const char *name,
2254                 snd_pcm_stream_t stream, int mode)
2255 {
2256         snd_pcm_t *pcm;
2257         pcm = calloc(1, sizeof(*pcm));
2258         if (!pcm)
2259                 return -ENOMEM;
2260         pcm->type = type;
2261         if (name)
2262                 pcm->name = strdup(name);
2263         pcm->stream = stream;
2264         pcm->mode = mode;
2265         pcm->poll_fd_count = 1;
2266         pcm->poll_fd = -1;
2267         pcm->op_arg = pcm;
2268         pcm->fast_op_arg = pcm;
2269         INIT_LIST_HEAD(&pcm->async_handlers);
2270         *pcmp = pcm;
2271         return 0;
2272 }
2273
2274 int snd_pcm_free(snd_pcm_t *pcm)
2275 {
2276         assert(pcm);
2277         free(pcm->name);
2278         free(pcm->hw.link_dst);
2279         free(pcm->appl.link_dst);
2280         if (pcm->dl_handle)
2281                 snd_dlclose(pcm->dl_handle);
2282         free(pcm);
2283         return 0;
2284 }
2285
2286 int snd_pcm_open_named_slave(snd_pcm_t **pcmp, const char *name,
2287                              snd_config_t *root,
2288                              snd_config_t *conf, snd_pcm_stream_t stream,
2289                              int mode, snd_config_t *parent_conf)
2290 {
2291         const char *str;
2292         int hop;
2293
2294         if ((hop = snd_config_check_hop(parent_conf)) < 0)
2295                 return hop;
2296         if (snd_config_get_string(conf, &str) >= 0)
2297                 return snd_pcm_open_noupdate(pcmp, root, str, stream, mode,
2298                                              hop + 1);
2299         return snd_pcm_open_conf(pcmp, name, root, conf, stream, mode);
2300 }
2301 #endif
2302
2303 /**
2304  * \brief Wait for a PCM to become ready
2305  * \param pcm PCM handle
2306  * \param timeout maximum time in milliseconds to wait,
2307  *        a negative value means infinity
2308  * \return a positive value on success otherwise a negative error code
2309  *         (-EPIPE for the xrun and -ESTRPIPE for the suspended status,
2310  *          others for general errors) 
2311  * \retval 0 timeout occurred
2312  * \retval 1 PCM stream is ready for I/O
2313  */
2314 int snd_pcm_wait(snd_pcm_t *pcm, int timeout)
2315 {
2316         if (snd_pcm_mmap_avail(pcm) >= pcm->avail_min) {
2317                 /* check more precisely */
2318                 switch (snd_pcm_state(pcm)) {
2319                 case SND_PCM_STATE_XRUN:
2320                         return -EPIPE;
2321                 case SND_PCM_STATE_SUSPENDED:
2322                         return -ESTRPIPE;
2323                 case SND_PCM_STATE_DISCONNECTED:
2324                         return -ENODEV;
2325                 default:
2326                         return 1;
2327                 }
2328         }
2329         return snd_pcm_wait_nocheck(pcm, timeout);
2330 }
2331
2332 #ifndef DOC_HIDDEN
2333 /* 
2334  * like snd_pcm_wait() but doesn't check mmap_avail before calling poll()
2335  *
2336  * used in drain code in some plugins
2337  */
2338 int snd_pcm_wait_nocheck(snd_pcm_t *pcm, int timeout)
2339 {
2340         struct pollfd *pfd;
2341         unsigned short *revents;
2342         int i, npfds, pollio, err, err_poll;
2343         
2344         npfds = snd_pcm_poll_descriptors_count(pcm);
2345         if (npfds <= 0 || npfds >= 16) {
2346                 SNDERR("Invalid poll_fds %d\n", npfds);
2347                 return -EIO;
2348         }
2349         pfd = alloca(sizeof(*pfd) * npfds);
2350         revents = alloca(sizeof(*revents) * npfds);
2351         err = snd_pcm_poll_descriptors(pcm, pfd, npfds);
2352         if (err < 0)
2353                 return err;
2354         if (err != npfds) {
2355                 SNDMSG("invalid poll descriptors %d\n", err);
2356                 return -EIO;
2357         }
2358         do {
2359                 pollio = 0;
2360                 err_poll = poll(pfd, npfds, timeout);
2361                 if (err_poll < 0) {
2362                         if (errno == EINTR)
2363                                 continue;
2364                         return -errno;
2365                 }
2366                 if (! err_poll)
2367                         break;
2368                 err = snd_pcm_poll_descriptors_revents(pcm, pfd, npfds, revents);
2369                 if (err < 0)
2370                         return err;
2371                 for (i = 0; i < npfds; i++) {
2372                         if (revents[i] & (POLLERR | POLLNVAL)) {
2373                                 /* check more precisely */
2374                                 switch (snd_pcm_state(pcm)) {
2375                                 case SND_PCM_STATE_XRUN:
2376                                         return -EPIPE;
2377                                 case SND_PCM_STATE_SUSPENDED:
2378                                         return -ESTRPIPE;
2379                                 case SND_PCM_STATE_DISCONNECTED:
2380                                         return -ENODEV;
2381                                 default:
2382                                         return -EIO;
2383                                 }
2384                         }
2385                         if ((revents[i] & (POLLIN | POLLOUT)) == 0)
2386                                 continue;
2387                         pollio++;
2388                 }
2389         } while (! pollio);
2390 #if 0 /* very useful code to test poll related problems */
2391         {
2392                 snd_pcm_sframes_t avail_update;
2393                 snd_pcm_hwsync(pcm);
2394                 avail_update = snd_pcm_avail_update(pcm);
2395                 if (avail_update < (snd_pcm_sframes_t)pcm->avail_min) {
2396                         printf("*** snd_pcm_wait() FATAL ERROR!!!\n");
2397                         printf("avail_min = %li, avail_update = %li\n", pcm->avail_min, avail_update);
2398                 }
2399         }
2400 #endif
2401         return err_poll > 0 ? 1 : 0;
2402 }
2403 #endif
2404
2405 /**
2406  * \brief Return number of frames ready to be read (capture) / written (playback)
2407  * \param pcm PCM handle
2408  * \return a positive number of frames ready otherwise a negative
2409  * error code
2410  *
2411  * On capture does all the actions needed to transport to application
2412  * level all the ready frames across underlying layers.
2413  *
2414  * The position is not synced with hardware (driver) position in the sound
2415  * ring buffer in this function. This function is a light version of
2416  * #snd_pcm_avail() .
2417  *
2418  * Using this function is ideal after poll() or select() when audio
2419  * file descriptor made the event and when application expects just period
2420  * timing.
2421  *
2422  * Also this function might be called after #snd_pcm_delay() or
2423  * #snd_pcm_hwsync() functions to move private ring buffer pointers
2424  * in alsa-lib (the internal plugin chain).
2425  */
2426 snd_pcm_sframes_t snd_pcm_avail_update(snd_pcm_t *pcm)
2427 {
2428         return pcm->fast_ops->avail_update(pcm->fast_op_arg);
2429 }
2430
2431 /**
2432  * \brief Return number of frames ready to be read (capture) / written (playback)
2433  * \param pcm PCM handle
2434  * \return a positive number of frames ready otherwise a negative
2435  * error code
2436  *
2437  * On capture does all the actions needed to transport to application
2438  * level all the ready frames across underlying layers.
2439  *
2440  * The position is synced with hardware (driver) position in the sound
2441  * ring buffer in this functions.
2442  */
2443 snd_pcm_sframes_t snd_pcm_avail(snd_pcm_t *pcm)
2444 {
2445         int err;
2446
2447         assert(pcm);
2448         if (CHECK_SANITY(! pcm->setup)) {
2449                 SNDMSG("PCM not set up");
2450                 return -EIO;
2451         }
2452         err = pcm->fast_ops->hwsync(pcm->fast_op_arg);
2453         if (err < 0)
2454                 return err;
2455         return pcm->fast_ops->avail_update(pcm->fast_op_arg);
2456 }
2457
2458 /**
2459  * \brief Combine snd_pcm_avail and snd_pcm_delay functions
2460  * \param pcm PCM handle
2461  * \param avail Number of available frames in the ring buffer
2462  * \param delay Total I/O latency in frames
2463  * \return zero on success otherwise a negative error code
2464  *
2465  * The avail and delay values retuned are in sync.
2466  */
2467 int snd_pcm_avail_delay(snd_pcm_t *pcm,
2468                         snd_pcm_sframes_t *availp,
2469                         snd_pcm_sframes_t *delayp)
2470 {
2471         snd_pcm_sframes_t sf;
2472
2473         assert(pcm && availp && delayp);
2474         if (CHECK_SANITY(! pcm->setup)) {
2475                 SNDMSG("PCM not set up");
2476                 return -EIO;
2477         }
2478         sf = pcm->fast_ops->delay(pcm->fast_op_arg, delayp);
2479         if (sf < 0)
2480                 return (int)sf;
2481         sf = pcm->fast_ops->avail_update(pcm->fast_op_arg);
2482         if (sf < 0)
2483                 return (int)sf;
2484         *availp = sf;
2485         return 0;
2486 }
2487
2488 /**
2489  * \brief Silence an area
2490  * \param dst_area area specification
2491  * \param dst_offset offset in frames inside area
2492  * \param samples samples to silence
2493  * \param format PCM sample format
2494  * \return 0 on success otherwise a negative error code
2495  */
2496 int snd_pcm_area_silence(const snd_pcm_channel_area_t *dst_area, snd_pcm_uframes_t dst_offset,
2497                          unsigned int samples, snd_pcm_format_t format)
2498 {
2499         /* FIXME: sub byte resolution and odd dst_offset */
2500         char *dst;
2501         unsigned int dst_step;
2502         int width;
2503         u_int64_t silence;
2504         if (!dst_area->addr)
2505                 return 0;
2506         dst = snd_pcm_channel_area_addr(dst_area, dst_offset);
2507         width = snd_pcm_format_physical_width(format);
2508         silence = snd_pcm_format_silence_64(format);
2509         if (dst_area->step == (unsigned int) width) {
2510                 unsigned int dwords = samples * width / 64;
2511                 u_int64_t *dstp = (u_int64_t *)dst;
2512                 samples -= dwords * 64 / width;
2513                 while (dwords-- > 0)
2514                         *dstp++ = silence;
2515                 if (samples == 0)
2516                         return 0;
2517         }
2518         dst_step = dst_area->step / 8;
2519         switch (width) {
2520         case 4: {
2521                 u_int8_t s0 = silence & 0xf0;
2522                 u_int8_t s1 = silence & 0x0f;
2523                 int dstbit = dst_area->first % 8;
2524                 int dstbit_step = dst_area->step % 8;
2525                 while (samples-- > 0) {
2526                         if (dstbit) {
2527                                 *dst &= 0xf0;
2528                                 *dst |= s1;
2529                         } else {
2530                                 *dst &= 0x0f;
2531                                 *dst |= s0;
2532                         }
2533                         dst += dst_step;
2534                         dstbit += dstbit_step;
2535                         if (dstbit == 8) {
2536                                 dst++;
2537                                 dstbit = 0;
2538                         }
2539                 }
2540                 break;
2541         }
2542         case 8: {
2543                 u_int8_t sil = silence;
2544                 while (samples-- > 0) {
2545                         *dst = sil;
2546                         dst += dst_step;
2547                 }
2548                 break;
2549         }
2550         case 16: {
2551                 u_int16_t sil = silence;
2552                 while (samples-- > 0) {
2553                         *(u_int16_t*)dst = sil;
2554                         dst += dst_step;
2555                 }
2556                 break;
2557         }
2558         case 24:
2559 #ifdef SNDRV_LITTLE_ENDIAN
2560                 *(dst + 0) = silence >> 0;
2561                 *(dst + 1) = silence >> 8;
2562                 *(dst + 2) = silence >> 16;
2563 #else
2564                 *(dst + 2) = silence >> 0;
2565                 *(dst + 1) = silence >> 8;
2566                 *(dst + 0) = silence >> 16;
2567 #endif
2568                 break;
2569         case 32: {
2570                 u_int32_t sil = silence;
2571                 while (samples-- > 0) {
2572                         *(u_int32_t*)dst = sil;
2573                         dst += dst_step;
2574                 }
2575                 break;
2576         }
2577         case 64: {
2578                 while (samples-- > 0) {
2579                         *(u_int64_t*)dst = silence;
2580                         dst += dst_step;
2581                 }
2582                 break;
2583         }
2584         default:
2585                 SNDMSG("invalid format width %d", width);
2586                 return -EINVAL;
2587         }
2588         return 0;
2589 }
2590
2591 /**
2592  * \brief Silence one or more areas
2593  * \param dst_areas areas specification (one for each channel)
2594  * \param dst_offset offset in frames inside area
2595  * \param channels channels count
2596  * \param frames frames to silence
2597  * \param format PCM sample format
2598  * \return 0 on success otherwise a negative error code
2599  */
2600 int snd_pcm_areas_silence(const snd_pcm_channel_area_t *dst_areas, snd_pcm_uframes_t dst_offset,
2601                           unsigned int channels, snd_pcm_uframes_t frames, snd_pcm_format_t format)
2602 {
2603         int width = snd_pcm_format_physical_width(format);
2604         while (channels > 0) {
2605                 void *addr = dst_areas->addr;
2606                 unsigned int step = dst_areas->step;
2607                 const snd_pcm_channel_area_t *begin = dst_areas;
2608                 int channels1 = channels;
2609                 unsigned int chns = 0;
2610                 int err;
2611                 while (1) {
2612                         channels1--;
2613                         chns++;
2614                         dst_areas++;
2615                         if (channels1 == 0 ||
2616                             dst_areas->addr != addr ||
2617                             dst_areas->step != step ||
2618                             dst_areas->first != dst_areas[-1].first + width)
2619                                 break;
2620                 }
2621                 if (chns > 1 && chns * width == step) {
2622                         /* Collapse the areas */
2623                         snd_pcm_channel_area_t d;
2624                         d.addr = begin->addr;
2625                         d.first = begin->first;
2626                         d.step = width;
2627                         err = snd_pcm_area_silence(&d, dst_offset * chns, frames * chns, format);
2628                         channels -= chns;
2629                 } else {
2630                         err = snd_pcm_area_silence(begin, dst_offset, frames, format);
2631                         dst_areas = begin + 1;
2632                         channels--;
2633                 }
2634                 if (err < 0)
2635                         return err;
2636         }
2637         return 0;
2638 }
2639
2640
2641 /**
2642  * \brief Copy an area
2643  * \param dst_area destination area specification
2644  * \param dst_offset offset in frames inside destination area
2645  * \param src_area source area specification
2646  * \param src_offset offset in frames inside source area
2647  * \param samples samples to copy
2648  * \param format PCM sample format
2649  * \return 0 on success otherwise a negative error code
2650  */
2651 int snd_pcm_area_copy(const snd_pcm_channel_area_t *dst_area, snd_pcm_uframes_t dst_offset,
2652                       const snd_pcm_channel_area_t *src_area, snd_pcm_uframes_t src_offset,
2653                       unsigned int samples, snd_pcm_format_t format)
2654 {
2655         /* FIXME: sub byte resolution and odd dst_offset */
2656         const char *src;
2657         char *dst;
2658         int width;
2659         int src_step, dst_step;
2660         if (dst_area == src_area && dst_offset == src_offset)
2661                 return 0;
2662         if (!src_area->addr)
2663                 return snd_pcm_area_silence(dst_area, dst_offset, samples, format);
2664         src = snd_pcm_channel_area_addr(src_area, src_offset);
2665         if (!dst_area->addr)
2666                 return 0;
2667         dst = snd_pcm_channel_area_addr(dst_area, dst_offset);
2668         width = snd_pcm_format_physical_width(format);
2669         if (src_area->step == (unsigned int) width &&
2670             dst_area->step == (unsigned int) width) {
2671                 size_t bytes = samples * width / 8;
2672                 samples -= bytes * 8 / width;
2673                 memcpy(dst, src, bytes);
2674                 if (samples == 0)
2675                         return 0;
2676         }
2677         src_step = src_area->step / 8;
2678         dst_step = dst_area->step / 8;
2679         switch (width) {
2680         case 4: {
2681                 int srcbit = src_area->first % 8;
2682                 int srcbit_step = src_area->step % 8;
2683                 int dstbit = dst_area->first % 8;
2684                 int dstbit_step = dst_area->step % 8;
2685                 while (samples-- > 0) {
2686                         unsigned char srcval;
2687                         if (srcbit)
2688                                 srcval = *src & 0x0f;
2689                         else
2690                                 srcval = *src & 0xf0;
2691                         if (dstbit)
2692                                 *dst &= 0xf0;
2693                         else
2694                                 *dst &= 0x0f;
2695                         *dst |= srcval;
2696                         src += src_step;
2697                         srcbit += srcbit_step;
2698                         if (srcbit == 8) {
2699                                 src++;
2700                                 srcbit = 0;
2701                         }
2702                         dst += dst_step;
2703                         dstbit += dstbit_step;
2704                         if (dstbit == 8) {
2705                                 dst++;
2706                                 dstbit = 0;
2707                         }
2708                 }
2709                 break;
2710         }
2711         case 8: {
2712                 while (samples-- > 0) {
2713                         *dst = *src;
2714                         src += src_step;
2715                         dst += dst_step;
2716                 }
2717                 break;
2718         }
2719         case 16: {
2720                 while (samples-- > 0) {
2721                         *(u_int16_t*)dst = *(const u_int16_t*)src;
2722                         src += src_step;
2723                         dst += dst_step;
2724                 }
2725                 break;
2726         }
2727         case 24:
2728                 while (samples-- > 0) {
2729                         *(dst + 0) = *(src + 0);
2730                         *(dst + 1) = *(src + 1);
2731                         *(dst + 2) = *(src + 2);
2732                         src += src_step;
2733                         dst += dst_step;
2734                 }
2735                 break;
2736         case 32: {
2737                 while (samples-- > 0) {
2738                         *(u_int32_t*)dst = *(const u_int32_t*)src;
2739                         src += src_step;
2740                         dst += dst_step;
2741                 }
2742                 break;
2743         }
2744         case 64: {
2745                 while (samples-- > 0) {
2746                         *(u_int64_t*)dst = *(const u_int64_t*)src;
2747                         src += src_step;
2748                         dst += dst_step;
2749                 }
2750                 break;
2751         }
2752         default:
2753                 SNDMSG("invalid format width %d", width);
2754                 return -EINVAL;
2755         }
2756         return 0;
2757 }
2758
2759 /**
2760  * \brief Copy one or more areas
2761  * \param dst_areas destination areas specification (one for each channel)
2762  * \param dst_offset offset in frames inside destination area
2763  * \param src_areas source areas specification (one for each channel)
2764  * \param src_offset offset in frames inside source area
2765  * \param channels channels count
2766  * \param frames frames to copy
2767  * \param format PCM sample format
2768  * \return 0 on success otherwise a negative error code
2769  */
2770 int snd_pcm_areas_copy(const snd_pcm_channel_area_t *dst_areas, snd_pcm_uframes_t dst_offset,
2771                        const snd_pcm_channel_area_t *src_areas, snd_pcm_uframes_t src_offset,
2772                        unsigned int channels, snd_pcm_uframes_t frames, snd_pcm_format_t format)
2773 {
2774         int width = snd_pcm_format_physical_width(format);
2775         assert(dst_areas);
2776         assert(src_areas);
2777         if (! channels) {
2778                 SNDMSG("invalid channels %d", channels);
2779                 return -EINVAL;
2780         }
2781         if (! frames) {
2782                 SNDMSG("invalid frames %ld", frames);
2783                 return -EINVAL;
2784         }
2785         while (channels > 0) {
2786                 unsigned int step = src_areas->step;
2787                 void *src_addr = src_areas->addr;
2788                 const snd_pcm_channel_area_t *src_start = src_areas;
2789                 void *dst_addr = dst_areas->addr;
2790                 const snd_pcm_channel_area_t *dst_start = dst_areas;
2791                 int channels1 = channels;
2792                 unsigned int chns = 0;
2793                 while (dst_areas->step == step) {
2794                         channels1--;
2795                         chns++;
2796                         src_areas++;
2797                         dst_areas++;
2798                         if (channels1 == 0 ||
2799                             src_areas->step != step ||
2800                             src_areas->addr != src_addr ||
2801                             dst_areas->addr != dst_addr ||
2802                             src_areas->first != src_areas[-1].first + width ||
2803                             dst_areas->first != dst_areas[-1].first + width)
2804                                 break;
2805                 }
2806                 if (chns > 1 && chns * width == step) {
2807                         /* Collapse the areas */
2808                         snd_pcm_channel_area_t s, d;
2809                         s.addr = src_start->addr;
2810                         s.first = src_start->first;
2811                         s.step = width;
2812                         d.addr = dst_start->addr;
2813                         d.first = dst_start->first;
2814                         d.step = width;
2815                         snd_pcm_area_copy(&d, dst_offset * chns,
2816                                           &s, src_offset * chns, 
2817                                           frames * chns, format);
2818                         channels -= chns;
2819                 } else {
2820                         snd_pcm_area_copy(dst_start, dst_offset,
2821                                           src_start, src_offset,
2822                                           frames, format);
2823                         src_areas = src_start + 1;
2824                         dst_areas = dst_start + 1;
2825                         channels--;
2826                 }
2827         }
2828         return 0;
2829 }
2830
2831 static void dump_one_param(snd_pcm_hw_params_t *params, unsigned int k, snd_output_t *out)
2832 {
2833         snd_output_printf(out, "%s: ", snd_pcm_hw_param_name(k));
2834         snd_pcm_hw_param_dump(params, k, out);
2835         snd_output_putc(out, '\n');
2836 }
2837
2838 /**
2839  * \brief Dump a PCM hardware configuration space
2840  * \param params Configuration space
2841  * \param out Output handle
2842  * \return 0 on success otherwise a negative error code
2843  */
2844 int snd_pcm_hw_params_dump(snd_pcm_hw_params_t *params, snd_output_t *out)
2845 {
2846         unsigned int k;
2847         for (k = SND_PCM_HW_PARAM_FIRST_MASK; k <= SND_PCM_HW_PARAM_LAST_MASK; k++)
2848                 dump_one_param(params, k, out);
2849         for (k = SND_PCM_HW_PARAM_FIRST_INTERVAL; k <= SND_PCM_HW_PARAM_LAST_INTERVAL; k++)
2850                 dump_one_param(params, k, out);
2851         return 0;
2852 }
2853
2854 /**
2855  * \brief Check, if hardware supports sample-resolution mmap for given configuration
2856  * \param params Configuration space
2857  * \return Boolean value
2858  * \retval 0 Hardware doesn't support sample-resolution mmap
2859  * \retval 1 Hardware supports sample-resolution mmap
2860  *
2861  * The return value is always one when given configuration is not exactly one.
2862  * Usually, #snd_pcm_hw_params() function chooses one configuration
2863  * from the configuration space.
2864  */
2865 int snd_pcm_hw_params_can_mmap_sample_resolution(const snd_pcm_hw_params_t *params)
2866 {
2867         assert(params);
2868         if (CHECK_SANITY(params->info == ~0U)) {
2869                 SNDMSG("invalid PCM info field");
2870                 return 0; /* FIXME: should be a negative error? */
2871         }
2872         return !!(params->info & SNDRV_PCM_INFO_MMAP_VALID);
2873 }
2874
2875 /**
2876  * \brief Check, if hardware does double buffering for start/stop for given configuration
2877  * \param params Configuration space
2878  * \return Boolean value
2879  * \retval 0 Hardware doesn't do double buffering for start/stop
2880  * \retval 1 Hardware does double buffering for start/stop
2881  *
2882  * It is not allowed to call this function when given configuration is not exactly one.
2883  * Usually, #snd_pcm_hw_params() function chooses one configuration
2884  * from the configuration space.
2885  */
2886 int snd_pcm_hw_params_is_double(const snd_pcm_hw_params_t *params)
2887 {
2888         assert(params);
2889         if (CHECK_SANITY(params->info == ~0U)) {
2890                 SNDMSG("invalid PCM info field");
2891                 return 0; /* FIXME: should be a negative error? */
2892         }
2893         return !!(params->info & SNDRV_PCM_INFO_DOUBLE);
2894 }
2895
2896 /**
2897  * \brief Check, if hardware does double buffering for data transfers for given configuration
2898  * \param params Configuration space
2899  * \return Boolean value
2900  * \retval 0 Hardware doesn't do double buffering for data transfers
2901  * \retval 1 Hardware does double buffering for data transfers
2902  *
2903  * It is not allowed to call this function when given configuration is not exactly one.
2904  * Usually, #snd_pcm_hw_params() function chooses one configuration
2905  * from the configuration space.
2906  */
2907 int snd_pcm_hw_params_is_batch(const snd_pcm_hw_params_t *params)
2908 {
2909         assert(params);
2910         if (CHECK_SANITY(params->info == ~0U)) {
2911                 SNDMSG("invalid PCM info field");
2912                 return 0; /* FIXME: should be a negative error? */
2913         }
2914         return !!(params->info & SNDRV_PCM_INFO_BATCH);
2915 }
2916
2917 /**
2918  * \brief Check, if hardware does block transfers for samples for given configuration
2919  * \param params Configuration space
2920  * \return Boolean value
2921  * \retval 0 Hardware doesn't block transfers
2922  * \retval 1 Hardware does block transfers
2923  *
2924  * It is not allowed to call this function when given configuration is not exactly one.
2925  * Usually, #snd_pcm_hw_params() function chooses one configuration
2926  * from the configuration space.
2927  */
2928 int snd_pcm_hw_params_is_block_transfer(const snd_pcm_hw_params_t *params)
2929 {
2930         assert(params);
2931         if (CHECK_SANITY(params->info == ~0U)) {
2932                 SNDMSG("invalid PCM info field");
2933                 return 0; /* FIXME: should be a negative error? */
2934         }
2935         return !!(params->info & SNDRV_PCM_INFO_BLOCK_TRANSFER);
2936 }
2937
2938 /**
2939  * \brief Check, if timestamps are monotonic for given configuration
2940  * \param params Configuration space
2941  * \return Boolean value
2942  * \retval 0 Device doesn't do monotomic timestamps
2943  * \retval 1 Device does monotonic timestamps
2944  *
2945  * It is not allowed to call this function when given configuration is not exactly one.
2946  * Usually, #snd_pcm_hw_params() function chooses one configuration
2947  * from the configuration space.
2948  */
2949 int snd_pcm_hw_params_is_monotonic(const snd_pcm_hw_params_t *params)
2950 {
2951         assert(params);
2952         if (CHECK_SANITY(params->info == ~0U)) {
2953                 SNDMSG("invalid PCM info field");
2954                 return 0; /* FIXME: should be a negative error? */
2955         }
2956         return !!(params->info & SND_PCM_INFO_MONOTONIC);
2957 }
2958
2959 /**
2960  * \brief Check, if hardware supports overrange detection
2961  * \param params Configuration space
2962  * \return Boolean value
2963  * \retval 0 Hardware doesn't support overrange detection
2964  * \retval 1 Hardware supports overrange detection
2965  *
2966  * It is not allowed to call this function when given configuration is not exactly one.
2967  * Usually, #snd_pcm_hw_params() function chooses one configuration
2968  * from the configuration space.
2969  */
2970 int snd_pcm_hw_params_can_overrange(const snd_pcm_hw_params_t *params)
2971 {
2972         assert(params);
2973         if (CHECK_SANITY(params->info == ~0U)) {
2974                 SNDMSG("invalid PCM info field");
2975                 return 0; /* FIXME: should be a negative error? */
2976         }
2977         return !!(params->info & SNDRV_PCM_INFO_OVERRANGE);
2978 }
2979
2980 /**
2981  * \brief Check, if hardware supports pause
2982  * \param params Configuration space
2983  * \return Boolean value
2984  * \retval 0 Hardware doesn't support pause
2985  * \retval 1 Hardware supports pause
2986  *
2987  * It is not allowed to call this function when given configuration is not exactly one.
2988  * Usually, #snd_pcm_hw_params() function chooses one configuration
2989  * from the configuration space.
2990  */
2991 int snd_pcm_hw_params_can_pause(const snd_pcm_hw_params_t *params)
2992 {
2993         assert(params);
2994         if (CHECK_SANITY(params->info == ~0U)) {
2995                 SNDMSG("invalid PCM info field");
2996                 return 0; /* FIXME: should be a negative error? */
2997         }
2998         return !!(params->info & SNDRV_PCM_INFO_PAUSE);
2999 }
3000
3001 /**
3002  * \brief Check, if hardware supports resume
3003  * \param params Configuration space
3004  * \return Boolean value
3005  * \retval 0 Hardware doesn't support resume
3006  * \retval 1 Hardware supports resume
3007  *
3008  * It is not allowed to call this function when given configuration is not exactly one.
3009  * Usually, #snd_pcm_hw_params() function chooses one configuration
3010  * from the configuration space.
3011  */
3012 int snd_pcm_hw_params_can_resume(const snd_pcm_hw_params_t *params)
3013 {
3014         assert(params);
3015         if (CHECK_SANITY(params->info == ~0U)) {
3016                 SNDMSG("invalid PCM info field");
3017                 return 0; /* FIXME: should be a negative error? */
3018         }
3019         return !!(params->info & SNDRV_PCM_INFO_RESUME);
3020 }
3021
3022 /**
3023  * \brief Check, if hardware does half-duplex only
3024  * \param params Configuration space
3025  * \return Boolean value
3026  * \retval 0 Hardware doesn't do half-duplex
3027  * \retval 1 Hardware does half-duplex
3028  *
3029  * It is not allowed to call this function when given configuration is not exactly one.
3030  * Usually, #snd_pcm_hw_params() function chooses one configuration
3031  * from the configuration space.
3032  */
3033 int snd_pcm_hw_params_is_half_duplex(const snd_pcm_hw_params_t *params)
3034 {
3035         assert(params);
3036         if (CHECK_SANITY(params->info == ~0U)) {
3037                 SNDMSG("invalid PCM info field");
3038                 return 0; /* FIXME: should be a negative error? */
3039         }
3040         return !!(params->info & SNDRV_PCM_INFO_HALF_DUPLEX);
3041 }
3042
3043 /**
3044  * \brief Check, if hardware does joint-duplex (playback and capture are somewhat correlated)
3045  * \param params Configuration space
3046  * \return Boolean value
3047  * \retval 0 Hardware doesn't do joint-duplex
3048  * \retval 1 Hardware does joint-duplex
3049  *
3050  * It is not allowed to call this function when given configuration is not exactly one.
3051  * Usually, #snd_pcm_hw_params() function chooses one configuration
3052  * from the configuration space.
3053  */
3054 int snd_pcm_hw_params_is_joint_duplex(const snd_pcm_hw_params_t *params)
3055 {
3056         assert(params);
3057         if (CHECK_SANITY(params->info == ~0U)) {
3058                 SNDMSG("invalid PCM info field");
3059                 return 0; /* FIXME: should be a negative error? */
3060         }
3061         return !!(params->info & SNDRV_PCM_INFO_JOINT_DUPLEX);
3062 }
3063
3064 /**
3065  * \brief Check, if hardware supports synchronized start with sample resolution
3066  * \param params Configuration space
3067  * \return Boolean value
3068  * \retval 0 Hardware doesn't support synchronized start
3069  * \retval 1 Hardware supports synchronized start
3070  *
3071  * It is not allowed to call this function when given configuration is not exactly one.
3072  * Usually, #snd_pcm_hw_params() function chooses one configuration
3073  * from the configuration space.
3074  */
3075 int snd_pcm_hw_params_can_sync_start(const snd_pcm_hw_params_t *params)
3076 {
3077         assert(params);
3078         if (CHECK_SANITY(params->info == ~0U)) {
3079                 SNDMSG("invalid PCM info field");
3080                 return 0; /* FIXME: should be a negative error? */
3081         }
3082         return !!(params->info & SNDRV_PCM_INFO_SYNC_START);
3083 }
3084
3085 /**
3086  * \brief Get rate exact info from a configuration space
3087  * \param params Configuration space
3088  * \param rate_num Pointer to returned rate numerator
3089  * \param rate_den Pointer to returned rate denominator
3090  * \return 0 otherwise a negative error code if the info is not available
3091  *
3092  * It is not allowed to call this function when given configuration is not exactly one.
3093  * Usually, #snd_pcm_hw_params() function chooses one configuration
3094  * from the configuration space.
3095  */
3096 int snd_pcm_hw_params_get_rate_numden(const snd_pcm_hw_params_t *params,
3097                                       unsigned int *rate_num, unsigned int *rate_den)
3098 {
3099         assert(params);
3100         if (CHECK_SANITY(params->rate_den == 0)) {
3101                 SNDMSG("invalid rate_den value");
3102                 return -EINVAL;
3103         }
3104         *rate_num = params->rate_num;
3105         *rate_den = params->rate_den;
3106         return 0;
3107 }
3108
3109 /**
3110  * \brief Get sample resolution info from a configuration space
3111  * \param params Configuration space
3112  * \return signification bits in sample otherwise a negative error code if the info is not available
3113  *
3114  * It is not allowed to call this function when given configuration is not exactly one.
3115  * Usually, #snd_pcm_hw_params() function chooses one configuration
3116  * from the configuration space.
3117  */
3118 int snd_pcm_hw_params_get_sbits(const snd_pcm_hw_params_t *params)
3119 {
3120         assert(params);
3121         if (CHECK_SANITY(params->msbits == 0)) {
3122                 SNDMSG("invalid msbits value");
3123                 return -EINVAL;
3124         }
3125         return params->msbits;
3126 }
3127
3128 /**
3129  * \brief Get hard are FIFO size info from a configuration space
3130  * \param params Configuration space
3131  * \return FIFO size in frames otherwise a negative error code if the info is not available
3132  *
3133  * It is not allowed to call this function when given configuration is not exactly one.
3134  * Usually, #snd_pcm_hw_params() function chooses one configuration
3135  * from the configuration space.
3136  */
3137 int snd_pcm_hw_params_get_fifo_size(const snd_pcm_hw_params_t *params)
3138 {
3139         assert(params);
3140         if (CHECK_SANITY(params->info == ~0U)) {
3141                 SNDMSG("invalid PCM info field");
3142                 return -EINVAL;
3143         }
3144         return params->fifo_size;
3145 }
3146
3147 /**
3148  * \brief Fill params with a full configuration space for a PCM
3149  * \param pcm PCM handle
3150  * \param params Configuration space
3151  */
3152 int snd_pcm_hw_params_any(snd_pcm_t *pcm, snd_pcm_hw_params_t *params)
3153 {
3154         _snd_pcm_hw_params_any(params);
3155         return snd_pcm_hw_refine(pcm, params);
3156 }
3157
3158 /**
3159  * \brief get size of #snd_pcm_access_mask_t
3160  * \return size in bytes
3161  */
3162 size_t snd_pcm_access_mask_sizeof()
3163 {
3164         return sizeof(snd_pcm_access_mask_t);
3165 }
3166
3167 /**
3168  * \brief allocate an empty #snd_pcm_access_mask_t using standard malloc
3169  * \param ptr returned pointer
3170  * \return 0 on success otherwise negative error code
3171  */
3172 int snd_pcm_access_mask_malloc(snd_pcm_access_mask_t **ptr)
3173 {
3174         assert(ptr);
3175         *ptr = calloc(1, sizeof(snd_pcm_access_mask_t));
3176         if (!*ptr)
3177                 return -ENOMEM;
3178         return 0;
3179 }
3180
3181 /**
3182  * \brief frees a previously allocated #snd_pcm_access_mask_t
3183  * \param obj pointer to object to free
3184  */
3185 void snd_pcm_access_mask_free(snd_pcm_access_mask_t *obj)
3186 {
3187         free(obj);
3188 }
3189
3190 /**
3191  * \brief copy one #snd_pcm_access_mask_t to another
3192  * \param dst pointer to destination
3193  * \param src pointer to source
3194  */
3195 void snd_pcm_access_mask_copy(snd_pcm_access_mask_t *dst, const snd_pcm_access_mask_t *src)
3196 {
3197         assert(dst && src);
3198         *dst = *src;
3199 }
3200
3201 /**
3202  * \brief reset all bits in a #snd_pcm_access_mask_t
3203  * \param mask pointer to mask
3204  */
3205 void snd_pcm_access_mask_none(snd_pcm_access_mask_t *mask)
3206 {
3207         snd_mask_none((snd_mask_t *) mask);
3208 }
3209
3210 /**
3211  * \brief set all bits in a #snd_pcm_access_mask_t
3212  * \param mask pointer to mask
3213  */
3214 void snd_pcm_access_mask_any(snd_pcm_access_mask_t *mask)
3215 {
3216         snd_mask_any((snd_mask_t *) mask);
3217 }
3218
3219 /**
3220  * \brief test the presence of an access type in a #snd_pcm_access_mask_t
3221  * \param mask pointer to mask
3222  * \param val access type
3223  */
3224 int snd_pcm_access_mask_test(const snd_pcm_access_mask_t *mask, snd_pcm_access_t val)
3225 {
3226         return snd_mask_test((const snd_mask_t *) mask, (unsigned long) val);
3227 }
3228
3229 /**
3230  * \brief test, if given a #snd_pcm_access_mask_t is empty
3231  * \param mask pointer to mask
3232  * \retval 0 not empty
3233  * \retval 1 empty
3234  */
3235 int snd_pcm_access_mask_empty(const snd_pcm_access_mask_t *mask)
3236 {
3237         return snd_mask_empty((const snd_mask_t *) mask);
3238 }
3239
3240 /**
3241  * \brief make an access type present in a #snd_pcm_access_mask_t
3242  * \param mask pointer to mask
3243  * \param val access type
3244  */
3245 void snd_pcm_access_mask_set(snd_pcm_access_mask_t *mask, snd_pcm_access_t val)
3246 {
3247         snd_mask_set((snd_mask_t *) mask, (unsigned long) val);
3248 }
3249
3250 /**
3251  * \brief make an access type missing from a #snd_pcm_access_mask_t
3252  * \param mask pointer to mask
3253  * \param val access type
3254  */
3255 void snd_pcm_access_mask_reset(snd_pcm_access_mask_t *mask, snd_pcm_access_t val)
3256 {
3257         snd_mask_reset((snd_mask_t *) mask, (unsigned long) val);
3258 }
3259
3260 /**
3261  * \brief get size of #snd_pcm_format_mask_t
3262  * \return size in bytes
3263  */
3264 size_t snd_pcm_format_mask_sizeof()
3265 {
3266         return sizeof(snd_pcm_format_mask_t);
3267 }
3268
3269 /**
3270  * \brief allocate an empty #snd_pcm_format_mask_t using standard malloc
3271  * \param ptr returned pointer
3272  * \return 0 on success otherwise negative error code
3273  */
3274 int snd_pcm_format_mask_malloc(snd_pcm_format_mask_t **ptr)
3275 {
3276         assert(ptr);
3277         *ptr = calloc(1, sizeof(snd_pcm_format_mask_t));
3278         if (!*ptr)
3279                 return -ENOMEM;
3280         return 0;
3281 }
3282
3283 /**
3284  * \brief frees a previously allocated #snd_pcm_format_mask_t
3285  * \param obj pointer to object to free
3286  */
3287 void snd_pcm_format_mask_free(snd_pcm_format_mask_t *obj)
3288 {
3289         free(obj);
3290 }
3291
3292 /**
3293  * \brief copy one #snd_pcm_format_mask_t to another
3294  * \param dst pointer to destination
3295  * \param src pointer to source
3296  */
3297 void snd_pcm_format_mask_copy(snd_pcm_format_mask_t *dst, const snd_pcm_format_mask_t *src)
3298 {
3299         assert(dst && src);
3300         *dst = *src;
3301 }
3302
3303 /**
3304  * \brief reset all bits in a #snd_pcm_format_mask_t
3305  * \param mask pointer to mask
3306  */
3307 void snd_pcm_format_mask_none(snd_pcm_format_mask_t *mask)
3308 {
3309         snd_mask_none((snd_mask_t *) mask);
3310 }
3311
3312 /**
3313  * \brief set all bits in a #snd_pcm_format_mask_t
3314  * \param mask pointer to mask
3315  */
3316 void snd_pcm_format_mask_any(snd_pcm_format_mask_t *mask)
3317 {
3318         snd_mask_any((snd_mask_t *) mask);
3319 }
3320
3321 /**
3322  * \brief test the presence of a format in a #snd_pcm_format_mask_t
3323  * \param mask pointer to mask
3324  * \param val format
3325  */
3326 int snd_pcm_format_mask_test(const snd_pcm_format_mask_t *mask, snd_pcm_format_t val)
3327 {
3328         return snd_mask_test((const snd_mask_t *) mask, (unsigned long) val);
3329 }
3330
3331 /**
3332  * \brief test, if given a #snd_pcm_format_mask_t is empty
3333  * \param mask pointer to mask
3334  * \retval 0 not empty
3335  * \retval 1 empty
3336  */
3337 int snd_pcm_format_mask_empty(const snd_pcm_format_mask_t *mask)
3338 {
3339         return snd_mask_empty((const snd_mask_t *) mask);
3340 }
3341
3342 /**
3343  * \brief make a format present in a #snd_pcm_format_mask_t
3344  * \param mask pointer to mask
3345  * \param val format
3346  */
3347 void snd_pcm_format_mask_set(snd_pcm_format_mask_t *mask, snd_pcm_format_t val)
3348 {
3349         snd_mask_set((snd_mask_t *) mask, (unsigned long) val);
3350 }
3351
3352 /**
3353  * \brief make a format missing from a #snd_pcm_format_mask_t
3354  * \param mask pointer to mask
3355  * \param val format
3356  */
3357 void snd_pcm_format_mask_reset(snd_pcm_format_mask_t *mask, snd_pcm_format_t val)
3358 {
3359         snd_mask_reset((snd_mask_t *) mask, (unsigned long) val);
3360 }
3361
3362
3363 /**
3364  * \brief get size of #snd_pcm_subformat_mask_t
3365  * \return size in bytes
3366  */
3367 size_t snd_pcm_subformat_mask_sizeof()
3368 {
3369         return sizeof(snd_pcm_subformat_mask_t);
3370 }
3371
3372 /**
3373  * \brief allocate an empty #snd_pcm_subformat_mask_t using standard malloc
3374  * \param ptr returned pointer
3375  * \return 0 on success otherwise negative error code
3376  */
3377 int snd_pcm_subformat_mask_malloc(snd_pcm_subformat_mask_t **ptr)
3378 {
3379         assert(ptr);
3380         *ptr = calloc(1, sizeof(snd_pcm_subformat_mask_t));
3381         if (!*ptr)
3382                 return -ENOMEM;
3383         return 0;
3384 }
3385
3386 /**
3387  * \brief frees a previously allocated #snd_pcm_subformat_mask_t
3388  * \param obj pointer to object to free
3389  */
3390 void snd_pcm_subformat_mask_free(snd_pcm_subformat_mask_t *obj)
3391 {
3392         free(obj);
3393 }
3394
3395 /**
3396  * \brief copy one #snd_pcm_subformat_mask_t to another
3397  * \param dst pointer to destination
3398  * \param src pointer to source
3399  */
3400 void snd_pcm_subformat_mask_copy(snd_pcm_subformat_mask_t *dst, const snd_pcm_subformat_mask_t *src)
3401 {
3402         assert(dst && src);
3403         *dst = *src;
3404 }
3405
3406 /**
3407  * \brief reset all bits in a #snd_pcm_subformat_mask_t
3408  * \param mask pointer to mask
3409  */
3410 void snd_pcm_subformat_mask_none(snd_pcm_subformat_mask_t *mask)
3411 {
3412         snd_mask_none((snd_mask_t *) mask);
3413 }
3414
3415 /**
3416  * \brief set all bits in a #snd_pcm_subformat_mask_t
3417  * \param mask pointer to mask
3418  */
3419 void snd_pcm_subformat_mask_any(snd_pcm_subformat_mask_t *mask)
3420 {
3421         snd_mask_any((snd_mask_t *) mask);
3422 }
3423
3424 /**
3425  * \brief test the presence of a subformat in a #snd_pcm_subformat_mask_t
3426  * \param mask pointer to mask
3427  * \param val subformat
3428  */
3429 int snd_pcm_subformat_mask_test(const snd_pcm_subformat_mask_t *mask, snd_pcm_subformat_t val)
3430 {
3431         return snd_mask_test((const snd_mask_t *) mask, (unsigned long) val);
3432 }
3433
3434 /**
3435  * \brief test, if given a #snd_pcm_subformat_mask_t is empty
3436  * \param mask pointer to mask
3437  * \retval 0 not empty
3438  * \retval 1 empty
3439  */
3440 int snd_pcm_subformat_mask_empty(const snd_pcm_subformat_mask_t *mask)
3441 {
3442         return snd_mask_empty((const snd_mask_t *) mask);
3443 }
3444
3445 /**
3446  * \brief make a subformat present in a #snd_pcm_subformat_mask_t
3447  * \param mask pointer to mask
3448  * \param val subformat
3449  */
3450 void snd_pcm_subformat_mask_set(snd_pcm_subformat_mask_t *mask, snd_pcm_subformat_t val)
3451 {
3452         snd_mask_set((snd_mask_t *) mask, (unsigned long) val);
3453 }
3454
3455 /**
3456  * \brief make a subformat missing from a #snd_pcm_subformat_mask_t
3457  * \param mask pointer to mask
3458  * \param val subformat
3459  */
3460 void snd_pcm_subformat_mask_reset(snd_pcm_subformat_mask_t *mask, snd_pcm_subformat_t val)
3461 {
3462         snd_mask_reset((snd_mask_t *) mask, (unsigned long) val);
3463 }
3464
3465
3466 /**
3467  * \brief get size of #snd_pcm_hw_params_t
3468  * \return size in bytes
3469  */
3470 size_t snd_pcm_hw_params_sizeof()
3471 {
3472         return sizeof(snd_pcm_hw_params_t);
3473 }
3474
3475 /**
3476  * \brief allocate an invalid #snd_pcm_hw_params_t using standard malloc
3477  * \param ptr returned pointer
3478  * \return 0 on success otherwise negative error code
3479  */
3480 int snd_pcm_hw_params_malloc(snd_pcm_hw_params_t **ptr)
3481 {
3482         assert(ptr);
3483         *ptr = calloc(1, sizeof(snd_pcm_hw_params_t));
3484         if (!*ptr)
3485                 return -ENOMEM;
3486         return 0;
3487 }
3488
3489 /**
3490  * \brief frees a previously allocated #snd_pcm_hw_params_t
3491  * \param obj pointer to object to free
3492  */
3493 void snd_pcm_hw_params_free(snd_pcm_hw_params_t *obj)
3494 {
3495         free(obj);
3496 }
3497
3498 /**
3499  * \brief copy one #snd_pcm_hw_params_t to another
3500  * \param dst pointer to destination
3501  * \param src pointer to source
3502  */
3503 void snd_pcm_hw_params_copy(snd_pcm_hw_params_t *dst, const snd_pcm_hw_params_t *src)
3504 {
3505         assert(dst && src);
3506         *dst = *src;
3507 }
3508
3509
3510 /**
3511  * \brief Extract access type from a configuration space
3512  * \param params Configuration space
3513  * \param access Returned value
3514  * \return access type otherwise a negative error code if not exactly one is present
3515  */
3516 #ifndef DOXYGEN
3517 int INTERNAL(snd_pcm_hw_params_get_access)(const snd_pcm_hw_params_t *params, snd_pcm_access_t *access)
3518 #else
3519 int snd_pcm_hw_params_get_access(const snd_pcm_hw_params_t *params, snd_pcm_access_t *access)
3520 #endif
3521 {
3522         unsigned int _val;
3523         int err = snd_pcm_hw_param_get(params, SND_PCM_HW_PARAM_ACCESS, &_val, NULL);
3524         if (err >= 0)
3525                 *access = _val;
3526         return err;
3527 }
3528
3529 /**
3530  * \brief Verify if an access type is available inside a configuration space for a PCM
3531  * \param pcm PCM handle
3532  * \param params Configuration space
3533  * \param access access type
3534  * \return 0 if available a negative error code otherwise
3535  */
3536 int snd_pcm_hw_params_test_access(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, snd_pcm_access_t access)
3537 {
3538         return snd_pcm_hw_param_set(pcm, params, SND_TEST, SND_PCM_HW_PARAM_ACCESS, access, 0);
3539 }
3540
3541 /**
3542  * \brief Restrict a configuration space to contain only one access type
3543  * \param pcm PCM handle
3544  * \param params Configuration space
3545  * \param access access type
3546  * \return 0 otherwise a negative error code if configuration space would become empty
3547  */
3548 int snd_pcm_hw_params_set_access(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, snd_pcm_access_t access)
3549 {
3550         return snd_pcm_hw_param_set(pcm, params, SND_TRY, SND_PCM_HW_PARAM_ACCESS, access, 0);
3551 }
3552
3553 /**
3554  * \brief Restrict a configuration space to contain only its first access type
3555  * \param pcm PCM handle
3556  * \param params Configuration space
3557  * \param access Returned first access type
3558  * \return 0 otherwise a negative error code
3559  */
3560 #ifndef DOXYGEN
3561 int INTERNAL(snd_pcm_hw_params_set_access_first)(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, snd_pcm_access_t *access)
3562 #else
3563 int snd_pcm_hw_params_set_access_first(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, snd_pcm_access_t *access)
3564 #endif
3565 {
3566         return snd_pcm_hw_param_set_first(pcm, params, SND_PCM_HW_PARAM_ACCESS, access, NULL);
3567 }
3568
3569 /**
3570  * \brief Restrict a configuration space to contain only its last access type
3571  * \param pcm PCM handle
3572  * \param params Configuration space
3573  * \param access Returned last access type
3574  * \return 0 otherwise a negative error code
3575  */
3576 #ifndef DOXYGEN
3577 int INTERNAL(snd_pcm_hw_params_set_access_last)(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, snd_pcm_access_t *access)
3578 #else
3579 int snd_pcm_hw_params_set_access_last(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, snd_pcm_access_t *access)
3580 #endif
3581 {
3582         return snd_pcm_hw_param_set_last(pcm, params, SND_PCM_HW_PARAM_ACCESS, access, NULL);
3583 }
3584
3585 /**
3586  * \brief Restrict a configuration space to contain only a set of access types
3587  * \param pcm PCM handle
3588  * \param params Configuration space
3589  * \param mask Access mask
3590  * \return 0 otherwise a negative error code
3591  */
3592 int snd_pcm_hw_params_set_access_mask(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, snd_pcm_access_mask_t *mask)
3593 {
3594         return snd_pcm_hw_param_set_mask(pcm, params, SND_TRY, SND_PCM_HW_PARAM_ACCESS, (snd_mask_t *) mask);
3595 }
3596
3597 /**
3598  * \brief Get access mask from a configuration space
3599  * \param params Configuration space
3600  * \param mask Returned Access mask
3601  */
3602 int snd_pcm_hw_params_get_access_mask(snd_pcm_hw_params_t *params, snd_pcm_access_mask_t *mask)
3603 {
3604         if (params == NULL || mask == NULL)
3605                 return -EINVAL;
3606         snd_pcm_access_mask_copy(mask, snd_pcm_hw_param_get_mask(params, SND_PCM_HW_PARAM_ACCESS));
3607         return 0;
3608 }
3609
3610
3611 /**
3612  * \brief Extract format from a configuration space
3613  * \param params Configuration space
3614  * \param format returned format
3615  * \return format otherwise a negative error code if not exactly one is present
3616  */
3617 #ifndef DOXYGEN
3618 int INTERNAL(snd_pcm_hw_params_get_format)(const snd_pcm_hw_params_t *params, snd_pcm_format_t *format)
3619 #else
3620 int snd_pcm_hw_params_get_format(const snd_pcm_hw_params_t *params, snd_pcm_format_t *format)
3621 #endif
3622 {
3623         return snd_pcm_hw_param_get(params, SND_PCM_HW_PARAM_FORMAT, (unsigned int *)format, NULL);
3624 }
3625
3626 /**
3627  * \brief Verify if a format is available inside a configuration space for a PCM
3628  * \param pcm PCM handle
3629  * \param params Configuration space
3630  * \param format format
3631  * \return 0 if available a negative error code otherwise
3632  */
3633 int snd_pcm_hw_params_test_format(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, snd_pcm_format_t format)
3634 {
3635         return snd_pcm_hw_param_set(pcm, params, SND_TEST, SND_PCM_HW_PARAM_FORMAT, format, 0);
3636 }
3637
3638 /**
3639  * \brief Restrict a configuration space to contain only one format
3640  * \param pcm PCM handle
3641  * \param params Configuration space
3642  * \param format format
3643  * \return 0 otherwise a negative error code
3644  */
3645 int snd_pcm_hw_params_set_format(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, snd_pcm_format_t format)
3646 {
3647         return snd_pcm_hw_param_set(pcm, params, SND_TRY, SND_PCM_HW_PARAM_FORMAT, format, 0);
3648 }
3649
3650 /**
3651  * \brief Restrict a configuration space to contain only its first format
3652  * \param pcm PCM handle
3653  * \param params Configuration space
3654  * \param format Returned first format
3655  * \return 0 otherwise a negative error code
3656  */
3657 #ifndef DOXYGEN
3658 int INTERNAL(snd_pcm_hw_params_set_format_first)(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, snd_pcm_format_t *format)
3659 #else
3660 int snd_pcm_hw_params_set_format_first(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, snd_pcm_format_t *format)
3661 #endif
3662 {
3663         return snd_pcm_hw_param_set_first(pcm, params, SND_PCM_HW_PARAM_FORMAT, (unsigned int *)format, NULL);
3664 }
3665
3666 /**
3667  * \brief Restrict a configuration space to contain only its last format
3668  * \param pcm PCM handle
3669  * \param params Configuration space
3670  * \param format Returned last format
3671  * \return 0 otherwise a negative error code
3672  */
3673 #ifndef DOXYGEN
3674 int INTERNAL(snd_pcm_hw_params_set_format_last)(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, snd_pcm_format_t *format)
3675 #else
3676 int snd_pcm_hw_params_set_format_last(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, snd_pcm_format_t *format)
3677 #endif
3678 {
3679         return snd_pcm_hw_param_set_last(pcm, params, SND_PCM_HW_PARAM_FORMAT, (unsigned int *)format, NULL);
3680 }
3681
3682 /**
3683  * \brief Restrict a configuration space to contain only a set of formats
3684  * \param pcm PCM handle
3685  * \param params Configuration space
3686  * \param mask Format mask
3687  * \return 0 otherwise a negative error code
3688  */
3689 int snd_pcm_hw_params_set_format_mask(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, snd_pcm_format_mask_t *mask)
3690 {
3691         return snd_pcm_hw_param_set_mask(pcm, params, SND_TRY, SND_PCM_HW_PARAM_FORMAT, (snd_mask_t *) mask);
3692 }
3693
3694 /**
3695  * \brief Get format mask from a configuration space
3696  * \param params Configuration space
3697  * \param mask Returned Format mask
3698  */
3699 void snd_pcm_hw_params_get_format_mask(snd_pcm_hw_params_t *params, snd_pcm_format_mask_t *mask)
3700 {
3701         snd_pcm_format_mask_copy(mask, snd_pcm_hw_param_get_mask(params, SND_PCM_HW_PARAM_FORMAT));
3702 }
3703
3704
3705 /**
3706  * \brief Extract subformat from a configuration space
3707  * \param params Configuration space
3708  * \param subformat Returned subformat value
3709  * \return subformat otherwise a negative error code if not exactly one is present
3710  */
3711 #ifndef DOXYGEN
3712 int INTERNAL(snd_pcm_hw_params_get_subformat)(const snd_pcm_hw_params_t *params, snd_pcm_subformat_t *subformat)
3713 #else
3714 int snd_pcm_hw_params_get_subformat(const snd_pcm_hw_params_t *params, snd_pcm_subformat_t *subformat)
3715 #endif
3716 {
3717         return snd_pcm_hw_param_get(params, SND_PCM_HW_PARAM_SUBFORMAT, subformat, NULL);
3718 }
3719
3720 /**
3721  * \brief Verify if a subformat is available inside a configuration space for a PCM
3722  * \param pcm PCM handle
3723  * \param params Configuration space
3724  * \param subformat subformat value
3725  * \return 0 if available a negative error code otherwise
3726  */
3727 int snd_pcm_hw_params_test_subformat(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, snd_pcm_subformat_t subformat)
3728 {
3729         return snd_pcm_hw_param_set(pcm, params, SND_TEST, SND_PCM_HW_PARAM_SUBFORMAT, subformat, 0);
3730 }
3731
3732 /**
3733  * \brief Restrict a configuration space to contain only one subformat
3734  * \param pcm PCM handle
3735  * \param params Configuration space
3736  * \param subformat subformat value
3737  * \return 0 otherwise a negative error code if configuration space would become empty
3738  */
3739 int snd_pcm_hw_params_set_subformat(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, snd_pcm_subformat_t subformat)
3740 {
3741         return snd_pcm_hw_param_set(pcm, params, SND_TRY, SND_PCM_HW_PARAM_SUBFORMAT, subformat, 0);
3742 }
3743
3744 /**
3745  * \brief Restrict a configuration space to contain only its first subformat
3746  * \param pcm PCM handle
3747  * \param params Configuration space
3748  * \param subformat Returned subformat
3749  * \return 0 otherwise a negative error code
3750  */
3751 #ifndef DOXYGEN
3752 int INTERNAL(snd_pcm_hw_params_set_subformat_first)(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, snd_pcm_subformat_t *subformat)
3753 #else
3754 int snd_pcm_hw_params_set_subformat_first(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, snd_pcm_subformat_t *subformat)
3755 #endif
3756 {
3757         return snd_pcm_hw_param_set_first(pcm, params, SND_PCM_HW_PARAM_SUBFORMAT, subformat, NULL);
3758 }
3759
3760 /**
3761  * \brief Restrict a configuration space to contain only its last subformat
3762  * \param pcm PCM handle
3763  * \param params Configuration space
3764  * \param subformat Returned subformat
3765  * \return 0 otherwise a negative error code
3766  */
3767 #ifndef DOXYGEN
3768 int INTERNAL(snd_pcm_hw_params_set_subformat_last)(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, snd_pcm_subformat_t *subformat)
3769 #else
3770 int snd_pcm_hw_params_set_subformat_last(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, snd_pcm_subformat_t *subformat)
3771 #endif
3772 {
3773         return snd_pcm_hw_param_set_last(pcm, params, SND_PCM_HW_PARAM_SUBFORMAT, subformat, NULL);
3774 }
3775
3776 /**
3777  * \brief Restrict a configuration space to contain only a set of subformats
3778  * \param pcm PCM handle
3779  * \param params Configuration space
3780  * \param mask Subformat mask
3781  * \return 0 otherwise a negative error code
3782  */
3783 int snd_pcm_hw_params_set_subformat_mask(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, snd_pcm_subformat_mask_t *mask)
3784 {
3785         return snd_pcm_hw_param_set_mask(pcm, params, SND_TRY, SND_PCM_HW_PARAM_SUBFORMAT, (snd_mask_t *) mask);
3786 }
3787
3788 /**
3789  * \brief Get subformat mask from a configuration space
3790  * \param params Configuration space
3791  * \param mask Returned Subformat mask
3792  */
3793 void snd_pcm_hw_params_get_subformat_mask(snd_pcm_hw_params_t *params, snd_pcm_subformat_mask_t *mask)
3794 {
3795         snd_pcm_subformat_mask_copy(mask, snd_pcm_hw_param_get_mask(params, SND_PCM_HW_PARAM_SUBFORMAT));
3796 }
3797
3798
3799 /**
3800  * \brief Extract channels from a configuration space
3801  * \param params Configuration space
3802  * \param val Returned channels count
3803  * \return 0 otherwise a negative error code if not exactly one is present
3804  */
3805 #ifndef DOXYGEN
3806 int INTERNAL(snd_pcm_hw_params_get_channels)(const snd_pcm_hw_params_t *params, unsigned int *val)
3807 #else
3808 int snd_pcm_hw_params_get_channels(const snd_pcm_hw_params_t *params, unsigned int *val)
3809 #endif
3810 {
3811         return snd_pcm_hw_param_get(params, SND_PCM_HW_PARAM_CHANNELS, val, NULL);
3812 }
3813
3814 /**
3815  * \brief Extract minimum channels count from a configuration space
3816  * \param params Configuration space
3817  * \param val minimum channels count
3818  * \return 0 otherwise a negative error code
3819  */
3820 #ifndef DOXYGEN
3821 int INTERNAL(snd_pcm_hw_params_get_channels_min)(const snd_pcm_hw_params_t *params, unsigned int *val)
3822 #else
3823 int snd_pcm_hw_params_get_channels_min(const snd_pcm_hw_params_t *params, unsigned int *val)
3824 #endif
3825 {
3826         return snd_pcm_hw_param_get_min(params, SND_PCM_HW_PARAM_CHANNELS, val, NULL);
3827 }
3828
3829 /**
3830  * \brief Extract maximum channels count from a configuration space
3831  * \param params Configuration space
3832  * \param val maximum channels count
3833  * \return 0 otherwise a negative error code
3834  */
3835 #ifndef DOXYGEN
3836 int INTERNAL(snd_pcm_hw_params_get_channels_max)(const snd_pcm_hw_params_t *params, unsigned int *val)
3837 #else
3838 int snd_pcm_hw_params_get_channels_max(const snd_pcm_hw_params_t *params, unsigned int *val)
3839 #endif
3840 {
3841         return snd_pcm_hw_param_get_max(params, SND_PCM_HW_PARAM_CHANNELS, val, NULL);
3842 }
3843
3844 /**
3845  * \brief Verify if a channels count is available inside a configuration space for a PCM
3846  * \param pcm PCM handle
3847  * \param params Configuration space
3848  * \param val channels count
3849  * \return 0 if available a negative error code otherwise
3850  */
3851 int snd_pcm_hw_params_test_channels(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, unsigned int val)
3852 {
3853         return snd_pcm_hw_param_set(pcm, params, SND_TEST, SND_PCM_HW_PARAM_CHANNELS, val, 0);
3854 }
3855
3856 /**
3857  * \brief Restrict a configuration space to contain only one channels count
3858  * \param pcm PCM handle
3859  * \param params Configuration space
3860  * \param val channels count
3861  * \return 0 otherwise a negative error code if configuration space would become empty
3862  */
3863 int snd_pcm_hw_params_set_channels(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, unsigned int val)
3864 {
3865         return snd_pcm_hw_param_set(pcm, params, SND_TRY, SND_PCM_HW_PARAM_CHANNELS, val, 0);
3866 }
3867
3868 /**
3869  * \brief Restrict a configuration space with a minimum channels count
3870  * \param pcm PCM handle
3871  * \param params Configuration space
3872  * \param val minimum channels count (on return filled with actual minimum)
3873  * \return 0 otherwise a negative error code if configuration space would become empty
3874  */
3875 int snd_pcm_hw_params_set_channels_min(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, unsigned int *val)
3876 {
3877         return snd_pcm_hw_param_set_min(pcm, params, SND_TRY, SND_PCM_HW_PARAM_CHANNELS, val, NULL);
3878 }
3879
3880 /**
3881  * \brief Restrict a configuration space with a maximum channels count
3882  * \param pcm PCM handle
3883  * \param params Configuration space
3884  * \param val maximum channels count (on return filled with actual maximum)
3885  * \return 0 otherwise a negative error code if configuration space would become empty
3886  */
3887 int snd_pcm_hw_params_set_channels_max(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, unsigned int *val)
3888 {
3889         return snd_pcm_hw_param_set_max(pcm, params, SND_TRY, SND_PCM_HW_PARAM_CHANNELS, val, NULL);
3890 }
3891
3892 /**
3893  * \brief Restrict a configuration space to have channels counts in a given range
3894  * \param pcm PCM handle
3895  * \param params Configuration space
3896  * \param min minimum channels count (on return filled with actual minimum)
3897  * \param max maximum channels count (on return filled with actual maximum)
3898  * \return 0 otherwise a negative error code if configuration space would become empty
3899  */
3900 int snd_pcm_hw_params_set_channels_minmax(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, unsigned int *min, unsigned int *max)
3901 {
3902         return snd_pcm_hw_param_set_minmax(pcm, params, SND_TRY, SND_PCM_HW_PARAM_CHANNELS, min, NULL, max, NULL);
3903 }
3904
3905 /**
3906  * \brief Restrict a configuration space to have channels count nearest to a target
3907  * \param pcm PCM handle
3908  * \param params Configuration space
3909  * \param val target channels count, returned chosen channels count
3910  * \return 0 otherwise a negative error code if configuration space is empty
3911  */
3912 #ifndef DOXYGEN
3913 int INTERNAL(snd_pcm_hw_params_set_channels_near)(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, unsigned int *val)
3914 #else
3915 int snd_pcm_hw_params_set_channels_near(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, unsigned int *val)
3916 #endif
3917 {
3918         return snd_pcm_hw_param_set_near(pcm, params, SND_PCM_HW_PARAM_CHANNELS, val, NULL);
3919 }
3920
3921 /**
3922  * \brief Restrict a configuration space to contain only its minimum channels count
3923  * \param pcm PCM handle
3924  * \param params Configuration space
3925  * \param val minimum channels count
3926  * \return 0 otherwise a negative error code
3927  */
3928 #ifndef DOXYGEN
3929 int INTERNAL(snd_pcm_hw_params_set_channels_first)(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, unsigned int *val)
3930 #else
3931 int snd_pcm_hw_params_set_channels_first(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, unsigned int *val)
3932 #endif
3933 {
3934         return snd_pcm_hw_param_set_first(pcm, params, SND_PCM_HW_PARAM_CHANNELS, val, NULL);
3935 }
3936
3937 /**
3938  * \brief Restrict a configuration space to contain only its maximum channels count
3939  * \param pcm PCM handle
3940  * \param params Configuration space
3941  * \param val maximum channels count
3942  * \return 0 otherwise a negative error code
3943  */
3944 #ifndef DOXYGEN
3945 int INTERNAL(snd_pcm_hw_params_set_channels_last)(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, unsigned int *val)
3946 #else
3947 int snd_pcm_hw_params_set_channels_last(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, unsigned int *val)
3948 #endif
3949 {
3950         return snd_pcm_hw_param_set_last(pcm, params, SND_PCM_HW_PARAM_CHANNELS, val, NULL);
3951 }
3952
3953
3954 /**
3955  * \brief Extract rate from a configuration space
3956  * \param params Configuration space
3957  * \param val Returned approximate rate
3958  * \param dir Sub unit direction
3959  * \return 0 otherwise a negative error code if not exactly one is present
3960  *
3961  * Actual exact value is <,=,> the approximate one following dir (-1, 0, 1)
3962  */
3963 #ifndef DOXYGEN
3964 int INTERNAL(snd_pcm_hw_params_get_rate)(const snd_pcm_hw_params_t *params, unsigned int *val, int *dir)
3965 #else
3966 int snd_pcm_hw_params_get_rate(const snd_pcm_hw_params_t *params, unsigned int *val, int *dir)
3967 #endif
3968 {
3969         return snd_pcm_hw_param_get(params, SND_PCM_HW_PARAM_RATE, val, dir);
3970 }
3971
3972 /**
3973  * \brief Extract minimum rate from a configuration space
3974  * \param params Configuration space
3975  * \param val Returned approximate minimum rate
3976  * \param dir Sub unit direction
3977  * \return 0 otherwise a negative error code
3978  *
3979  * Exact value is <,=,> the returned one following dir (-1,0,1)
3980  */
3981 #ifndef DOXYGEN
3982 int INTERNAL(snd_pcm_hw_params_get_rate_min)(const snd_pcm_hw_params_t *params, unsigned int *val, int *dir)
3983 #else
3984 int snd_pcm_hw_params_get_rate_min(const snd_pcm_hw_params_t *params, unsigned int *val, int *dir)
3985 #endif
3986 {
3987         return snd_pcm_hw_param_get_min(params, SND_PCM_HW_PARAM_RATE, val, dir);
3988 }
3989
3990 /**
3991  * \brief Extract maximum rate from a configuration space
3992  * \param params Configuration space
3993  * \param val Returned approximate maximum rate
3994  * \param dir Sub unit direction
3995  * \return 0 otherwise a negative error code
3996  *
3997  * Exact value is <,=,> the returned one following dir (-1,0,1)
3998  */
3999 #ifndef DOXYGEN
4000 int INTERNAL(snd_pcm_hw_params_get_rate_max)(const snd_pcm_hw_params_t *params, unsigned int *val, int *dir)
4001 #else
4002 int snd_pcm_hw_params_get_rate_max(const snd_pcm_hw_params_t *params, unsigned int *val, int *dir)
4003 #endif
4004 {
4005         return snd_pcm_hw_param_get_max(params, SND_PCM_HW_PARAM_RATE, val, dir);
4006 }
4007
4008 /**
4009  * \brief Verify if a rate is available inside a configuration space for a PCM
4010  * \param pcm PCM handle
4011  * \param params Configuration space
4012  * \param val approximate rate
4013  * \param dir Sub unit direction
4014  * \return 0 if available a negative error code otherwise
4015  *
4016  * Wanted exact value is <,=,> val following dir (-1,0,1)
4017  */
4018 int snd_pcm_hw_params_test_rate(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, unsigned int val, int dir)
4019 {
4020         return snd_pcm_hw_param_set(pcm, params, SND_TEST, SND_PCM_HW_PARAM_RATE, val, dir);
4021 }
4022
4023 /**
4024  * \brief Restrict a configuration space to contain only one rate
4025  * \param pcm PCM handle
4026  * \param params Configuration space
4027  * \param val approximate rate
4028  * \param dir Sub unit direction
4029  * \return 0 otherwise a negative error code if configuration space would become empty
4030  *
4031  * Wanted exact value is <,=,> val following dir (-1,0,1)
4032  */
4033 int snd_pcm_hw_params_set_rate(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, unsigned int val, int dir)
4034 {
4035         return snd_pcm_hw_param_set(pcm, params, SND_TRY, SND_PCM_HW_PARAM_RATE, val, dir);
4036 }
4037
4038 /**
4039  * \brief Restrict a configuration space with a minimum rate
4040  * \param pcm PCM handle
4041  * \param params Configuration space
4042  * \param val approximate minimum rate (on return filled with actual minimum)
4043  * \param dir Sub unit direction (on return filled with actual direction)
4044  * \return 0 otherwise a negative error code if configuration space would become empty
4045  *
4046  * Wanted/actual exact minimum is <,=,> val following dir (-1,0,1)
4047  */
4048 int snd_pcm_hw_params_set_rate_min(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, unsigned int *val, int *dir)
4049 {
4050         return snd_pcm_hw_param_set_min(pcm, params, SND_TRY, SND_PCM_HW_PARAM_RATE, val, dir);
4051 }
4052
4053 /**
4054  * \brief Restrict a configuration space with a maximum rate
4055  * \param pcm PCM handle
4056  * \param params Configuration space
4057  * \param val approximate maximum rate (on return filled with actual maximum)
4058  * \param dir Sub unit direction (on return filled with actual direction)
4059  * \return 0 otherwise a negative error code if configuration space would become empty
4060  *
4061  * Wanted/actual exact maximum is <,=,> val following dir (-1,0,1)
4062  */
4063 int snd_pcm_hw_params_set_rate_max(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, unsigned int *val, int *dir)
4064 {
4065         return snd_pcm_hw_param_set_max(pcm, params, SND_TRY, SND_PCM_HW_PARAM_RATE, val, dir);
4066 }
4067
4068 /**
4069  * \brief Restrict a configuration space to have rates in a given range
4070  * \param pcm PCM handle
4071  * \param params Configuration space
4072  * \param min approximate minimum rate (on return filled with actual minimum)
4073  * \param mindir Sub unit direction for minimum (on return filled with actual direction)
4074  * \param max approximate maximum rate (on return filled with actual maximum)
4075  * \param maxdir Sub unit direction for maximum (on return filled with actual direction)
4076  * \return 0 otherwise a negative error code if configuration space would become empty
4077  *
4078  * Wanted/actual exact min/max is <,=,> val following dir (-1,0,1)
4079  */
4080 int snd_pcm_hw_params_set_rate_minmax(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, unsigned int *min, int *mindir, unsigned int *max, int *maxdir)
4081 {
4082         return snd_pcm_hw_param_set_minmax(pcm, params, SND_TRY, SND_PCM_HW_PARAM_RATE, min, mindir, max, maxdir);
4083 }
4084
4085 /**
4086  * \brief Restrict a configuration space to have rate nearest to a target
4087  * \param pcm PCM handle
4088  * \param params Configuration space
4089  * \param val approximate target rate / returned approximate set rate
4090  * \param dir Sub unit direction
4091  * \return 0 otherwise a negative error code if configuration space is empty
4092  *
4093  * target/chosen exact value is <,=,> val following dir (-1,0,1)
4094  */
4095 #ifndef DOXYGEN
4096 int INTERNAL(snd_pcm_hw_params_set_rate_near)(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, unsigned int *val, int *dir)
4097 #else
4098 int snd_pcm_hw_params_set_rate_near(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, unsigned int *val, int *dir)
4099 #endif
4100 {
4101         return snd_pcm_hw_param_set_near(pcm, params, SND_PCM_HW_PARAM_RATE, val, dir);
4102 }
4103
4104 /**
4105  * \brief Restrict a configuration space to contain only its minimum rate
4106  * \param pcm PCM handle
4107  * \param params Configuration space
4108  * \param val Returned minimum approximate rate
4109  * \param dir Sub unit direction
4110  * \return 0 otherwise a negative error code
4111  *
4112  * Actual exact value is <,=,> the approximate one following dir (-1, 0, 1)
4113  */
4114 #ifndef DOXYGEN
4115 int INTERNAL(snd_pcm_hw_params_set_rate_first)(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, unsigned int *val, int *dir)
4116 #else
4117 int snd_pcm_hw_params_set_rate_first(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, unsigned int *val, int *dir)
4118 #endif
4119 {
4120         return snd_pcm_hw_param_set_first(pcm, params, SND_PCM_HW_PARAM_RATE, val, dir);
4121 }
4122
4123 /**
4124  * \brief Restrict a configuration space to contain only its maximum rate
4125  * \param pcm PCM handle
4126  * \param params Configuration space
4127  * \param val Returned maximum approximate rate
4128  * \param dir Sub unit direction
4129  * \return 0 otherwise a negative error code
4130  *
4131  * Actual exact value is <,=,> the approximate one following dir (-1, 0, 1)
4132  */
4133 #ifndef DOXYGEN
4134 int INTERNAL(snd_pcm_hw_params_set_rate_last)(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, unsigned int *val, int *dir)
4135 #else
4136 int snd_pcm_hw_params_set_rate_last(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, unsigned int *val, int *dir)
4137 #endif
4138 {
4139         return snd_pcm_hw_param_set_last(pcm, params, SND_PCM_HW_PARAM_RATE, val, dir);
4140 }
4141
4142 /**
4143  * \brief Restrict a configuration space to contain only real hardware rates
4144  * \param pcm PCM handle
4145  * \param params Configuration space
4146  * \param val 0 = disable, 1 = enable (default) rate resampling
4147  * \return 0 otherwise a negative error code
4148  */
4149 int snd_pcm_hw_params_set_rate_resample(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, unsigned int val)
4150 {
4151         assert(pcm && params);
4152         if (!val)
4153                 params->flags |= SND_PCM_HW_PARAMS_NORESAMPLE;
4154         else
4155                 params->flags &= ~SND_PCM_HW_PARAMS_NORESAMPLE;
4156         return snd_pcm_hw_refine(pcm, params);
4157 }
4158
4159 /**
4160  * \brief Extract resample state from a configuration space
4161  * \param pcm PCM handle
4162  * \param params Configuration space
4163  * \param val 0 = disable, 1 = enable rate resampling
4164  * \return 0 otherwise a negative error code
4165  */
4166 int snd_pcm_hw_params_get_rate_resample(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, unsigned int *val)
4167 {
4168         assert(pcm && params && val);
4169         *val = params->flags & SND_PCM_HW_PARAMS_NORESAMPLE ? 0 : 1;
4170         return 0;
4171 }
4172
4173 /**
4174  * \brief Restrict a configuration space to allow the buffer accessible from outside
4175  * \param pcm PCM handle
4176  * \param params Configuration space
4177  * \param val 0 = disable, 1 = enable (default) exporting buffer
4178  * \return 0 otherwise a negative error code
4179  */
4180 int snd_pcm_hw_params_set_export_buffer(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, unsigned int val)
4181 {
4182         assert(pcm && params);
4183         if (val)
4184                 params->flags |= SND_PCM_HW_PARAMS_EXPORT_BUFFER;
4185         else
4186                 params->flags &= ~SND_PCM_HW_PARAMS_EXPORT_BUFFER;
4187         return snd_pcm_hw_refine(pcm, params);
4188 }
4189
4190 /**
4191  * \brief Extract buffer accessibility from a configuration space
4192  * \param pcm PCM handle
4193  * \param params Configuration space
4194  * \param val 0 = disable, 1 = enable exporting buffer
4195  * \return 0 otherwise a negative error code
4196  */
4197 int snd_pcm_hw_params_get_export_buffer(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, unsigned int *val)
4198 {
4199         assert(pcm && params && val);
4200         *val = params->flags & SND_PCM_HW_PARAMS_EXPORT_BUFFER ? 1 : 0;
4201         return 0;
4202 }
4203
4204 /**
4205  * \brief Extract period time from a configuration space
4206  * \param params Configuration space
4207  * \param val Returned approximate period duration in us
4208  * \param dir Sub unit direction
4209  * \return 0 otherwise a negative error code if not exactly one is present
4210  *
4211  * Actual exact value is <,=,> the approximate one following dir (-1, 0, 1)
4212  */
4213 #ifndef DOXYGEN
4214 int INTERNAL(snd_pcm_hw_params_get_period_time)(const snd_pcm_hw_params_t *params, unsigned int *val, int *dir)
4215 #else
4216 int snd_pcm_hw_params_get_period_time(const snd_pcm_hw_params_t *params, unsigned int *val, int *dir)
4217 #endif
4218 {
4219         return snd_pcm_hw_param_get(params, SND_PCM_HW_PARAM_PERIOD_TIME, val, dir);
4220 }
4221
4222 /**
4223  * \brief Extract minimum period time from a configuration space
4224  * \param params Configuration space
4225  * \param val approximate minimum period duration in us
4226  * \param dir Sub unit direction
4227  * \return 0 otherwise a negative error code
4228  *
4229  * Exact value is <,=,> the returned one following dir (-1,0,1)
4230  */
4231 #ifndef DOXYGEN
4232 int INTERNAL(snd_pcm_hw_params_get_period_time_min)(const snd_pcm_hw_params_t *params, unsigned int *val, int *dir)
4233 #else
4234 int snd_pcm_hw_params_get_period_time_min(const snd_pcm_hw_params_t *params, unsigned int *val, int *dir)
4235 #endif
4236 {
4237         return snd_pcm_hw_param_get_min(params, SND_PCM_HW_PARAM_PERIOD_TIME, val, dir);
4238 }
4239
4240 /**
4241  * \brief Extract maximum period time from a configuration space
4242  * \param params Configuration space
4243  * \param val approximate maximum period duration in us
4244  * \param dir Sub unit direction
4245  * \return 0 otherwise a negative error code
4246  *
4247  * Exact value is <,=,> the returned one following dir (-1,0,1)
4248  */
4249 #ifndef DOXYGEN
4250 int INTERNAL(snd_pcm_hw_params_get_period_time_max)(const snd_pcm_hw_params_t *params, unsigned int *val, int *dir)
4251 #else
4252 int snd_pcm_hw_params_get_period_time_max(const snd_pcm_hw_params_t *params, unsigned int *val, int *dir)
4253 #endif
4254 {
4255         return snd_pcm_hw_param_get_max(params, SND_PCM_HW_PARAM_PERIOD_TIME, val, dir);
4256 }
4257
4258 /**
4259  * \brief Verify if a period time is available inside a configuration space for a PCM
4260  * \param pcm PCM handle
4261  * \param params Configuration space
4262  * \param val approximate period duration in us
4263  * \param dir Sub unit direction
4264  * \return 0 if available a negative error code otherwise
4265  *
4266  * Wanted exact value is <,=,> val following dir (-1,0,1)
4267  */
4268 int snd_pcm_hw_params_test_period_time(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, unsigned int val, int dir)
4269 {
4270         return snd_pcm_hw_param_set(pcm, params, SND_TEST, SND_PCM_HW_PARAM_PERIOD_TIME, val, dir);
4271 }
4272
4273 /**
4274  * \brief Restrict a configuration space to contain only one period time
4275  * \param pcm PCM handle
4276  * \param params Configuration space
4277  * \param val approximate period duration in us
4278  * \param dir Sub unit direction
4279  * \return 0 otherwise a negative error code if configuration space would become empty
4280  *
4281  * Wanted exact value is <,=,> val following dir (-1,0,1)
4282  */
4283 int snd_pcm_hw_params_set_period_time(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, unsigned int val, int dir)
4284 {
4285         return snd_pcm_hw_param_set(pcm, params, SND_TRY, SND_PCM_HW_PARAM_PERIOD_TIME, val, dir);
4286 }
4287
4288
4289 /**
4290  * \brief Restrict a configuration space with a minimum period time
4291  * \param pcm PCM handle
4292  * \param params Configuration space
4293  * \param val approximate minimum period duration in us (on return filled with actual minimum)
4294  * \param dir Sub unit direction (on return filled with actual direction)
4295  * \return 0 otherwise a negative error code if configuration space would become empty
4296  *
4297  * Wanted/actual exact minimum is <,=,> val following dir (-1,0,1)
4298  */
4299 int snd_pcm_hw_params_set_period_time_min(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, unsigned int *val, int *dir)
4300 {
4301         return snd_pcm_hw_param_set_min(pcm, params, SND_TRY, SND_PCM_HW_PARAM_PERIOD_TIME, val, dir);
4302 }
4303
4304 /**
4305  * \brief Restrict a configuration space with a maximum period time
4306  * \param pcm PCM handle
4307  * \param params Configuration space
4308  * \param val approximate maximum period duration in us (on return filled with actual maximum)
4309  * \param dir Sub unit direction (on return filled with actual direction)
4310  * \return 0 otherwise a negative error code if configuration space would become empty
4311  *
4312  * Wanted/actual exact maximum is <,=,> val following dir (-1,0,1)
4313  */
4314 int snd_pcm_hw_params_set_period_time_max(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, unsigned int *val, int *dir)
4315 {
4316         return snd_pcm_hw_param_set_max(pcm, params, SND_TRY, SND_PCM_HW_PARAM_PERIOD_TIME, val, dir);
4317 }
4318
4319 /**
4320  * \brief Restrict a configuration space to have period times in a given range
4321  * \param pcm PCM handle
4322  * \param params Configuration space
4323  * \param min approximate minimum period duration in us (on return filled with actual minimum)
4324  * \param mindir Sub unit direction for minimum (on return filled with actual direction)
4325  * \param max approximate maximum period duration in us (on return filled with actual maximum)
4326  * \param maxdir Sub unit direction for maximum (on return filled with actual direction)
4327  * \return 0 otherwise a negative error code if configuration space would become empty
4328  *
4329  * Wanted/actual exact min/max is <,=,> val following dir (-1,0,1)
4330  */
4331 int snd_pcm_hw_params_set_period_time_minmax(snd_pcm_t *pcm, snd_pcm_hw_params_t *params, unsigned int *min, int *mindir, unsigned int *max, int *maxdir)
4332 {
4333         return snd_pcm_hw_param_set_minmax(pcm, params, SND_TRY, SND_PCM_HW_PARAM_PERIOD_TIME, min, mindir, max, maxdir);
4334 }
4335
4336 /**
4337  * \brief Restrict a configuration space to have period time nearest to a target
4338  * \param pcm PCM handle
4339  * \param params Configuration space
4340  * \param val approximate target period duration in us / returned chosen approximate target period duration
4341  * \param dir Sub unit direction