[PATCH 2/2 v2] Improve hw_params documentation

[PATCH 2/2 v2] Improve hw_params documentation

[Andrew Eikum]

[-- Attachment #1: Type: text/plain, Size: 288 bytes --]

---

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(-)


[-- Attachment #2: 0001-Improve-hw_params-documentation.patch --]
[-- Type: text/x-patch, Size: 2809 bytes --]

diff --git a/include/pcm.h b/include/pcm.h
index be355a9..4997557 100644
--- a/include/pcm.h
+++ b/include/pcm.h
@@ -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 */
diff --git a/src/pcm/pcm.c b/src/pcm/pcm.c
index dc91f79..ea1afdc 100644
--- a/src/pcm/pcm.c
+++ b/src/pcm/pcm.c
@@ -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)
 {

[-- Attachment #3: Type: text/plain, Size: 0 bytes --]

Re: [PATCH 2/2 v2] Improve hw_params documentation

[Raymond Yau]

2011/11/23 Andrew Eikum <aeikum@codeweavers.com>:
> ---
>
> 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