Improve hw_params documentation

PATCH In review Andrew Eikum 2 participants 2 messages Nov 23, 2011 – Nov 27, 2011

lore

Share & tools

lore

Andrew Eikum

author

2011-11-23 15:08 UTC #0 lore raw

PATCH v2 2/2 Improve hw_params documentation

---

Tweaked the snd_pcm_hw_params_t description to reflect how ALSA is intended to work, even if that's not how some plugins (pulse) currently work due to bugs.

 include/pcm.h |   17 ++++++++++++++++-
 src/pcm/pcm.c |   10 +++++++++-
 2 files changed, 25 insertions(+), 2 deletions(-)

include/pcm.h +16 -1

index be355a9..4997557 100644
@@ -44,8 +44,23 @@ extern "C" {
 
 /** PCM generic info container */
 typedef struct _snd_pcm_info snd_pcm_info_t;
-/** PCM hardware configuration space container */
+
+/** PCM hardware configuration space container
+ *
+ *  snd_pcm_hw_params_t is an opaque structure which contains a set of possible
+ *  PCM hardware configurations. For example, a given instance might include a
+ *  range of buffer sizes, a range of period sizes, and a set of several sample
+ *  formats. Some subset of all possible combinations these sets may be valid,
+ *  but not necessarily any combination will be valid.
+ *
+ *  When a parameter is set or restricted using a snd_pcm_hw_params_set*
+ *  function, all of the other ranges will be updated to exclude as many
+ *  impossible configurations as possible. Attempting to set a parameter
+ *  outside of its acceptable range will result in the function failing
+ *  and an error code being returned.
+ */
 typedef struct _snd_pcm_hw_params snd_pcm_hw_params_t;
+
 /** PCM software configuration container */
 typedef struct _snd_pcm_sw_params snd_pcm_sw_params_t;
 /** PCM status container */

src/pcm/pcm.c +9 -1

index dc91f79..ea1afdc 100644
@@ -809,7 +809,9 @@ int snd_pcm_hw_params_current(snd_pcm_t *pcm, snd_pcm_hw_params_t *params)
  *
  * The configuration is chosen fixing single parameters in this order:
  * first access, first format, first subformat, min channels, min rate, 
- * min period time, max buffer size, min tick time
+ * min period time, max buffer size, min tick time. If no mutually
+ * compatible set of parameters can be chosen, a negative error code
+ * will be returned.
  *
  * After this call, #snd_pcm_prepare() is called automatically and
  * the stream is brought to \c #SND_PCM_STATE_PREPARED state.

@@ -817,6 +819,9 @@ int snd_pcm_hw_params_current(snd_pcm_t *pcm, snd_pcm_hw_params_t *params)
  * The hardware parameters cannot be changed when the stream is
  * running (active). The software parameters can be changed
  * at any time.
+ *
+ * The configuration space will be updated to reflect the chosen
+ * parameters.
  */
 int snd_pcm_hw_params(snd_pcm_t *pcm, snd_pcm_hw_params_t *params)
 {

@@ -3183,6 +3188,9 @@ int snd_pcm_hw_params_get_fifo_size(const snd_pcm_hw_params_t *params)
  * \brief Fill params with a full configuration space for a PCM
  * \param pcm PCM handle
  * \param params Configuration space
+ *
+ * The configuration space will be filled with all possible ranges
+ * for the PCM device.
  */
 int snd_pcm_hw_params_any(snd_pcm_t *pcm, snd_pcm_hw_params_t *params)
 {

Raymond Yau

2011-11-27 04:31 UTC #1 lore raw

2011/11/23 Andrew Eikum <[email protected]>:

Quoted 11 lines

---
Tweaked the snd_pcm_hw_params_t description to reflect how ALSA is intended to work, even if that's not how some plugins (pulse) currently work due to bugs.
include/pcm.h | 17 ++++++++++++++++-
src/pcm/pcm.c | 10 +++++++++-
 2 files changed, 25 insertions(+), 2 deletions(-)

But Tick time is already deprecated.

Some sound cards such au88x0 may return error when there is no enough SRC

and there is another error for plughw with snd-hda-intel

./alsa_period_count plughw:1
min periods 0 dir 1
max periods 4294967295 dir 0
min_buffer_frames: 10240
set max buffer size: 10240
snd_pcm_hw_params: -22
[raymond@localhost ~]$ export LIBASOUND_DEBUG=1 [raymond@localhost ~]$ ./alsa_period_count plughw:1 min periods 0 dir 1
max periods 4294967295 dir 0
min_buffer_frames: 10240
set max buffer size: 10240
ALSA ERROR hw_params: set (RATE)
value = 4000 : Invalid argument

ACCESS:  MMAP_INTERLEAVED RW_INTERLEAVED
FORMAT:  S16_LE S32_LE
SUBFORMAT:  STD
SAMPLE_BITS: [16 32]
FRAME_BITS: [32 448]
CHANNELS: [2 14]
RATE: [8000 192000]
PERIOD_TIME: (15 1024000]
PERIOD_SIZE: [3 8192]
PERIOD_BYTES: [128 458752]
PERIODS: [2 32]
BUFFER_TIME: (31 2048000]
BUFFER_SIZE: [6 16384]
BUFFER_BYTES: [128 65536]
TICK_TIME: ALL
ALSA ERROR hw_params: set (RATE)
           value = 4000 : Invalid argument
ACCESS:  MMAP_INTERLEAVED RW_INTERLEAVED
FORMAT:  S16_LE S32_LE
SUBFORMAT:  STD
SAMPLE_BITS: [16 32]
FRAME_BITS: [32 448]
CHANNELS: [2 14]
RATE: [8000 192000]
PERIOD_TIME: (15 1024000]
PERIOD_SIZE: [3 8192]
PERIOD_BYTES: [128 458752]
PERIODS: [2 32]
BUFFER_TIME: (31 2048000]
BUFFER_SIZE: [6 16384]
BUFFER_BYTES: [128 65536]
TICK_TIME: ALL
snd_pcm_hw_params: -22