Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1753567AbcC1S2a (ORCPT ); Mon, 28 Mar 2016 14:28:30 -0400 Received: from lists.s-osg.org ([54.187.51.154]:58650 "EHLO lists.s-osg.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1750860AbcC1S21 (ORCPT ); Mon, 28 Mar 2016 14:28:27 -0400 Date: Mon, 28 Mar 2016 15:28:21 -0300 From: Mauro Carvalho Chehab To: Shuah Khan Cc: , , , , , , , , , Subject: Re: [RFC PATCH 2/4] media: Add Media Device Allocator API documentation Message-ID: <20160328152821.18142532@recife.lan> In-Reply-To: <33083175297b174a68b937e9bf2d867add363e23.1458966594.git.shuahkh@osg.samsung.com> References: <33083175297b174a68b937e9bf2d867add363e23.1458966594.git.shuahkh@osg.samsung.com> Organization: Samsung X-Mailer: Claws Mail 3.13.2 (GTK+ 2.24.30; x86_64-redhat-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 2412 Lines: 61 Em Fri, 25 Mar 2016 22:38:43 -0600 Shuah Khan escreveu: > Add Media Device Allocator API documentation. Please merge this with the previous patch. > > 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 -- Thanks, Mauro