diff --git a/bluetooth/audio/2.0/Android.bp b/bluetooth/audio/2.0/Android.bp new file mode 100644 index 0000000000..6049fe2b54 --- /dev/null +++ b/bluetooth/audio/2.0/Android.bp @@ -0,0 +1,32 @@ +hidl_interface { + name: "android.hardware.bluetooth.audio@2.0", + root: "android.hardware", + vndk: { + enabled: true, + }, + srcs: [ + "types.hal", + "IBluetoothAudioPort.hal", + "IBluetoothAudioProvider.hal", + "IBluetoothAudioProvidersFactory.hal", + ], + interfaces: [ + "android.hidl.base@1.0", + "android.hardware.audio.common@5.0", + ], + types: [ + "AacObjectType", + "BitsPerSample", + "ChannelMode", + "CodecConfiguration", + "CodecType", + "LdacChannelMode", + "SampleRate", + "SbcChannelMode", + "SessionType", + "Status", + "TimeSpec", + ], + gen_java: false, +} + diff --git a/bluetooth/audio/2.0/IBluetoothAudioPort.hal b/bluetooth/audio/2.0/IBluetoothAudioPort.hal new file mode 100644 index 0000000000..17d13b8663 --- /dev/null +++ b/bluetooth/audio/2.0/IBluetoothAudioPort.hal @@ -0,0 +1,82 @@ +/* + * Copyright 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.bluetooth.audio@2.0; + +import android.hardware.audio.common@5.0::SourceMetadata; + +/** + * HAL interface from the Audio HAL to the Bluetooth stack + * + * The Audio HAL calls methods in this interface to start, suspend, and stop + * an audio stream. These calls return immediately and the results, if any, + * are sent over the IBluetoothAudioProvider interface. + * + * Moreover, the Audio HAL can also get the presentation position of the stream + * and provide stream metadata. + */ +interface IBluetoothAudioPort { + /** + * This indicates that the caller of this method has opened the data path + * and wants to start an audio stream. The caller must wait for a + * IBluetoothAudioProvider.streamStarted(Status) call. + */ + startStream(); + + /** + * This indicates that the caller of this method wants to suspend the audio + * stream. The caller must wait for the Bluetooth process to call + * IBluetoothAudioProvider.streamSuspended(Status). The caller still keeps + * the data path open. + */ + suspendStream(); + + /** + * This indicates that the caller of this method wants to stop the audio + * stream. The data path will be closed after this call. There is no + * callback from the IBluetoothAudioProvider interface even though the + * teardown is asynchronous. + */ + stopStream(); + + /** + * Get the audio presentation position. + * + * @return status the command status + * @return remoteDeviceAudioDelayNanos the audio delay from when the remote + * device (e.g. headset) receives audio data to when the device plays the + * sound. If the delay is unknown, the value is set to zero. + * @return transmittedOctets the number of audio data octets that were sent + * to a remote device. This excludes octets that have been written to the + * data path but have not been sent to the remote device. The count is + * not reset until stopStream() is called. If the software data path is + * unused (e.g. A2DP Hardware Offload), the value is set to 0. + * @return transmittedOctetsTimeStamp the value of CLOCK_MONOTONIC + * corresponding to transmittedOctets. If the software data path is + * unused (e.g., for A2DP Hardware Offload), the value is set to zero. + */ + getPresentationPosition() generates (Status status, + uint64_t remoteDeviceAudioDelayNanos, uint64_t transmittedOctets, + TimeSpec transmittedOctetsTimeStamp); + + /** + * Called when the metadata of the stream's source has been changed. + * + * @param sourceMetadata Description of the audio that is played by the + * clients. + */ + updateMetadata(SourceMetadata sourceMetadata); +}; diff --git a/bluetooth/audio/2.0/IBluetoothAudioProvider.hal b/bluetooth/audio/2.0/IBluetoothAudioProvider.hal new file mode 100644 index 0000000000..bb5eb1b9e3 --- /dev/null +++ b/bluetooth/audio/2.0/IBluetoothAudioProvider.hal @@ -0,0 +1,75 @@ +/* + * Copyright 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.bluetooth.audio@2.0; + +import IBluetoothAudioPort; + +/** + * HAL interface from the Bluetooth stack to the Audio HAL + * + * The Bluetooth stack calls methods in this interface to start and end audio + * sessions and sends callback events to the Audio HAL. + */ +interface IBluetoothAudioProvider { + + /** + * This method indicates that the Bluetooth stack is ready to stream audio. + * It registers an instance of IBluetoothAudioPort with and provides the + * current negotiated codec to the Audio HAL. After this method is called, + * the Audio HAL can invoke IBluetoothAudioPort.startStream(). + * + * Note: endSession() must be called to unregister this IBluetoothAudioPort + * + * @param hostIf An instance of IBluetoothAudioPort for stream control + * @param codecConfig The codec configuration negotiated with the remote + * device + * + * @return status One of the following + * SUCCESS if this IBluetoothAudioPort was successfully registered with + * the Audio HAL + * UNSUPPORTED_CODEC_CONFIGURATION if the Audio HAL cannot register this + * IBluetoothAudioPort with the given codec configuration + * FAILURE if the Audio HAL cannot register this IBluetoothAudioPort for + * any other reason + * @return dataMQ The fast message queue for audio data from this provider. + * Audio data will be in PCM format as specified by the + * codecConfig.pcmDataConfiguration parameter. + * nullptr if streaming is offloaded to hardware or on failure. + */ + startSession(IBluetoothAudioPort hostIf, CodecConfiguration codecConfig) + generates (Status status, fmq_sync dataMQ); + + /** + * Callback for IBluetoothAudioPort.startStream() + * + * @param status SUCCESS or FAILURE + */ + streamStarted(Status status); + + /** + * Callback for IBluetoothAudioPort.suspendStream() + * + * @param status SUCCESS or FAILURE + */ + streamSuspended(Status status); + + /** + * Ends the current session and unregisters the IBluetoothAudioPort + * interface. + */ + endSession(); +}; diff --git a/bluetooth/audio/2.0/IBluetoothAudioProvidersFactory.hal b/bluetooth/audio/2.0/IBluetoothAudioProvidersFactory.hal new file mode 100644 index 0000000000..56b8594178 --- /dev/null +++ b/bluetooth/audio/2.0/IBluetoothAudioProvidersFactory.hal @@ -0,0 +1,46 @@ +/* + * Copyright 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.bluetooth.audio@2.0; + +import IBluetoothAudioProvider; + +/** + * This factory allows a HAL implementation to be split into multiple + * independent providers. + * + * When the Bluetooth stack is ready to create an audio session, it must first + * obtain the IBluetoothAudioProvider for that session type by calling + * openProvider(). + */ +interface IBluetoothAudioProvidersFactory { + + /** + * Opens an audio provider for a session type. To close the provider, it is + * necessary to release references to the returned provider object. + * + * @param sessionType The session type (e.g. + * A2DP_SOFTWARE_ENCODING_DATAPATH). + * + * @return status One of the following + * SUCCESS if the Audio HAL successfully opens the provider with the + * given session type + * FAILURE if the Audio HAL cannot open the provider + * @return provider The provider of the specified session type + */ + openProvider(SessionType sessionType) + generates (Status status, IBluetoothAudioProvider provider); +}; diff --git a/bluetooth/audio/2.0/types.hal b/bluetooth/audio/2.0/types.hal new file mode 100644 index 0000000000..928694866a --- /dev/null +++ b/bluetooth/audio/2.0/types.hal @@ -0,0 +1,170 @@ +/* + * Copyright 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.bluetooth.audio@2.0; + +/** + * POSIX timespec. + */ +struct TimeSpec { + uint64_t tvSec; // seconds + uint64_t tvNSec; // nanoseconds +}; + +enum Status : uint8_t { + SUCCESS = 0x00, + /** Codec configuration not supported by the audio platform */ + UNSUPPORTED_CODEC_CONFIGURATION, + /** Any other failure */ + FAILURE, +}; + +enum SessionType : uint8_t { + UNKNOWN, + /** A2DP legacy that AVDTP media is encoded by Bluetooth Stack */ + A2DP_SOFTWARE_ENCODING_DATAPATH, + /** The encoding of AVDTP media is done by HW and there is control only */ + A2DP_HARDWARE_OFFLOAD_DATAPATH, + /** Used when encoded by Bluetooth Stack and streaming to Hearing Aid */ + HEARING_AID_SOFTWARE_ENCODING_DATAPATH, +}; + +enum CodecType : uint32_t { + UNKNOWN = 0x00, + SBC = 0x01, + AAC = 0x02, + APTX = 0x04, + APTX_HD = 0x08, + LDAC = 0x10, +}; + +enum SampleRate : uint32_t { + RATE_UNKNOWN = 0x00, + RATE_44100 = 0x01, + RATE_48000 = 0x02, + RATE_88200 = 0x04, + RATE_96000 = 0x08, + RATE_176400 = 0x10, + RATE_192000 = 0x20, + RATE_16000 = 0x40, + RATE_24000 = 0x80, +}; + +enum BitsPerSample : uint8_t { + BITS_UNKNOWN = 0x00, + BITS_16 = 0x01, + BITS_24 = 0x02, + BITS_32 = 0x04, +}; + +enum ChannelMode : uint8_t { + UNKNOWN = 0x00, + MONO = 0x01, + STEREO = 0x02, +}; + +enum SbcChannelMode : uint8_t { + /** Channel Mode: 4 bits */ + UNKNOWN = 0x00, + JOINT_STEREO = 0x01, + STEREO = 0x02, + DUAL = 0x04, + MONO = 0x08, +}; + +enum AacObjectType : uint8_t { + /** MPEG-2 Low Complexity. Support is Mandatory. */ + MPEG2_LC = 0x80, + /** MPEG-4 Low Complexity. Support is Optional. */ + MPEG4_LC = 0x40, + /** MPEG-4 Long Term Prediction. Support is Optional. */ + MPEG4_LTP = 0x20, + /** MPEG-4 Scalable. Support is Optional. */ + MPEG4_SCALABLE = 0x10, +}; + +enum LdacChannelMode : uint8_t { + /** Channel Mode: 3 bits */ + UNKNOWN = 0x00, + STEREO = 0x01, + DUAL = 0x02, + MONO = 0x04, +}; + +struct CodecConfiguration { + /** Audio PCM data configuration */ + struct PcmDataConfiguration { + /** Sampling rate for encoder */ + SampleRate sampleRate; + /** Bits per sample for encoder */ + BitsPerSample bitsPerSample; + /** Channel mode for encoder */ + ChannelMode channelMode; + } pcmDataConfiguration; + + /** Encoded audio data codec configuration. It is used only if the + * HAL is responsible for encoding the PCM audio data. */ + struct EncodedDataConfiguration { + /** Bluetooth A2DP codec */ + CodecType codecType; + /** + * The encoded audio bitrate in bits / second. + * 0x00000000 - The audio bitrate is not specified / unused + * 0x00000001 - 0x00FFFFFF - Encoded audio bitrate in bits/second + * 0x01000000 - 0xFFFFFFFF - Reserved + */ + uint32_t encodedAudioBitrate; + /** Peer MTU (in octets) */ + uint16_t peerMtu; + /** Content protection by SCMS-T */ + bool isScmstEnabled; + safe_union CodecSpecific { + /** + * SBC Codec specific information + * Refer to SBC Codec specific information elements in A2DP v1.3 + * Profile Specification. + */ + struct SbcData { + /** Reserved: 4 bits | Channel Mode: 4 bits */ + SbcChannelMode channelMode; + /** Block length: 4 bits | Subbands: 2 bits | Allocation Method: 2 bits */ + uint8_t codecParameters; + /** Minimum bitpool value */ + uint8_t minBitpool; + /** Maximum bitpool value */ + uint8_t maxBitpool; + } sbcData; + struct AacData { + /** AAC Object Type */ + AacObjectType aacObjectType; + /** True if Variable Bit Rate is enabled */ + bool variableBitRateEnabled; + } aacData; + struct LdacData { + /** Reserved: 5 bits | Channel Mode: 3 bits */ + LdacChannelMode channelMode; + /** + * LDAC bitrate index value: + * 0x00 - High + * 0x01 - Mid + * 0x02 - Low + * 0x7F - ABR (Adaptive Bit Rate) + */ + uint8_t bitrateIndex; + } ldacData; + } codecSpecific; + } encodedDataConfiguration; +}; diff --git a/compatibility_matrices/compatibility_matrix.current.xml b/compatibility_matrices/compatibility_matrix.current.xml index b519b755a9..a4259c1142 100644 --- a/compatibility_matrices/compatibility_matrix.current.xml +++ b/compatibility_matrices/compatibility_matrix.current.xml @@ -87,6 +87,14 @@ default + + android.hardware.bluetooth.audio + 2.0 + + IBluetoothAudioProvidersFactory + default + + android.hardware.boot 1.0