[alsa-devel] [alsa-cvslog] alsa-lib: SND_PCM_TSTAMP_MMAP -> SND_PCM_TSTAMP_ENABLE change

[Takashi Iwai]

At Fri, 11 Jan 2008 09:35:08 +0100 (CET),
Jaroslav Kysela wrote:
> 
> On Fri, 11 Jan 2008, Clemens Ladisch wrote:
> 
> > Jaroslav Kysela wrote:
> > > description:
> > > SND_PCM_TSTAMP_MMAP -> SND_PCM_TSTAMP_ENABLE change
> > > 
> > > diff -r 3c87e22e70d8 -r 2519fcd54901 include/pcm.h
> > > --- a/include/pcm.h	Thu Jan 10 10:01:14 2008 +0100
> > > +++ b/include/pcm.h	Fri Jan 11 08:54:07 2008 +0100
> > > @@ -281,9 +281,9 @@
> > >  typedef enum _snd_pcm_tstamp {
> > >  	/** No timestamp */
> > >  	SND_PCM_TSTAMP_NONE = 0,
> > > -	/** Update mmap'ed timestamp */
> > > -	SND_PCM_TSTAMP_MMAP,
> > > -	SND_PCM_TSTAMP_LAST = SND_PCM_TSTAMP_MMAP
> > > +	/** Update timestamp at every hardware position update */
> > > +	SND_PCM_TSTAMP_ENABLE,
> > > +	SND_PCM_TSTAMP_LAST = SND_PCM_TSTAMP_ENABLE
> > >  } snd_pcm_tstamp_t;
> > 
> > This change breaks backward compatibility.
> > The v19-devel branch of PortAudio uses SND_PCM_TSTAMP_MMAP.
> 
> It's no problem to add SND_PCM_TSTAMP_MMAP as alias to 
> SND_PCM_TSTAMP_ENABLE back. But I think that it would be better to let 
> developers using SND_PCM_TSTAMP_MMAP realize that something was changed.

I think we shouldn't break the API, at least.
Let's add alias.

> Binary compatibility is kept.
> 
> Note that SND_PCM_TSTAMP_MMAP is also quite unusable without 
> new snd_pcm_htimestamp() function and support for monotonic timestamps in 
> the latest driver/library code.

Right.  It's meaningless without the fast timestamp read.  The result
is as same as TSTAMP_NONE. 
Maybe they took it blindly (because of the name 'TSTAMP_NONE').


Regarding this change, one idea that came to my mind is to rename this
API function.
For example,  snd_pcm_sw_params_get/set_fast_tstamp(sw, bool), and
deprecate snd_pcm_sw_params_get/set_tstamp_mode().  The bool function
seems more intuitive in this case.  The mode enum might be good if
we'll have more complicated timestamp modes, but I don't think this
will ever happen...


Takashi