[alsa-devel] Improve hw_params documentation -- details of constraint resolution

[Joerg-Cyril.Hoehle at t-systems.com]

Hi,

Andrew Eikum recently improved the (still much lacking) ALSA documentation
 -- thanks Andrew:
+ *  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.

I'd like to check whether that's exactly what's happening.

1. Consider the following scenario:

set_hw_params_period_near([in,out]10ms,[out]dir)
yields 16ms and direction=0 <=> "exact match"

set_hw_params_buffer_size(X)
set_hw_params()

So far, I thought that if ALSA replied with direction=0, then that
corner stone of the configuration space was fixed.  OTOH, if
constraint resolutions occurs at the time of set_hw_params() *again
and finally*, ALSA may realize that the particularly large or small
buffer size X is not reachable with the 16ms period, whereas a 50ms or
5ms period may allow buffer size X.

So what is the outcome?
a) 16ms period and error from set_hw_params()
   because the constraints don't fit?
b) revised 5 or 50ms period with buffer size X,
   because 5 or 50ms is a near period?
c) 16ms period, error from set_buffer_size and success from set_hw_params
   as ALSA chooses an arbitrary buffer size (typically 4-8 periods)?

I believe c) is implemented. The documentation may lead one to believe b) happens.

Behaviour b) may better suit what users expect, but compatibility likely imposes c).

Any "official" statement?


2.
+ *  Attempting to set a parameter
+ *  outside of its acceptable range will result in the function failing
+ *  and an error code being returned.

That does not seem to apply to the set_*_near() functions.

set_hw_params_period_time(2ms) may fail because it's too small for the
device at hand, whereas set_hw_params_period_time_near(2ms) causes the
smallest supported period to be chosen.  Does this need clarification
or is using *_near not "attempting to set a parameter"?

*_min and *_max appear to behave likewise: they set lower and upper
bounds without checking whether these are reachable.

I think the current behaviour, namely not checking whether near, min
or max fall into the "acceptable range", is useful.

Thank you for your help,
	Jörg Höhle