From patchwork Mon Aug 29 23:44:44 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Takashi Sakamoto X-Patchwork-Id: 9304645 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id B941260756 for ; Mon, 29 Aug 2016 23:46:36 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id A4F33288E6 for ; Mon, 29 Aug 2016 23:46:36 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 9833A28970; Mon, 29 Aug 2016 23:46:36 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-1.9 required=2.0 tests=BAYES_00, RCVD_IN_DNSWL_NONE autolearn=ham version=3.3.1 Received: from alsa0.perex.cz (alsa0.perex.cz [77.48.224.243]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id D9314288E6 for ; Mon, 29 Aug 2016 23:46:35 +0000 (UTC) Received: by alsa0.perex.cz (Postfix, from userid 1000) id CEED626691A; Tue, 30 Aug 2016 01:46:34 +0200 (CEST) Received: from alsa0.perex.cz (localhost [127.0.0.1]) by alsa0.perex.cz (Postfix) with ESMTP id D006D2666F1; Tue, 30 Aug 2016 01:45:08 +0200 (CEST) X-Original-To: alsa-devel@alsa-project.org Delivered-To: alsa-devel@alsa-project.org Received: by alsa0.perex.cz (Postfix, from userid 1000) id ACD562666F1; Tue, 30 Aug 2016 01:45:07 +0200 (CEST) Received: from smtp-proxy001.phy.lolipop.jp (smtp-proxy001.phy.lolipop.jp [157.7.104.42]) by alsa0.perex.cz (Postfix) with ESMTP id F1BCA2657F6 for ; Tue, 30 Aug 2016 01:44:56 +0200 (CEST) Received: from smtp-proxy001.phy.lolipop.lan (HELO smtp-proxy001.phy.lolipop.jp) (172.19.44.42) (smtp-auth username m12129643-o-takashi, mechanism plain) by smtp-proxy001.phy.lolipop.jp (qpsmtpd/0.82) with ESMTPA; Tue, 30 Aug 2016 08:44:53 +0900 Received: from 127.0.0.1 (127.0.0.1) by smtp-proxy001.phy.lolipop.jp (LOLIPOP-Fsecure); Tue, 30 Aug 2016 08:44:45 +0900 (JST) X-Virus-Status: clean(LOLIPOP-Fsecure) From: Takashi Sakamoto To: clemens@ladisch.de, tiwai@suse.de Date: Tue, 30 Aug 2016 08:44:44 +0900 Message-Id: <1472514285-3769-4-git-send-email-o-takashi@sakamocchi.jp> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1472514285-3769-1-git-send-email-o-takashi@sakamocchi.jp> References: <1472514285-3769-1-git-send-email-o-takashi@sakamocchi.jp> Cc: vinod.koul@intel.com, alsa-devel@alsa-project.org, broonie@linaro.org, omair.m.abdullah@intel.com Subject: [alsa-devel] [PATCH 3/4] ALSA: control: add kerneldoc for snd_kcontrol_tlv_rw_t X-BeenThere: alsa-devel@alsa-project.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Alsa-devel mailing list for ALSA developers - http://www.alsa-project.org" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: alsa-devel-bounces@alsa-project.org Sender: alsa-devel-bounces@alsa-project.org X-Virus-Scanned: ClamAV using ClamSMTP Currently, there's no documentation about implementation requirement of snd_kcontrol_tlv_rw_t. This function prototype includes historical complexities and probably puzzles driver developers. This commit adds a kerneldoc for this feature. Signed-off-by: Takashi Sakamoto --- include/sound/control.h | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/include/sound/control.h b/include/sound/control.h index 848940c..6c1c4234 100644 --- a/include/sound/control.h +++ b/include/sound/control.h @@ -30,9 +30,27 @@ struct snd_kcontrol; typedef int (snd_kcontrol_info_t) (struct snd_kcontrol * kcontrol, struct snd_ctl_elem_info * uinfo); typedef int (snd_kcontrol_get_t) (struct snd_kcontrol * kcontrol, struct snd_ctl_elem_value * ucontrol); typedef int (snd_kcontrol_put_t) (struct snd_kcontrol * kcontrol, struct snd_ctl_elem_value * ucontrol); + +/** + * snd_kcontrol_tlv_rw_t - a type of callback function to operate information + * for threshold level or arbitrary I/O, via TLV + * feature of ALSA control interface. + * @kcontrol: A pointer to an instance for control element set. + * @op_flag: One of SNDRV_CTL_TLV_OP_READ/WRITE/CMD. + * @size: The size of buffer in user space in byte unit. After operated, the + * size should be changed to size of actually operated data in byte unit, + * @tlv: A pointer to the buffer in user space. + * + * Originally, this function is designed to allow each driver to generate and + * transfer data about threshold level. Later, this function is used to operate + * arbitrary I/O depending on each driver. + * + * Return: Zero if successful. Negative value in error. Positive value generates + * an event with SNDRV_CTL_EVENT_MASK_TLV. This return value is received + * by applications as a result of ioctl(2). + */ typedef int (snd_kcontrol_tlv_rw_t)(struct snd_kcontrol *kcontrol, - int op_flag, /* SNDRV_CTL_TLV_OP_XXX */ - unsigned int *size, + int op_flag, unsigned int *size, unsigned int __user *tlv); enum {