Subject: audio_engine_playahead/qlen [PSARC/2009/639 Self Review]
To:      PSARC-ext@Sun.Com
Cc:      audio-oss-ext@sun.com
Bcc:     one-pager-list@sac.sfbay one-pager-log@sac.sfbay sac-bar@sac.sfbay

The following case documents an intent to make a couple of minor bug-fix
related changes to the Boomer audio driver DDI.  As the changes affect only
a consolidation private API which has not been released in any official
product yet, both the consumers and producers of the interfaces are owned
by the same project team, and the changes themselves are very minor "obvious"
changes to the interface, we believe self-review is appropriate.

This case is for Minor binding, and retains the Consolidation Private 
commitment level for the Boomer DDI.

(Note that at some future point we anticipate making some further, and perhaps
significant, changes to this portion of the Boomer DDI.  The details of any
such changes are still under investigation, however.)

Template Version: @(#)sac_nextcase 1.68 02/23/09 SMI
This information is Copyright 2009 Sun Microsystems
1. Introduction
    1.1. Project/Component Working Name:
	 audio_engine_playahead/qlen
    1.2. Name of Document Author/Supplier:
	 Author:  Garrett D'Amore
    1.3  Date of This Document:
	23 November, 2009
4. Technical Description

Problem:

Debugging CR 6901849 (audio810 is choppy when run in a virtualbox guest),
it turns out that we need to queue up more audio data than we would need to
for a "real device".  We're going to have this requirement for Sun Ray
audio as well.  Boomer (PSARC 2008/318) currently queues up 1.5 "fragments"
(interrupt periods) worth of data by default.

We need to provide a way for drivers to ask for more data to be queued to
them, without changing the interrupt frequency for the device.

While here, we found two issues with the audio_engine_qlen() entry point:

1) It returns a size_t, inconsistently with respect to other entry points
   which use unsigned for small frame counts.

2) It is "mandatory", but nearly all device drivers have entry points which
   simply return 0.  It seems like we could make this entry point optional
   and save a few lines of code in many of the device drivers.  (Only drivers
   with deep FIFOs, or without an ability to accurately report position
   data, need this.  Right now that means only audiocs and usb_ac.  In the
   future it will include Sun Ray audio, and we can probably eliminate it
   for usb_ac with some enhancements to that code.)

Solution:

A) We provide a new entry point in audio_engine_ops, audio_engine_playahead.
   It simply returns a count in frames of data that should be queued for
   the device.  The prototype is:

	unsigned audio_engine_playahead(void *);

   This entry point is added to the end of the audio_engine_ops structure.

   NULL may be supplied to use the default value.  Note that the default
   of 1.5 fragments is used if an unreasonable value is returned.
   (Reasonable values are more than 1.5 fragments, and not more than
   the total audio buffer size.)

B) We have changed the prototype for audio_engine_qlen() as follows:

	unsigned audio_engine_qlen(void *);

   NULL may be supplied, in which case the hardware FIFO depth is assumed
   to be zero.  Note that for very small hardware FIFOs, such as 64 frames,
   it is still reasonable to supply NULL.  (The difference amounts to less
   than 2 milliseconds of error in latency reporting.)

C) To accomodate the above change, the audio_engine_version member of the
   audio_engine_ops structure is bumped from 0 to 1.   This should prevent
   any errorneous attempt to use a driver built against an older (or newer)
   header from operating with the revised framework.  Note that since this
   is a consolidation private API, we are not doing anything more than
   simply refusing to register an engine with an invalid version.  (There
   is no need to support using older drivers with the updated framework.)

6. Resources and Schedule
    6.4. Steering Committee requested information
   	6.4.1. Consolidation C-team Name:
		ON
    6.5. ARC review type: Automatic
    6.6. ARC Exposure: open