Bluetooth Audio HAL interface v2
Generalized Bluetooth Audio HAL interface.
It is similar to the original android.hardware.bluetooth.a2dp@1.0
interface with the following modifications:
* The session type can be one of the following:
- A2DP Software Encoding Datapath
- A2DP Hardware Encoding Datapath
- Hearing Aid Software Encoding Datapath
* For Hardware Offload Datapath (A2DP), the HAL interface is used only
for the control path
* For Software Encoding Datapath (A2DP or Hearing Aid), the HAL
interface is used for both the control and data paths
* Added Delay Report support: IBluetoothAudioHost.getPresentationPosition()
that was missing in the original android.hardware.bluetooth.a2dp@1.0
HAL interface.
* Removed "oneway" calls to avoid potential reordering of HAL calls:
b/111244402
* Updated SBC-specific codec configuration
* Added AAC-specific and LDAC-specific codec configuration
* Reorganized the original CodecConfiguration into two sections:
- PcmDataConfiguration: Audio PCM data configuration
- EncodedDataConfiguration: Encoded audio data codec configuration.
It is used only if the HAL is responsible for encoding the PCM audio
data.
* Added new HAL IBluetoothAudioProvidersFactory.
It is used to open an audio provider for an audio session as specified by
the session type and the codec configuration as negotiated with the
remote device.
Bug: 111519504
Test: manual
Change-Id: I2ee4cf50b177baee077cf0b5143dbeadda57c8fb
Merged-In: I2ee4cf50b177baee077cf0b5143dbeadda57c8fb
(cherry picked from commit fcc0732db4af7586ee71310e5d4f6b9b0d94e6c4)
diff --git a/bluetooth/audio/2.0/Android.bp b/bluetooth/audio/2.0/Android.bp
new file mode 100644
index 0000000..6049fe2
--- /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 0000000..17d13b8
--- /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 0000000..bb5eb1b
--- /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<uint8_t> 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 0000000..56b8594
--- /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 0000000..9286948
--- /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;
+};