xref: /openbmc/linux/include/sound/control.h (revision 0e17c50f)
1 /* SPDX-License-Identifier: GPL-2.0-or-later */
2 #ifndef __SOUND_CONTROL_H
3 #define __SOUND_CONTROL_H
4 
5 /*
6  *  Header file for control interface
7  *  Copyright (c) by Jaroslav Kysela <perex@perex.cz>
8  */
9 
10 #include <linux/wait.h>
11 #include <linux/nospec.h>
12 #include <sound/asound.h>
13 
14 #define snd_kcontrol_chip(kcontrol) ((kcontrol)->private_data)
15 
16 struct snd_kcontrol;
17 typedef int (snd_kcontrol_info_t) (struct snd_kcontrol * kcontrol, struct snd_ctl_elem_info * uinfo);
18 typedef int (snd_kcontrol_get_t) (struct snd_kcontrol * kcontrol, struct snd_ctl_elem_value * ucontrol);
19 typedef int (snd_kcontrol_put_t) (struct snd_kcontrol * kcontrol, struct snd_ctl_elem_value * ucontrol);
20 typedef int (snd_kcontrol_tlv_rw_t)(struct snd_kcontrol *kcontrol,
21 				    int op_flag, /* SNDRV_CTL_TLV_OP_XXX */
22 				    unsigned int size,
23 				    unsigned int __user *tlv);
24 
25 /* internal flag for skipping validations */
26 #ifdef CONFIG_SND_CTL_VALIDATION
27 #define SNDRV_CTL_ELEM_ACCESS_SKIP_CHECK	(1 << 27)
28 #define snd_ctl_skip_validation(info) \
29 	((info)->access & SNDRV_CTL_ELEM_ACCESS_SKIP_CHECK)
30 #else
31 #define SNDRV_CTL_ELEM_ACCESS_SKIP_CHECK	0
32 #define snd_ctl_skip_validation(info)		true
33 #endif
34 
35 enum {
36 	SNDRV_CTL_TLV_OP_READ = 0,
37 	SNDRV_CTL_TLV_OP_WRITE = 1,
38 	SNDRV_CTL_TLV_OP_CMD = -1,
39 };
40 
41 struct snd_kcontrol_new {
42 	snd_ctl_elem_iface_t iface;	/* interface identifier */
43 	unsigned int device;		/* device/client number */
44 	unsigned int subdevice;		/* subdevice (substream) number */
45 	const unsigned char *name;	/* ASCII name of item */
46 	unsigned int index;		/* index of item */
47 	unsigned int access;		/* access rights */
48 	unsigned int count;		/* count of same elements */
49 	snd_kcontrol_info_t *info;
50 	snd_kcontrol_get_t *get;
51 	snd_kcontrol_put_t *put;
52 	union {
53 		snd_kcontrol_tlv_rw_t *c;
54 		const unsigned int *p;
55 	} tlv;
56 	unsigned long private_value;
57 };
58 
59 struct snd_kcontrol_volatile {
60 	struct snd_ctl_file *owner;	/* locked */
61 	unsigned int access;	/* access rights */
62 };
63 
64 struct snd_kcontrol {
65 	struct list_head list;		/* list of controls */
66 	struct snd_ctl_elem_id id;
67 	unsigned int count;		/* count of same elements */
68 	snd_kcontrol_info_t *info;
69 	snd_kcontrol_get_t *get;
70 	snd_kcontrol_put_t *put;
71 	union {
72 		snd_kcontrol_tlv_rw_t *c;
73 		const unsigned int *p;
74 	} tlv;
75 	unsigned long private_value;
76 	void *private_data;
77 	void (*private_free)(struct snd_kcontrol *kcontrol);
78 	struct snd_kcontrol_volatile vd[0];	/* volatile data */
79 };
80 
81 #define snd_kcontrol(n) list_entry(n, struct snd_kcontrol, list)
82 
83 struct snd_kctl_event {
84 	struct list_head list;	/* list of events */
85 	struct snd_ctl_elem_id id;
86 	unsigned int mask;
87 };
88 
89 #define snd_kctl_event(n) list_entry(n, struct snd_kctl_event, list)
90 
91 struct pid;
92 
93 enum {
94 	SND_CTL_SUBDEV_PCM,
95 	SND_CTL_SUBDEV_RAWMIDI,
96 	SND_CTL_SUBDEV_ITEMS,
97 };
98 
99 struct snd_ctl_file {
100 	struct list_head list;		/* list of all control files */
101 	struct snd_card *card;
102 	struct pid *pid;
103 	int preferred_subdevice[SND_CTL_SUBDEV_ITEMS];
104 	wait_queue_head_t change_sleep;
105 	spinlock_t read_lock;
106 	struct fasync_struct *fasync;
107 	int subscribed;			/* read interface is activated */
108 	struct list_head events;	/* waiting events for read */
109 };
110 
111 #define snd_ctl_file(n) list_entry(n, struct snd_ctl_file, list)
112 
113 typedef int (*snd_kctl_ioctl_func_t) (struct snd_card * card,
114 				      struct snd_ctl_file * control,
115 				      unsigned int cmd, unsigned long arg);
116 
117 void snd_ctl_notify(struct snd_card * card, unsigned int mask, struct snd_ctl_elem_id * id);
118 
119 struct snd_kcontrol *snd_ctl_new1(const struct snd_kcontrol_new * kcontrolnew, void * private_data);
120 void snd_ctl_free_one(struct snd_kcontrol * kcontrol);
121 int snd_ctl_add(struct snd_card * card, struct snd_kcontrol * kcontrol);
122 int snd_ctl_remove(struct snd_card * card, struct snd_kcontrol * kcontrol);
123 int snd_ctl_replace(struct snd_card *card, struct snd_kcontrol *kcontrol, bool add_on_replace);
124 int snd_ctl_remove_id(struct snd_card * card, struct snd_ctl_elem_id *id);
125 int snd_ctl_rename_id(struct snd_card * card, struct snd_ctl_elem_id *src_id, struct snd_ctl_elem_id *dst_id);
126 int snd_ctl_activate_id(struct snd_card *card, struct snd_ctl_elem_id *id,
127 			int active);
128 struct snd_kcontrol *snd_ctl_find_numid(struct snd_card * card, unsigned int numid);
129 struct snd_kcontrol *snd_ctl_find_id(struct snd_card * card, struct snd_ctl_elem_id *id);
130 
131 int snd_ctl_create(struct snd_card *card);
132 
133 int snd_ctl_register_ioctl(snd_kctl_ioctl_func_t fcn);
134 int snd_ctl_unregister_ioctl(snd_kctl_ioctl_func_t fcn);
135 #ifdef CONFIG_COMPAT
136 int snd_ctl_register_ioctl_compat(snd_kctl_ioctl_func_t fcn);
137 int snd_ctl_unregister_ioctl_compat(snd_kctl_ioctl_func_t fcn);
138 #else
139 #define snd_ctl_register_ioctl_compat(fcn)
140 #define snd_ctl_unregister_ioctl_compat(fcn)
141 #endif
142 
143 int snd_ctl_get_preferred_subdevice(struct snd_card *card, int type);
144 
145 static inline unsigned int snd_ctl_get_ioffnum(struct snd_kcontrol *kctl, struct snd_ctl_elem_id *id)
146 {
147 	unsigned int ioff = id->numid - kctl->id.numid;
148 	return array_index_nospec(ioff, kctl->count);
149 }
150 
151 static inline unsigned int snd_ctl_get_ioffidx(struct snd_kcontrol *kctl, struct snd_ctl_elem_id *id)
152 {
153 	unsigned int ioff = id->index - kctl->id.index;
154 	return array_index_nospec(ioff, kctl->count);
155 }
156 
157 static inline unsigned int snd_ctl_get_ioff(struct snd_kcontrol *kctl, struct snd_ctl_elem_id *id)
158 {
159 	if (id->numid) {
160 		return snd_ctl_get_ioffnum(kctl, id);
161 	} else {
162 		return snd_ctl_get_ioffidx(kctl, id);
163 	}
164 }
165 
166 static inline struct snd_ctl_elem_id *snd_ctl_build_ioff(struct snd_ctl_elem_id *dst_id,
167 						    struct snd_kcontrol *src_kctl,
168 						    unsigned int offset)
169 {
170 	*dst_id = src_kctl->id;
171 	dst_id->index += offset;
172 	dst_id->numid += offset;
173 	return dst_id;
174 }
175 
176 /*
177  * Frequently used control callbacks/helpers
178  */
179 int snd_ctl_boolean_mono_info(struct snd_kcontrol *kcontrol,
180 			      struct snd_ctl_elem_info *uinfo);
181 int snd_ctl_boolean_stereo_info(struct snd_kcontrol *kcontrol,
182 				struct snd_ctl_elem_info *uinfo);
183 int snd_ctl_enum_info(struct snd_ctl_elem_info *info, unsigned int channels,
184 		      unsigned int items, const char *const names[]);
185 
186 /*
187  * virtual master control
188  */
189 struct snd_kcontrol *snd_ctl_make_virtual_master(char *name,
190 						 const unsigned int *tlv);
191 int _snd_ctl_add_slave(struct snd_kcontrol *master, struct snd_kcontrol *slave,
192 		       unsigned int flags);
193 /* optional flags for slave */
194 #define SND_CTL_SLAVE_NEED_UPDATE	(1 << 0)
195 
196 /**
197  * snd_ctl_add_slave - Add a virtual slave control
198  * @master: vmaster element
199  * @slave: slave element to add
200  *
201  * Add a virtual slave control to the given master element created via
202  * snd_ctl_create_virtual_master() beforehand.
203  *
204  * All slaves must be the same type (returning the same information
205  * via info callback).  The function doesn't check it, so it's your
206  * responsibility.
207  *
208  * Also, some additional limitations:
209  * at most two channels,
210  * logarithmic volume control (dB level) thus no linear volume,
211  * master can only attenuate the volume without gain
212  *
213  * Return: Zero if successful or a negative error code.
214  */
215 static inline int
216 snd_ctl_add_slave(struct snd_kcontrol *master, struct snd_kcontrol *slave)
217 {
218 	return _snd_ctl_add_slave(master, slave, 0);
219 }
220 
221 /**
222  * snd_ctl_add_slave_uncached - Add a virtual slave control
223  * @master: vmaster element
224  * @slave: slave element to add
225  *
226  * Add a virtual slave control to the given master.
227  * Unlike snd_ctl_add_slave(), the element added via this function
228  * is supposed to have volatile values, and get callback is called
229  * at each time queried from the master.
230  *
231  * When the control peeks the hardware values directly and the value
232  * can be changed by other means than the put callback of the element,
233  * this function should be used to keep the value always up-to-date.
234  *
235  * Return: Zero if successful or a negative error code.
236  */
237 static inline int
238 snd_ctl_add_slave_uncached(struct snd_kcontrol *master,
239 			   struct snd_kcontrol *slave)
240 {
241 	return _snd_ctl_add_slave(master, slave, SND_CTL_SLAVE_NEED_UPDATE);
242 }
243 
244 int snd_ctl_add_vmaster_hook(struct snd_kcontrol *kctl,
245 			     void (*hook)(void *private_data, int),
246 			     void *private_data);
247 void snd_ctl_sync_vmaster(struct snd_kcontrol *kctl, bool hook_only);
248 #define snd_ctl_sync_vmaster_hook(kctl)	snd_ctl_sync_vmaster(kctl, true)
249 int snd_ctl_apply_vmaster_slaves(struct snd_kcontrol *kctl,
250 				 int (*func)(struct snd_kcontrol *vslave,
251 					     struct snd_kcontrol *slave,
252 					     void *arg),
253 				 void *arg);
254 
255 /*
256  * Helper functions for jack-detection controls
257  */
258 struct snd_kcontrol *
259 snd_kctl_jack_new(const char *name, struct snd_card *card);
260 void snd_kctl_jack_report(struct snd_card *card,
261 			  struct snd_kcontrol *kctl, bool status);
262 
263 #endif	/* __SOUND_CONTROL_H */
264