1 // SPDX-License-Identifier: GPL-2.0-only 2 /* 3 * Virtual master and follower controls 4 * 5 * Copyright (c) 2008 by Takashi Iwai <tiwai@suse.de> 6 */ 7 8 #include <linux/slab.h> 9 #include <linux/export.h> 10 #include <sound/core.h> 11 #include <sound/control.h> 12 #include <sound/tlv.h> 13 14 /* 15 * a subset of information returned via ctl info callback 16 */ 17 struct link_ctl_info { 18 snd_ctl_elem_type_t type; /* value type */ 19 int count; /* item count */ 20 int min_val, max_val; /* min, max values */ 21 }; 22 23 /* 24 * link master - this contains a list of follower controls that are 25 * identical types, i.e. info returns the same value type and value 26 * ranges, but may have different number of counts. 27 * 28 * The master control is so far only mono volume/switch for simplicity. 29 * The same value will be applied to all followers. 30 */ 31 struct link_master { 32 struct list_head followers; 33 struct link_ctl_info info; 34 int val; /* the master value */ 35 unsigned int tlv[4]; 36 void (*hook)(void *private_data, int); 37 void *hook_private_data; 38 }; 39 40 /* 41 * link follower - this contains a follower control element 42 * 43 * It fakes the control callbacks with additional attenuation by the 44 * master control. A follower may have either one or two channels. 45 */ 46 47 struct link_follower { 48 struct list_head list; 49 struct link_master *master; 50 struct link_ctl_info info; 51 int vals[2]; /* current values */ 52 unsigned int flags; 53 struct snd_kcontrol *kctl; /* original kcontrol pointer */ 54 struct snd_kcontrol follower; /* the copy of original control entry */ 55 }; 56 57 static int follower_update(struct link_follower *follower) 58 { 59 int err, ch; 60 struct snd_ctl_elem_value *uctl __free(kfree) = 61 kzalloc_obj(*uctl); 62 63 if (!uctl) 64 return -ENOMEM; 65 uctl->id = follower->follower.id; 66 err = follower->follower.get(&follower->follower, uctl); 67 if (err < 0) 68 return err; 69 for (ch = 0; ch < follower->info.count; ch++) 70 follower->vals[ch] = uctl->value.integer.value[ch]; 71 return 0; 72 } 73 74 /* get the follower ctl info and save the initial values */ 75 static int follower_init(struct link_follower *follower) 76 { 77 int err; 78 79 if (follower->info.count) { 80 /* already initialized */ 81 if (follower->flags & SND_CTL_FOLLOWER_NEED_UPDATE) 82 return follower_update(follower); 83 return 0; 84 } 85 86 struct snd_ctl_elem_info *uinfo __free(kfree) = 87 kmalloc_obj(*uinfo); 88 if (!uinfo) 89 return -ENOMEM; 90 uinfo->id = follower->follower.id; 91 err = follower->follower.info(&follower->follower, uinfo); 92 if (err < 0) 93 return err; 94 follower->info.type = uinfo->type; 95 follower->info.count = uinfo->count; 96 if (follower->info.count > 2 || 97 (follower->info.type != SNDRV_CTL_ELEM_TYPE_INTEGER && 98 follower->info.type != SNDRV_CTL_ELEM_TYPE_BOOLEAN)) { 99 pr_err("ALSA: vmaster: invalid follower element\n"); 100 return -EINVAL; 101 } 102 follower->info.min_val = uinfo->value.integer.min; 103 follower->info.max_val = uinfo->value.integer.max; 104 105 return follower_update(follower); 106 } 107 108 /* initialize master volume */ 109 static int master_init(struct link_master *master) 110 { 111 struct link_follower *follower; 112 113 if (master->info.count) 114 return 0; /* already initialized */ 115 116 list_for_each_entry(follower, &master->followers, list) { 117 int err = follower_init(follower); 118 if (err < 0) 119 return err; 120 master->info = follower->info; 121 master->info.count = 1; /* always mono */ 122 /* set full volume as default (= no attenuation) */ 123 master->val = master->info.max_val; 124 if (master->hook) 125 master->hook(master->hook_private_data, master->val); 126 return 1; 127 } 128 return -ENOENT; 129 } 130 131 static int follower_get_val(struct link_follower *follower, 132 struct snd_ctl_elem_value *ucontrol) 133 { 134 int err, ch; 135 136 err = follower_init(follower); 137 if (err < 0) 138 return err; 139 for (ch = 0; ch < follower->info.count; ch++) 140 ucontrol->value.integer.value[ch] = follower->vals[ch]; 141 return 0; 142 } 143 144 static int follower_put_val(struct link_follower *follower, 145 struct snd_ctl_elem_value *ucontrol) 146 { 147 int err, ch, vol; 148 149 err = master_init(follower->master); 150 if (err < 0) 151 return err; 152 153 switch (follower->info.type) { 154 case SNDRV_CTL_ELEM_TYPE_BOOLEAN: 155 for (ch = 0; ch < follower->info.count; ch++) 156 ucontrol->value.integer.value[ch] &= 157 !!follower->master->val; 158 break; 159 case SNDRV_CTL_ELEM_TYPE_INTEGER: 160 for (ch = 0; ch < follower->info.count; ch++) { 161 /* max master volume is supposed to be 0 dB */ 162 vol = ucontrol->value.integer.value[ch]; 163 vol += follower->master->val - follower->master->info.max_val; 164 if (vol < follower->info.min_val) 165 vol = follower->info.min_val; 166 else if (vol > follower->info.max_val) 167 vol = follower->info.max_val; 168 ucontrol->value.integer.value[ch] = vol; 169 } 170 break; 171 } 172 return follower->follower.put(&follower->follower, ucontrol); 173 } 174 175 /* 176 * ctl callbacks for followers 177 */ 178 static int follower_info(struct snd_kcontrol *kcontrol, 179 struct snd_ctl_elem_info *uinfo) 180 { 181 struct link_follower *follower = snd_kcontrol_chip(kcontrol); 182 return follower->follower.info(&follower->follower, uinfo); 183 } 184 185 static int follower_get(struct snd_kcontrol *kcontrol, 186 struct snd_ctl_elem_value *ucontrol) 187 { 188 struct link_follower *follower = snd_kcontrol_chip(kcontrol); 189 return follower_get_val(follower, ucontrol); 190 } 191 192 static int follower_put(struct snd_kcontrol *kcontrol, 193 struct snd_ctl_elem_value *ucontrol) 194 { 195 struct link_follower *follower = snd_kcontrol_chip(kcontrol); 196 int err, ch, changed = 0; 197 198 err = follower_init(follower); 199 if (err < 0) 200 return err; 201 for (ch = 0; ch < follower->info.count; ch++) { 202 if (ucontrol->value.integer.value[ch] < follower->info.min_val || 203 ucontrol->value.integer.value[ch] > follower->info.max_val) 204 return -EINVAL; 205 } 206 207 for (ch = 0; ch < follower->info.count; ch++) { 208 if (follower->vals[ch] != ucontrol->value.integer.value[ch]) { 209 changed = 1; 210 follower->vals[ch] = ucontrol->value.integer.value[ch]; 211 } 212 } 213 if (!changed) 214 return 0; 215 err = follower_put_val(follower, ucontrol); 216 if (err < 0) 217 return err; 218 return 1; 219 } 220 221 static int follower_tlv_cmd(struct snd_kcontrol *kcontrol, 222 int op_flag, unsigned int size, 223 unsigned int __user *tlv) 224 { 225 struct link_follower *follower = snd_kcontrol_chip(kcontrol); 226 /* FIXME: this assumes that the max volume is 0 dB */ 227 return follower->follower.tlv.c(&follower->follower, op_flag, size, tlv); 228 } 229 230 static void follower_free(struct snd_kcontrol *kcontrol) 231 { 232 struct link_follower *follower = snd_kcontrol_chip(kcontrol); 233 if (follower->follower.private_free) 234 follower->follower.private_free(&follower->follower); 235 if (follower->master) 236 list_del(&follower->list); 237 kfree(follower); 238 } 239 240 /* 241 * Add a follower control to the group with the given master control 242 * 243 * All followers must be the same type (returning the same information 244 * via info callback). The function doesn't check it, so it's your 245 * responsibility. 246 * 247 * Also, some additional limitations: 248 * - at most two channels 249 * - logarithmic volume control (dB level), no linear volume 250 * - master can only attenuate the volume, no gain 251 */ 252 int _snd_ctl_add_follower(struct snd_kcontrol *master, 253 struct snd_kcontrol *follower, 254 unsigned int flags) 255 { 256 struct link_master *master_link = snd_kcontrol_chip(master); 257 struct link_follower *srec; 258 259 srec = kzalloc_flex(*srec, follower.vd, follower->count); 260 if (!srec) 261 return -ENOMEM; 262 srec->kctl = follower; 263 srec->follower = *follower; 264 memcpy(srec->follower.vd, follower->vd, follower->count * sizeof(*follower->vd)); 265 srec->master = master_link; 266 srec->flags = flags; 267 268 /* override callbacks */ 269 follower->info = follower_info; 270 follower->get = follower_get; 271 follower->put = follower_put; 272 if (follower->vd[0].access & SNDRV_CTL_ELEM_ACCESS_TLV_CALLBACK) 273 follower->tlv.c = follower_tlv_cmd; 274 follower->private_data = srec; 275 follower->private_free = follower_free; 276 277 list_add_tail(&srec->list, &master_link->followers); 278 return 0; 279 } 280 EXPORT_SYMBOL(_snd_ctl_add_follower); 281 282 /** 283 * snd_ctl_add_followers - add multiple followers to vmaster 284 * @card: card instance 285 * @master: the target vmaster kcontrol object 286 * @list: NULL-terminated list of name strings of followers to be added 287 * 288 * Adds the multiple follower kcontrols with the given names. 289 * Returns 0 for success or a negative error code. 290 * 291 * Note that this function takes card->controls_rwsem lock internally. 292 */ 293 int snd_ctl_add_followers(struct snd_card *card, struct snd_kcontrol *master, 294 const char * const *list) 295 { 296 struct snd_kcontrol *follower; 297 int err; 298 299 guard(rwsem_write)(&card->controls_rwsem); 300 for (; *list; list++) { 301 follower = snd_ctl_find_id_mixer(card, *list); 302 if (follower) { 303 err = snd_ctl_add_follower(master, follower); 304 if (err < 0) 305 return err; 306 } 307 } 308 309 return 0; 310 } 311 EXPORT_SYMBOL_GPL(snd_ctl_add_followers); 312 313 /* 314 * ctl callbacks for master controls 315 */ 316 static int master_info(struct snd_kcontrol *kcontrol, 317 struct snd_ctl_elem_info *uinfo) 318 { 319 struct link_master *master = snd_kcontrol_chip(kcontrol); 320 int ret; 321 322 ret = master_init(master); 323 if (ret < 0) 324 return ret; 325 uinfo->type = master->info.type; 326 uinfo->count = master->info.count; 327 uinfo->value.integer.min = master->info.min_val; 328 uinfo->value.integer.max = master->info.max_val; 329 return 0; 330 } 331 332 static int master_get(struct snd_kcontrol *kcontrol, 333 struct snd_ctl_elem_value *ucontrol) 334 { 335 struct link_master *master = snd_kcontrol_chip(kcontrol); 336 int err = master_init(master); 337 if (err < 0) 338 return err; 339 ucontrol->value.integer.value[0] = master->val; 340 return 0; 341 } 342 343 static int sync_followers(struct link_master *master, int old_val, int new_val) 344 { 345 struct link_follower *follower; 346 struct snd_ctl_elem_value *uval __free(kfree) = 347 kmalloc_obj(*uval); 348 349 if (!uval) 350 return -ENOMEM; 351 list_for_each_entry(follower, &master->followers, list) { 352 master->val = old_val; 353 uval->id = follower->follower.id; 354 follower_get_val(follower, uval); 355 master->val = new_val; 356 follower_put_val(follower, uval); 357 } 358 return 0; 359 } 360 361 static int master_put(struct snd_kcontrol *kcontrol, 362 struct snd_ctl_elem_value *ucontrol) 363 { 364 struct link_master *master = snd_kcontrol_chip(kcontrol); 365 int err, new_val, old_val; 366 bool first_init; 367 368 err = master_init(master); 369 if (err < 0) 370 return err; 371 first_init = err; 372 old_val = master->val; 373 new_val = ucontrol->value.integer.value[0]; 374 if (new_val == old_val) 375 return 0; 376 if (new_val < master->info.min_val || new_val > master->info.max_val) 377 return -EINVAL; 378 379 err = sync_followers(master, old_val, new_val); 380 if (err < 0) 381 return err; 382 if (master->hook && !first_init) 383 master->hook(master->hook_private_data, master->val); 384 return 1; 385 } 386 387 static void master_free(struct snd_kcontrol *kcontrol) 388 { 389 struct link_master *master = snd_kcontrol_chip(kcontrol); 390 struct link_follower *follower, *n; 391 392 /* free all follower links and retore the original follower kctls */ 393 list_for_each_entry_safe(follower, n, &master->followers, list) { 394 struct snd_kcontrol *sctl = follower->kctl; 395 struct list_head olist = sctl->list; 396 memcpy(sctl, &follower->follower, sizeof(*sctl)); 397 memcpy(sctl->vd, follower->follower.vd, 398 sctl->count * sizeof(*sctl->vd)); 399 sctl->list = olist; /* keep the current linked-list */ 400 kfree(follower); 401 } 402 kfree(master); 403 } 404 405 406 /** 407 * snd_ctl_make_virtual_master - Create a virtual master control 408 * @name: name string of the control element to create 409 * @tlv: optional TLV int array for dB information 410 * 411 * Creates a virtual master control with the given name string. 412 * 413 * After creating a vmaster element, you can add the follower controls 414 * via snd_ctl_add_follower() or snd_ctl_add_follower_uncached(). 415 * 416 * The optional argument @tlv can be used to specify the TLV information 417 * for dB scale of the master control. It should be a single element 418 * with #SNDRV_CTL_TLVT_DB_SCALE, #SNDRV_CTL_TLV_DB_MINMAX or 419 * #SNDRV_CTL_TLVT_DB_MINMAX_MUTE type, and should be the max 0dB. 420 * 421 * Return: The created control element, or %NULL for errors (ENOMEM). 422 */ 423 struct snd_kcontrol *snd_ctl_make_virtual_master(char *name, 424 const unsigned int *tlv) 425 { 426 struct link_master *master; 427 struct snd_kcontrol *kctl; 428 struct snd_kcontrol_new knew; 429 430 memset(&knew, 0, sizeof(knew)); 431 knew.iface = SNDRV_CTL_ELEM_IFACE_MIXER; 432 knew.name = name; 433 knew.info = master_info; 434 435 master = kzalloc_obj(*master); 436 if (!master) 437 return NULL; 438 INIT_LIST_HEAD(&master->followers); 439 440 kctl = snd_ctl_new1(&knew, master); 441 if (!kctl) { 442 kfree(master); 443 return NULL; 444 } 445 /* override some callbacks */ 446 kctl->info = master_info; 447 kctl->get = master_get; 448 kctl->put = master_put; 449 kctl->private_free = master_free; 450 451 /* additional (constant) TLV read */ 452 if (tlv) { 453 unsigned int type = tlv[SNDRV_CTL_TLVO_TYPE]; 454 if (type == SNDRV_CTL_TLVT_DB_SCALE || 455 type == SNDRV_CTL_TLVT_DB_MINMAX || 456 type == SNDRV_CTL_TLVT_DB_MINMAX_MUTE) { 457 kctl->vd[0].access |= SNDRV_CTL_ELEM_ACCESS_TLV_READ; 458 memcpy(master->tlv, tlv, sizeof(master->tlv)); 459 kctl->tlv.p = master->tlv; 460 } 461 } 462 463 return kctl; 464 } 465 EXPORT_SYMBOL(snd_ctl_make_virtual_master); 466 467 /** 468 * snd_ctl_add_vmaster_hook - Add a hook to a vmaster control 469 * @card: the card instance 470 * @kcontrol: vmaster kctl element 471 * @hook: the hook function 472 * @private_data: the private_data pointer to be saved 473 * 474 * Adds the given hook to the vmaster control element so that it's called 475 * at each time when the value is changed. 476 * 477 * Takes the card's controls_rwsem lock internally. 478 * 479 * Return: Zero. 480 */ 481 int snd_ctl_add_vmaster_hook(struct snd_card *card, struct snd_kcontrol *kcontrol, 482 void (*hook)(void *private_data, int), 483 void *private_data) 484 { 485 struct link_master *master = snd_kcontrol_chip(kcontrol); 486 487 guard(rwsem_write)(&card->controls_rwsem); 488 master->hook = hook; 489 master->hook_private_data = private_data; 490 return 0; 491 } 492 EXPORT_SYMBOL_GPL(snd_ctl_add_vmaster_hook); 493 494 /** 495 * snd_ctl_sync_vmaster - Sync the vmaster followers and hook 496 * @kcontrol: vmaster kctl element 497 * @hook_only: sync only the hook 498 * 499 * Forcibly call the put callback of each follower and call the hook function 500 * to synchronize with the current value of the given vmaster element. 501 * NOP when NULL is passed to @kcontrol. 502 */ 503 void snd_ctl_sync_vmaster(struct snd_kcontrol *kcontrol, bool hook_only) 504 { 505 struct link_master *master; 506 bool first_init = false; 507 508 if (!kcontrol) 509 return; 510 master = snd_kcontrol_chip(kcontrol); 511 if (!hook_only) { 512 int err = master_init(master); 513 if (err < 0) 514 return; 515 first_init = err; 516 err = sync_followers(master, master->val, master->val); 517 if (err < 0) 518 return; 519 } 520 521 if (master->hook && !first_init) 522 master->hook(master->hook_private_data, master->val); 523 } 524 EXPORT_SYMBOL_GPL(snd_ctl_sync_vmaster); 525 526 /** 527 * snd_ctl_apply_vmaster_followers - Apply function to each vmaster follower 528 * @kctl: vmaster kctl element 529 * @func: function to apply 530 * @arg: optional function argument 531 * 532 * Apply the function @func to each follower kctl of the given vmaster kctl. 533 * 534 * Return: 0 if successful, or a negative error code 535 */ 536 int snd_ctl_apply_vmaster_followers(struct snd_kcontrol *kctl, 537 int (*func)(struct snd_kcontrol *vfollower, 538 struct snd_kcontrol *follower, 539 void *arg), 540 void *arg) 541 { 542 struct link_master *master; 543 struct link_follower *follower; 544 int err; 545 546 master = snd_kcontrol_chip(kctl); 547 err = master_init(master); 548 if (err < 0) 549 return err; 550 list_for_each_entry(follower, &master->followers, list) { 551 err = func(follower->kctl, &follower->follower, arg); 552 if (err < 0) 553 return err; 554 } 555 556 return 0; 557 } 558 EXPORT_SYMBOL_GPL(snd_ctl_apply_vmaster_followers); 559