[alsa-devel] My issues with the ALSA API

[Takashi Iwai]

At Sun, 20 Apr 2008 03:31:32 +0200,
Lennart Poettering wrote:
> 
> On Tue, 15.04.08 14:19, Takashi Iwai (tiwai at suse.de) wrote:
> 
> > > As far as I understood there are a few soundcards around where
> > > the playback sample index is only known each time the hw changes to
> > > the next fragment. It would be good to know about this, to tweak the
> > > time interpolation in timer-based scheduling.
> > 
> > We may add some hints to the PCM information, but I think maybe this
> > isn't only the question about granualrity.  For example, on some
> > hardwares, the query of the current position costs much due to the
> > hardware design.
> 
> What is "much" if I may ask?

10 to 100 msec, IIRC.  Maybe depends on HZ and system loads.

> > > > Documentantion - if you ask specific questions, we try to update 
> > > > documentantion for other developers.. unfortunately, saying that whole 
> > > > documentantion is bad is not productive
> > > 
> > > Sorry. I'll make sure I'll ask for clarifications more clearly on
> > > alsa-devel from now on.
> > > 
> > > Here's my first batch of questions:
> > > 
> > > I am not sure I get what the "transfer align" is about.
> > 
> > Just ignore, this is obsoleted in the latest version :)
> 
> Please remove from the docs, then!

Patch please :)

> Also the part in the "Managing parameters" chapter in the PCM
> introduction text.
> 
> > > It is not clear how snd_pcm_update_avail() and snd_pcm_hwsync()
> > > actually play together, why they exist at all, and how exactly the
> > > optimization they are apparently useful for should  be used.
> > 
> > The detailed description is found in PCM documentation.
> 
> Uh, and that's the part I don't get. I did read it, and didn't get
> it. What exactly does _hwsync() do that _update_avail() doesnt?

There are two PCM pointers in ALSA implementation: hw-pointer and
appl-poiter.  The former is a kind of DMA position, and the latter the
position the app filled.  In principle, hwsync() updates the former.
When you use normal read/write method (snd_pcm_wrieti(), etc), the
latter is updated automatically.  But, in the case of mmap mode, you
have to update it manually.  This is snd_pcm_avail_update() for.

The hw and appl pointers may be updated by some other methods, but the
above two calls are ones that (are supposed to) update directly.

> > > It would be good to have an explanation what a "card", what an "id",
> > > what a "name", what a "device" and what a "subdevice" actually refers
> > > to, with examples.
> > 
> > The card (index) is the index number of the sound card instance.
> > Each card has an id string and name string(s).
> > One card instance may have several belonging components.  And each
> > component has (usually) a device index.  Some components (e.g. PCM or
> > rawmidi) can have multiple subdevices (or substreams).  Each subdevice
> > has a subdevice index.
> 
> The question remains: what exactly is is a "device" and what is a
> "subdevice"? Examples?
> 
> For a while I thought that for those sound cards wich can output to
> SPDIF and analog at the same time we have two different device
> indexes, but a single card index. However, for my HDA card that is
> listed in /proc/asound/pcm as "04-00 ALC882 Analog" and "04-01 ALC882
> Digital", aplay -L suggests to use "ec958:CARD=Intel,DEV=0" for spdif
> and "front:CARD=Intel,DEV=0" for analog -- both times with DEV=0!

Because actually both of these point to the same device.  They are
exclusive.

> Since then I have no idea what devices, subdevices and stuff should
> actually be.
> So again, what exactly qualifies subdevices? Do they share a single
> crystal? Are they usually combined for multi-channel output? What's
> the story?

There is so strict definition at all for device/subdevice
classification.  The multiple subdevices are often provided to handle
the multi-playback streams (not multi-channels), such as emu10k1, or
multiplexing streams for captures.
With such a system, you can open multiple streams for the same
purpose, mixed or multiplexed on the hardware for the same I/O.
In the case of PCM, subdevice is often referred as "substream", BTW.  

Note that the multi-channel is often a different story.  On many
systems, the multi-channel output is implemented only as a single
interleaved stream, thus has only one subdevice.


> > > regarding hw params: What exactly is "double buffering",
> > > "sample-resolution mmap", "block transfer", "batch", "sync_start" ,
> > > "fifo_size", "subformat", "export buffer", "min align";
> > 
> > Most of them can be ignored, at least for PA :)  I'd love to get rid
> > of most of them in future, too.
> 
> Really? "block transfer" sounds to me like something that would be
> interesting for mmap playback for cases where i randomly seek around
> in my mmap buffer, with frame granularity. Which is exactly what I do
> all the time in PA.

If it were implemented correctly through all devices, some information
might be useful.  But currently not, unfortunately.

> > > why there is a
> > > need for a seperate can_pause() and can_resume()?
> > 
> > can_pause() means the ability to pause/restart the stream.
> > 
> > can_resume() means the ability to resume the suspended/hibernated
> > stream by the driver natively.
> 
> Uh. This has very confusing naming.

Yes.

> > > regarding sw params: What exactly is a "boundary"? Difference between
> > > tstamp modes?
> > 
> > The boundary defines the limit PCM position (frames) can reach.  When
> > the PCM position reaches to the boundary size, then it backs to 0 at
> > next.  The boundary size is aligned to the buffer size, and it's not
> > LONG_MAX (although close to it).
> 
> But what is this interesting for? I mean, I cannot read the raw
> hardware pointer index anyway from ALSA, so why should I care?

If you run a program for a long time, it much overwrap at some point.
The boundary defines that point.

> Or is it all for the case where I create a *major* buffer underrun
> with disabled stop_threshold and the value of _update_avail() keeps
> increasing but eventually wraps around?

Unlikely.

> > > how do silence_size and silence_threshold relate?
> > 
> > The PCM driver core has a feature to clear the samples automatically
> > at each period elapse call.  The silence_size and silence_threshold
> > defines this behavior.
> 
> But in which way? Please elaborate!

Later.

> > > What is snd_pcm_xrun_t useful for? (I think it is obsolete, should
> > > also be removed from docs, then)
> > 
> > Right.  Maybe should be classified to the section "obsoleted
> > functions".  A part of the problem is that the reference document is
> > generated via doxygen, and it seems a bit confusing to arrange the
> > sections in a single file.
> 
> You can use stuff like \cond in doxygen to hide certain parts of the
> API pretty easily. 

Hm, but what about to put these obsoleted functions to a dedicate
section?  Removing the API functions from a reference is a bad idea,
IMHO.

> > > Why is snd_pcm_scope included in the normal PCM docs?
> > 
> > I guess it was thought it'd be pretty useful.
> 
> Maybe the plugin is useful. But why is it part of the API docs?

Because the feature is included in alsa-lib.


thanks,

Takashi