/usr/include/alsa/use-case.h is in libasound2-dev 1.1.0-0ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 | /**
* \file include/use-case.h
* \brief use case interface for the ALSA driver
* \author Liam Girdwood <lrg@slimlogic.co.uk>
* \author Stefan Schmidt <stefan@slimlogic.co.uk>
* \author Jaroslav Kysela <perex@perex.cz>
* \author Justin Xu <justinx@slimlogic.co.uk>
* \date 2008-2010
*/
/*
*
* This library is free software; you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as
* published by the Free Software Foundation; either version 2.1 of
* the License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*
* Copyright (C) 2008-2010 SlimLogic Ltd
* Copyright (C) 2010 Wolfson Microelectronics PLC
* Copyright (C) 2010 Texas Instruments Inc.
*
* Support for the verb/device/modifier core logic and API,
* command line tool and file parser was kindly sponsored by
* Texas Instruments Inc.
* Support for multiple active modifiers and devices,
* transition sequences, multiple client access and user defined use
* cases was kindly sponsored by Wolfson Microelectronics PLC.
*/
#ifndef __ALSA_USE_CASE_H
#define __ALSA_USE_CASE_H
#ifdef __cplusplus
extern "C" {
#endif
/**
* \defgroup ucm Use Case Interface
* The ALSA Use Case manager interface.
* See \ref Usecase page for more details.
* \{
*/
/*! \page Usecase ALSA Use Case Interface
*
* The use case manager works by configuring the sound card ALSA kcontrols to
* change the hardware digital and analog audio routing to match the requested
* device use case. The use case manager kcontrol configurations are stored in
* easy to modify text files.
*
* An audio use case can be defined by a verb and device parameter. The verb
* describes the use case action i.e. a phone call, listening to music, recording
* a conversation etc. The device describes the physical audio capture and playback
* hardware i.e. headphones, phone handset, bluetooth headset, etc.
*
* It's intended clients will mostly only need to set the use case verb and
* device for each system use case change (as the verb and device parameters
* cover most audio use cases).
*
* However there are times when a use case has to be modified at runtime. e.g.
*
* + Incoming phone call when the device is playing music
* + Recording sections of a phone call
* + Playing tones during a call.
*
* In order to allow asynchronous runtime use case adaptations, we have a third
* optional modifier parameter that can be used to further configure
* the use case during live audio runtime.
*
* This interface allows clients to :-
*
* + Query the supported use case verbs, devices and modifiers for the machine.
* + Set and Get use case verbs, devices and modifiers for the machine.
* + Get the ALSA PCM playback and capture device PCMs for use case verb,
* use case device and modifier.
* + Get the TQ parameter for each use case verb, use case device and
* modifier.
* + Get the ALSA master playback and capture volume/switch kcontrols
* for each use case.
*/
/*
* Use Case Verb.
*
* The use case verb is the main device audio action. e.g. the "HiFi" use
* case verb will configure the audio hardware for HiFi Music playback
* and capture.
*/
#define SND_USE_CASE_VERB_INACTIVE "Inactive" /**< Inactive Verb */
#define SND_USE_CASE_VERB_HIFI "HiFi" /**< HiFi Verb */
#define SND_USE_CASE_VERB_HIFI_LOW_POWER "HiFi Low Power" /**< HiFi Low Power Verb */
#define SND_USE_CASE_VERB_VOICE "Voice" /**< Voice Verb */
#define SND_USE_CASE_VERB_VOICE_LOW_POWER "Voice Low Power" /**< Voice Low Power Verb */
#define SND_USE_CASE_VERB_VOICECALL "Voice Call" /**< Voice Call Verb */
#define SND_USE_CASE_VERB_IP_VOICECALL "Voice Call IP" /**< Voice Call IP Verb */
#define SND_USE_CASE_VERB_ANALOG_RADIO "FM Analog Radio" /**< FM Analog Radio Verb */
#define SND_USE_CASE_VERB_DIGITAL_RADIO "FM Digital Radio" /**< FM Digital Radio Verb */
/* add new verbs to end of list */
/*
* Use Case Device.
*
* Physical system devices the render and capture audio. Devices can be OR'ed
* together to support audio on simultaneous devices.
*/
#define SND_USE_CASE_DEV_NONE "None" /**< None Device */
#define SND_USE_CASE_DEV_SPEAKER "Speaker" /**< Speaker Device */
#define SND_USE_CASE_DEV_LINE "Line" /**< Line Device */
#define SND_USE_CASE_DEV_HEADPHONES "Headphones" /**< Headphones Device */
#define SND_USE_CASE_DEV_HEADSET "Headset" /**< Headset Device */
#define SND_USE_CASE_DEV_HANDSET "Handset" /**< Handset Device */
#define SND_USE_CASE_DEV_BLUETOOTH "Bluetooth" /**< Bluetooth Device */
#define SND_USE_CASE_DEV_EARPIECE "Earpiece" /**< Earpiece Device */
#define SND_USE_CASE_DEV_SPDIF "SPDIF" /**< SPDIF Device */
#define SND_USE_CASE_DEV_HDMI "HDMI" /**< HDMI Device */
/* add new devices to end of list */
/*
* Use Case Modifiers.
*
* The use case modifier allows runtime configuration changes to deal with
* asynchronous events.
*
* e.g. to record a voice call :-
* 1. Set verb to SND_USE_CASE_VERB_VOICECALL (for voice call)
* 2. Set modifier SND_USE_CASE_MOD_CAPTURE_VOICE when capture required.
* 3. Call snd_use_case_get("CapturePCM") to get ALSA source PCM name
* with captured voice pcm data.
*
* e.g. to play a ring tone when listenin to MP3 Music :-
* 1. Set verb to SND_USE_CASE_VERB_HIFI (for MP3 playback)
* 2. Set modifier to SND_USE_CASE_MOD_PLAY_TONE when incoming call happens.
* 3. Call snd_use_case_get("PlaybackPCM") to get ALSA PCM sink name for
* ringtone pcm data.
*/
#define SND_USE_CASE_MOD_CAPTURE_VOICE "Capture Voice" /**< Capture Voice Modifier */
#define SND_USE_CASE_MOD_CAPTURE_MUSIC "Capture Music" /**< Capture Music Modifier */
#define SND_USE_CASE_MOD_PLAY_MUSIC "Play Music" /**< Play Music Modifier */
#define SND_USE_CASE_MOD_PLAY_VOICE "Play Voice" /**< Play Voice Modifier */
#define SND_USE_CASE_MOD_PLAY_TONE "Play Tone" /**< Play Tone Modifier */
#define SND_USE_CASE_MOD_ECHO_REF "Echo Reference" /**< Echo Reference Modifier */
/* add new modifiers to end of list */
/**
* TQ - Tone Quality
*
* The interface allows clients to determine the audio TQ required for each
* use case verb and modifier. It's intended as an optional hint to the
* audio driver in order to lower power consumption.
*
*/
#define SND_USE_CASE_TQ_MUSIC "Music" /**< Music Tone Quality */
#define SND_USE_CASE_TQ_VOICE "Voice" /**< Voice Tone Quality */
#define SND_USE_CASE_TQ_TONES "Tones" /**< Tones Tone Quality */
/** use case container */
typedef struct snd_use_case_mgr snd_use_case_mgr_t;
/**
* \brief Create an identifier
* \param fmt Format (sprintf like)
* \param ... Optional arguments for sprintf like format
* \return Allocated string identifier or NULL on error
*/
char *snd_use_case_identifier(const char *fmt, ...);
/**
* \brief Free a string list
* \param list The string list to free
* \param items Count of strings
* \return Zero if success, otherwise a negative error code
*/
int snd_use_case_free_list(const char *list[], int items);
/**
* \brief Obtain a list of entries
* \param uc_mgr Use case manager (may be NULL - card list)
* \param identifier (may be NULL - card list)
* \param list Returned allocated list
* \return Number of list entries if success, otherwise a negative error code
*
* Defined identifiers:
* NULL - get card list
* (in pair cardname+comment)
* _verbs - get verb list
* (in pair verb+comment)
* _devices[/{verb}] - get list of supported devices
* (in pair device+comment)
* _modifiers[/{verb}]- get list of supported modifiers
* (in pair modifier+comment)
* TQ[/{verb}] - get list of TQ identifiers
* _enadevs - get list of enabled devices
* _enamods - get list of enabled modifiers
*
* _supporteddevs/{modifier}|{device}[/{verb}] - list of supported devices
* _conflictingdevs/{modifier}|{device}[/{verb}] - list of conflicting devices
* Note that at most one of the supported/conflicting devs lists has
* any entries, and when neither is present, all devices are supported.
*
*/
int snd_use_case_get_list(snd_use_case_mgr_t *uc_mgr,
const char *identifier,
const char **list[]);
/**
* \brief Get current - string
* \param uc_mgr Use case manager
* \param identifier
* \param value Value pointer
* \return Zero if success, otherwise a negative error code
*
* Note: The returned string is dynamically allocated, use free() to
* deallocate this string. (Yes, the value parameter shouldn't be marked as
* "const", but it's too late to fix it, sorry about that.)
*
* Known identifiers:
* - NULL - return current card
* - _verb - return current verb
*
* - [=]{NAME}[/[{modifier}|{/device}][/{verb}]]
* - value identifier {NAME}
* - Search starts at given modifier or device if any,
* else at a verb
* - Search starts at given verb if any,
* else current verb
* - Searches modifier/device, then verb, then defaults
* - Specify a leading "=" to search only the exact
* device/modifier/verb specified, and not search
* through each object in turn.
* - Examples:
* - "PlaybackPCM/Play Music"
* - "CapturePCM/SPDIF"
* - From ValueDefaults only:
* "=Variable"
* - From current active verb:
* "=Variable//"
* - From verb "Verb":
* "=Variable//Verb"
* - From "Modifier" in current active verb:
* "=Variable/Modifier/"
* - From "Modifier" in "Verb":
* "=Variable/Modifier/Verb"
*
* Recommended names for values:
* - TQ
* - Tone Quality
* - PlaybackPCM
* - full PCM playback device name
* - PlaybackPCMIsDummy
* - Valid values: "yes" and "no". If set to "yes", the PCM named by the
* PlaybackPCM value is a dummy device, meaning that opening it enables
* an audio path in the hardware, but writing to the PCM device has no
* effect.
* - CapturePCM
* - full PCM capture device name
* - CapturePCMIsDummy
* - Valid values: "yes" and "no". If set to "yes", the PCM named by the
* CapturePCM value is a dummy device, meaning that opening it enables
* an audio path in the hardware, but reading from the PCM device has no
* effect.
* - PlaybackRate
* - playback device sample rate
* - PlaybackChannels
* - playback device channel count
* - PlaybackCTL
* - playback control device name
* - PlaybackVolume
* - playback control volume ID string
* - PlaybackSwitch
* - playback control switch ID string
* - CaptureRate
* - capture device sample rate
* - CaptureChannels
* - capture device channel count
* - CaptureCTL
* - capture control device name
* - CaptureVolume
* - capture control volume ID string
* - CaptureSwitch
* - capture control switch ID string
* - PlaybackMixer
* - name of playback mixer
* - PlaybackMixerID
* - mixer playback ID
* - CaptureMixer
* - name of capture mixer
* - CaptureMixerID
* - mixer capture ID
* - JackControl, JackDev, JackHWMute
* - Jack information for a device. The jack status can be reported via
* a kcontrol and/or via an input device. **JackControl** is the
* kcontrol name of the jack, and **JackDev** is the input device id of
* the jack (if the full input device path is /dev/input/by-id/foo, the
* JackDev value should be "foo"). UCM configuration files should
* contain both JackControl and JackDev when possible, because
* applications are likely to support only one or the other.
*
* If **JackHWMute** is set, it indicates that when the jack is plugged
* in, the hardware automatically mutes some other device(s). The
* JackHWMute value is a space-separated list of device names (this
* isn't compatible with device names with spaces in them, so don't use
* such device names!). Note that JackHWMute should be used only when
* the hardware enforces the automatic muting. If the hardware doesn't
* enforce any muting, it may still be tempting to set JackHWMute to
* trick upper software layers to e.g. automatically mute speakers when
* headphones are plugged in, but that's application policy
* configuration that doesn't belong to UCM configuration files.
*/
int snd_use_case_get(snd_use_case_mgr_t *uc_mgr,
const char *identifier,
const char **value);
/**
* \brief Get current - integer
* \param uc_mgr Use case manager
* \param identifier
* \param value result
* \return Zero if success, otherwise a negative error code
*
* Known identifiers:
* _devstatus/{device} - return status for given device
* _modstatus/{modifier} - return status for given modifier
*/
int snd_use_case_geti(snd_use_case_mgr_t *uc_mgr,
const char *identifier,
long *value);
/**
* \brief Set new
* \param uc_mgr Use case manager
* \param identifier
* \param value Value
* \return Zero if success, otherwise a negative error code
*
* Known identifiers:
* _verb - set current verb = value
* _enadev - enable given device = value
* _disdev - disable given device = value
* _swdev/{old_device} - new_device = value
* - disable old_device and then enable new_device
* - if old_device is not enabled just return
* - check transmit sequence firstly
* _enamod - enable given modifier = value
* _dismod - disable given modifier = value
* _swmod/{old_modifier} - new_modifier = value
* - disable old_modifier and then enable new_modifier
* - if old_modifier is not enabled just return
* - check transmit sequence firstly
*/
int snd_use_case_set(snd_use_case_mgr_t *uc_mgr,
const char *identifier,
const char *value);
/**
* \brief Open and initialise use case core for sound card
* \param uc_mgr Returned use case manager pointer
* \param card_name Sound card name.
* \return zero if success, otherwise a negative error code
*/
int snd_use_case_mgr_open(snd_use_case_mgr_t **uc_mgr, const char *card_name);
/**
* \brief Reload and re-parse use case configuration files for sound card.
* \param uc_mgr Use case manager
* \return zero if success, otherwise a negative error code
*/
int snd_use_case_mgr_reload(snd_use_case_mgr_t *uc_mgr);
/**
* \brief Close use case manager
* \param uc_mgr Use case manager
* \return zero if success, otherwise a negative error code
*/
int snd_use_case_mgr_close(snd_use_case_mgr_t *uc_mgr);
/**
* \brief Reset use case manager verb, device, modifier to deafult settings.
* \param uc_mgr Use case manager
* \return zero if success, otherwise a negative error code
*/
int snd_use_case_mgr_reset(snd_use_case_mgr_t *uc_mgr);
/*
* helper functions
*/
/**
* \brief Obtain a list of cards
* \param list Returned allocated list
* \return Number of list entries if success, otherwise a negative error code
*/
static __inline__ int snd_use_case_card_list(const char **list[])
{
return snd_use_case_get_list(NULL, NULL, list);
}
/**
* \brief Obtain a list of verbs
* \param uc_mgr Use case manager
* \param list Returned list of verbs
* \return Number of list entries if success, otherwise a negative error code
*/
static __inline__ int snd_use_case_verb_list(snd_use_case_mgr_t *uc_mgr,
const char **list[])
{
return snd_use_case_get_list(uc_mgr, "_verbs", list);
}
/**
* \}
*/
#ifdef __cplusplus
}
#endif
#endif /* __ALSA_USE_CASE_H */
|