From patchwork Sat Mar 26 04:38:43 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Shuah Khan X-Patchwork-Id: 8674001 Return-Path: X-Original-To: patchwork-alsa-devel@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork1.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.136]) by patchwork1.web.kernel.org (Postfix) with ESMTP id A17B89F65E for ; Sat, 26 Mar 2016 04:39:50 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id AB79F202B8 for ; Sat, 26 Mar 2016 04:39:49 +0000 (UTC) Received: from alsa0.perex.cz (alsa0.perex.cz [77.48.224.243]) by mail.kernel.org (Postfix) with ESMTP id 7101E20219 for ; Sat, 26 Mar 2016 04:39:48 +0000 (UTC) Received: by alsa0.perex.cz (Postfix, from userid 1000) id 853BA265DB9; Sat, 26 Mar 2016 05:39:47 +0100 (CET) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Spam-Level: X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_NONE, UNPARSEABLE_RELAY autolearn=unavailable version=3.3.1 Received: from alsa0.perex.cz (localhost [127.0.0.1]) by alsa0.perex.cz (Postfix) with ESMTP id 57533264F74; Sat, 26 Mar 2016 05:39:05 +0100 (CET) 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 C5E92261AE7; Sat, 26 Mar 2016 05:39:03 +0100 (CET) Received: from mailout.easymail.ca (mailout.easymail.ca [64.68.201.169]) by alsa0.perex.cz (Postfix) with ESMTP id 7ABE32612AF for ; Sat, 26 Mar 2016 05:38:53 +0100 (CET) Received: from localhost (localhost [127.0.0.1]) by mailout.easymail.ca (Postfix) with ESMTP id D6BE7F3BC; Sat, 26 Mar 2016 00:38:47 -0400 (EDT) X-Quarantine-ID: X-Virus-Scanned: Debian amavisd-new at mailout.easymail.ca X-Amavis-Alert: BAD HEADER SECTION, Duplicate header field: "References" Received: from mailout.easymail.ca ([127.0.0.1]) by localhost (easymail-mailout.easydns.vpn [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id DFzF+x9NGGmj; Sat, 26 Mar 2016 00:38:47 -0400 (EDT) Received: from mail.gonehiking.org (c-73-181-52-62.hsd1.co.comcast.net [73.181.52.62]) by mailout.easymail.ca (Postfix) with ESMTPA id 8F6FAF2F2; Sat, 26 Mar 2016 00:38:47 -0400 (EDT) Received: from lorien.internal (lorien-wl.internal [192.168.1.40]) by mail.gonehiking.org (Postfix) with ESMTP id 2A2A49F3E1; Fri, 25 Mar 2016 22:38:47 -0600 (MDT) From: Shuah Khan To: laurent.pinchart@ideasonboard.com, mchehab@osg.samsung.com, perex@perex.cz, tiwai@suse.com, hans.verkuil@cisco.com, chehabrafael@gmail.com, javier@osg.samsung.com, jh1009.sung@samsung.com Date: Fri, 25 Mar 2016 22:38:43 -0600 Message-Id: <33083175297b174a68b937e9bf2d867add363e23.1458966594.git.shuahkh@osg.samsung.com> X-Mailer: git-send-email 2.5.0 In-Reply-To: References: In-Reply-To: References: Cc: alsa-devel@alsa-project.org, linux-media@vger.kernel.org, Shuah Khan , linux-kernel@vger.kernel.org Subject: [alsa-devel] [RFC PATCH 2/4] media: Add Media Device Allocator API documentation 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 Add Media Device Allocator API documentation. Signed-off-by: Shuah Khan --- include/media/media-dev-allocator.h | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/include/media/media-dev-allocator.h b/include/media/media-dev-allocator.h index 2932c90..174840c 100644 --- a/include/media/media-dev-allocator.h +++ b/include/media/media-dev-allocator.h @@ -20,6 +20,38 @@ #ifdef CONFIG_MEDIA_CONTROLLER /** + * DOC: Media Controller Device Allocator API + * There are known problems with media device life time management. When media + * device is released while an media ioctl is in progress, ioctls fail with + * use-after-free errors and kernel hangs in some cases. + * + * Media Device can be in any the following states: + * + * - Allocated + * - Registered (could be tied to more than one driver) + * - Unregistered, not in use (media device file is not open) + * - Unregistered, in use (media device file is not open) + * - Released + * + * When media device belongs to more than one driver, registrations should be + * refcounted to avoid unregistering when one of the drivers does unregister. + * A refcount field in the struct media_device covers this case. Unregister on + * a Media Allocator media device is a kref_put() call. The media device should + * be unregistered only when the last unregister occurs. + * + * When a media device is in use when it is unregistered, it should not be + * released until the application exits when it detects the unregistered + * status. Media device that is in use when it is unregistered is moved to + * to_delete_list. When the last unregister occurs, media device is unregistered + * and becomes an unregistered, still allocated device. Unregister marks the + * device to be deleted. + * + * When media device belongs to more than one driver, as both drivers could be + * unbound/bound, driver should not end up getting stale media device that is + * on its way out. Moving the unregistered media device to to_delete_list helps + * this case as well. + */ +/** * media_device_get() - Allocate and return global media device * * @mdev