/*
* Copyright (C) 2018 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@4.0;
import android.hardware.audio.common@4.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);
/**
* 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;
};
/**
* Called when the metadata of the stream's sink has been changed.
* @param sinkMetadata Description of the audio that is suggested by the clients.
*/
updateSinkMetadata(SinkMetadata sinkMetadata);
/**
* 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 identifiers
* 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 threadInfo identifiers of the driver's dedicated thread.
*/
prepareForReading(uint32_t frameSize, uint32_t framesCount)
generates (
Result retval,
fmq_sync<ReadParameters> commandMQ,
fmq_sync<uint8_t> dataMQ,
fmq_sync<ReadStatus> statusMQ,
ThreadInfo threadInfo);
/**
* 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.
*
* @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);
};