Branch data     Line data    Source code

       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                 :            : enum {
      26                 :            :         SNDRV_CTL_TLV_OP_READ = 0,
      27                 :            :         SNDRV_CTL_TLV_OP_WRITE = 1,
      28                 :            :         SNDRV_CTL_TLV_OP_CMD = -1,
      29                 :            : };
      30                 :            : 
      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;
      42                 :            :         union {
      43                 :            :                 snd_kcontrol_tlv_rw_t *c;
      44                 :            :                 const unsigned int *p;
      45                 :            :         } tlv;
      46                 :            :         unsigned long private_value;
      47                 :            : };
      48                 :            : 
      49                 :            : struct snd_kcontrol_volatile {
      50                 :            :         struct snd_ctl_file *owner;     /* locked */
      51                 :            :         unsigned int access;    /* access rights */
      52                 :            : };
      53                 :            : 
      54                 :            : struct snd_kcontrol {
      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;
      61                 :            :         union {
      62                 :            :                 snd_kcontrol_tlv_rw_t *c;
      63                 :            :                 const unsigned int *p;
      64                 :            :         } tlv;
      65                 :            :         unsigned long private_value;
      66                 :            :         void *private_data;
      67                 :            :         void (*private_free)(struct snd_kcontrol *kcontrol);
      68                 :            :         struct snd_kcontrol_volatile vd[0];     /* volatile data */
      69                 :            : };
      70                 :            : 
      71                 :            : #define snd_kcontrol(n) list_entry(n, struct snd_kcontrol, list)
      72                 :            : 
      73                 :            : struct snd_kctl_event {
      74                 :            :         struct list_head list;  /* list of events */
      75                 :            :         struct snd_ctl_elem_id id;
      76                 :            :         unsigned int mask;
      77                 :            : };
      78                 :            : 
      79                 :            : #define snd_kctl_event(n) list_entry(n, struct snd_kctl_event, list)
      80                 :            : 
      81                 :            : struct pid;
      82                 :            : 
      83                 :            : enum {
      84                 :            :         SND_CTL_SUBDEV_PCM,
      85                 :            :         SND_CTL_SUBDEV_RAWMIDI,
      86                 :            :         SND_CTL_SUBDEV_ITEMS,
      87                 :            : };
      88                 :            : 
      89                 :            : struct snd_ctl_file {
      90                 :            :         struct list_head list;          /* list of all control files */
      91                 :            :         struct snd_card *card;
      92                 :            :         struct pid *pid;
      93                 :            :         int preferred_subdevice[SND_CTL_SUBDEV_ITEMS];
      94                 :            :         wait_queue_head_t change_sleep;
      95                 :            :         spinlock_t read_lock;
      96                 :            :         struct fasync_struct *fasync;
      97                 :            :         int subscribed;                 /* read interface is activated */
      98                 :            :         struct list_head events;        /* waiting events for read */
      99                 :            : };
     100                 :            : 
     101                 :            : #define snd_ctl_file(n) list_entry(n, struct snd_ctl_file, list)
     102                 :            : 
     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);
     106                 :            : 
     107                 :            : void snd_ctl_notify(struct snd_card * card, unsigned int mask, struct snd_ctl_elem_id * id);
     108                 :            : 
     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,
     117                 :            :                         int active);
     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);
     120                 :            : 
     121                 :            : int snd_ctl_create(struct snd_card *card);
     122                 :            : 
     123                 :            : int snd_ctl_register_ioctl(snd_kctl_ioctl_func_t fcn);
     124                 :            : int snd_ctl_unregister_ioctl(snd_kctl_ioctl_func_t fcn);
     125                 :            : #ifdef CONFIG_COMPAT
     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);
     128                 :            : #else
     129                 :            : #define snd_ctl_register_ioctl_compat(fcn)
     130                 :            : #define snd_ctl_unregister_ioctl_compat(fcn)
     131                 :            : #endif
     132                 :            : 
     133                 :            : int snd_ctl_get_preferred_subdevice(struct snd_card *card, int type);
     134                 :            : 
     135                 :            : static inline unsigned int snd_ctl_get_ioffnum(struct snd_kcontrol *kctl, struct snd_ctl_elem_id *id)
     136                 :            : {
     137                 :          3 :         unsigned int ioff = id->numid - kctl->id.numid;
     138                 :          3 :         return array_index_nospec(ioff, kctl->count);
     139                 :            : }
     140                 :            : 
     141                 :            : static inline unsigned int snd_ctl_get_ioffidx(struct snd_kcontrol *kctl, struct snd_ctl_elem_id *id)
     142                 :            : {
     143                 :          3 :         unsigned int ioff = id->index - kctl->id.index;
     144                 :          3 :         return array_index_nospec(ioff, kctl->count);
     145                 :            : }
     146                 :            : 
     147                 :            : static inline unsigned int snd_ctl_get_ioff(struct snd_kcontrol *kctl, struct snd_ctl_elem_id *id)
     148                 :            : {
     149                 :          3 :         if (id->numid) {
     150                 :            :                 return snd_ctl_get_ioffnum(kctl, id);
     151                 :            :         } else {
     152                 :            :                 return snd_ctl_get_ioffidx(kctl, id);
     153                 :            :         }
     154                 :            : }
     155                 :            : 
     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,
     158                 :            :                                                     unsigned int offset)
     159                 :            : {
     160                 :          3 :         *dst_id = src_kctl->id;
     161                 :          3 :         dst_id->index += offset;
     162                 :          3 :         dst_id->numid += offset;
     163                 :            :         return dst_id;
     164                 :            : }
     165                 :            : 
     166                 :            : /*
     167                 :            :  * Frequently used control callbacks/helpers
     168                 :            :  */
     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[]);
     175                 :            : 
     176                 :            : /*
     177                 :            :  * virtual master control
     178                 :            :  */
     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,
     182                 :            :                        unsigned int flags);
     183                 :            : /* optional flags for slave */
     184                 :            : #define SND_CTL_SLAVE_NEED_UPDATE       (1 << 0)
     185                 :            : 
     186                 :            : /**
     187                 :            :  * snd_ctl_add_slave - Add a virtual slave control
     188                 :            :  * @master: vmaster element
     189                 :            :  * @slave: slave element to add
     190                 :            :  *
     191                 :            :  * Add a virtual slave control to the given master element created via
     192                 :            :  * snd_ctl_create_virtual_master() beforehand.
     193                 :            :  *
     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
     196                 :            :  * responsibility.
     197                 :            :  *
     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
     202                 :            :  *
     203                 :            :  * Return: Zero if successful or a negative error code.
     204                 :            :  */
     205                 :            : static inline int
     206                 :            : snd_ctl_add_slave(struct snd_kcontrol *master, struct snd_kcontrol *slave)
     207                 :            : {
     208                 :            :         return _snd_ctl_add_slave(master, slave, 0);
     209                 :            : }
     210                 :            : 
     211                 :            : /**
     212                 :            :  * snd_ctl_add_slave_uncached - Add a virtual slave control
     213                 :            :  * @master: vmaster element
     214                 :            :  * @slave: slave element to add
     215                 :            :  *
     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.
     220                 :            :  *
     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.
     224                 :            :  *
     225                 :            :  * Return: Zero if successful or a negative error code.
     226                 :            :  */
     227                 :            : static inline int
     228                 :            : snd_ctl_add_slave_uncached(struct snd_kcontrol *master,
     229                 :            :                            struct snd_kcontrol *slave)
     230                 :            : {
     231                 :            :         return _snd_ctl_add_slave(master, slave, SND_CTL_SLAVE_NEED_UPDATE);
     232                 :            : }
     233                 :            : 
     234                 :            : int snd_ctl_add_vmaster_hook(struct snd_kcontrol *kctl,
     235                 :            :                              void (*hook)(void *private_data, int),
     236                 :            :                              void *private_data);
     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,
     242                 :            :                                              void *arg),
     243                 :            :                                  void *arg);
     244                 :            : 
     245                 :            : /*
     246                 :            :  * Helper functions for jack-detection controls
     247                 :            :  */
     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);
     252                 :            : 
     253                 :            : #endif  /* __SOUND_CONTROL_H */