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[]; /* 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_follower(struct snd_kcontrol *master, 192 struct snd_kcontrol *follower, 193 unsigned int flags); 194 /* optional flags for follower */ 195 #define SND_CTL_FOLLOWER_NEED_UPDATE (1 << 0) 196 197 /** 198 * snd_ctl_add_follower - Add a virtual follower control 199 * @master: vmaster element 200 * @follower: follower element to add 201 * 202 * Add a virtual follower control to the given master element created via 203 * snd_ctl_create_virtual_master() beforehand. 204 * 205 * All followers must be the same type (returning the same information 206 * via info callback). The function doesn't check it, so it's your 207 * responsibility. 208 * 209 * Also, some additional limitations: 210 * at most two channels, 211 * logarithmic volume control (dB level) thus no linear volume, 212 * master can only attenuate the volume without gain 213 * 214 * Return: Zero if successful or a negative error code. 215 */ 216 static inline int 217 snd_ctl_add_follower(struct snd_kcontrol *master, struct snd_kcontrol *follower) 218 { 219 return _snd_ctl_add_follower(master, follower, 0); 220 } 221 222 /** 223 * snd_ctl_add_follower_uncached - Add a virtual follower control 224 * @master: vmaster element 225 * @follower: follower element to add 226 * 227 * Add a virtual follower control to the given master. 228 * Unlike snd_ctl_add_follower(), the element added via this function 229 * is supposed to have volatile values, and get callback is called 230 * at each time queried from the master. 231 * 232 * When the control peeks the hardware values directly and the value 233 * can be changed by other means than the put callback of the element, 234 * this function should be used to keep the value always up-to-date. 235 * 236 * Return: Zero if successful or a negative error code. 237 */ 238 static inline int 239 snd_ctl_add_follower_uncached(struct snd_kcontrol *master, 240 struct snd_kcontrol *follower) 241 { 242 return _snd_ctl_add_follower(master, follower, SND_CTL_FOLLOWER_NEED_UPDATE); 243 } 244 245 int snd_ctl_add_vmaster_hook(struct snd_kcontrol *kctl, 246 void (*hook)(void *private_data, int), 247 void *private_data); 248 void snd_ctl_sync_vmaster(struct snd_kcontrol *kctl, bool hook_only); 249 #define snd_ctl_sync_vmaster_hook(kctl) snd_ctl_sync_vmaster(kctl, true) 250 int snd_ctl_apply_vmaster_followers(struct snd_kcontrol *kctl, 251 int (*func)(struct snd_kcontrol *vfollower, 252 struct snd_kcontrol *follower, 253 void *arg), 254 void *arg); 255 256 /* 257 * Helper functions for jack-detection controls 258 */ 259 struct snd_kcontrol * 260 snd_kctl_jack_new(const char *name, struct snd_card *card); 261 void snd_kctl_jack_report(struct snd_card *card, 262 struct snd_kcontrol *kctl, bool status); 263 264 #endif /* __SOUND_CONTROL_H */ 265