aa88f5b270
Specifies how HAL needs to handle the frame counter for input and output streams on standby and flush. Also add whitespaces before "Optional method" spec for better readability. Bug: 161253754 Test: in progress Change-Id: I357739a2382f9425da74fcddbe7ab720be1f0e18
211 lines
8 KiB
Text
211 lines
8 KiB
Text
/*
|
|
* Copyright (C) 2020 The Android Open Source Project
|
|
*
|
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
* you may not use this file except in compliance with the License.
|
|
* You may obtain a copy of the License at
|
|
*
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
* See the License for the specific language governing permissions and
|
|
* limitations under the License.
|
|
*/
|
|
|
|
package android.hardware.audio@7.0;
|
|
|
|
import android.hardware.audio.common@7.0;
|
|
import IStream;
|
|
|
|
interface IStreamIn extends IStream {
|
|
/**
|
|
* Returns the source descriptor of the input stream. Calling this method is
|
|
* equivalent to getting AUDIO_PARAMETER_STREAM_INPUT_SOURCE on the legacy
|
|
* HAL.
|
|
*
|
|
* Optional method
|
|
*
|
|
* @return retval operation completion status.
|
|
* @return source audio source.
|
|
*/
|
|
getAudioSource() generates (Result retval, AudioSource source);
|
|
|
|
/**
|
|
* Set the input gain for the audio driver.
|
|
*
|
|
* Optional method
|
|
*
|
|
* @param gain 1.0f is unity, 0.0f is zero.
|
|
* @result retval operation completion status.
|
|
*/
|
|
setGain(float gain) generates (Result retval);
|
|
|
|
/**
|
|
* Called when the metadata of the stream's sink has been changed.
|
|
*
|
|
* Optional method
|
|
*
|
|
* @param sinkMetadata Description of the audio that is suggested by the clients.
|
|
* @return retval operation completion status.
|
|
* If any of the metadata fields contains an invalid value,
|
|
* returns INVALID_ARGUMENTS.
|
|
* If method isn't supported by the HAL returns NOT_SUPPORTED.
|
|
*/
|
|
updateSinkMetadata(SinkMetadata sinkMetadata) generates (Result retval);
|
|
|
|
/**
|
|
* Commands that can be executed on the driver reader thread.
|
|
*/
|
|
enum ReadCommand : int32_t {
|
|
READ,
|
|
GET_CAPTURE_POSITION
|
|
};
|
|
|
|
/**
|
|
* Data structure passed to the driver for executing commands
|
|
* on the driver reader thread.
|
|
*/
|
|
struct ReadParameters {
|
|
ReadCommand command; // discriminator
|
|
union Params {
|
|
uint64_t read; // READ command, amount of bytes to read, >= 0.
|
|
// No parameters for GET_CAPTURE_POSITION.
|
|
} params;
|
|
};
|
|
|
|
/**
|
|
* Data structure passed back to the client via status message queue
|
|
* of 'read' operation.
|
|
*
|
|
* Possible values of 'retval' field:
|
|
* - OK, read operation was successful;
|
|
* - INVALID_ARGUMENTS, stream was not configured properly;
|
|
* - INVALID_STATE, stream is in a state that doesn't allow reads.
|
|
*/
|
|
struct ReadStatus {
|
|
Result retval;
|
|
ReadCommand replyTo; // discriminator
|
|
union Reply {
|
|
uint64_t read; // READ command, amount of bytes read, >= 0.
|
|
struct CapturePosition { // same as generated by getCapturePosition.
|
|
uint64_t frames;
|
|
uint64_t time;
|
|
} capturePosition;
|
|
} reply;
|
|
};
|
|
|
|
/**
|
|
* Set up required transports for receiving audio buffers from the driver.
|
|
*
|
|
* The transport consists of three message queues:
|
|
* -- command queue is used to instruct the reader thread what operation
|
|
* to perform;
|
|
* -- data queue is used for passing audio data from the driver
|
|
* to the client;
|
|
* -- status queue is used for reporting operation status
|
|
* (e.g. amount of bytes actually read or error code).
|
|
*
|
|
* The driver operates on a dedicated thread. The client must ensure that
|
|
* the thread is given an appropriate priority and assigned to correct
|
|
* scheduler and cgroup. For this purpose, the method returns the identifier
|
|
* of the driver thread.
|
|
*
|
|
* @param frameSize the size of a single frame, in bytes.
|
|
* @param framesCount the number of frames in a buffer.
|
|
* @param threadPriority priority of the driver thread.
|
|
* @return retval OK if both message queues were created successfully.
|
|
* INVALID_STATE if the method was already called.
|
|
* INVALID_ARGUMENTS if there was a problem setting up
|
|
* the queues.
|
|
* @return commandMQ a message queue used for passing commands.
|
|
* @return dataMQ a message queue used for passing audio data in the format
|
|
* specified at the stream opening.
|
|
* @return statusMQ a message queue used for passing status from the driver
|
|
* using ReadStatus structures.
|
|
* @return threadId identifier of the driver's dedicated thread; the caller
|
|
* may adjust the thread priority to match the priority
|
|
* of the thread that provides audio data.
|
|
*/
|
|
prepareForReading(uint32_t frameSize, uint32_t framesCount)
|
|
generates (
|
|
Result retval,
|
|
fmq_sync<ReadParameters> commandMQ,
|
|
fmq_sync<uint8_t> dataMQ,
|
|
fmq_sync<ReadStatus> statusMQ,
|
|
int32_t threadId);
|
|
|
|
/**
|
|
* Return the amount of input frames lost in the audio driver since the last
|
|
* call of this function.
|
|
*
|
|
* Audio driver is expected to reset the value to 0 and restart counting
|
|
* upon returning the current value by this function call. Such loss
|
|
* typically occurs when the user space process is blocked longer than the
|
|
* capacity of audio driver buffers.
|
|
*
|
|
* @return framesLost the number of input audio frames lost.
|
|
*/
|
|
getInputFramesLost() generates (uint32_t framesLost);
|
|
|
|
/**
|
|
* Return a recent count of the number of audio frames received and the
|
|
* clock time associated with that frame count. The count must not reset to
|
|
* zero when a PCM input enters standby.
|
|
*
|
|
* @return retval INVALID_STATE if the device is not ready/available,
|
|
* NOT_SUPPORTED if the command is not supported,
|
|
* OK otherwise.
|
|
* @return frames the total frame count received. This must be as early in
|
|
* the capture pipeline as possible. In general, frames
|
|
* must be non-negative and must not go "backwards".
|
|
* @return time is the clock monotonic time when frames was measured. In
|
|
* general, time must be a positive quantity and must not
|
|
* go "backwards".
|
|
*/
|
|
getCapturePosition()
|
|
generates (Result retval, uint64_t frames, uint64_t time);
|
|
|
|
/**
|
|
* Returns an array with active microphones in the stream.
|
|
*
|
|
* @return retval INVALID_STATE if the call is not successful,
|
|
* OK otherwise.
|
|
*
|
|
* @return microphones array with microphones info
|
|
*/
|
|
getActiveMicrophones()
|
|
generates(Result retval, vec<MicrophoneInfo> microphones);
|
|
|
|
/**
|
|
* Specifies the logical microphone (for processing).
|
|
*
|
|
* If the feature is not supported an error should be returned
|
|
* If multiple microphones are present, this should be treated as a preference
|
|
* for their combined direction.
|
|
*
|
|
* Optional method
|
|
*
|
|
* @param Direction constant
|
|
* @return retval OK if the call is successful, an error code otherwise.
|
|
*/
|
|
setMicrophoneDirection(MicrophoneDirection direction)
|
|
generates(Result retval);
|
|
|
|
/**
|
|
* Specifies the zoom factor for the selected microphone (for processing).
|
|
*
|
|
* If the feature is not supported an error should be returned
|
|
* If multiple microphones are present, this should be treated as a preference
|
|
* for their combined field dimension.
|
|
*
|
|
* Optional method
|
|
*
|
|
* @param the desired field dimension of microphone capture. Range is from -1 (wide angle),
|
|
* though 0 (no zoom) to 1 (maximum zoom).
|
|
*
|
|
* @return retval OK if the call is not successful, an error code otherwise.
|
|
*/
|
|
setMicrophoneFieldDimension(float zoom) generates(Result retval);
|
|
};
|