audio: Clarify that MMap h/w position must be continuous
The VTS test already verifies that the MMap hardware position
never resets or goes back, but the official wording in the AIDL
interface was lacking.
Bug: 350998390
Bug: 363139283
Test: none, doc change
Change-Id: I07b9842f53c89549fe648ee839d875d31a7a849d
diff --git a/audio/aidl/android/hardware/audio/core/StreamDescriptor.aidl b/audio/aidl/android/hardware/audio/core/StreamDescriptor.aidl
index 65ea9ef..cfe001e 100644
--- a/audio/aidl/android/hardware/audio/core/StreamDescriptor.aidl
+++ b/audio/aidl/android/hardware/audio/core/StreamDescriptor.aidl
@@ -386,14 +386,23 @@
* For input streams: the moment when data at the specified stream position
* was acquired (i.e. capture position).
*
- * The observable position must never be reset by the HAL module.
- * The data type of the frame counter is large enough to support
- * continuous counting for years of operation.
+ * The observable position must never be reset by the HAL module,
+ * providing an abstraction of continuous audio data flow. The data
+ * type of the frame counter is large enough to support continuous
+ * counting for years of operation.
*/
Position observable;
/**
* Used only for MMap streams to provide the hardware read / write
* position for audio data in the shared memory buffer 'audio.mmap'.
+ * Similar to the observable position, the 'Position::UNKNOWN' value
+ * can be returned when the HAL module is unable to retrieve the current
+ * position.
+ *
+ * The hardware position must never be reset by the HAL module,
+ * providing an abstraction of continuous audio data flow. The data
+ * type of the frame counter is large enough to support continuous
+ * counting for years of operation.
*/
Position hardware;
/**