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 35 /* Destroys a cras_use_case_mgr that was returned from ucm_create. 36 * Args: 37 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 38 */ 39 void ucm_destroy(struct cras_use_case_mgr *mgr); 40 41 /* Sets the new use case for the given cras_use_case_mgr. 42 * Args: 43 * mgr - The cras_use_case_mgr pointer returned from ucm_create. 44 * use_case - The new use case to be set. 45 * Returns: 46 * 0 on success or negative error code on failure. 47 */ 48 int ucm_set_use_case(struct cras_use_case_mgr *mgr, 49 enum CRAS_STREAM_TYPE use_case); 50 51 /* Checks if modifier for left right swap mode exists in ucm. 52 * Args: 53 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 54 * Returns: 55 * 1 if it exists, 0 otherwise. 56 */ 57 int ucm_swap_mode_exists(struct cras_use_case_mgr *mgr); 58 59 /* Enables or disables swap mode for the given node_name. First checks 60 * if the modifier is already enabled or disabled. 61 * Args: 62 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 63 * node_name - The node name. 64 * enable - Enable device if non-zero. 65 * Returns: 66 * 0 on success or negative error code on failure. 67 */ 68 int ucm_enable_swap_mode(struct cras_use_case_mgr *mgr, const char *node_name, 69 int enable); 70 71 /* Enables or disables a UCM device. First checks if the device is already 72 * enabled or disabled. 73 * Args: 74 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 75 * dev - The ucm device to enable of disable. 76 * enable - Enable device if non-zero. 77 * Returns: 78 * 0 on success or negative error code on failure. 79 */ 80 int ucm_set_enabled(struct cras_use_case_mgr *mgr, const char *dev, int enable); 81 82 /* Gets the value of given flag name. 83 * Args: 84 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 85 * flag_name - The name of the flag. 86 * Returns: 87 * A pointer to the allocated string containing the flag value, or 88 * NULL if the flag is not set. 89 */ 90 char *ucm_get_flag(struct cras_use_case_mgr *mgr, const char *flag_name); 91 92 /* Gets the capture control name which associated with given ucm device. 93 * Args: 94 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 95 * ucm_dev - The ucm device to get capture control for. 96 * Returns: 97 * A pointer to the allocated string containing the name of the capture 98 * control, or NULL if no capture control is found. 99 */ 100 char *ucm_get_cap_control(struct cras_use_case_mgr *mgr, const char *ucm_dev); 101 102 /* Gets the mic positions string for internal mic. 103 * Args: 104 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 105 * Returns: 106 * A pointer to the allocated string containing the mic positions 107 * information, or NULL if not specified. 108 */ 109 char *ucm_get_mic_positions(struct cras_use_case_mgr *mgr); 110 111 /* Gets the new node type name which user wants to override the old one for 112 * given ucm device. 113 * Args: 114 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 115 * ucm_dev - The ucm device to override node type. 116 * Returns: 117 * A pointer to the allocated string containing the new type name, 118 * or NULL if no override_type_name is found. 119 */ 120 const char *ucm_get_override_type_name(struct cras_use_case_mgr *mgr, 121 const char *ucm_dev); 122 123 /* Gets the name of the ucm device for the given jack name. 124 * Args: 125 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 126 * jack - The name of the jack to search for. 127 * direction - input or output 128 * Rreturns: 129 * A pointer to the allocated string containing the name of the device, or 130 * NULL if no device is found. 131 */ 132 char *ucm_get_dev_for_jack(struct cras_use_case_mgr *mgr, const char *jack, 133 enum CRAS_STREAM_DIRECTION direction); 134 135 /* Gets the name of the ucm device for the given mixer name. 136 * Args: 137 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 138 * mixer - The name of the mixer control to search for. 139 * dir - 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_mixer(struct cras_use_case_mgr *mgr, const char *mixer, 145 enum CRAS_STREAM_DIRECTION dir); 146 147 /* If there is an EDID file variable specified for dev, return it. The EDID 148 * file will be used for HDMI devices so supported audio formats can be checked. 149 * Args: 150 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 151 * dev - The device to check for an EDID file. 152 * Returns: 153 * A string containing the name of the edid file on Success (Must be freed 154 * later). NULL if none found. 155 */ 156 const char *ucm_get_edid_file_for_dev(struct cras_use_case_mgr *mgr, 157 const char *dev); 158 159 /* Gets the dsp name which is associated with the given ucm device. 160 * Args: 161 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 162 * ucm_dev - The ucm device to get dsp name for. 163 * direction - playback(CRAS_STREAM_OUTPUT) or capture(CRAS_STREAM_INPUT). 164 * Returns: 165 * A pointer to the allocated string containing the dsp name, or NULL if no 166 * dsp name is found. 167 */ 168 const char *ucm_get_dsp_name(struct cras_use_case_mgr *mgr, const char *ucm_dev, 169 int direction); 170 171 /* Gets the default dsp name. 172 * Args: 173 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 174 * direction - playback(CRAS_STREAM_OUTPUT) or capture(CRAS_STREAM_INPUT). 175 * Returns: 176 * A pointer to the allocated string containing the default dsp name, or 177 * NULL if no default dsp name is found. 178 */ 179 const char *ucm_get_dsp_name_default(struct cras_use_case_mgr *mgr, 180 int direction); 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 minimum software gain. 202 * Args: 203 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 204 * dev - The device to check for minimum software 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_min_software_gain(struct cras_use_case_mgr *mgr, const char *dev, 210 long *gain); 211 212 /* Gets the value for maximum software gain. 213 * Args: 214 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 215 * dev - The device to check for maximum software gain. 216 * gain - The pointer to the returned value; 217 * Returns: 218 * 0 on success, other error codes on failure. 219 */ 220 int ucm_get_max_software_gain(struct cras_use_case_mgr *mgr, const char *dev, 221 long *gain); 222 223 /* Gets the value for default node gain. 224 * Args: 225 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 226 * dev - The device to check for default node gain. 227 * gain - The pointer to the returned value; 228 * Returns: 229 * 0 on success, other error codes on failure. 230 */ 231 int ucm_get_default_node_gain(struct cras_use_case_mgr *mgr, const char *dev, 232 long *gain); 233 234 /* Gets the flag if an input device can preempt hotword recording. 235 * Args: 236 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 237 * dev - The device to check for preempt hotword flag. 238 * Returns: 239 * Non-zero value means input can preempt hotword recording, otherwise 240 * return zero. 241 */ 242 int ucm_get_preempt_hotword(struct cras_use_case_mgr *mgr, const char *dev); 243 244 /* Gets the device name of this device on the card.. 245 * 246 * Args: 247 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 248 * dev - The device to check for device name 249 * direction - playback(CRAS_STREAM_OUTPUT) or capture(CRAS_STREAM_INPUT). 250 * Returns: 251 * A pointer to the allocated string containing the device name, or NULL 252 * if no device name is found. The device name is of format 253 * "card_name:device_index". 254 */ 255 const char *ucm_get_device_name_for_dev( 256 struct cras_use_case_mgr *mgr, const char *dev, 257 enum CRAS_STREAM_DIRECTION direction); 258 259 /* Gets the node name of the echo reference device on the card. 260 * Args: 261 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 262 * dev - The device to check echo reference for. 263 * Returns: 264 * String containing the node name of the echo reference to this 265 * dev, caller is responsible to free it later. NULL if echo reference 266 * doesn't exist. 267 */ 268 const char *ucm_get_echo_reference_dev_name_for_dev( 269 struct cras_use_case_mgr *mgr, const char *dev); 270 271 /* Gets the sample rate at which to run this device. 272 * 273 * Args: 274 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 275 * dev - The device to check for sample rate. 276 * direction - playback(CRAS_STREAM_OUTPUT) or capture(CRAS_STREAM_INPUT). 277 * Returns: 278 * The sample rate if specified, or negative error if not. 279 */ 280 int ucm_get_sample_rate_for_dev(struct cras_use_case_mgr *mgr, const char *dev, 281 enum CRAS_STREAM_DIRECTION direction); 282 283 /* Gets the capture channel map for this device. 284 * Args: 285 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 286 * dev - The device to check for capture channel map. 287 * channel_layout - The channel layout to fill. 288 */ 289 int ucm_get_capture_chmap_for_dev(struct cras_use_case_mgr *mgr, 290 const char *dev, 291 int8_t *channel_layout); 292 293 /* Gets the mixer names for the coupled mixer controls of this device 294 * on the card. 295 * 296 * Args: 297 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 298 * dev - The device to check for coupled mixer controls. 299 * Returns: 300 * A list of cras_alsa_control. 301 */ 302 struct mixer_name *ucm_get_coupled_mixer_names( 303 struct cras_use_case_mgr *mgr, const char *dev); 304 305 /* Gets a list of UCM sections 306 * 307 * The data includes the represented devices and their controls. 308 * 309 * Args: 310 * mgr - The cras_use_case_mgr pointer return from alsa_ucm_create. 311 * 312 * Returns: 313 * A list of ucm_section or NULL. Free it with ucm_section_free_list(). 314 */ 315 struct ucm_section *ucm_get_sections(struct cras_use_case_mgr *mgr); 316 317 /* Gets the list of supported hotword model names. 318 * Args: 319 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 320 * Returns: 321 * String containing comma separated model names, e.g 'en,fr,zh'. Needs 322 * to be freed by caller. 323 */ 324 char *ucm_get_hotword_models(struct cras_use_case_mgr *mgr); 325 326 /* Sets the desired hotword model. 327 * Args: 328 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 329 * Returns: 330 * 0 on success or negative error code on failure. 331 */ 332 int ucm_set_hotword_model(struct cras_use_case_mgr *mgr, const char *model); 333 334 /* Checks if this card has fully specified UCM config. 335 * 336 * Args: 337 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 338 * Returns: 339 * 1 if this UCM uses fully specified UCM config. 0 otherwise. 340 */ 341 int ucm_has_fully_specified_ucm_flag(struct cras_use_case_mgr *mgr); 342 343 /* Gets the mixer name of this device on the card. 344 * 345 * Args: 346 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 347 * dev - The device to check for device name 348 * Returns: 349 * A pointer to the allocated string containing the mixer name, or NULL 350 * if no device name is found. 351 */ 352 const char *ucm_get_mixer_name_for_dev(struct cras_use_case_mgr *mgr, 353 const char *dev); 354 355 /* Gets the mixer names for the main volume controls on the card. 356 * 357 * The main volume controls in the list are considered in series. 358 * If 3 controls are specified, MainVolumeNames "A,B,C", with dB ranges 359 * A=-10dB~0dB, B=-20dB~0dB, C=-30dB~0dB, then applying -35dB overall volume 360 * sets A=-10dB, B=-20dB, C=-5dB. 361 * The volume control affects all output on this card, e.g. 362 * speaker and headphone. 363 * 364 * Args: 365 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 366 * Returns: 367 * names - A list of mixer_name. 368 */ 369 struct mixer_name *ucm_get_main_volume_names(struct cras_use_case_mgr *mgr); 370 371 /* The callback to be provided with a reference to the section name. 372 * 373 * Args: 374 * section_name: The name of a SectionDevice in UCM. 375 * arg - Argument to pass to this callback. 376 */ 377 typedef void (*ucm_list_section_devices_callback)( 378 const char *section_name, void *arg); 379 380 /* Invokes the provided callback once for each section with matched device name. 381 * 382 * Iterate through each SectionDevice in UCM of this card. Invoke callback if 383 * "PlaybackPCM" for output or "CapturePCM" for input of the section matches 384 * the specified device_name. 385 * 386 * Args: 387 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 388 * device_name - A string for device name of format "card_name:device_index". 389 * cb - Function to call for each section. 390 * cb_arg - Argument to pass to cb. 391 * Returns: 392 * Number of sections listed. 393 */ 394 int ucm_list_section_devices_by_device_name( 395 struct cras_use_case_mgr *mgr, 396 enum CRAS_STREAM_DIRECTION direction, 397 const char *device_name, 398 ucm_list_section_devices_callback cb, 399 void *cb_arg); 400 401 /* Gets the jack name of this device on the card. 402 * 403 * Args: 404 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 405 * dev - The device to check for jack name. 406 * Returns: 407 * A pointer to the allocated string containing the jack name, or NULL 408 * if no jack name is found. 409 */ 410 const char *ucm_get_jack_name_for_dev(struct cras_use_case_mgr *mgr, 411 const char *dev); 412 413 /* Gets the jack type of this device on the card. 414 * 415 * Args: 416 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 417 * dev - The device to check for jack type. 418 * Returns: 419 * A pointer to the allocated string containing the jack type, or NULL 420 * if no jack type is found or the found jack type is invalid. The valid 421 * jack types are "hctl" or "gpio". 422 */ 423 const char *ucm_get_jack_type_for_dev(struct cras_use_case_mgr *mgr, 424 const char *dev); 425 426 /* Gets the jack switch number for this device. 427 * Some sound cards can detect multiple types of connections into the 428 * audio jack - for example distinguish between line-out and headphones 429 * by measuring the impedance on the other end. In that case we want each 430 * jack to have it's own I/O node so that each can have it's own volume 431 * settings. This allows us to specify the jack used more exactly. 432 * Valid values are defined in /usr/include/linux/input.h. 433 * Args: 434 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 435 * dev - The device to check. 436 * Returns: 437 * A value >= 0 when the switch is defined, or -1 otherwise. 438 */ 439 int ucm_get_jack_switch_for_dev(struct cras_use_case_mgr *mgr, const char *dev); 440 441 /* Gets the DMA period time in microseconds for the given device. 442 * 443 * Args: 444 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 445 * dev - The device to check. 446 * Returns: 447 * A value > 0, or 0 if no period is defined. 448 */ 449 unsigned int ucm_get_dma_period_for_dev(struct cras_use_case_mgr *mgr, 450 const char *dev); 451 452 /* Gets the flag of optimization for no stream state. 453 * This flag enables no_stream ops in alsa_io. 454 * Args: 455 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 456 * Returns: 457 * 1 if the flag is enabled. 0 otherwise. 458 */ 459 unsigned int ucm_get_optimize_no_stream_flag(struct cras_use_case_mgr *mgr); 460 461 /* Retrieve the flag that enables use of htimestamp. 462 * Args: 463 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 464 * Returns: 465 * 1 if the flag is enabled. 0 otherwise. 466 */ 467 unsigned int ucm_get_enable_htimestamp_flag(struct cras_use_case_mgr *mgr); 468 469 #endif /* _CRAS_ALSA_UCM_H */ 470