1 /* SPDX-License-Identifier: GPL-2.0-or-later */
2 #ifndef __SOUND_CONTROL_H
3 #define __SOUND_CONTROL_H
6 * Header file for control interface
7 * Copyright (c) by Jaroslav Kysela <perex@perex.cz>
10 #include <linux/wait.h>
11 #include <linux/nospec.h>
12 #include <sound/asound.h>
14 #define snd_kcontrol_chip(kcontrol) ((kcontrol)->private_data)
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 */
23 unsigned int __user
*tlv
);
26 SNDRV_CTL_TLV_OP_READ
= 0,
27 SNDRV_CTL_TLV_OP_WRITE
= 1,
28 SNDRV_CTL_TLV_OP_CMD
= -1,
31 struct snd_kcontrol_new
{
32 snd_ctl_elem_iface_t iface
; /* interface identifier */
33 unsigned int device
; /* device/client number */
34 unsigned int subdevice
; /* subdevice (substream) number */
35 const unsigned char *name
; /* ASCII name of item */
36 unsigned int index
; /* index of item */
37 unsigned int access
; /* access rights */
38 unsigned int count
; /* count of same elements */
39 snd_kcontrol_info_t
*info
;
40 snd_kcontrol_get_t
*get
;
41 snd_kcontrol_put_t
*put
;
43 snd_kcontrol_tlv_rw_t
*c
;
44 const unsigned int *p
;
46 unsigned long private_value
;
49 struct snd_kcontrol_volatile
{
50 struct snd_ctl_file
*owner
; /* locked */
51 unsigned int access
; /* access rights */
55 struct list_head list
; /* list of controls */
56 struct snd_ctl_elem_id id
;
57 unsigned int count
; /* count of same elements */
58 snd_kcontrol_info_t
*info
;
59 snd_kcontrol_get_t
*get
;
60 snd_kcontrol_put_t
*put
;
62 snd_kcontrol_tlv_rw_t
*c
;
63 const unsigned int *p
;
65 unsigned long private_value
;
67 void (*private_free
)(struct snd_kcontrol
*kcontrol
);
68 struct snd_kcontrol_volatile vd
[0]; /* volatile data */
71 #define snd_kcontrol(n) list_entry(n, struct snd_kcontrol, list)
73 struct snd_kctl_event
{
74 struct list_head list
; /* list of events */
75 struct snd_ctl_elem_id id
;
79 #define snd_kctl_event(n) list_entry(n, struct snd_kctl_event, list)
85 SND_CTL_SUBDEV_RAWMIDI
,
90 struct list_head list
; /* list of all control files */
91 struct snd_card
*card
;
93 int preferred_subdevice
[SND_CTL_SUBDEV_ITEMS
];
94 wait_queue_head_t change_sleep
;
96 struct fasync_struct
*fasync
;
97 int subscribed
; /* read interface is activated */
98 struct list_head events
; /* waiting events for read */
101 #define snd_ctl_file(n) list_entry(n, struct snd_ctl_file, list)
103 typedef int (*snd_kctl_ioctl_func_t
) (struct snd_card
* card
,
104 struct snd_ctl_file
* control
,
105 unsigned int cmd
, unsigned long arg
);
107 void snd_ctl_notify(struct snd_card
* card
, unsigned int mask
, struct snd_ctl_elem_id
* id
);
109 struct snd_kcontrol
*snd_ctl_new1(const struct snd_kcontrol_new
* kcontrolnew
, void * private_data
);
110 void snd_ctl_free_one(struct snd_kcontrol
* kcontrol
);
111 int snd_ctl_add(struct snd_card
* card
, struct snd_kcontrol
* kcontrol
);
112 int snd_ctl_remove(struct snd_card
* card
, struct snd_kcontrol
* kcontrol
);
113 int snd_ctl_replace(struct snd_card
*card
, struct snd_kcontrol
*kcontrol
, bool add_on_replace
);
114 int snd_ctl_remove_id(struct snd_card
* card
, struct snd_ctl_elem_id
*id
);
115 int snd_ctl_rename_id(struct snd_card
* card
, struct snd_ctl_elem_id
*src_id
, struct snd_ctl_elem_id
*dst_id
);
116 int snd_ctl_activate_id(struct snd_card
*card
, struct snd_ctl_elem_id
*id
,
118 struct snd_kcontrol
*snd_ctl_find_numid(struct snd_card
* card
, unsigned int numid
);
119 struct snd_kcontrol
*snd_ctl_find_id(struct snd_card
* card
, struct snd_ctl_elem_id
*id
);
121 int snd_ctl_create(struct snd_card
*card
);
123 int snd_ctl_register_ioctl(snd_kctl_ioctl_func_t fcn
);
124 int snd_ctl_unregister_ioctl(snd_kctl_ioctl_func_t fcn
);
126 int snd_ctl_register_ioctl_compat(snd_kctl_ioctl_func_t fcn
);
127 int snd_ctl_unregister_ioctl_compat(snd_kctl_ioctl_func_t fcn
);
129 #define snd_ctl_register_ioctl_compat(fcn)
130 #define snd_ctl_unregister_ioctl_compat(fcn)
133 int snd_ctl_get_preferred_subdevice(struct snd_card
*card
, int type
);
135 static inline unsigned int snd_ctl_get_ioffnum(struct snd_kcontrol
*kctl
, struct snd_ctl_elem_id
*id
)
137 unsigned int ioff
= id
->numid
- kctl
->id
.numid
;
138 return array_index_nospec(ioff
, kctl
->count
);
141 static inline unsigned int snd_ctl_get_ioffidx(struct snd_kcontrol
*kctl
, struct snd_ctl_elem_id
*id
)
143 unsigned int ioff
= id
->index
- kctl
->id
.index
;
144 return array_index_nospec(ioff
, kctl
->count
);
147 static inline unsigned int snd_ctl_get_ioff(struct snd_kcontrol
*kctl
, struct snd_ctl_elem_id
*id
)
150 return snd_ctl_get_ioffnum(kctl
, id
);
152 return snd_ctl_get_ioffidx(kctl
, id
);
156 static inline struct snd_ctl_elem_id
*snd_ctl_build_ioff(struct snd_ctl_elem_id
*dst_id
,
157 struct snd_kcontrol
*src_kctl
,
160 *dst_id
= src_kctl
->id
;
161 dst_id
->index
+= offset
;
162 dst_id
->numid
+= offset
;
167 * Frequently used control callbacks/helpers
169 int snd_ctl_boolean_mono_info(struct snd_kcontrol
*kcontrol
,
170 struct snd_ctl_elem_info
*uinfo
);
171 int snd_ctl_boolean_stereo_info(struct snd_kcontrol
*kcontrol
,
172 struct snd_ctl_elem_info
*uinfo
);
173 int snd_ctl_enum_info(struct snd_ctl_elem_info
*info
, unsigned int channels
,
174 unsigned int items
, const char *const names
[]);
177 * virtual master control
179 struct snd_kcontrol
*snd_ctl_make_virtual_master(char *name
,
180 const unsigned int *tlv
);
181 int _snd_ctl_add_slave(struct snd_kcontrol
*master
, struct snd_kcontrol
*slave
,
183 /* optional flags for slave */
184 #define SND_CTL_SLAVE_NEED_UPDATE (1 << 0)
187 * snd_ctl_add_slave - Add a virtual slave control
188 * @master: vmaster element
189 * @slave: slave element to add
191 * Add a virtual slave control to the given master element created via
192 * snd_ctl_create_virtual_master() beforehand.
194 * All slaves must be the same type (returning the same information
195 * via info callback). The function doesn't check it, so it's your
198 * Also, some additional limitations:
199 * at most two channels,
200 * logarithmic volume control (dB level) thus no linear volume,
201 * master can only attenuate the volume without gain
203 * Return: Zero if successful or a negative error code.
206 snd_ctl_add_slave(struct snd_kcontrol
*master
, struct snd_kcontrol
*slave
)
208 return _snd_ctl_add_slave(master
, slave
, 0);
212 * snd_ctl_add_slave_uncached - Add a virtual slave control
213 * @master: vmaster element
214 * @slave: slave element to add
216 * Add a virtual slave control to the given master.
217 * Unlike snd_ctl_add_slave(), the element added via this function
218 * is supposed to have volatile values, and get callback is called
219 * at each time queried from the master.
221 * When the control peeks the hardware values directly and the value
222 * can be changed by other means than the put callback of the element,
223 * this function should be used to keep the value always up-to-date.
225 * Return: Zero if successful or a negative error code.
228 snd_ctl_add_slave_uncached(struct snd_kcontrol
*master
,
229 struct snd_kcontrol
*slave
)
231 return _snd_ctl_add_slave(master
, slave
, SND_CTL_SLAVE_NEED_UPDATE
);
234 int snd_ctl_add_vmaster_hook(struct snd_kcontrol
*kctl
,
235 void (*hook
)(void *private_data
, int),
237 void snd_ctl_sync_vmaster(struct snd_kcontrol
*kctl
, bool hook_only
);
238 #define snd_ctl_sync_vmaster_hook(kctl) snd_ctl_sync_vmaster(kctl, true)
239 int snd_ctl_apply_vmaster_slaves(struct snd_kcontrol
*kctl
,
240 int (*func
)(struct snd_kcontrol
*vslave
,
241 struct snd_kcontrol
*slave
,
246 * Helper functions for jack-detection controls
248 struct snd_kcontrol
*
249 snd_kctl_jack_new(const char *name
, struct snd_card
*card
);
250 void snd_kctl_jack_report(struct snd_card
*card
,
251 struct snd_kcontrol
*kctl
, bool status
);
253 #endif /* __SOUND_CONTROL_H */