Merge "audio HAL: Support for external device connections" am: eefac18b26 (62be0023) · Commits · e / os / android_hardware_interfaces

audio/aidl/Android.bp

+1 −2

Original line number	Diff line number	Diff line
		@@ -75,6 +75,7 @@ aidl_interface {
		"android/hardware/audio/core/IModule.aidl",
		"android/hardware/audio/core/IStreamIn.aidl",
		"android/hardware/audio/core/IStreamOut.aidl",
		"android/hardware/audio/core/ModuleDebug.aidl",
		],
		imports: [
		"android.hardware.audio.common-V1",
		@@ -86,6 +87,4 @@ aidl_interface {
		platform_apis: true,
		},
		},
		versions: [
		],
		}

audio/aidl/aidl_api/android.hardware.audio.core/current/android/hardware/audio/core/IModule.aidl

+4 −0

Original line number	Diff line number	Diff line
		@@ -34,11 +34,15 @@
		package android.hardware.audio.core;
		@VintfStability
		interface IModule {
		void setModuleDebug(in android.hardware.audio.core.ModuleDebug debug);
		android.media.audio.common.AudioPort connectExternalDevice(in android.media.audio.common.AudioPort templateIdAndAdditionalData);
		void disconnectExternalDevice(int portId);
		android.hardware.audio.core.AudioPatch[] getAudioPatches();
		android.media.audio.common.AudioPort getAudioPort(int portId);
		android.media.audio.common.AudioPortConfig[] getAudioPortConfigs();
		android.media.audio.common.AudioPort[] getAudioPorts();
		android.hardware.audio.core.AudioRoute[] getAudioRoutes();
		android.hardware.audio.core.AudioRoute[] getAudioRoutesForAudioPort(int portId);
		android.hardware.audio.core.IStreamIn openInputStream(int portConfigId, in android.hardware.audio.common.SinkMetadata sinkMetadata);
		android.hardware.audio.core.IStreamOut openOutputStream(int portConfigId, in android.hardware.audio.common.SourceMetadata sourceMetadata, in @nullable android.media.audio.common.AudioOffloadInfo offloadInfo);
		android.hardware.audio.core.AudioPatch setAudioPatch(in android.hardware.audio.core.AudioPatch requested);

audio/aidl/aidl_api/android.hardware.audio.core/current/android/hardware/audio/core/ModuleDebug.aidl

0 → 100644

+38 −0

Original line number	Diff line number	Diff line
		/*
		* Copyright (C) 2022 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.
		*/
		///////////////////////////////////////////////////////////////////////////////
		// THIS FILE IS IMMUTABLE. DO NOT EDIT IN ANY CASE. //
		///////////////////////////////////////////////////////////////////////////////

		// This file is a snapshot of an AIDL file. Do not edit it manually. There are
		// two cases:
		// 1). this is a frozen version file - do not edit this in any case.
		// 2). this is a 'current' file. If you make a backwards compatible change to
		// the interface (from the latest frozen version), the build system will
		// prompt you to update this file with `m <name>-update-api`.
		//
		// You must not make a backward incompatible change to any AIDL file built
		// with the aidl_interface module type with versions property set. The module
		// type is used to build AIDL files in a way that they can be used across
		// independently updatable components of the system. If a device is shipped
		// with such a backward incompatible change, it has a high risk of breaking
		// later when a module using the interface is updated, e.g., Mainline modules.

		package android.hardware.audio.core;
		@JavaDerive(equals=true, toString=true) @VintfStability
		parcelable ModuleDebug {
		boolean simulateDeviceConnections;
		}

audio/aidl/android/hardware/audio/core/IModule.aidl

+146 −21

Original line number	Diff line number	Diff line
		@@ -22,6 +22,7 @@ import android.hardware.audio.core.AudioPatch;
		import android.hardware.audio.core.AudioRoute;
		import android.hardware.audio.core.IStreamIn;
		import android.hardware.audio.core.IStreamOut;
		import android.hardware.audio.core.ModuleDebug;
		import android.media.audio.common.AudioOffloadInfo;
		import android.media.audio.common.AudioPort;
		import android.media.audio.common.AudioPortConfig;
		@@ -43,6 +44,116 @@ import android.media.audio.common.AudioPortConfig;
		*/
		@VintfStability
		interface IModule {
		/**
		* Sets debugging configuration for the HAL module. This method is only
		* called during xTS testing and is intended for validating the aspects of
		* the HAL module behavior that would otherwise require human intervention.
		*
		* The HAL module must throw an error if there is an attempt to change
		* the debug behavior for the aspect which is currently in use.
		*
		* @param debug The debug options.
		* @throws EX_ILLEGAL_STATE If the flag(s) being changed affect functionality
		* which is currently in use.
		*/
		void setModuleDebug(in ModuleDebug debug);

		/**
		* Set a device port of an external device into connected state.
		*
		* This method is used to inform the HAL module that an external device has
		* been connected to a device port selected using the 'id' field of the
		* input AudioPort parameter. This device port must have dynamic profiles
		* (an empty list of profiles). This port is further referenced to as "port
		* template" because it acts as a template for creating a new instance of a
		* "connected" device port which gets returned from this method.
		*
		* The input AudioPort parameter may contain any additional data obtained by
		* the system side from other subsystems. The nature of data depends on the
		* type of the connection. For example, for point-to-multipoint external
		* device connections, the input parameter may contain the address of the
		* connected external device. Another example is EDID information for HDMI
		* connections (ExtraAudioDescriptor), which can be provided by the HDMI-CEC
		* HAL module.
		*
		* It is the responsibility of the HAL module to query audio profiles
		* supported by the connected device and return them as part of the returned
		* AudioPort instance. In the case when the HAL is unable to query the
		* external device, an error must be thrown.
		*
		* Thus, the returned audio port instance is the result of combining the
		* following information:
		* - a unique port ID generated by the HAL module;
		* - static information from the port template;
		* - list of audio profiles supported by the connected device;
		* - additional data from the input AudioPort parameter.
		*
		* The HAL module must also update the list of audio routes to include the
		* ID of the instantiated connected device port. Normally, the connected
		* port allows the same routing as the port template.
		*
		* Also see notes on 'ModuleDebug.simulateDeviceConnections'.
		*
		* The following protocol is used by HAL module client for handling
		* connection of an external device:
		* 1. Obtain the list of device ports and their IDs via 'getAudioPorts'
		* method. Select the appropriate port template using
		* AudioDeviceDescription ('ext.device' field of AudioPort).
		* 2. Combine the ID of the port template with any additional data and call
		* 'connectExternalDevice'. The HAL module returns a new instance of
		* AudioPort created using the rules explained above. Both
		* 'getAudioPort' and 'getAudioPorts' methods will be returning the same
		* information for this port until disconnection.
		* 3. Configure the connected port with one of supported profiles using
		* 'setAudioPortConfig'.
		* 4. Query the list of AudioRoutes for the new AudioPort using
		* 'getAudioRoutesForAudioPort' or 'getAudioRoutes' methods.
		*
		* External devices are distinguished by the connection type and device
		* address. Calling this method multiple times to inform about connection of
		* the same external device without disconnecting it first is an error.
		*
		* The HAL module must perform validation of the input parameter and throw
		* an error if it is lacking required information, for example, when no
		* device address is specified for a point-to-multipoint external device
		* connection.
		*
		* Handling of a disconnect is done in a reverse order:
		* 1. Reset port configuration using the 'resetAudioPortConfig' method.
		* 2. Release the connected device port by calling the 'disconnectExternalDevice'
		* method. This also removes the audio routes associated with this
		* device port.
		*
		* @return New instance of an audio port for the connected external device.
		* @param templateIdAndAdditionalData Specifies port template ID and any
		* additional data.
		* @throws EX_ILLEGAL_ARGUMENT In the following cases:
		* - If the template port can not be found by the ID.
		* - If the template is not a device port, or
		* it does not have dynamic profiles.
		* - If the input parameter is lacking required
		* information.
		* @throws EX_ILLEGAL_STATE In the following cases:
		* - If the HAL module is unable to query audio profiles.
		* - If the external device has already been connected.
		*/
		AudioPort connectExternalDevice(in AudioPort templateIdAndAdditionalData);

		/**
		* Set a device port of a an external device into disconnected state.
		*
		* This method is used to inform the HAL module that an external device has
		* been disconnected. The 'portId' must be of a connected device port
		* instance previously instantiated using the 'connectExternalDevice'
		* method.
		*
		* @throws EX_ILLEGAL_ARGUMENT In the following cases:
		* - If the port can not be found by the ID.
		* - If this is not a connected device port.
		* @throws EX_ILLEGAL_STATE If the port has active configurations.
		*/
		void disconnectExternalDevice(int portId);

		/**
		* Return all audio patches of this module.
		*
		@@ -57,12 +168,10 @@ interface IModule {
		* Return the current state of the audio port.
		*
		* Using the port ID provided on input, returns the current state of the
		* audio port. For device port representing a connection to some external
		* device, e.g. over HDMI or USB, currently supported audio profiles and
		* extra audio descriptors may change.
		*
		* For all other audio ports it must be the same configuration as returned
		* for this port ID by 'getAudioPorts'.
		* audio port. The values of the AudioPort structure must be the same as
		* currently returned by the 'getAudioPorts' method. The 'getAudioPort'
		* method is provided to reduce overhead in the case when the client needs
		* to check the state of one port only.
		*
		* @return The current state of an audio port.
		* @param portId The ID of the audio port.
		@@ -87,32 +196,44 @@ interface IModule {
		AudioPortConfig[] getAudioPortConfigs();

		/**
		* Return all audio ports provided by this module.
		*
		* Returns a list of all mix ports and device ports provided by this
		* module. Each returned port must have a unique ID within this module
		* ('AudioPort.id' field). The returned list must not change during
		* the lifetime of the IModule instance. For audio ports with dynamic
		* profiles (changing depending on external devices being connected
		* to the system) an empty list of profiles must be returned. The list
		* of currently supported audio profiles is obtained from 'getAudioPort'
		* method.
		* Return the current state of all audio ports provided by this module.
		*
		* Returns a list of all mix ports and device ports provided by this HAL
		* module, reflecting their current states. Each returned port must have a
		* unique ID within this module ('AudioPort.id' field). The list also
		* includes "connected" ports created using 'connectExternalDevice' method.
		*
		* @return The list of audio ports.
		*/
		AudioPort[] getAudioPorts();

		/**
		* Return all audio routes of this module.
		* Return all current audio routes of this module.
		*
		* Returns a list of audio routes, that is, allowed connections between
		* audio ports. The returned list must not change during the lifetime of the
		* IModule instance.
		* Returns the current list of audio routes, that is, allowed connections
		* between audio ports. The list can change when new device audio ports
		* get created as a result of connecting or disconnecting of external
		* devices.
		*
		* @return The list of audio routes.
		*/
		AudioRoute[] getAudioRoutes();

		/**
		* Return audio routes related to the specified audio port.
		*
		* Returns the list of audio routes that include the specified port ID
		* as a source or as a sink. The returned list is a subset of the result
		* returned by the 'getAudioRoutes' method, filtered by the port ID.
		* An empty list can be returned, indicating that the audio port can not
		* be used for creating audio patches.
		*
		* @return The list of audio routes.
		* @param portId The ID of the audio port.
		* @throws EX_ILLEGAL_ARGUMENT If the port can not be found by the ID.
		*/
		AudioRoute[] getAudioRoutesForAudioPort(int portId);

		/**
		* Open an input stream using an existing audio mix port configuration.
		*
		@@ -230,6 +351,10 @@ interface IModule {
		* parameter. The framework can then set the suggested configuration on a
		* subsequent retry call to this method.
		*
		* Device ports with dynamic audio profiles (an empty list of profiles)
		* can not be used with this method. The list of profiles must be filled in
		* as a result of calling 'connectExternalDevice' method.
		*
		* @return Whether the requested configuration has been applied.
		* @param requested Requested audio port configuration.
		* @param suggested Same as requested configuration, if it was applied.
		@@ -241,7 +366,7 @@ interface IModule {
		* - If the port can not be found by the port ID.
		* - If it is not possible to generate a suggested port
		* configuration, for example, if the port only has dynamic
		* profiles and they are currently empty.
		* profiles.
		*/
		boolean setAudioPortConfig(in AudioPortConfig requested, out AudioPortConfig suggested);

audio/aidl/android/hardware/audio/core/ModuleDebug.aidl

0 → 100644

+38 −0

Original line number	Diff line number	Diff line
		/*
		* Copyright (C) 2022 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.core;

		/**
		* This structure contains flags used for enabling various debugging aspects
		* in a HAL module. By default, all debugging aspects are turned off. They
		* can be enabled during xTS tests for functionality that, for example, would
		* otherwise require human intervention (e.g. connection of external devices).
		*/
		@JavaDerive(equals=true, toString=true)
		@VintfStability
		parcelable ModuleDebug {
		/**
		* When set to 'true', HAL module must simulate connection of external
		* devices. An external device becomes 'connected' after a call to
		* IModule.connectExternalDevice, simulation of connection requires:
		* - provision of at least one non-dynamic device port profile on
		* connection (as if it was retrieved from a connected device);
		* - simulating successful application of port configurations for reported
		* profiles.
		*/
		boolean simulateDeviceConnections;
		}