From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-18.8 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER, INCLUDES_PATCH,MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 7E88CC07E96 for ; Thu, 15 Jul 2021 08:04:28 +0000 (UTC) Received: from alsa0.perex.cz (alsa0.perex.cz [77.48.224.243]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 04E4E61073 for ; Thu, 15 Jul 2021 08:04:27 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 04E4E61073 Authentication-Results: mail.kernel.org; dmarc=none (p=none dis=none) header.from=suse.de Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=alsa-devel-bounces@alsa-project.org Received: from alsa1.perex.cz (alsa1.perex.cz [207.180.221.201]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by alsa0.perex.cz (Postfix) with ESMTPS id 8D90E167A; Thu, 15 Jul 2021 10:03:36 +0200 (CEST) DKIM-Filter: OpenDKIM Filter v2.11.0 alsa0.perex.cz 8D90E167A DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=alsa-project.org; s=default; t=1626336266; bh=rXd3rGaZ0EkgeHDojGaFPpZiTaj1DBoxC6XqwIBWSCo=; h=From:To:Subject:Date:In-Reply-To:References:List-Id: List-Unsubscribe:List-Archive:List-Post:List-Help:List-Subscribe: From; b=s9IIyFcqRG+p8XvNdi4MBo2sXxwXKgFoXndActPhAUI4yG7Sh46RIhPUs86CgKJfS L5gfnQ94Rkd0hFptat3UHyn9oD8n0ZWgawz14BIEzWvO/kqRWFg5JYuJKPXOZBiZbr XON37yo8K8Xp8hpEu17tTgRrTalC+1EwwG4+x7wk= Received: from alsa1.perex.cz (localhost.localdomain [127.0.0.1]) by alsa1.perex.cz (Postfix) with ESMTP id 32A0CF80578; Thu, 15 Jul 2021 10:00:21 +0200 (CEST) Received: by alsa1.perex.cz (Postfix, from userid 50401) id 7DF04F80544; Thu, 15 Jul 2021 10:00:15 +0200 (CEST) Received: from smtp-out2.suse.de (smtp-out2.suse.de [195.135.220.29]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by alsa1.perex.cz (Postfix) with ESMTPS id CA574F804DA for ; Thu, 15 Jul 2021 09:59:52 +0200 (CEST) DKIM-Filter: OpenDKIM Filter v2.11.0 alsa1.perex.cz CA574F804DA Authentication-Results: alsa1.perex.cz; dkim=pass (1024-bit key) header.d=suse.de header.i=@suse.de header.b="HckqRdQ6"; dkim=permerror (0-bit key) header.d=suse.de header.i=@suse.de header.b="VzJte51Y" Received: from relay2.suse.de (relay2.suse.de [149.44.160.134]) by smtp-out2.suse.de (Postfix) with ESMTP id 981531FDEB for ; Thu, 15 Jul 2021 07:59:52 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.de; s=susede2_rsa; t=1626335992; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=p+80vNdV6jE9Ou8O5FXAHfr7DOF9xGqto4WGILLz14c=; b=HckqRdQ6SGh9JzUdfNrkvTAQIQpQ8AtVZ8hhlYczC8/S1FTrWpscB1Cd4ENS1ATSTyvhnu 0pgkie22c1dI8Ve0p5VMexSKbTQQZxqkbQlEsdZ+ULSCS5jG8rFQUh0yB1sEL7kSiF+R8P jMnsFW1L+9OZ0UyCp555sF75wGcO530= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.de; s=susede2_ed25519; t=1626335992; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=p+80vNdV6jE9Ou8O5FXAHfr7DOF9xGqto4WGILLz14c=; b=VzJte51YWp6KnPn/utzTLyfXukQZ3h+HcGFW01eGjE3snTFnX5WqVpPSl3q51Idn+q6/S/ +R571eUdXWWaqiDA== Received: from alsa1.nue.suse.com (alsa1.suse.de [10.160.4.42]) by relay2.suse.de (Postfix) with ESMTP id 85BF4A3B8F; Thu, 15 Jul 2021 07:59:52 +0000 (UTC) From: Takashi Iwai To: alsa-devel@alsa-project.org Subject: [PATCH v2 04/79] ALSA: doc: Add device-managed resource section Date: Thu, 15 Jul 2021 09:58:26 +0200 Message-Id: <20210715075941.23332-5-tiwai@suse.de> X-Mailer: git-send-email 2.26.2 In-Reply-To: <20210715075941.23332-1-tiwai@suse.de> References: <20210715075941.23332-1-tiwai@suse.de> MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: alsa-devel@alsa-project.org X-Mailman-Version: 2.1.15 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: , Errors-To: alsa-devel-bounces@alsa-project.org Sender: "Alsa-devel" Give brief explanations about the device-managed resources and the newly introduced snd_devm_card_new() helper. Signed-off-by: Takashi Iwai --- .../kernel-api/writing-an-alsa-driver.rst | 33 +++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst index 01d59b8aea92..255b7d3bebd6 100644 --- a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst +++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst @@ -4172,6 +4172,39 @@ module license as GPL, etc., otherwise the system is shown as “tainted”. MODULE_LICENSE("GPL"); +Device-Managed Resources +======================== + +In the examples above, all resources are allocated and released +manually. But human beings are lazy in nature, especially developers +are lazier. So there are some ways to automate the release part; it's +the (device-)managed resources aka devres or devm family. For +example, an object allocated via :c:func:`devm_kmalloc()` will be +freed automatically at unbinding the device. + +ALSA core provides also the device-managed helper, namely, +:c:func:`snd_devm_card_new()` for creating a card object. +Call this functions instead of the normal :c:func:`snd_card_new()`, +and you can forget the explicit :c:func:`snd_card_free()` call, as +it's called automagically at error and removal paths. + +One caveat is that the call of :c:func:`snd_card_free()` would be put +at the beginning of the call chain only after you call +:c:func:`snd_card_register()`. + +Also, the ``private_free`` callback is always called at the card free, +so be careful to put the hardware clean-up procedure in +``private_free`` callback. It might be called even before you +actually set up at an earlier error path. For avoiding such an +invalid initialization, you can set ``private_free`` callback after +:c:func:`snd_card_register()` call succeeds. + +Another thing to be remarked is that you should use device-managed +helpers for each component as much as possible once when you manage +the card in that way. Mixing up with the normal and the managed +resources may screw up the release order. + + How To Put Your Driver Into ALSA Tree ===================================== -- 2.26.2