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 */ 188 unsigned int ucm_get_min_buffer_level(struct cras_use_case_mgr *mgr); 189 190 /* Gets the flag for disabling software volume. 191 * Args: 192 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 193 */ 194 unsigned int ucm_get_disable_software_volume(struct cras_use_case_mgr *mgr); 195 196 /* Gets the value for maximum software gain. 197 * Args: 198 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 199 * dev - The device to check for maximum software gain. 200 * gain - The pointer to the returned value; 201 * Returns: 202 * 0 on success, other error codes on failure. 203 */ 204 int ucm_get_max_software_gain(struct cras_use_case_mgr *mgr, const char *dev, 205 long *gain); 206 207 /* Gets the value for default node gain. 208 * Args: 209 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 210 * dev - The device to check for default node gain. 211 * gain - The pointer to the returned value; 212 * Returns: 213 * 0 on success, other error codes on failure. 214 */ 215 int ucm_get_default_node_gain(struct cras_use_case_mgr *mgr, const char *dev, 216 long *gain); 217 218 /* Gets the device name of this device on the card.. 219 * 220 * Args: 221 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 222 * dev - The device to check for device name 223 * direction - playback(CRAS_STREAM_OUTPUT) or capture(CRAS_STREAM_INPUT). 224 * Returns: 225 * A pointer to the allocated string containing the device name, or NULL 226 * if no device name is found. The device name is of format 227 * "card_name:device_index". 228 */ 229 const char *ucm_get_device_name_for_dev( 230 struct cras_use_case_mgr *mgr, const char *dev, 231 enum CRAS_STREAM_DIRECTION direction); 232 233 /* Gets the sample rate at which to run this device. 234 * 235 * Args: 236 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 237 * dev - The device to check for sample rate. 238 * direction - playback(CRAS_STREAM_OUTPUT) or capture(CRAS_STREAM_INPUT). 239 * Returns: 240 * The sample rate if specified, or negative error if not. 241 */ 242 int ucm_get_sample_rate_for_dev(struct cras_use_case_mgr *mgr, const char *dev, 243 enum CRAS_STREAM_DIRECTION direction); 244 245 /* Gets the capture channel map for this device. 246 * Args: 247 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 248 * dev - The device to check for capture channel map. 249 * channel_layout - The channel layout to fill. 250 */ 251 int ucm_get_capture_chmap_for_dev(struct cras_use_case_mgr *mgr, 252 const char *dev, 253 int8_t *channel_layout); 254 255 /* Gets the mixer names for the coupled mixer controls of this device 256 * on the card. 257 * 258 * Args: 259 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 260 * dev - The device to check for coupled mixer controls. 261 * Returns: 262 * A list of cras_alsa_control. 263 */ 264 struct mixer_name *ucm_get_coupled_mixer_names( 265 struct cras_use_case_mgr *mgr, const char *dev); 266 267 /* Gets a list of UCM sections 268 * 269 * The data includes the represented devices and their controls. 270 * 271 * Args: 272 * mgr - The cras_use_case_mgr pointer return from alsa_ucm_create. 273 * 274 * Returns: 275 * A list of ucm_section or NULL. Free it with ucm_section_free_list(). 276 */ 277 struct ucm_section *ucm_get_sections(struct cras_use_case_mgr *mgr); 278 279 /* Gets the list of supported hotword model names. 280 * Args: 281 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 282 * Returns: 283 * String containing comma separated model names, e.g 'en,fr,zh'. Needs 284 * to be freed by caller. 285 */ 286 char *ucm_get_hotword_models(struct cras_use_case_mgr *mgr); 287 288 /* Sets the desired hotword model. 289 * Args: 290 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 291 * Returns: 292 * 0 on success or negative error code on failure. 293 */ 294 int ucm_set_hotword_model(struct cras_use_case_mgr *mgr, const char *model); 295 296 /* Checks if this card has fully specified UCM config. 297 * 298 * Args: 299 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 300 * Returns: 301 * 1 if this UCM uses fully specified UCM config. 0 otherwise. 302 */ 303 int ucm_has_fully_specified_ucm_flag(struct cras_use_case_mgr *mgr); 304 305 /* Gets the mixer name of this device on the card. 306 * 307 * Args: 308 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 309 * dev - The device to check for device name 310 * Returns: 311 * A pointer to the allocated string containing the mixer name, or NULL 312 * if no device name is found. 313 */ 314 const char *ucm_get_mixer_name_for_dev(struct cras_use_case_mgr *mgr, 315 const char *dev); 316 317 /* Gets the mixer names for the main volume controls on the card. 318 * 319 * The main volume controls in the list are considered in series. 320 * If 3 controls are specified, MainVolumeNames "A,B,C", with dB ranges 321 * A=-10dB~0dB, B=-20dB~0dB, C=-30dB~0dB, then applying -35dB overall volume 322 * sets A=-10dB, B=-20dB, C=-5dB. 323 * The volume control affects all output on this card, e.g. 324 * speaker and headphone. 325 * 326 * Args: 327 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 328 * Returns: 329 * names - A list of mixer_name. 330 */ 331 struct mixer_name *ucm_get_main_volume_names(struct cras_use_case_mgr *mgr); 332 333 /* The callback to be provided with a reference to the section name. 334 * 335 * Args: 336 * section_name: The name of a SectionDevice in UCM. 337 * arg - Argument to pass to this callback. 338 */ 339 typedef void (*ucm_list_section_devices_callback)( 340 const char *section_name, void *arg); 341 342 /* Invokes the provided callback once for each section with matched device name. 343 * 344 * Iterate through each SectionDevice in UCM of this card. Invoke callback if 345 * "PlaybackPCM" for output or "CapturePCM" for input of the section matches 346 * the specified device_name. 347 * 348 * Args: 349 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 350 * device_name - A string for device name of format "card_name:device_index". 351 * cb - Function to call for each section. 352 * cb_arg - Argument to pass to cb. 353 * Returns: 354 * Number of sections listed. 355 */ 356 int ucm_list_section_devices_by_device_name( 357 struct cras_use_case_mgr *mgr, 358 enum CRAS_STREAM_DIRECTION direction, 359 const char *device_name, 360 ucm_list_section_devices_callback cb, 361 void *cb_arg); 362 363 /* Gets the jack name of this device on the card. 364 * 365 * Args: 366 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 367 * dev - The device to check for jack name. 368 * Returns: 369 * A pointer to the allocated string containing the jack name, or NULL 370 * if no jack name is found. 371 */ 372 const char *ucm_get_jack_name_for_dev(struct cras_use_case_mgr *mgr, 373 const char *dev); 374 375 /* Gets the jack type of this device on the card. 376 * 377 * Args: 378 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 379 * dev - The device to check for jack type. 380 * Returns: 381 * A pointer to the allocated string containing the jack type, or NULL 382 * if no jack type is found or the found jack type is invalid. The valid 383 * jack types are "hctl" or "gpio". 384 */ 385 const char *ucm_get_jack_type_for_dev(struct cras_use_case_mgr *mgr, 386 const char *dev); 387 388 /* Gets the jack switch number for this device. 389 * Some sound cards can detect multiple types of connections into the 390 * audio jack - for example distinguish between line-out and headphones 391 * by measuring the impedance on the other end. In that case we want each 392 * jack to have it's own I/O node so that each can have it's own volume 393 * settings. This allows us to specify the jack used more exactly. 394 * Valid values are defined in /usr/include/linux/input.h. 395 * Args: 396 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 397 * dev - The device to check. 398 * Returns: 399 * A value >= 0 when the switch is defined, or -1 otherwise. 400 */ 401 int ucm_get_jack_switch_for_dev(struct cras_use_case_mgr *mgr, const char *dev); 402 403 /* Gets the DMA period time in microseconds for the given device. 404 * 405 * Args: 406 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 407 * dev - The device to check. 408 * Returns: 409 * A value > 0, or 0 if no period is defined. 410 */ 411 unsigned int ucm_get_dma_period_for_dev(struct cras_use_case_mgr *mgr, 412 const char *dev); 413 414 /* Gets the flag of optimization for no stream state. 415 * This flag enables no_stream ops in alsa_io. 416 * Args: 417 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 418 * Returns: 419 * 1 if the flag is enabled. 0 otherwise. 420 */ 421 unsigned int ucm_get_optimize_no_stream_flag(struct cras_use_case_mgr *mgr); 422 423 /* Retrieve the flag that enables use of htimestamp. 424 * Args: 425 * mgr - The cras_use_case_mgr pointer returned from alsa_ucm_create. 426 * Returns: 427 * 1 if the flag is enabled. 0 otherwise. 428 */ 429 unsigned int ucm_get_enable_htimestamp_flag(struct cras_use_case_mgr *mgr); 430 431 #endif /* _CRAS_ALSA_UCM_H */ 432