leandrof/linux
1
0
Fork 0
forked from Minki/linux
Code Issues Pull Requests Packages Projects Releases Wiki Activity

media: Media Device Allocator API

Browse Source 
Media Device Allocator API to allows multiple drivers share a media device.
This API solves a very common use-case for media devices where one physical
device (an USB stick) provides both audio and video. When such media device
exposes a standard USB Audio class, a proprietary Video class, two or more
independent drivers will share a single physical USB bridge. In such cases,
it is necessary to coordinate access to the shared resource.

Using this API, drivers can allocate a media device with the shared struct
device as the key. Once the media device is allocated by a driver, other
drivers can get a reference to it. The media device is released when all
the references are released.

Signed-off-by: Shuah Khan <shuah@kernel.org>
Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
This commit is contained in:
Shuah Khan 2019-04-01 20:40:19 -04:00 committed by Mauro Carvalho Chehab
parent 33dfeb62e2
commit 6e1d824e7a
4 changed files with 245 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
Documentation/media/kapi/mc-core.rst
View File

@ -259,6 +259,45 @@ Subsystems should facilitate link validation by providing subsystem specific
helper functions to provide easy access for commonly needed information, and
in the end provide a way to use driver-specific callbacks.
Media Controller Device Allocator API
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When the media device belongs to more than one driver, the shared media
device is allocated with the shared struct device as the key for look ups.
The shared media device should stay in registered state until the last
driver unregisters it. In addition, the media device should be released when
all the references are released. Each driver gets a reference to the media
device during probe, when it allocates the media device. If media device is
already allocated, the allocate API bumps up the refcount and returns the
existing media device. The driver puts the reference back in its disconnect
routine when it calls :c:func:`media_device_delete()`.
The media device is unregistered and cleaned up from the kref put handler to
ensure that the media device stays in registered state until the last driver
unregisters the media device.
**Driver Usage**
Drivers should use the appropriate media-core routines to manage the shared
media device life-time handling the two states:
1. allocate -> register -> delete
2. get reference to already registered device -> delete
call :c:func:`media_device_delete()` routine to make sure the shared media
device delete is handled correctly.
**driver probe:**
Call :c:func:`media_device_usb_allocate()` to allocate or get a reference
Call :c:func:`media_device_register()`, if media devnode isn't registered
**driver disconnect:**
Call :c:func:`media_device_delete()` to free the media_device. Freeing is
handled by the kref put handler.
API Definitions
^^^^^^^^^^^^^^^
.. kernel-doc:: include/media/media-device.h
.. kernel-doc:: include/media/media-devnode.h
@ -266,3 +305,5 @@ in the end provide a way to use driver-specific callbacks.
.. kernel-doc:: include/media/media-entity.h
.. kernel-doc:: include/media/media-request.h
.. kernel-doc:: include/media/media-dev-allocator.h

6
drivers/media/Makefile
View File

@ -6,6 +6,12 @@
media-objs := media-device.o media-devnode.o media-entity.o \
media-request.o
ifeq ($(CONFIG_MEDIA_CONTROLLER),y)
ifeq ($(CONFIG_USB),y)
media-objs += media-dev-allocator.o
endif
endif
#
# I2C drivers should come before other drivers, otherwise they'll fail
# when compiled as builtin drivers

135
drivers/media/media-dev-allocator.c Normal file
View File

