xref: /linux/sound/core/vmaster.c (revision db2db2dec96e24d067cc5692ac5eec35830ee8d9)
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