1 /* Copyright (c) 2012 The Chromium OS Authors. All rights reserved. 2 * Use of this source code is governed by a BSD-style license that can be 3 * found in the LICENSE file. 4 */ 5 6 #ifndef _CRAS_ALSA_UCM_H 7 #define _CRAS_ALSA_UCM_H 8 9 #include <alsa/asoundlib.h> 10 11 #include "cras_alsa_mixer_name.h" 12 #include "cras_alsa_ucm_section.h" 13 #include "cras_types.h" 14 15 struct cras_use_case_mgr; 16 17 /* Helpers to access UCM configuration for a card if any is provided. 18 * This configuration can specify how to enable or disable certain inputs and 19 * outputs on the card. 20 */ 21 22 /* Creates a cras_use_case_mgr instance for the given card name if there is a 23 * matching ucm configuration. It there is a matching UCM config, then it will 24 * be configured to the default state. 25 * 26 * Args: 27 * name - Name of the card to match against the UCM card list. 28 * Returns: 29 * A pointer to the use case manager if found, otherwise NULL. The pointer 30 * must later be freed with ucm_destroy(). 31 */ 32 struct cras_use_case_mgr *ucm_create(const char *name); 33 34 /* Destroys a cras_use_case_mgr that was returned from ucm_create. 35 * Args: 36 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 37 */ 38 void ucm_destroy(struct cras_use_case_mgr *mgr); 39 40 /* Sets the new use case for the given cras_use_case_mgr. 41 * Args: 42 * mgr - The cras_use_case_mgr pointer returned from ucm_create. 43 * use_case - The new use case to be set. 44 * Returns: 45 * 0 on success or negative error code on failure. 46 */ 47 int ucm_set_use_case(struct cras_use_case_mgr *mgr, 48 enum CRAS_STREAM_TYPE use_case); 49 50 /* Checks if modifier for left right swap mode exists in ucm. 51 * Args: 52 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 53 * Returns: 54 * 1 if it exists, 0 otherwise. 55 */ 56 int ucm_swap_mode_exists(struct cras_use_case_mgr *mgr); 57 58 /* Enables or disables swap mode for the given node_name. First checks 59 * if the modifier is already enabled or disabled. 60 * Args: 61 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 62 * node_name - The node name. 63 * enable - Enable device if non-zero. 64 * Returns: 65 * 0 on success or negative error code on failure. 66 */ 67 int ucm_enable_swap_mode(struct cras_use_case_mgr *mgr, const char *node_name, 68 int enable); 69 70 /* Checks if modifier of noise cancellation for given node_name exists in ucm. 71 * Args: 72 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 73 * node_name - The node name. 74 * Returns: 75 * 1 if it exists, 0 otherwise. 76 */ 77 int ucm_node_noise_cancellation_exists(struct cras_use_case_mgr *mgr, 78 const char *node_name); 79 80 /* Enables or disables noise cancellation for the given node_name. First checks 81 * if the modifier is already enabled or disabled. 82 * Args: 83 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 84 * node_name - The node name. 85 * enable - Enable device if non-zero. 86 * Returns: 87 * 0 on success or negative error code on failure. 88 */ 89 int ucm_enable_node_noise_cancellation(struct cras_use_case_mgr *mgr, 90 const char *node_name, int enable); 91 92 /* Enables or disables a UCM device. First checks if the device is already 93 * enabled or disabled. 94 * Args: 95 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 96 * dev - The ucm device to enable of disable. 97 * enable - Enable device if non-zero. 98 * Returns: 99 * 0 on success or negative error code on failure. 100 */ 101 int ucm_set_enabled(struct cras_use_case_mgr *mgr, const char *dev, int enable); 102 103 /* Gets the value of given flag name. 104 * Args: 105 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 106 * flag_name - The name of the flag. 107 * Returns: 108 * A pointer to the allocated string containing the flag value, or 109 * NULL if the flag is not set. 110 */ 111 char *ucm_get_flag(struct cras_use_case_mgr *mgr, const char *flag_name); 112 113 /* Gets the capture control name which associated with given ucm device. 114 * Args: 115 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 116 * ucm_dev - The ucm device to get capture control for. 117 * Returns: 118 * A pointer to the allocated string containing the name of the capture 119 * control, or NULL if no capture control is found. 120 */ 121 char *ucm_get_cap_control(struct cras_use_case_mgr *mgr, const char *ucm_dev); 122 123 /* Gets the new node type name which user wants to override the old one for 124 * given ucm device. 125 * Args: 126 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 127 * ucm_dev - The ucm device to override node type. 128 * Returns: 129 * A pointer to the allocated string containing the new type name, 130 * or NULL if no override_type_name is found. 131 */ 132 const char *ucm_get_override_type_name(struct cras_use_case_mgr *mgr, 133 const char *ucm_dev); 134 135 /* Gets the name of the ucm device for the given jack name. 136 * Args: 137 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 138 * jack - The name of the jack to search for. 139 * direction - input or output 140 * Rreturns: 141 * A pointer to the allocated string containing the name of the device, or 142 * NULL if no device is found. 143 */ 144 char *ucm_get_dev_for_jack(struct cras_use_case_mgr *mgr, const char *jack, 145 enum CRAS_STREAM_DIRECTION direction); 146 147 /* Gets the name of the ucm device for the given mixer name. 148 * Args: 149 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 150 * mixer - The name of the mixer control to search for. 151 * dir - input or output 152 * Rreturns: 153 * A pointer to the allocated string containing the name of the device, or 154 * NULL if no device is found. 155 */ 156 char *ucm_get_dev_for_mixer(struct cras_use_case_mgr *mgr, const char *mixer, 157 enum CRAS_STREAM_DIRECTION dir); 158 159 /* If there is an EDID file variable specified for dev, return it. The EDID 160 * file will be used for HDMI devices so supported audio formats can be checked. 161 * Args: 162 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 163 * dev - The device to check for an EDID file. 164 * Returns: 165 * A string containing the name of the edid file on Success (Must be freed 166 * later). NULL if none found. 167 */ 168 const char *ucm_get_edid_file_for_dev(struct cras_use_case_mgr *mgr, 169 const char *dev); 170 171 /* Gets the dsp name which is associated with the given ucm device. 172 * Args: 173 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 174 * dev - The device to get dsp name for. 175 * Returns: 176 * A pointer to the allocated string containing the dsp name, or NULL if no 177 * dsp name is found. 178 */ 179 const char *ucm_get_dsp_name_for_dev(struct cras_use_case_mgr *mgr, 180 const char *dev); 181 182 /* Gets the minimum buffer level for an output. This level will add latency to 183 * all streams playing on the output, but can be used to work around an 184 * unreliable dma residue. 185 * Args: 186 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 187 * level - The pointer to the returned value. 188 * 189 */ 190 int ucm_get_min_buffer_level(struct cras_use_case_mgr *mgr, 191 unsigned int *level); 192 193 /* Gets the flag for disabling software volume. 194 * Args: 195 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 196 * Returns: 197 * 0 on success, -ENOENT on failure. 198 */ 199 unsigned int ucm_get_disable_software_volume(struct cras_use_case_mgr *mgr); 200 201 /* Gets the value for default node gain. 202 * Args: 203 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 204 * dev - The device to check for default node gain. 205 * gain - The pointer to the returned value. 206 * Returns: 207 * 0 on success, other error codes on failure. 208 */ 209 int ucm_get_default_node_gain(struct cras_use_case_mgr *mgr, const char *dev, 210 long *gain); 211 212 /* Gets the value for intrinsic sensitivity. 213 * Args: 214 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 215 * dev - The device to query for intrinsic volume. 216 * sensitivity - The pointer to the returned value. 217 * Returns: 218 * 0 on success, other error codes on failure. 219 */ 220 int ucm_get_intrinsic_sensitivity(struct cras_use_case_mgr *mgr, 221 const char *dev, long *sensitivity); 222 223 /* Gets the flag if an input device can preempt hotword recording. 224 * Args: 225 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 226 * dev - The device to check for preempt hotword flag. 227 * Returns: 228 * Non-zero value means input can preempt hotword recording, otherwise 229 * return zero. 230 */ 231 int ucm_get_preempt_hotword(struct cras_use_case_mgr *mgr, const char *dev); 232 233 /* Gets the ALSA device index on the card for given UCM dev. 234 * 235 * Args: 236 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 237 * dev - The UCM device to check for ALSA device index. 238 * direction - playback(CRAS_STREAM_OUTPUT) or capture(CRAS_STREAM_INPUT). 239 * Returns: 240 * Non-negative integer for the ALSA device index on the card, -1 if not 241 * found. The ALSA device index is parsed from the PCM name which is 242 * formatted as "hw:<some-name>,<idx>". 243 */ 244 int ucm_get_alsa_dev_idx_for_dev(struct cras_use_case_mgr *mgr, const char *dev, 245 enum CRAS_STREAM_DIRECTION direction); 246 247 /* Gets the node name of the echo reference device on the card. 248 * Args: 249 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 250 * dev - The device to check echo reference for. 251 * Returns: 252 * String containing the node name of the echo reference to this 253 * dev, caller is responsible to free it later. NULL if echo reference 254 * doesn't exist. 255 */ 256 const char * 257 ucm_get_echo_reference_dev_name_for_dev(struct cras_use_case_mgr *mgr, 258 const char *dev); 259 260 /* Gets the sample rate at which to run this device. 261 * 262 * Args: 263 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 264 * dev - The device to check for sample rate. 265 * direction - playback(CRAS_STREAM_OUTPUT) or capture(CRAS_STREAM_INPUT). 266 * Returns: 267 * The sample rate if specified, or negative error if not. 268 */ 269 int ucm_get_sample_rate_for_dev(struct cras_use_case_mgr *mgr, const char *dev, 270 enum CRAS_STREAM_DIRECTION direction); 271 272 /* Gets the channel count at which to run this device. 273 * 274 * Args: 275 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 276 * dev - The device to check for channel count. 277 * direction - playback(CRAS_STREAM_OUTPUT) or capture(CRAS_STREAM_INPUT). 278 * channels - The pointer to the returned channel count. 279 * Returns: 280 * 0 on success, other error codes on failure. 281 */ 282 int ucm_get_channels_for_dev(struct cras_use_case_mgr *mgr, const char *dev, 283 enum CRAS_STREAM_DIRECTION direction, 284 size_t *channels); 285 286 /* Gets the capture channel map for this device. 287 * Args: 288 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 289 * dev - The device to check for capture channel map. 290 * channel_layout - The channel layout to fill. 291 */ 292 int ucm_get_capture_chmap_for_dev(struct cras_use_case_mgr *mgr, 293 const char *dev, int8_t *channel_layout); 294 295 /* Gets the mixer names for the coupled mixer controls of this device 296 * on the card. 297 * 298 * Args: 299 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 300 * dev - The device to check for coupled mixer controls. 301 * Returns: 302 * A list of cras_alsa_control. 303 */ 304 struct mixer_name *ucm_get_coupled_mixer_names(struct cras_use_case_mgr *mgr, 305 const char *dev); 306 307 /* Gets a list of UCM sections 308 * 309 * The data includes the represented devices and their controls. 310 * 311 * Args: 312 * mgr - The cras_use_case_mgr pointer return from alsa_ucm_create. 313 * 314 * Returns: 315 * A list of ucm_section or NULL. Free it with ucm_section_free_list(). 316 */ 317 struct ucm_section *ucm_get_sections(struct cras_use_case_mgr *mgr); 318 319 /* Gets the list of supported hotword model names. 320 * Args: 321 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 322 * Returns: 323 * String containing comma separated model names, e.g 'en,fr,zh'. Needs 324 * to be freed by caller. 325 */ 326 char *ucm_get_hotword_models(struct cras_use_case_mgr *mgr); 327 328 /* Sets the desired hotword model. 329 * Args: 330 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 331 * model - locale for model 332 * Returns: 333 * 0 on success or negative error code on failure. 334 */ 335 int ucm_set_hotword_model(struct cras_use_case_mgr *mgr, const char *model); 336 337 /* Enable previously set hotword modifier 338 * Args: 339 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 340 * Returns: 341 * 0 on success or negative error code on failure. 342 */ 343 int ucm_enable_hotword_model(struct cras_use_case_mgr *mgr); 344 345 /* Disable all hotword model modifiers 346 * Args: 347 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 348 */ 349 void ucm_disable_all_hotword_models(struct cras_use_case_mgr *mgr); 350 351 /* Checks if this card has fully specified UCM config. 352 * 353 * Args: 354 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 355 * Returns: 356 * 1 if this UCM uses fully specified UCM config. 0 otherwise. 357 */ 358 int ucm_has_fully_specified_ucm_flag(struct cras_use_case_mgr *mgr); 359 360 /* Gets the playback mixer name of this device on the card. 361 * 362 * Args: 363 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 364 * dev - The device to check for device name 365 * Returns: 366 * A pointer to the allocated string containing the mixer name, or NULL 367 * if no device name is found. 368 */ 369 const char *ucm_get_playback_mixer_elem_for_dev(struct cras_use_case_mgr *mgr, 370 const char *dev); 371 372 /* Gets the capture mixer name of this device on the card. 373 * 374 * Args: 375 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 376 * dev - The device to check for device name 377 * Returns: 378 * A pointer to the allocated string containing the mixer name, or NULL 379 * if no device name is found. 380 */ 381 const char *ucm_get_capture_mixer_elem_for_dev(struct cras_use_case_mgr *mgr, 382 const char *dev); 383 384 /* Gets the mixer names for the main volume controls on the card. 385 * 386 * The main volume controls in the list are considered in series. 387 * If 3 controls are specified, MainVolumeNames "A,B,C", with dB ranges 388 * A=-10dB~0dB, B=-20dB~0dB, C=-30dB~0dB, then applying -35dB overall volume 389 * sets A=-10dB, B=-20dB, C=-5dB. 390 * The volume control affects all output on this card, e.g. 391 * speaker and headphone. 392 * 393 * Args: 394 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 395 * Returns: 396 * names - A list of mixer_name. 397 */ 398 struct mixer_name *ucm_get_main_volume_names(struct cras_use_case_mgr *mgr); 399 400 /* The callback to be provided with a reference to the section name. 401 * 402 * Args: 403 * section_name: The name of a SectionDevice in UCM. 404 * arg - Argument to pass to this callback. 405 */ 406 typedef void (*ucm_list_section_devices_callback)(const char *section_name, 407 void *arg); 408 409 /* Invokes the provided callback once for each section with matched device name. 410 * 411 * Iterate through each SectionDevice in UCM of this card. Invoke callback if 412 * "PlaybackPCM" for output or "CapturePCM" for input of the section matches 413 * the specified device_name. 414 * 415 * Args: 416 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 417 * device_name - A string for device name of format "card_name:device_index". 418 * cb - Function to call for each section. 419 * cb_arg - Argument to pass to cb. 420 * Returns: 421 * Number of sections listed. 422 */ 423 int ucm_list_section_devices_by_device_name( 424 struct cras_use_case_mgr *mgr, enum CRAS_STREAM_DIRECTION direction, 425 const char *device_name, ucm_list_section_devices_callback cb, 426 void *cb_arg); 427 428 /* Gets the jack name of this device on the card. 429 * 430 * Args: 431 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 432 * dev - The device to check for jack name. 433 * Returns: 434 * A pointer to the allocated string containing the jack name, or NULL 435 * if no jack name is found. 436 */ 437 const char *ucm_get_jack_name_for_dev(struct cras_use_case_mgr *mgr, 438 const char *dev); 439 440 /* Gets the jack type of this device on the card. 441 * 442 * Args: 443 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 444 * dev - The device to check for jack type. 445 * Returns: 446 * A pointer to the allocated string containing the jack type, or NULL 447 * if no jack type is found or the found jack type is invalid. The valid 448 * jack types are "hctl" or "gpio". 449 */ 450 const char *ucm_get_jack_type_for_dev(struct cras_use_case_mgr *mgr, 451 const char *dev); 452 453 /* Gets the jack dev of this device on the card. 454 * 455 * Args: 456 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 457 * dev - The device to check for jack name. 458 * Returns: 459 * A pointer to the allocated string containing the input jack name, or NULL 460 * if no jack name is found. 461 */ 462 const char *ucm_get_jack_dev_for_dev(struct cras_use_case_mgr *mgr, 463 const char *dev); 464 465 /* Gets the jack control of this device on the card. 466 * 467 * Args: 468 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 469 * dev - The device to check for jack type. 470 * Returns: 471 * A pointer to the allocated string containing the alsa jack name, or NULL 472 * if no jack type is found or the found jack type is invalid. 473 */ 474 const char *ucm_get_jack_control_for_dev(struct cras_use_case_mgr *mgr, 475 const char *dev); 476 477 /* Gets the jack switch number for this device. 478 * Some sound cards can detect multiple types of connections into the 479 * audio jack - for example distinguish between line-out and headphones 480 * by measuring the impedance on the other end. In that case we want each 481 * jack to have it's own I/O node so that each can have it's own volume 482 * settings. This allows us to specify the jack used more exactly. 483 * Valid values are defined in /usr/include/linux/input.h. 484 * Args: 485 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 486 * dev - The device to check. 487 * Returns: 488 * A value >= 0 when the switch is defined, or -1 otherwise. 489 */ 490 int ucm_get_jack_switch_for_dev(struct cras_use_case_mgr *mgr, const char *dev); 491 492 /* Gets the DMA period time in microseconds for the given device. 493 * 494 * Args: 495 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 496 * dev - The device to check. 497 * Returns: 498 * A value > 0, or 0 if no period is defined. 499 */ 500 unsigned int ucm_get_dma_period_for_dev(struct cras_use_case_mgr *mgr, 501 const char *dev); 502 503 /* Gets the flag of optimization for no stream state. 504 * This flag enables no_stream ops in alsa_io. 505 * Args: 506 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 507 * Returns: 508 * 1 if the flag is enabled. 0 otherwise. 509 */ 510 unsigned int ucm_get_optimize_no_stream_flag(struct cras_use_case_mgr *mgr); 511 512 #endif /* _CRAS_ALSA_UCM_H */ 513