Merge "Bluetooth Audio HAL interface v2"

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,
+}
+

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);
+};

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();
+};

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);
+};

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;
+};

compatibility_matrices/compatibility_matrix.current.xml

@@ -79,6 +79,14 @@
             <instance>default</instance>
         </interface>
     </hal>
+    <hal format="hidl" optional="true">
+        <name>android.hardware.bluetooth.audio</name>
+        <version>2.0</version>
+        <interface>
+            <name>IBluetoothAudioProvidersFactory</name>
+            <instance>default</instance>
+        </interface>
+    </hal>
     <hal format="hidl" optional="true">
         <name>android.hardware.boot</name>
         <version>1.0</version>