Hello,

I noticed that the API documentation leaves a lot of room for interpretation, resulting in inconsistent behavior between drivers and sound server plugins. I believe we need some documented consensus on how the API is supposed to work, so one can refer to it when reporting bugs. I'd also volunteer to help out if I can.

Here is a list of things I've encountered so far that I think need clarifications:

- Are the descriptors (and their flags) returned from snd_pcm_poll_descriptors guaranteed to stay static for a given snd_pcm_t device, i.e. is it ok to just get them once and reuse them (which is also what the test/pcm.c does), or are there situations where the client needs to update the descriptors or their event flags? It may also be good to be explicit about snd_pcm_poll_descriptors_revents guaranteeing to not modify its input parameter in any way, which I assume it does (ideally by simply making the parameters const pointers, though I'm not sure if you can modify the API like that at this point).

- Will the revents return parameter of snd_pcm_poll_descriptors_revents be set to something != 0 for a period event (or any other event), or is it strictly corresponding to whether the availabe buffer is >= avail_min (e.g. for playback, it will be set to POLLOUT iff available buffer to write >= avail_min)? And as long as the available buffers are >= avail_min, is it not possible to wait for anything other event (as poll would just immediately return again)?

- Does avail_min trigger while you are draining the stream?

- What is the correct way to disable wakeups by avail_min? Is snd_pcm_sw_params_set_avail_min(.., ULONG_MAX) guaranteed to work? Side question: Since the documentation of snd_pcm_sw_params_set_avail_min states that accepted values depend on th hardware I wonder how one is supposed to use it at all reliably for portable applications, and it seems generally better to just use period events plus your own internal (clock_gettime) timers for scheduling, right?

- The exact semantics of the various timestamps (htstamp, audio_htstamp, driver_htstamp, trigger_htstamp) does not seem to be explained anywhere?

- The `dir` direction parameter in the various getters (such as snd_pcm_hw_params_get_period_size) is rather unclear. Is that an input, output or both-direction-parameter and how is it to be interpreted exactly?

Thank you & best regards, Zeno Endemann