5. Media Controller devices¶
5.1. Media Controller¶
The media controller userspace API is documented in the Media Controller uAPI book. This document focus on the kernel-side implementation of the media framework.
5.1.1. Abstract media device model¶
Discovering a device internal topology, and configuring it at runtime, is one of the goals of the media framework. To achieve this, hardware devices are modelled as an oriented graph of building blocks called entities connected through pads.
An entity is a basic media hardware building block. It can correspond to a large variety of logical blocks such as physical hardware devices (CMOS sensor for instance), logical hardware devices (a building block in a System-on-Chip image processing pipeline), DMA channels or physical connectors.
A pad is a connection endpoint through which an entity can interact with other entities. Data (not restricted to video) produced by an entity flows from the entity’s output to one or more entity inputs. Pads should not be confused with physical pins at chip boundaries.
A link is a point-to-point oriented connection between two pads, either on the same entity or on different entities. Data flows from a source pad to a sink pad.
5.1.2. Media device¶
A media device is represented by a struct media_device
instance, defined in include/media/media-device.h
.
Allocation of the structure is handled by the media device driver, usually by
embedding the media_device
instance in a larger driver-specific
structure.
Drivers register media device instances by calling
__media_device_register()
via the macro media_device_register()
and unregistered by calling media_device_unregister()
.
5.1.3. Entities¶
Entities are represented by a struct media_entity
instance, defined in include/media/media-entity.h
. The structure is usually
embedded into a higher-level structure, such as
v4l2_subdev
or video_device
instances, although drivers can allocate entities directly.
Drivers initialize entity pads by calling
media_entity_pads_init()
.
Drivers register entities with a media device by calling
media_device_register_entity()
and unregistered by calling
media_device_unregister_entity()
.
5.1.4. Interfaces¶
Interfaces are represented by a
struct media_interface instance, defined in
include/media/media-entity.h
. Currently, only one type of interface is
defined: a device node. Such interfaces are represented by a
struct media_intf_devnode.
Drivers initialize and create device node interfaces by calling
media_devnode_create()
and remove them by calling:
media_devnode_remove()
.
5.1.5. Pads¶
Pads are represented by a struct media_pad instance,
defined in include/media/media-entity.h
. Each entity stores its pads in
a pads array managed by the entity driver. Drivers usually embed the array in
a driver-specific structure.
Pads are identified by their entity and their 0-based index in the pads array.
Both information are stored in the struct media_pad, making the struct media_pad pointer the canonical way to store and pass link references.
Pads have flags that describe the pad capabilities and state.
MEDIA_PAD_FL_SINK
indicates that the pad supports sinking data.
MEDIA_PAD_FL_SOURCE
indicates that the pad supports sourcing data.
Note
One and only one of MEDIA_PAD_FL_SINK
or MEDIA_PAD_FL_SOURCE
must
be set for each pad.
5.1.6. Links¶
Links are represented by a struct media_link instance,
defined in include/media/media-entity.h
. There are two types of links:
1. pad to pad links:
Associate two entities via their PADs. Each entity has a list that points to all links originating at or targeting any of its pads. A given link is thus stored twice, once in the source entity and once in the target entity.
Drivers create pad to pad links by calling:
media_create_pad_link()
and remove with
media_entity_remove_links()
.
2. interface to entity links:
Associate one interface to a Link.
Drivers create interface to entity links by calling:
media_create_intf_link()
and remove with
media_remove_intf_links()
.
Note
Links can only be created after having both ends already created.
Links have flags that describe the link capabilities and state. The
valid values are described at media_create_pad_link()
and
media_create_intf_link()
.
5.1.7. Graph traversal¶
The media framework provides APIs to iterate over entities in a graph.
To iterate over all entities belonging to a media device, drivers can use
the media_device_for_each_entity macro, defined in
include/media/media-device.h
.
struct media_entity *entity;
media_device_for_each_entity(entity, mdev) {
// entity will point to each entity in turn
...
}
Drivers might also need to iterate over all entities in a graph that can be reached only through enabled links starting at a given entity. The media framework provides a depth-first graph traversal API for that purpose.
Note
Graphs with cycles (whether directed or undirected) are NOT
supported by the graph traversal API. To prevent infinite loops, the graph
traversal code limits the maximum depth to MEDIA_ENTITY_ENUM_MAX_DEPTH
,
currently defined as 16.
Drivers initiate a graph traversal by calling
media_graph_walk_start()
The graph structure, provided by the caller, is initialized to start graph traversal at the given entity.
Drivers can then retrieve the next entity by calling
media_graph_walk_next()
When the graph traversal is complete the function will return NULL
.
Graph traversal can be interrupted at any moment. No cleanup function call is required and the graph structure can be freed normally.
Helper functions can be used to find a link between two given pads, or a pad
connected to another pad through an enabled link
media_entity_find_link()
and
media_entity_remote_pad()
.
5.1.8. Use count and power handling¶
Due to the wide differences between drivers regarding power management
needs, the media controller does not implement power management. However,
the struct media_entity includes a use_count
field that media drivers
can use to track the number of users of every entity for power management
needs.
The media_entity
.use_count
field is owned by
media drivers and must not be
touched by entity drivers. Access to the field must be protected by the
media_device
.graph_mutex
lock.
5.1.9. Links setup¶
Link properties can be modified at runtime by calling
media_entity_setup_link()
.
5.1.10. Pipelines and media streams¶
When starting streaming, drivers must notify all entities in the pipeline to
prevent link states from being modified during streaming by calling
media_pipeline_start()
.
The function will mark all entities connected to the given entity through enabled links, either directly or indirectly, as streaming.
The struct media_pipeline instance pointed to by the pipe argument will be stored in every entity in the pipeline. Drivers should embed the struct media_pipeline in higher-level pipeline structures and can then access the pipeline through the struct media_entity pipe field.
Calls to media_pipeline_start()
can be nested.
The pipeline pointer must be identical for all nested calls to the function.
media_pipeline_start()
may return an error. In that case,
it will clean up any of the changes it did by itself.
When stopping the stream, drivers must notify the entities with
media_pipeline_stop()
.
If multiple calls to media_pipeline_start()
have been
made the same number of media_pipeline_stop()
calls
are required to stop streaming.
The media_entity
.pipe
field is reset to NULL
on the last
nested stop call.
Link configuration will fail with -EBUSY
by default if either end of the
link is a streaming entity. Links that can be modified while streaming must
be marked with the MEDIA_LNK_FL_DYNAMIC
flag.
If other operations need to be disallowed on streaming entities (such as changing entities configuration parameters) drivers can explicitly check the media_entity stream_count field to find out if an entity is streaming. This operation must be done with the media_device graph_mutex held.
5.1.11. Link validation¶
Link validation is performed by media_pipeline_start()
for any entity which has sink pads in the pipeline. The
media_entity
.link_validate()
callback is used for that
purpose. In link_validate()
callback, entity driver should check
that the properties of the source pad of the connected entity and its own
sink pad match. It is up to the type of the entity (and in the end, the
properties of the hardware) what matching actually means.
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.
5.1.12. 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 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 media_device_delete()
routine to make sure the shared media
device delete is handled correctly.
driver probe:
Call media_device_usb_allocate()
to allocate or get a reference
Call media_device_register()
, if media devnode isn’t registered
driver disconnect:
Call media_device_delete()
to free the media_device. Freeing is
handled by the kref put handler.
5.1.13. API Definitions¶
-
struct
media_entity_notify
¶ Media Entity Notify
Definition
struct media_entity_notify {
struct list_head list;
void *notify_data;
void (*notify)(struct media_entity *entity, void *notify_data);
};
Members
list
List head
notify_data
Input data to invoke the callback
notify
Callback function pointer
Description
Drivers may register a callback to take action when new entities get registered with the media device. This handler is intended for creating links between existing entities and should not create entities and register them.
-
struct
media_device_ops
¶ Media device operations
Definition
struct media_device_ops {
int (*link_notify)(struct media_link *link, u32 flags, unsigned int notification);
struct media_request *(*req_alloc)(struct media_device *mdev);
void (*req_free)(struct media_request *req);
int (*req_validate)(struct media_request *req);
void (*req_queue)(struct media_request *req);
};
Members
link_notify
Link state change notification callback. This callback is called with the graph_mutex held.
req_alloc
Allocate a request. Set this if you need to allocate a struct larger then
struct media_request
. req_alloc and req_free must either both be set or both be NULL.req_free
Free a request. Set this if req_alloc was set as well, leave to NULL otherwise.
req_validate
Validate a request, but do not queue yet. The req_queue_mutex lock is held when this op is called.
req_queue
Queue a validated request, cannot fail. If something goes wrong when queueing this request then it should be marked as such internally in the driver and any related buffers must eventually return to vb2 with state VB2_BUF_STATE_ERROR. The req_queue_mutex lock is held when this op is called. It is important that vb2 buffer objects are queued last after all other object types are queued: queueing a buffer kickstarts the request processing, so all other objects related to the request (and thus the buffer) must be available to the driver. And once a buffer is queued, then the driver can complete or delete objects from the request before req_queue exits.
-
struct
media_device
¶ Media device
Definition
struct media_device {
struct device *dev;
struct media_devnode *devnode;
char model[32];
char driver_name[32];
char serial[40];
char bus_info[32];
u32 hw_revision;
u64 topology_version;
u32 id;
struct ida entity_internal_idx;
int entity_internal_idx_max;
struct list_head entities;
struct list_head interfaces;
struct list_head pads;
struct list_head links;
struct list_head entity_notify;
struct mutex graph_mutex;
struct media_graph pm_count_walk;
void *source_priv;
int (*enable_source)(struct media_entity *entity, struct media_pipeline *pipe);
void (*disable_source)(struct media_entity *entity);
const struct media_device_ops *ops;
struct mutex req_queue_mutex;
atomic_t request_id;
};
Members
dev
Parent device
devnode
Media device node
model
Device model name
driver_name
Optional device driver name. If not set, calls to
MEDIA_IOC_DEVICE_INFO
will returndev->driver->name
. This is needed for USB drivers for example, as otherwise they’ll all appear as if the driver name was “usb”.serial
Device serial number (optional)
bus_info
Unique and stable device location identifier
hw_revision
Hardware device revision
topology_version
Monotonic counter for storing the version of the graph topology. Should be incremented each time the topology changes.
id
Unique ID used on the last registered graph object
entity_internal_idx
Unique internal entity ID used by the graph traversal algorithms
entity_internal_idx_max
Allocated internal entity indices
entities
List of registered entities
interfaces
List of registered interfaces
pads
List of registered pads
links
List of registered links
entity_notify
List of registered entity_notify callbacks
graph_mutex
Protects access to
struct media_device
datapm_count_walk
Graph walk for power state walk. Access serialised using graph_mutex.
source_priv
Driver Private data for enable/disable source handlers
enable_source
Enable Source Handler function pointer
disable_source
Disable Source Handler function pointer
ops
Operation handler callbacks
req_queue_mutex
Serialise the MEDIA_REQUEST_IOC_QUEUE ioctl w.r.t. other operations that stop or start streaming.
request_id
Used to generate unique request IDs
Description
This structure represents an abstract high-level media device. It allows easy access to entities and provides basic media device-level support. The structure can be allocated directly or embedded in a larger structure.
The parent dev is a physical device. It must be set before registering the media device.
model is a descriptive model name exported through sysfs. It doesn’t have to be unique.
enable_source is a handler to find source entity for the sink entity and activate the link between them if source entity is free. Drivers should call this handler before accessing the source.
disable_source is a handler to find source entity for the sink entity and deactivate the link between them. Drivers should call this handler to release the source.
Use-case: find tuner entity connected to the decoder entity and check if it is available, and activate the link between them from enable_source and deactivate from disable_source.
Note
Bridge driver is expected to implement and set the
handler when media_device
is registered or when
bridge driver finds the media_device during probe.
Bridge driver sets source_priv with information
necessary to run enable_source and disable_source handlers.
Callers should hold graph_mutex to access and call enable_source
and disable_source handlers.
-
int
media_entity_enum_init
(struct media_entity_enum *ent_enum, struct media_device *mdev)¶ Initialise an entity enumeration
Parameters
struct media_entity_enum *ent_enum
Entity enumeration to be initialised
struct media_device *mdev
The related media device
Return
zero on success or a negative error code.
-
void
media_device_init
(struct media_device *mdev)¶ Initializes a media device element
Parameters
struct media_device *mdev
pointer to struct
media_device
Description
This function initializes the media device prior to its registration. The media device initialization and registration is split in two functions to avoid race conditions and make the media device available to user-space before the media graph has been completed.
So drivers need to first initialize the media device, register any entity
within the media device, create pad to pad links and then finally register
the media device by calling media_device_register()
as a final step.
-
void
media_device_cleanup
(struct media_device *mdev)¶ Cleanups a media device element
Parameters
struct media_device *mdev
pointer to struct
media_device
Description
This function that will destroy the graph_mutex that is
initialized in media_device_init()
.
-
int
__media_device_register
(struct media_device *mdev, struct module *owner)¶ Registers a media device element
Parameters
struct media_device *mdev
pointer to struct
media_device
struct module *owner
should be filled with
THIS_MODULE
Description
Users, should, instead, call the media_device_register()
macro.
The caller is responsible for initializing the media_device
structure
before registration. The following fields of media_device
must be set:
media_entity.dev
must point to the parent device (usually apci_dev
,usb_interface
orplatform_device
instance).
media_entity.model
must be filled with the device model name as a NUL-terminated UTF-8 string. The device/model revision must not be stored in this field.
The following fields are optional:
media_entity.serial
is a unique serial number stored as a NUL-terminated ASCII string. The field is big enough to store a GUID in text form. If the hardware doesn’t provide a unique serial number this field must be left empty.
media_entity.bus_info
represents the location of the device in the system as a NUL-terminated ASCII string. For PCI/PCIe devicesmedia_entity.bus_info
must be set to “PCI:” (or “PCIe:”) followed by the value of pci_name(). For USB devices,the usb_make_path() function must be used. This field is used by applications to distinguish between otherwise identical devices that don’t provide a serial number.
media_entity.hw_revision
is the hardware device revision in a driver-specific format. When possible the revision should be formatted with the KERNEL_VERSION() macro.
Note
Upon successful registration a character device named media[0-9]+ is created. The device major and minor numbers are dynamic. The model name is exported as a sysfs attribute.
Unregistering a media device that hasn’t been registered is NOT safe.
Return
returns zero on success or a negative error code.
-
media_device_register
(mdev)¶ Registers a media device element
Parameters
mdev
pointer to struct
media_device
Description
This macro calls __media_device_register()
passing THIS_MODULE
as
the __media_device_register()
second argument (owner).
-
void
media_device_unregister
(struct media_device *mdev)¶ Unregisters a media device element
Parameters
struct media_device *mdev
pointer to struct
media_device
Description
It is safe to call this function on an unregistered (but initialised) media device.
-
int
media_device_register_entity
(struct media_device *mdev, struct media_entity *entity)¶ registers a media entity inside a previously registered media device.
Parameters
struct media_device *mdev
pointer to struct
media_device
struct media_entity *entity
pointer to struct
media_entity
to be registered
Description
Entities are identified by a unique positive integer ID. The media controller framework will such ID automatically. IDs are not guaranteed to be contiguous, and the ID number can change on newer Kernel versions. So, neither the driver nor userspace should hardcode ID numbers to refer to the entities, but, instead, use the framework to find the ID, when needed.
The media_entity name, type and flags fields should be initialized before
calling media_device_register_entity()
. Entities embedded in higher-level
standard structures can have some of those fields set by the higher-level
framework.
If the device has pads, media_entity_pads_init() should be called before
this function. Otherwise, the media_entity.pad
and media_entity.num_pads
should be zeroed before calling this function.
Entities have flags that describe the entity capabilities and state:
MEDIA_ENT_FL_DEFAULT
indicates the default entity for a given type. This can be used to report the default audio and video devices or the default camera sensor.
Note
Drivers should set the entity function before calling this function.
Please notice that the values MEDIA_ENT_F_V4L2_SUBDEV_UNKNOWN
and
MEDIA_ENT_F_UNKNOWN
should not be used by the drivers.
-
void
media_device_unregister_entity
(struct media_entity *entity)¶ unregisters a media entity.
Parameters
struct media_entity *entity
pointer to struct
media_entity
to be unregistered
Description
All links associated with the entity and all PADs are automatically unregistered from the media_device when this function is called.
Unregistering an entity will not change the IDs of the other entities and the previoully used ID will never be reused for a newly registered entities.
When a media device is unregistered, all its entities are unregistered automatically. No manual entities unregistration is then required.
Note
The media_entity instance itself must be freed explicitly by the driver if required.
-
int
media_device_register_entity_notify
(struct media_device *mdev, struct media_entity_notify *nptr)¶ Registers a media entity_notify callback
Parameters
struct media_device *mdev
The media device
struct media_entity_notify *nptr
The media_entity_notify
Description
Note
When a new entity is registered, all the registered media_entity_notify callbacks are invoked.
-
void
media_device_unregister_entity_notify
(struct media_device *mdev, struct media_entity_notify *nptr)¶ Unregister a media entity notify callback
Parameters
struct media_device *mdev
The media device
struct media_entity_notify *nptr
The media_entity_notify
-
void
media_device_pci_init
(struct media_device *mdev, struct pci_dev *pci_dev, const char *name)¶ create and initialize a struct
media_device
from a PCI device.
Parameters
struct media_device *mdev
pointer to struct
media_device
struct pci_dev *pci_dev
pointer to struct pci_dev
const char *name
media device name. If
NULL
, the routine will use the default name for the pci device, given by pci_name() macro.
-
void
__media_device_usb_init
(struct media_device *mdev, struct usb_device *udev, const char *board_name, const char *driver_name)¶ create and initialize a struct
media_device
from a PCI device.
Parameters
struct media_device *mdev
pointer to struct
media_device
struct usb_device *udev
pointer to struct usb_device
const char *board_name
media device name. If
NULL
, the routine will use the usb product name, if available.const char *driver_name
name of the driver. if
NULL
, the routine will use the name given byudev->dev->driver->name
, with is usually the wrong thing to do.
Description
Note
It is better to call media_device_usb_init()
instead, as
such macro fills driver_name with KBUILD_MODNAME
.
-
media_device_usb_init
(mdev, udev, name)¶ create and initialize a struct
media_device
from a PCI device.
Parameters
mdev
pointer to struct
media_device
udev
pointer to struct usb_device
name
media device name. If
NULL
, the routine will use the usb product name, if available.
Description
This macro calls media_device_usb_init()
passing the
media_device_usb_init()
driver_name parameter filled with
KBUILD_MODNAME
.
-
struct
media_file_operations
¶ Media device file operations
Definition
struct media_file_operations {
struct module *owner;
ssize_t (*read) (struct file *, char __user *, size_t, loff_t *);
ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *);
__poll_t (*poll) (struct file *, struct poll_table_struct *);
long (*ioctl) (struct file *, unsigned int, unsigned long);
long (*compat_ioctl) (struct file *, unsigned int, unsigned long);
int (*open) (struct file *);
int (*release) (struct file *);
};
Members
owner
should be filled with
THIS_MODULE
read
pointer to the function that implements read() syscall
write
pointer to the function that implements write() syscall
poll
pointer to the function that implements poll() syscall
ioctl
pointer to the function that implements ioctl() syscall
compat_ioctl
pointer to the function that will handle 32 bits userspace calls to the ioctl() syscall on a Kernel compiled with 64 bits.
open
pointer to the function that implements open() syscall
release
pointer to the function that will release the resources allocated by the open function.
-
struct
media_devnode
¶ Media device node
Definition
struct media_devnode {
struct media_device *media_dev;
const struct media_file_operations *fops;
struct device dev;
struct cdev cdev;
struct device *parent;
int minor;
unsigned long flags;
void (*release)(struct media_devnode *devnode);
};
Members
media_dev
pointer to struct
media_device
fops
pointer to struct
media_file_operations
with media device opsdev
pointer to struct
device
containing the media controller devicecdev
struct cdev pointer character device
parent
parent device
minor
device node minor number
flags
flags, combination of the
MEDIA_FLAG_*
constantsrelease
release callback called at the end of
media_devnode_release()
routine at media-device.c.
Description
This structure represents a media-related device node.
The parent is a physical device. It must be set by core or device drivers before registering the node.
-
int
media_devnode_register
(struct media_device *mdev, struct media_devnode *devnode, struct module *owner)¶ register a media device node
Parameters
struct media_device *mdev
struct media_device
we want to register a device nodestruct media_devnode *devnode
media device node structure we want to register
struct module *owner
should be filled with
THIS_MODULE
Description
The registration code assigns minor numbers and registers the new device node with the kernel. An error is returned if no free minor number can be found, or if the registration of the device node fails.
Zero is returned on success.
Note that if the media_devnode_register call fails, the release() callback of the media_devnode structure is not called, so the caller is responsible for freeing any data.
-
void
media_devnode_unregister_prepare
(struct media_devnode *devnode)¶ clear the media device node register bit
Parameters
struct media_devnode *devnode
the device node to prepare for unregister
Description
This clears the passed device register bit. Future open calls will be met
with errors. Should be called before media_devnode_unregister()
to avoid
races with unregister and device file open calls.
This function can safely be called if the device node has never been registered or has already been unregistered.
-
void
media_devnode_unregister
(struct media_devnode *devnode)¶ unregister a media device node
Parameters
struct media_devnode *devnode
the device node to unregister
Description
This unregisters the passed device. Future open calls will be met with errors.
Should be called after media_devnode_unregister_prepare()
-
struct media_devnode *
media_devnode_data
(struct file *filp)¶ returns a pointer to the
media_devnode
Parameters
struct file *filp
pointer to struct
file
-
int
media_devnode_is_registered
(struct media_devnode *devnode)¶ returns true if
media_devnode
is registered; false otherwise.
Parameters
struct media_devnode *devnode
pointer to struct
media_devnode
.
Note
If mdev is NULL, it also returns false.
Error
kernel-doc missing
-
enum
media_request_state
¶ media request state
Constants
MEDIA_REQUEST_STATE_IDLE
Idle
MEDIA_REQUEST_STATE_VALIDATING
Validating the request, no state changes allowed
MEDIA_REQUEST_STATE_QUEUED
Queued
MEDIA_REQUEST_STATE_COMPLETE
Completed, the request is done
MEDIA_REQUEST_STATE_CLEANING
Cleaning, the request is being re-inited
MEDIA_REQUEST_STATE_UPDATING
The request is being updated, i.e. request objects are being added, modified or removed
NR_OF_MEDIA_REQUEST_STATE
The number of media request states, used internally for sanity check purposes
-
struct
media_request
¶ Media device request
Definition
struct media_request {
struct media_device *mdev;
struct kref kref;
char debug_str[TASK_COMM_LEN + 11];
enum media_request_state state;
unsigned int updating_count;
unsigned int access_count;
struct list_head objects;
unsigned int num_incomplete_objects;
wait_queue_head_t poll_wait;
spinlock_t lock;
};
Members
mdev
Media device this request belongs to
kref
Reference count
debug_str
Prefix for debug messages (process name:fd)
state
The state of the request
updating_count
count the number of request updates that are in progress
access_count
count the number of request accesses that are in progress
objects
List of struct media_request_object request objects
num_incomplete_objects
The number of incomplete objects in the request
poll_wait
Wait queue for poll
lock
Serializes access to this struct
-
int
media_request_lock_for_access
(struct media_request *req)¶ Lock the request to access its objects
Parameters
struct media_request *req
The media request
Description
Use before accessing a completed request. A reference to the request must be held during the access. This usually takes place automatically through a file handle. Use media_request_unlock_for_access when done.
-
void
media_request_unlock_for_access
(struct media_request *req)¶ Unlock a request previously locked for access
Parameters
struct media_request *req
The media request
Description
Unlock a request that has previously been locked using media_request_lock_for_access.
-
int
media_request_lock_for_update
(struct media_request *req)¶ Lock the request for updating its objects
Parameters
struct media_request *req
The media request
Description
Use before updating a request, i.e. adding, modifying or removing a request object in it. A reference to the request must be held during the update. This usually takes place automatically through a file handle. Use media_request_unlock_for_update when done.
-
void
media_request_unlock_for_update
(struct media_request *req)¶ Unlock a request previously locked for update
Parameters
struct media_request *req
The media request
Description
Unlock a request that has previously been locked using media_request_lock_for_update.
-
void
media_request_get
(struct media_request *req)¶ Get the media request
Parameters
struct media_request *req
The media request
Description
Get the media request.
-
void
media_request_put
(struct media_request *req)¶ Put the media request
Parameters
struct media_request *req
The media request
Description
Put the media request. The media request will be released when the refcount reaches 0.
-
struct media_request *
media_request_get_by_fd
(struct media_device *mdev, int request_fd)¶ Get a media request by fd
Parameters
struct media_device *mdev
Media device this request belongs to
int request_fd
The file descriptor of the request
Description
Get the request represented by request_fd that is owned by the media device.
Return a -EBADR error pointer if requests are not supported by this driver. Return -EINVAL if the request was not found. Return the pointer to the request if found: the caller will have to call media_request_put when it finished using the request.
-
int
media_request_alloc
(struct media_device *mdev, int *alloc_fd)¶ Allocate the media request
Parameters
struct media_device *mdev
Media device this request belongs to
int *alloc_fd
Store the request’s file descriptor in this int
Description
Allocated the media request and put the fd in alloc_fd.
-
struct
media_request_object_ops
¶ Media request object operations
Definition
struct media_request_object_ops {
int (*prepare)(struct media_request_object *object);
void (*unprepare)(struct media_request_object *object);
void (*queue)(struct media_request_object *object);
void (*unbind)(struct media_request_object *object);
void (*release)(struct media_request_object *object);
};
Members
prepare
Validate and prepare the request object, optional.
unprepare
Unprepare the request object, optional.
queue
Queue the request object, optional.
unbind
Unbind the request object, optional.
release
Release the request object, required.
-
struct
media_request_object
¶ An opaque object that belongs to a media request
Definition
struct media_request_object {
const struct media_request_object_ops *ops;
void *priv;
struct media_request *req;
struct list_head list;
struct kref kref;
bool completed;
};
Members
ops
object’s operations
priv
object’s priv pointer
req
the request this object belongs to (can be NULL)
list
List entry of the object for struct media_request
kref
Reference count of the object, acquire before releasing req->lock
completed
If true, then this object was completed.
Description
An object related to the request. This struct is always embedded in another struct that contains the actual data for this request object.
-
void
media_request_object_get
(struct media_request_object *obj)¶ Get a media request object
Parameters
struct media_request_object *obj
The object
Description
Get a media request object.
-
void
media_request_object_put
(struct media_request_object *obj)¶ Put a media request object
Parameters
struct media_request_object *obj
The object
Description
Put a media request object. Once all references are gone, the object’s memory is released.
-
struct media_request_object *
media_request_object_find
(struct media_request *req, const struct media_request_object_ops *ops, void *priv)¶ Find an object in a request
Parameters
struct media_request *req
The media request
const struct media_request_object_ops *ops
Find an object with this ops value
void *priv
Find an object with this priv value
Description
Both ops and priv must be non-NULL.
Returns the object pointer or NULL if not found. The caller must
call media_request_object_put()
once it finished using the object.
Since this function needs to walk the list of objects it takes the req->lock spin lock to make this safe.
-
void
media_request_object_init
(struct media_request_object *obj)¶ Initialise a media request object
Parameters
struct media_request_object *obj
The object
Description
Initialise a media request object. The object will be released using the release callback of the ops once it has no references (this function initialises references to one).
-
int
media_request_object_bind
(struct media_request *req, const struct media_request_object_ops *ops, void *priv, bool is_buffer, struct media_request_object *obj)¶ Bind a media request object to a request
Parameters
struct media_request *req
The media request
const struct media_request_object_ops *ops
The object ops for this object
void *priv
A driver-specific priv pointer associated with this object
bool is_buffer
Set to true if the object a buffer object.
struct media_request_object *obj
The object
Description
Bind this object to the request and set the ops and priv values of
the object so it can be found later with media_request_object_find()
.
Every bound object must be unbound or completed by the kernel at some point in time, otherwise the request will never complete. When the request is released all completed objects will be unbound by the request core code.
Buffer objects will be added to the end of the request’s object list, non-buffer objects will be added to the front of the list. This ensures that all buffer objects are at the end of the list and that all non-buffer objects that they depend on are processed first.
-
void
media_request_object_unbind
(struct media_request_object *obj)¶ Unbind a media request object
Parameters
struct media_request_object *obj
The object
Description
Unbind the media request object from the request.
-
void
media_request_object_complete
(struct media_request_object *obj)¶ Mark the media request object as complete
Parameters
struct media_request_object *obj
The object
Description
Mark the media request object as complete. Only bound objects can be completed.
-
struct media_device *
media_device_usb_allocate
(struct usb_device *udev, const char *module_name, struct module *owner)¶ Allocate and return struct
media
device
Parameters
struct usb_device *udev
struct
usb_device
pointerconst char *module_name
should be filled with
KBUILD_MODNAME
struct module *owner
struct module pointer
THIS_MODULE
for the driver.THIS_MODULE
is null for a built-in driver. It is safe even whenTHIS_MODULE
is null.
Description
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.
-
void
media_device_delete
(struct media_device *mdev, const char *module_name, struct module *owner)¶ Release media device. Calls kref_put().
Parameters
struct media_device *mdev
struct
media_device
pointerconst char *module_name
should be filled with
KBUILD_MODNAME
struct module *owner
struct module pointer
THIS_MODULE
for the driver.THIS_MODULE
is null for a built-in driver. It is safe even whenTHIS_MODULE
is null.
Description
This interface should be called to put Media Device Instance kref.