@ -0,0 +1,135 @@
// SPDX-License-Identifier: GPL-2.0
/*
* media-dev-allocator.c - Media Controller Device Allocator API
*
* Copyright (c) 2019 Shuah Khan <shuah@kernel.org>
*
* Credits: Suggested by Laurent Pinchart <laurent.pinchart@ideasonboard.com>
*/
/*
* This file adds a global refcounted Media Controller Device Instance API.
* A system wide global media device list is managed and each media device
* includes a kref count. The last put on the media device releases the media
* device instance.
*
*/
#include <linux/kref.h>
#include <linux/module.h>
#include <linux/slab.h>
#include <linux/usb.h>
#include <media/media-device.h>
#include <media/media-dev-allocator.h>
static LIST_HEAD(media_device_list);
static DEFINE_MUTEX(media_device_lock);
struct media_device_instance {
struct media_device mdev;
struct module *owner;
struct list_head list;
struct kref refcount;
};
static inline struct media_device_instance *
to_media_device_instance(struct media_device *mdev)
{
return container_of(mdev, struct media_device_instance, mdev);
}
static void media_device_instance_release(struct kref *kref)
{
struct media_device_instance *mdi =
container_of(kref, struct media_device_instance, refcount);
dev_dbg(mdi->mdev.dev, "%s: releasing Media Device\n", __func__);
mutex_lock(&media_device_lock);
media_device_unregister(&mdi->mdev);
media_device_cleanup(&mdi->mdev);
list_del(&mdi->list);
mutex_unlock(&media_device_lock);
kfree(mdi);
}
/* Callers should hold media_device_lock when calling this function */
static struct media_device *__media_device_get(struct device *dev,
const char *module_name,
struct module *owner)
{
struct media_device_instance *mdi;
list_for_each_entry(mdi, &media_device_list, list) {
if (mdi->mdev.dev != dev)
continue;
kref_get(&mdi->refcount);
/* get module reference for the media_device owner */
if (owner != mdi->owner && !try_module_get(mdi->owner))
dev_err(dev,
"%s: module %s get owner reference error\n",
__func__, module_name);
else
dev_dbg(dev, "%s: module %s got owner reference\n",
__func__, module_name);
return &mdi->mdev;
}
mdi = kzalloc(sizeof(*mdi), GFP_KERNEL);
if (!mdi)
return NULL;
mdi->owner = owner;
kref_init(&mdi->refcount);
list_add_tail(&mdi->list, &media_device_list);
dev_dbg(dev, "%s: Allocated media device for owner %s\n",
__func__, module_name);
return &mdi->mdev;
}
struct media_device *media_device_usb_allocate(struct usb_device *udev,
const char *module_name,
struct module *owner)
{
struct media_device *mdev;
mutex_lock(&media_device_lock);
mdev = __media_device_get(&udev->dev, module_name, owner);
if (!mdev) {
mutex_unlock(&media_device_lock);
return ERR_PTR(-ENOMEM);
}
/* check if media device is already initialized */
if (!mdev->dev)
__media_device_usb_init(mdev, udev, udev->product,
module_name);
mutex_unlock(&media_device_lock);
return mdev;
}
EXPORT_SYMBOL_GPL(media_device_usb_allocate);
void media_device_delete(struct media_device *mdev, const char *module_name,
struct module *owner)
{
struct media_device_instance *mdi = to_media_device_instance(mdev);
mutex_lock(&media_device_lock);
/* put module reference for the media_device owner */
if (mdi->owner != owner) {
module_put(mdi->owner);
dev_dbg(mdi->mdev.dev,
"%s: module %s put owner module reference\n",
__func__, module_name);
}
mutex_unlock(&media_device_lock);
kref_put(&mdi->refcount, media_device_instance_release);
}
EXPORT_SYMBOL_GPL(media_device_delete);

63
include/media/media-dev-allocator.h Normal file
View File

@ -0,0 +1,63 @@
/* SPDX-License-Identifier: GPL-2.0+ */
/*
* media-dev-allocator.h - Media Controller Device Allocator API
*
* Copyright (c) 2019 Shuah Khan <shuah@kernel.org>
*
* Credits: Suggested by Laurent Pinchart <laurent.pinchart@ideasonboard.com>
*/
/*
* This file adds a global ref-counted Media Controller Device Instance API.
* A system wide global media device list is managed and each media device
* includes a kref count. The last put on the media device releases the media
* device instance.
*/
#ifndef _MEDIA_DEV_ALLOCATOR_H
#define _MEDIA_DEV_ALLOCATOR_H
struct usb_device;
#if defined(CONFIG_MEDIA_CONTROLLER) && defined(CONFIG_USB)
/**
* media_device_usb_allocate() - Allocate and return struct &media device
*
* @udev: struct &usb_device pointer
* @module_name: should be filled with %KBUILD_MODNAME
* @owner: struct module pointer %THIS_MODULE for the driver.
* %THIS_MODULE is null for a built-in driver.
* It is safe even when %THIS_MODULE is null.
*
* This interface should be called to allocate a Media Device when multiple
* drivers share usb_device and the media device. This interface allocates
* &media_device structure and calls media_device_usb_init() to initialize
* it.
*
*/
struct media_device *media_device_usb_allocate(struct usb_device *udev,
const char *module_name,
struct module *owner);
/**
* media_device_delete() - Release media device. Calls kref_put().
*
* @mdev: struct &media_device pointer
* @module_name: should be filled with %KBUILD_MODNAME
* @owner: struct module pointer %THIS_MODULE for the driver.
* %THIS_MODULE is null for a built-in driver.
* It is safe even when %THIS_MODULE is null.
*
* This interface should be called to put Media Device Instance kref.
*/
void media_device_delete(struct media_device *mdev, const char *module_name,
struct module *owner);
#else
static inline struct media_device *media_device_usb_allocate(
struct usb_device *udev, const char *module_name,
struct module *owner)
{ return NULL; }
static inline void media_device_delete(
struct media_device *mdev, const char *module_name,
struct module *owner) { }
#endif /* CONFIG_MEDIA_CONTROLLER && CONFIG_USB */
#endif /* _MEDIA_DEV_ALLOCATOR_H */