4.1.1. Abstract media device model¶

Discovering a device internal topology, and configuring it at runtime, is oneof the goals of the media framework. To achieve this, hardware devices aremodelled as an oriented graph of building blocks called entities connectedthrough pads.

An entity is a basic media hardware building block. It can correspond toa large variety of logical blocks such as physical hardware devices(CMOS sensor for instance), logical hardware devices (a building blockin a System-on-Chip image processing pipeline), DMA channels or physicalconnectors.

A pad is a connection endpoint through which an entity can interact withother entities. Data (not restricted to video) produced by an entityflows from the entity’s output to one or more entity inputs. Pads shouldnot be confused with physical pins at chip boundaries.

A link is a point-to-point oriented connection between two pads, eitheron the same entity or on different entities. Data flows from a sourcepad to a sink pad.

4.1.2. Media device¶

A media device is represented by a structmedia_deviceinstance, defined ininclude/media/media-device.h.Allocation of the structure is handled by the media device driver, usually byembedding themedia_device instance in a larger driver-specificstructure.

Drivers register media device instances by calling__media_device_register() via the macromedia_device_register()and unregistered by callingmedia_device_unregister().

4.1.3. Entities¶

Entities are represented by a structmedia_entityinstance, defined ininclude/media/media-entity.h. The structure is usuallyembedded into a higher-level structure, such asv4l2_subdev orvideo_deviceinstances, although drivers can allocate entities directly.

Drivers initialize entity pads by callingmedia_entity_pads_init().

Drivers register entities with a media device by callingmedia_device_register_entity()and unregistered by callingmedia_device_unregister_entity().

4.1.4. Interfaces¶

Interfaces are represented by astructmedia_interface instance, defined ininclude/media/media-entity.h. Currently, only one type of interface isdefined: a device node. Such interfaces are represented by astructmedia_intf_devnode.

Drivers initialize and create device node interfaces by callingmedia_devnode_create()and remove them by calling:media_devnode_remove().

4.1.5. Pads¶

Pads are represented by a structmedia_pad instance,defined ininclude/media/media-entity.h. Each entity stores its pads ina pads array managed by the entity driver. Drivers usually embed the array ina driver-specific structure.

Pads are identified by their entity and their 0-based index in the padsarray.

Both information are stored in the structmedia_pad,making the structmedia_pad pointer the canonical wayto 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.

4.1.6. Links¶

Links are represented by a structmedia_link instance,defined ininclude/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 pointsto all links originating at or targeting any of its pads.A given link is thus stored twice, once in the source entity and once inthe target entity.

Drivers create pad to pad links by calling:media_create_pad_link() and remove withmedia_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 withmedia_remove_intf_links().

Links have flags that describe the link capabilities and state. Thevalid values are described atmedia_create_pad_link() andmedia_create_intf_link().

4.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 usethe media_device_for_each_entity macro, defined ininclude/media/media-device.h.

structmedia_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 bereached only through enabled links starting at a given entity. The mediaframework provides a depth-first graph traversal API for that purpose.

Drivers initiate a graph traversal by callingmedia_graph_walk_start()

The graph structure, provided by the caller, is initialized to start graphtraversal at the given entity.

Drivers can then retrieve the next entity by callingmedia_graph_walk_next()

When the graph traversal is complete the function will returnNULL.

Graph traversal can be interrupted at any moment. No cleanup function callis required and the graph structure can be freed normally.

Helper functions can be used to find a link between two given pads, or a padconnected to another pad through an enabled linkmedia_entity_find_link() andmedia_entity_remote_pad().

4.1.8. Use count and power handling¶

Due to the wide differences between drivers regarding power managementneeds, the media controller does not implement power management. However,the structmedia_entity includes ause_countfield that media driverscan use to track the number of users of every entity for power managementneeds.

Themedia_entity.use_count field is owned bymedia drivers and must not betouched by entity drivers. Access to the field must be protected by themedia_device.graph_mutex lock.

4.1.9. Links setup¶

Link properties can be modified at runtime by callingmedia_entity_setup_link().

4.1.10. Pipelines and media streams¶

When starting streaming, drivers must notify all entities in the pipeline toprevent link states from being modified during streaming by callingmedia_pipeline_start().

The function will mark all entities connected to the given entity throughenabled links, either directly or indirectly, as streaming.

The structmedia_pipeline instance pointed to bythe pipe argument will be stored in every entity in the pipeline.Drivers should embed the structmedia_pipelinein higher-level pipeline structures and can then access thepipeline through the structmedia_entitypipe field.

Calls tomedia_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 withmedia_pipeline_stop().

If multiple calls tomedia_pipeline_start() have beenmade the same number ofmedia_pipeline_stop() callsare required to stop streaming.Themedia_entity.pipe field is reset toNULL on the lastnested stop call.

Link configuration will fail with-EBUSY by default if either end of thelink is a streaming entity. Links that can be modified while streaming mustbe marked with theMEDIA_LNK_FL_DYNAMIC flag.

If other operations need to be disallowed on streaming entities (such aschanging entities configuration parameters) drivers can explicitly check themedia_entity stream_count field to find out if an entity is streaming. Thisoperation must be done with the media_device graph_mutex held.

4.1.11. Link validation¶

Link validation is performed bymedia_pipeline_start()for any entity which has sink pads in the pipeline. Themedia_entity.link_validate() callback is used for thatpurpose. Inlink_validate() callback, entity driver should checkthat the properties of the source pad of the connected entity and its ownsink pad match. It is up to the type of the entity (and in the end, theproperties of the hardware) what matching actually means.

Subsystems should facilitate link validation by providing subsystem specifichelper functions to provide easy access for commonly needed information, andin the end provide a way to use driver-specific callbacks.

4.1.12. Media Controller Device Allocator API¶

When the media device belongs to more than one driver, the shared mediadevice is allocated with the shared struct device as the key for look ups.

The shared media device should stay in registered state until the lastdriver unregisters it. In addition, the media device should be released whenall the references are released. Each driver gets a reference to the mediadevice during probe, when it allocates the media device. If media device isalready allocated, the allocate API bumps up the refcount and returns theexisting media device. The driver puts the reference back in its disconnectroutine when it callsmedia_device_delete().

The media device is unregistered and cleaned up from the kref put handler toensure that the media device stays in registered state until the last driverunregisters the media device.

Driver Usage

Drivers should use the appropriate media-core routines to manage the sharedmedia device life-time handling the two states:1. allocate -> register -> delete2. get reference to already registered device -> delete

callmedia_device_delete() routine to make sure the shared mediadevice delete is handled correctly.

driver probe:Callmedia_device_usb_allocate() to allocate or get a referenceCallmedia_device_register(), if media devnode isn’t registered

driver disconnect:Callmedia_device_delete() to free the media_device. Freeing ishandled by the kref put handler.

4.1.13. API Definitions¶

structmedia_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 getregistered with the media device. This handler is intended for creatinglinks between existing entities and should not create entities and registerthem.

structmedia_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 iscalled with the graph_mutex held.

req_alloc

Allocate a request. Set this if you need to allocate a structlarger then struct media_request.req_alloc andreq_free musteither both be set or both be NULL.

req_free

Free a request. Set this ifreq_alloc was set as well, leaveto NULL otherwise.

req_validate

Validate a request, but do not queue yet. The req_queue_mutexlock is held when this op is called.

req_queue

Queue a validated request, cannot fail. If something goeswrong when queueing this request then it should be markedas such internally in the driver and any related buffersmust 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 afterall other object types are queued: queueing a buffer kickstartsthe request processing, so all other objects related to therequest (and thus the buffer) must be available to the driver.And once a buffer is queued, then the driver can completeor delete objects from the request before req_queue exits.

structmedia_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 toMEDIA_IOC_DEVICE_INFO will returndev->driver->name.This is needed for USB drivers for example, as otherwisethey’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 graphtopology. 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 traversalalgorithms

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 data

pm_count_walk

Graph walk for power state walk. Access serialised usinggraph_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 easyaccess to entities and provides basic media device-level support. Thestructure can be allocated directly or embedded in a larger structure.

The parentdev is a physical device. It must be set before registering themedia device.

model is a descriptive model name exported through sysfs. It doesn’t have tobe unique.

enable_source is a handler to find source entity for thesink entity and activate the link between them if sourceentity is free. Drivers should call this handler beforeaccessing the source.

disable_source is a handler to find source entity for thesink entity and deactivate the link between them. Driversshould call this handler to release the source.

Use-case: find tuner entity connected to the decoderentity and check if it is available, and activate thelink between them fromenable_source and deactivatefromdisable_source.

intmedia_entity_enum_init(structmedia_entity_enum * ent_enum, structmedia_device * mdev)¶

Initialise an entity enumeration

Parameters

structmedia_entity_enum*ent_enum

Entity enumeration to be initialised

structmedia_device*mdev

The related media device

Return

zero on success or a negative error code.

voidmedia_device_init(structmedia_device * mdev)¶

Initializes a media device element

Parameters

structmedia_device*mdev

pointer to structmedia_device

Description

This function initializes the media device prior to its registration.The media device initialization and registration is split in two functionsto avoid race conditions and make the media device available to user-spacebefore the media graph has been completed.

So drivers need to first initialize the media device, register any entitywithin the media device, create pad to pad links and then finally registerthe media device by callingmedia_device_register() as a final step.

voidmedia_device_cleanup(structmedia_device * mdev)¶

Cleanups a media device element

Parameters

structmedia_device*mdev

pointer to structmedia_device

Description

This function that will destroy the graph_mutex that isinitialized inmedia_device_init().

int__media_device_register(structmedia_device * mdev, struct module * owner)¶

Registers a media device element

Parameters

structmedia_device*mdev

pointer to structmedia_device

structmodule*owner

should be filled withTHIS_MODULE

Description

Users, should, instead, call themedia_device_register() macro.

The caller is responsible for initializing themedia_device structurebefore registration. The following fields ofmedia_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 aNUL-terminated UTF-8 string. The device/model revision must not bestored in this field.

The following fields are optional:

• media_entity.serial is a unique serial number stored as aNUL-terminated ASCII string. The field is big enough to store a GUIDin text form. If the hardware doesn’t provide a unique serial numberthis field must be left empty.
• media_entity.bus_info represents the location of the device in thesystem as a NUL-terminated ASCII string. For PCI/PCIe devicesmedia_entity.bus_info must be set to “PCI:” (or “PCIe:”) followed bythe value of pci_name(). For USB devices,theusb_make_path() functionmust be used. This field is used by applications to distinguish betweenotherwise identical devices that don’t provide a serial number.
• media_entity.hw_revision is the hardware device revision in adriver-specific format. When possible the revision should be formattedwith the KERNEL_VERSION() macro.

Return

returns zero on success or a negative error code.

media_device_register(mdev)¶

Registers a media device element

Parameters

mdev

pointer to structmedia_device

Description

This macro calls__media_device_register() passingTHIS_MODULE asthe__media_device_register() second argument (owner).

voidmedia_device_unregister(structmedia_device * mdev)¶

Unregisters a media device element

Parameters

structmedia_device*mdev

pointer to structmedia_device

Description

It is safe to call this function on an unregistered (but initialised)media device.

intmedia_device_register_entity(structmedia_device * mdev, structmedia_entity * entity)¶

registers a media entity inside a previously registered media device.

Parameters

structmedia_device*mdev

pointer to structmedia_device

structmedia_entity*entity

pointer to structmedia_entity to be registered

Description

Entities are identified by a unique positive integer ID. The mediacontroller framework will such ID automatically. IDs are not guaranteedto be contiguous, and the ID number can change on newer Kernel versions.So, neither the driver nor userspace should hardcode ID numbers to referto the entities, but, instead, use the framework to find the ID, whenneeded.

The media_entity name, type and flags fields should be initialized beforecallingmedia_device_register_entity(). Entities embedded in higher-levelstandard structures can have some of those fields set by the higher-levelframework.

If the device has pads,media_entity_pads_init() should be called beforethis function. Otherwise, themedia_entity.pad andmedia_entity.num_padsshould 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 thedefault camera sensor.

voidmedia_device_unregister_entity(structmedia_entity * entity)¶

unregisters a media entity.

Parameters

structmedia_entity*entity

pointer to structmedia_entity to be unregistered

Description

All links associated with the entity and all PADs are automaticallyunregistered from the media_device when this function is called.

Unregistering an entity will not change the IDs of the other entities andthe previoully used ID will never be reused for a newly registered entities.

When a media device is unregistered, all its entities are unregisteredautomatically. No manual entities unregistration is then required.

intmedia_device_register_entity_notify(structmedia_device * mdev, structmedia_entity_notify * nptr)¶

Registers a media entity_notify callback

Parameters

structmedia_device*mdev

The media device

structmedia_entity_notify*nptr

The media_entity_notify

Description

voidmedia_device_unregister_entity_notify(structmedia_device * mdev, structmedia_entity_notify * nptr)¶

Unregister a media entity notify callback

Parameters

structmedia_device*mdev

The media device

structmedia_entity_notify*nptr

The media_entity_notify

voidmedia_device_pci_init(structmedia_device * mdev, struct pci_dev * pci_dev, const char * name)¶

create and initialize a structmedia_device from a PCI device.

Parameters

structmedia_device*mdev

pointer to structmedia_device

structpci_dev*pci_dev

pointer to struct pci_dev

constchar*name

media device name. IfNULL, the routine will use the defaultname for the pci device, given by pci_name() macro.

void__media_device_usb_init(structmedia_device * mdev, structusb_device * udev, const char * board_name, const char * driver_name)¶

create and initialize a structmedia_device from a PCI device.

Parameters

structmedia_device*mdev

pointer to structmedia_device

structusb_device*udev

pointer to struct usb_device

constchar*board_name

media device name. IfNULL, the routine will use the usbproduct name, if available.

constchar*driver_name

name of the driver. ifNULL, the routine will use the namegiven byudev->dev->driver->name, with is usually the wrongthing to do.

Description

media_device_usb_init(mdev,udev,name)¶

create and initialize a structmedia_device from a PCI device.

Parameters

mdev

pointer to structmedia_device

udev

pointer to struct usb_device

name

media device name. IfNULL, the routine will use the usbproduct name, if available.

Description

This macro callsmedia_device_usb_init() passing themedia_device_usb_init()driver_name parameter filled withKBUILD_MODNAME.

structmedia_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 withTHIS_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 userspacecalls 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 allocatedby theopen function.

structmedia_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 structmedia_device

fops

pointer to structmedia_file_operations with media device ops

dev

pointer to structdevice containing the media controller device

cdev

struct cdev pointer character device

parent

parent device

minor

device node minor number

flags

flags, combination of theMEDIA_FLAG_* constants

release

release callback called at the end ofmedia_devnode_release()routine at media-device.c.

Description

This structure represents a media-related device node.

Theparent is a physical device. It must be set by core or device driversbefore registering the node.

intmedia_devnode_register(structmedia_device * mdev, structmedia_devnode * devnode, struct module * owner)¶

register a media device node

Parameters

structmedia_device*mdev

struct media_device we want to register a device node

structmedia_devnode*devnode

media device node structure we want to register

structmodule*owner

should be filled withTHIS_MODULE

Description

The registration code assigns minor numbers and registers the new device nodewith 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 ofthe media_devnode structure isnot called, so the caller is responsible forfreeing any data.

voidmedia_devnode_unregister_prepare(structmedia_devnode * devnode)¶

clear the media device node register bit

Parameters

structmedia_devnode*devnode

the device node to prepare for unregister

Description

This clears the passed device register bit. Future open calls will be metwith errors. Should be called beforemedia_devnode_unregister() to avoidraces with unregister and device file open calls.

This function can safely be called if the device node has never beenregistered or has already been unregistered.

voidmedia_devnode_unregister(structmedia_devnode * devnode)¶

unregister a media device node

Parameters

structmedia_devnode*devnode

the device node to unregister

Description

This unregisters the passed device. Future open calls will be met witherrors.

Should be called aftermedia_devnode_unregister_prepare()

structmedia_devnode *media_devnode_data(struct file * filp)¶

returns a pointer to themedia_devnode

Parameters

structfile*filp

pointer to structfile

intmedia_devnode_is_registered(structmedia_devnode * devnode)¶

returns true ifmedia_devnode is registered; false otherwise.

Parameters

structmedia_devnode*devnode

pointer to structmedia_devnode.

Note

If mdev is NULL, it also returns false.

enummedia_gobj_type¶

type of a graph object

Constants

MEDIA_GRAPH_ENTITY

Identify a media entity

MEDIA_GRAPH_PAD

Identify a media pad

MEDIA_GRAPH_LINK

Identify a media link

MEDIA_GRAPH_INTF_DEVNODE

Identify a media Kernel API interface viaa device node

structmedia_gobj¶

Define a graph object.

Definition

struct media_gobj {  struct media_device     *mdev;  u32 id;  struct list_head        list;};

Members

mdev

Pointer to the structmedia_device that owns the object

id

Non-zero object ID identifier. The ID should be uniqueinside a media_device, as it is composed byMEDIA_BITS_PER_TYPE to store the type plusMEDIA_BITS_PER_ID to store the ID

list

List entry stored in one of the per-type mdev object lists

Description

All objects on the media graph should have this struct embedded

structmedia_entity_enum¶

An enumeration of media entities.

Definition

struct media_entity_enum {  unsigned long *bmap;  int idx_max;};

Members

bmap

Bit map in which each bit represents one entity at structmedia_entity->internal_idx.

idx_max

Number of bits in bmap

structmedia_graph¶

Media graph traversal state

Definition

struct media_graph {  struct {    struct media_entity *entity;    struct list_head *link;  } stack[MEDIA_ENTITY_ENUM_MAX_DEPTH];  struct media_entity_enum ent_enum;  int top;};

Members

stack

Graph traversal stack; the stack contains informationon the path the media entities to be walked and thelinks through which they were reached.

stack.entity

pointer tostructmedia_entity at the graph.

stack.link

pointer tostructlist_head.

ent_enum

Visited entities

top

The top of the stack

structmedia_pipeline¶

Media pipeline related information

Definition

struct media_pipeline {  int streaming_count;  struct media_graph graph;};

Members

streaming_count

Streaming start count - streaming stop count

graph

Media graph walk during pipeline start / stop

structmedia_link¶

A link object part of a media graph.

Definition

struct media_link {  struct media_gobj graph_obj;  struct list_head list;  union {    struct media_gobj *gobj0;    struct media_pad *source;    struct media_interface *intf;  };  union {    struct media_gobj *gobj1;    struct media_pad *sink;    struct media_entity *entity;  };  struct media_link *reverse;  unsigned long flags;  bool is_backlink;};

Members

graph_obj

Embedded structure containing the media object common data

list

Linked list associated with an entity or an interface thatowns the link.

{unnamed_union}

anonymous

gobj0

Part of a union. Used to get the pointer for the firstgraph_object of the link.

source

Part of a union. Used only if the first object (gobj0) isa pad. In that case, it represents the source pad.

intf

Part of a union. Used only if the first object (gobj0) isan interface.

{unnamed_union}

anonymous

gobj1

Part of a union. Used to get the pointer for the secondgraph_object of the link.

sink

Part of a union. Used only if the second object (gobj1) isa pad. In that case, it represents the sink pad.

entity

Part of a union. Used only if the second object (gobj1) isan entity.

reverse

Pointer to the link for the reverse direction of a pad to padlink.

flags

Link flags, as defined in uapi/media.h (MEDIA_LNK_FL_*)

is_backlink

Indicate if the link is a backlink.

enummedia_pad_signal_type¶

type of the signal inside a media pad

Constants

PAD_SIGNAL_DEFAULT

Default signal. Use this when all inputs or all outputs areuniquely identified by the pad number.

PAD_SIGNAL_ANALOG

The pad contains an analog signal. It can be Radio Frequency,Intermediate Frequency, a baseband signal or sub-cariers.Tuner inputs, IF-PLL demodulators, composite and s-video signalsshould use it.

PAD_SIGNAL_DV

Contains a digital video signal, with can be a bitstream of samplestaken from an analog TV video source. On such case, it usuallycontains the VBI data on it.

PAD_SIGNAL_AUDIO

Contains an Intermediate Frequency analog signal from an audiosub-carrier or an audio bitstream. IF signals are provided by tunersand consumed by audio AM/FM decoders. Bitstream audio is provided byan audio decoder.

structmedia_pad¶

A media pad graph object.

Definition

struct media_pad {  struct media_gobj graph_obj;  struct media_entity *entity;  u16 index;  enum media_pad_signal_type sig_type;  unsigned long flags;};

Members

graph_obj

Embedded structure containing the media object common data

entity

Entity this pad belongs to

index

Pad index in the entity pads array, numbered from 0 to n

sig_type

Type of the signal inside a media pad

flags

Pad flags, as defined ininclude/uapi/linux/media.h(seek forMEDIA_PAD_FL_*)

structmedia_entity_operations¶

Media entity operations

Definition

struct media_entity_operations {  int (*get_fwnode_pad)(struct media_entity *entity, struct fwnode_endpoint *endpoint);  int (*link_setup)(struct media_entity *entity,const struct media_pad *local, const struct media_pad *remote, u32 flags);  int (*link_validate)(struct media_link *link);};

Members

get_fwnode_pad

Return the pad number based on a fwnode endpoint ora negative value on error. This operation can be usedto map a fwnode to a media pad number. Optional.

link_setup

Notify the entity of link changes. The operation canreturn an error, in which case link setup will becancelled. Optional.

link_validate

Return whether a link is valid from the entity point ofview. Themedia_pipeline_start() functionvalidates all links by calling this operation. Optional.

Description

enummedia_entity_type¶

Media entity type

Constants

MEDIA_ENTITY_TYPE_BASE

The entity isn’t embedded in another subsystem structure.

MEDIA_ENTITY_TYPE_VIDEO_DEVICE

The entity is embedded in a struct video_device instance.

MEDIA_ENTITY_TYPE_V4L2_SUBDEV

The entity is embedded in a struct v4l2_subdev instance.

Description

Media entity objects are often not instantiated directly, but the mediaentity structure is inherited by (through embedding) other subsystem-specificstructures. The media entity type identifies the type of the subclassstructure that implements a media entity instance.

This allows runtime type identification of media entities and safe casting tothe correct object type. For instance, a media entity structure instanceembedded in a v4l2_subdev structure instance will have the typeMEDIA_ENTITY_TYPE_V4L2_SUBDEV and can safely be cast to av4l2_subdevstructure using thecontainer_of() macro.

structmedia_entity¶

A media entity graph object.

Definition

struct media_entity {  struct media_gobj graph_obj;  const char *name;  enum media_entity_type obj_type;  u32 function;  unsigned long flags;  u16 num_pads;  u16 num_links;  u16 num_backlinks;  int internal_idx;  struct media_pad *pads;  struct list_head links;  const struct media_entity_operations *ops;  int stream_count;  int use_count;  struct media_pipeline *pipe;  union {    struct {      u32 major;      u32 minor;    } dev;  } info;};

Members

graph_obj

Embedded structure containing the media object common data.

name

Entity name.

obj_type

Type of the object that implements the media_entity.

function

Entity main function, as defined ininclude/uapi/linux/media.h(seek forMEDIA_ENT_F_*)

flags

Entity flags, as defined ininclude/uapi/linux/media.h(seek forMEDIA_ENT_FL_*)

num_pads

Number of sink and source pads.

num_links

Total number of links, forward and back, enabled and disabled.

num_backlinks

Number of backlinks

internal_idx

An unique internal entity specific number. The numbers arere-used if entities are unregistered or registered again.

pads

Pads array with the size defined bynum_pads.

links

List of data links.

ops

Entity operations.

stream_count

Stream count for the entity.

use_count

Use count for the entity.

pipe

Pipeline this entity belongs to.

info

Union with devnode information. Kept just for backwardcompatibility.

info.dev

Contains device major and minor info.

info.dev.major

device node major, if the device is a devnode.

info.dev.minor

device node minor, if the device is a devnode.

Description

structmedia_interface¶

A media interface graph object.

Definition

struct media_interface {  struct media_gobj               graph_obj;  struct list_head                links;  u32 type;  u32 flags;};

Members

graph_obj

embedded graph object

links

List of links pointing to graph entities

type

Type of the interface as defined ininclude/uapi/linux/media.h(seek forMEDIA_INTF_T_*)

flags

Interface flags as defined ininclude/uapi/linux/media.h(seek forMEDIA_INTF_FL_*)

Description

structmedia_intf_devnode¶

A media interface via a device node.

Definition

struct media_intf_devnode {  struct media_interface          intf;  u32 major;  u32 minor;};

Members

intf

embedded interface object

major

Major number of a device node

minor

Minor number of a device node

u32media_entity_id(structmedia_entity * entity)¶

return the media entity graph object id

Parameters

structmedia_entity*entity

pointer tomedia_entity

enummedia_gobj_typemedia_type(structmedia_gobj * gobj)¶

return the media object type

Parameters

structmedia_gobj*gobj

Pointer to the structmedia_gobj graph object

u32media_id(structmedia_gobj * gobj)¶

return the media object ID

Parameters

structmedia_gobj*gobj

Pointer to the structmedia_gobj graph object

u32media_gobj_gen_id(enummedia_gobj_type type, u64 local_id)¶

encapsulates type and ID on at the object ID

Parameters

enummedia_gobj_typetype

object type as define at enummedia_gobj_type.

u64local_id

next ID, from structmedia_device.id.

boolis_media_entity_v4l2_video_device(structmedia_entity * entity)¶

Check if the entity is a video_device

Parameters

structmedia_entity*entity

pointer to entity

Return

true if the entity is an instance of a video_device object and cansafely be cast to a struct video_device using thecontainer_of() macro, orfalse otherwise.

boolis_media_entity_v4l2_subdev(structmedia_entity * entity)¶

Check if the entity is a v4l2_subdev

Parameters

structmedia_entity*entity

pointer to entity

Return

true if the entity is an instance of av4l2_subdev object and cansafely be cast to a structv4l2_subdev using thecontainer_of() macro, orfalse otherwise.

int__media_entity_enum_init(structmedia_entity_enum * ent_enum, int idx_max)¶

Initialise an entity enumeration

Parameters

structmedia_entity_enum*ent_enum

Entity enumeration to be initialised

intidx_max

Maximum number of entities in the enumeration

Return

Returns zero on success or a negative error code.

voidmedia_entity_enum_cleanup(structmedia_entity_enum * ent_enum)¶

Release resources of an entity enumeration

Parameters

structmedia_entity_enum*ent_enum

Entity enumeration to be released

voidmedia_entity_enum_zero(structmedia_entity_enum * ent_enum)¶

Clear the entire enum

Parameters

structmedia_entity_enum*ent_enum

Entity enumeration to be cleared

voidmedia_entity_enum_set(structmedia_entity_enum * ent_enum, structmedia_entity * entity)¶

Mark a single entity in the enum

Parameters

structmedia_entity_enum*ent_enum

Entity enumeration

structmedia_entity*entity

Entity to be marked

voidmedia_entity_enum_clear(structmedia_entity_enum * ent_enum, structmedia_entity * entity)¶

Unmark a single entity in the enum

Parameters

structmedia_entity_enum*ent_enum

Entity enumeration

structmedia_entity*entity

Entity to be unmarked

boolmedia_entity_enum_test(structmedia_entity_enum * ent_enum, structmedia_entity * entity)¶

Test whether the entity is marked

Parameters

structmedia_entity_enum*ent_enum

Entity enumeration

structmedia_entity*entity

Entity to be tested

Description

Returnstrue if the entity was marked.

boolmedia_entity_enum_test_and_set(structmedia_entity_enum * ent_enum, structmedia_entity * entity)¶

Test whether the entity is marked, and mark it

Parameters

structmedia_entity_enum*ent_enum

Entity enumeration

structmedia_entity*entity

Entity to be tested

Description

Returnstrue if the entity was marked, and mark it before doing so.

boolmedia_entity_enum_empty(structmedia_entity_enum * ent_enum)¶

Test whether the entire enum is empty

Parameters

structmedia_entity_enum*ent_enum

Entity enumeration

Return

true if the entity was empty.

boolmedia_entity_enum_intersects(structmedia_entity_enum * ent_enum1, structmedia_entity_enum * ent_enum2)¶

Test whether two enums intersect

Parameters

structmedia_entity_enum*ent_enum1

First entity enumeration

structmedia_entity_enum*ent_enum2

Second entity enumeration

Return

true if entity enumerationsent_enum1 andent_enum2 intersect,otherwisefalse.

gobj_to_entity(gobj)¶

returns the structmedia_entity pointer from thegobj contained on it.

Parameters

gobj

Pointer to the structmedia_gobj graph object

gobj_to_pad(gobj)¶

returns the structmedia_pad pointer from thegobj contained on it.

Parameters

gobj

Pointer to the structmedia_gobj graph object

gobj_to_link(gobj)¶

returns the structmedia_link pointer from thegobj contained on it.

Parameters

gobj

Pointer to the structmedia_gobj graph object

gobj_to_intf(gobj)¶

returns the structmedia_interface pointer from thegobj contained on it.

Parameters

gobj

Pointer to the structmedia_gobj graph object

intf_to_devnode(intf)¶

returns the struct media_intf_devnode pointer from theintf contained on it.

Parameters

intf

Pointer to structmedia_intf_devnode

voidmedia_gobj_create(structmedia_device * mdev, enummedia_gobj_type type, structmedia_gobj * gobj)¶

Initialize a graph object

Parameters

structmedia_device*mdev

Pointer to themedia_device that contains the object

enummedia_gobj_typetype

Type of the object

structmedia_gobj*gobj

Pointer to the structmedia_gobj graph object

Description

This routine initializes the embedded structmedia_gobj inside amedia graph object. It is called automatically ifmedia_*_createfunction calls are used. However, if the object (entity, link, pad,interface) is embedded on some other object, this function should becalled before registering the object at the media controller.

voidmedia_gobj_destroy(structmedia_gobj * gobj)¶

Stop using a graph object on a media device

Parameters

structmedia_gobj*gobj

Pointer to the structmedia_gobj graph object

Description

This should be called by all routines likemedia_device_unregister()that remove/destroy media graph objects.

intmedia_entity_pads_init(structmedia_entity * entity, u16 num_pads, structmedia_pad * pads)¶

Initialize the entity pads

Parameters

structmedia_entity*entity

entity where the pads belong

u16num_pads

total number of sink and source pads

structmedia_pad*pads

Array ofnum_pads pads.

Description

The pads array is managed by the entity driver and passed tomedia_entity_pads_init() where its pointer will be stored in themedia_entity structure.

If no pads are needed, drivers could either directly fillmedia_entity->num_pads with 0 andmedia_entity->pads withNULL or callthis function that will do the same.

As the number of pads is known in advance, the pads array is not allocateddynamically but is managed by the entity driver. Most drivers will embed thepads array in a driver-specific structure, avoiding dynamic allocation.

Drivers must set the direction of every pad in the pads array before callingmedia_entity_pads_init(). The function will initialize the other pads fields.

voidmedia_entity_cleanup(structmedia_entity * entity)¶

free resources associated with an entity

Parameters

structmedia_entity*entity

entity where the pads belong

Description

This function must be called during the cleanup phase after unregisteringthe entity (currently, it does nothing).

intmedia_get_pad_index(structmedia_entity * entity, bool is_sink, enummedia_pad_signal_type sig_type)¶

retrieves a pad index from an entity

Parameters

structmedia_entity*entity

entity where the pads belong

boolis_sink

true if the pad is a sink, false if it is a source

enummedia_pad_signal_typesig_type

type of signal of the pad to be search

Description

This helper function finds the first pad index inside an entity thatsatisfies bothis_sink andsig_type conditions.

On success, return the pad number. If the pad was not found or the mediaentity is a NULL pointer, return -EINVAL.

Return

intmedia_create_pad_link(structmedia_entity * source, u16 source_pad, structmedia_entity * sink, u16 sink_pad, u32 flags)¶

creates a link between two entities.

Parameters

structmedia_entity*source

pointer tomedia_entity of the source pad.

u16source_pad

number of the source pad in the pads array

structmedia_entity*sink

pointer tomedia_entity of the sink pad.

u16sink_pad

number of the sink pad in the pads array.

u32flags

Link flags, as defined ininclude/uapi/linux/media.h( seek forMEDIA_LNK_FL_*)

Description

Valid values for flags:

MEDIA_LNK_FL_ENABLED

Indicates that the link is enabled and can be used to transfer media data.When two or more links target a sink pad, only one of them can beenabled at a time.

MEDIA_LNK_FL_IMMUTABLE

Indicates that the link enabled state can’t be modified at runtime. IfMEDIA_LNK_FL_IMMUTABLE is set, thenMEDIA_LNK_FL_ENABLED must also beset, since an immutable link is always enabled.

intmedia_create_pad_links(const structmedia_device * mdev, const u32 source_function, structmedia_entity * source, const u16 source_pad, const u32 sink_function, structmedia_entity * sink, const u16 sink_pad, u32 flags, const bool allow_both_undefined)¶

creates a link between two entities.

Parameters

conststructmedia_device*mdev

Pointer to the media_device that contains the object

constu32source_function

Function of the source entities. Used only ifsource isNULL.

structmedia_entity*source

pointer tomedia_entity of the source pad. If NULL, it will useall entities that matches thesink_function.

constu16source_pad

number of the source pad in the pads array

constu32sink_function

Function of the sink entities. Used only ifsink is NULL.

structmedia_entity*sink

pointer tomedia_entity of the sink pad. If NULL, it will useall entities that matches thesink_function.

constu16sink_pad

number of the sink pad in the pads array.

u32flags

Link flags, as defined in include/uapi/linux/media.h.

constboolallow_both_undefined

iftrue, then bothsource andsink can be NULL.In such case, it will create a crossbar between all entities thatmatchessource_function to all entities that matchessink_function.Iffalse, it will return 0 and won’t create any link if bothsourceandsink are NULL.

Description

Valid values for flags:

AMEDIA_LNK_FL_ENABLED flag indicates that the link is enabled and can be

used to transfer media data. If multiple links are created and thisflag is passed as an argument, only the first created link will havethis flag.

AMEDIA_LNK_FL_IMMUTABLE flag indicates that the link enabled state can’t

be modified at runtime. IfMEDIA_LNK_FL_IMMUTABLE is set, thenMEDIA_LNK_FL_ENABLED must also be set since an immutable link isalways enabled.

It is common for some devices to have multiple source and/or sink entitiesof the same type that should be linked. Whilemedia_create_pad_link()creates link by link, this function is meant to allow 1:n, n:1 and evencross-bar (n:n) links.

voidmedia_entity_remove_links(structmedia_entity * entity)¶

remove all links associated with an entity

Parameters

structmedia_entity*entity

pointer tomedia_entity

Description

int__media_entity_setup_link(structmedia_link * link, u32 flags)¶

Configure a media link without locking

Parameters

structmedia_link*link

The link being configured

u32flags

Link configuration flags

Description

The bulk of link setup is handled by the two entities connected through thelink. This function notifies both entities of the link configuration change.

If the link is immutable or if the current and new configuration areidentical, return immediately.

The user is expected to hold link->source->parent->mutex. If not,media_entity_setup_link() should be used instead.

intmedia_entity_setup_link(structmedia_link * link, u32 flags)¶

changes the link flags properties in runtime

Parameters

structmedia_link*link

pointer tomedia_link

u32flags

the requested new link flags

Description

The only configurable property is theMEDIA_LNK_FL_ENABLED link flagto enable/disable a link. Links marked with theMEDIA_LNK_FL_IMMUTABLE link flag can not be enabled or disabled.

When a link is enabled or disabled, the media framework calls thelink_setup operation for the two entities at the source and sink of thelink, in that order. If the second link_setup call fails, anotherlink_setup call is made on the first entity to restore the original linkflags.

Media device drivers can be notified of link setup operations by setting themedia_device.link_notify pointer to a callback function. If provided, thenotification callback will be called before enabling and after disablinglinks.

Entity drivers must implement the link_setup operation if any of their linksis non-immutable. The operation must either configure the hardware or storethe configuration information to be applied later.

Link configuration must not have any side effect on other links. If anenabled link at a sink pad prevents another link at the same pad frombeing enabled, the link_setup operation must return-EBUSY and can’timplicitly disable the first enabled link.

structmedia_link *media_entity_find_link(structmedia_pad * source, structmedia_pad * sink)¶

Find a link between two pads

Parameters

structmedia_pad*source

Source pad

structmedia_pad*sink

Sink pad

Return

returns a pointer to the link between the two entities. If nosuch link exists, returnNULL.

structmedia_pad *media_entity_remote_pad(const structmedia_pad * pad)¶

Find the pad at the remote end of a link

Parameters

conststructmedia_pad*pad

Pad at the local end of the link

Description

Search for a remote pad connected to the given pad by iterating over alllinks originating or terminating at that pad until an enabled link is found.

Return

returns a pointer to the pad at the remote end of the first foundenabled link, orNULL if no enabled link has been found.

intmedia_entity_get_fwnode_pad(structmedia_entity * entity, struct fwnode_handle * fwnode, unsigned long direction_flags)¶

Get pad number from fwnode

Parameters

structmedia_entity*entity

The entity

structfwnode_handle*fwnode

Pointer to the fwnode_handle which should be used to find the pad

unsignedlongdirection_flags

Expected direction of the pad, as defined ininclude/uapi/linux/media.h(seek forMEDIA_PAD_FL_*)

Description

This function can be used to resolve the media pad number froma fwnode. This is useful for devices which use more complexmappings of media pads.

If the entity does not implement the get_fwnode_pad() operationthen this function searches the entity for the first pad thatmatches thedirection_flags.

Return

returns the pad number on success or a negative error code.

intmedia_graph_walk_init(structmedia_graph * graph, structmedia_device * mdev)¶

Allocate resources used by graph walk.

Parameters

structmedia_graph*graph

Media graph structure that will be used to walk the graph

structmedia_device*mdev

Pointer to themedia_device that contains the object

voidmedia_graph_walk_cleanup(structmedia_graph * graph)¶

Release resources used by graph walk.

Parameters

structmedia_graph*graph

Media graph structure that will be used to walk the graph

voidmedia_graph_walk_start(structmedia_graph * graph, structmedia_entity * entity)¶

Start walking the media graph at a given entity

Parameters

structmedia_graph*graph

Media graph structure that will be used to walk the graph

structmedia_entity*entity

Starting entity

Description

Before using this function,media_graph_walk_init() must beused to allocate resources used for walking the graph. Thisfunction initializes the graph traversal structure to walk theentities graph starting at the given entity. The traversalstructure must not be modified by the caller during graphtraversal. After the graph walk, the resources must be releasedusingmedia_graph_walk_cleanup().

structmedia_entity *media_graph_walk_next(structmedia_graph * graph)¶

Get the next entity in the graph

Parameters

structmedia_graph*graph

Media graph structure

Description

Perform a depth-first traversal of the given media entities graph.

The graph structure must have been previously initialized with a call tomedia_graph_walk_start().

Return

returns the next entity in the graph orNULL if the whole graphhave been traversed.

intmedia_pipeline_start(structmedia_entity * entity, structmedia_pipeline * pipe)¶

Mark a pipeline as streaming

Parameters

structmedia_entity*entity

Starting entity

structmedia_pipeline*pipe

Media pipeline to be assigned to all entities in the pipeline.

Description

Mark all entities connected to a given entity through enabled links, eitherdirectly or indirectly, as streaming. The given pipeline object is assignedto every entity in the pipeline and stored in the media_entity pipe field.

Calls to this function can be nested, in which case the same number ofmedia_pipeline_stop() calls will be required to stop streaming. Thepipeline pointer must be identical for all nested calls tomedia_pipeline_start().

int__media_pipeline_start(structmedia_entity * entity, structmedia_pipeline * pipe)¶

Mark a pipeline as streaming

Parameters

structmedia_entity*entity

Starting entity

structmedia_pipeline*pipe

Media pipeline to be assigned to all entities in the pipeline.

Description

..note:: This is the non-locking version ofmedia_pipeline_start()

voidmedia_pipeline_stop(structmedia_entity * entity)¶

Mark a pipeline as not streaming

Parameters

structmedia_entity*entity

Starting entity

Description

Mark all entities connected to a given entity through enabled links, eitherdirectly or indirectly, as not streaming. The media_entity pipe field isreset toNULL.

If multiple calls tomedia_pipeline_start() have been made, the samenumber of calls to this function are required to mark the pipeline as notstreaming.

void__media_pipeline_stop(structmedia_entity * entity)¶

Mark a pipeline as not streaming

Parameters

structmedia_entity*entity

Starting entity

Description

structmedia_intf_devnode *media_devnode_create(structmedia_device * mdev, u32 type, u32 flags, u32 major, u32 minor)¶

creates and initializes a device node interface

Parameters

structmedia_device*mdev

pointer to structmedia_device

u32type

type of the interface, as given byinclude/uapi/linux/media.h( seek forMEDIA_INTF_T_*) macros.

u32flags

Interface flags, as defined ininclude/uapi/linux/media.h( seek forMEDIA_INTF_FL_*)

u32major

Device node major number.

u32minor

Device node minor number.

Return

if succeeded, returns a pointer to the newly allocated

media_intf_devnode pointer.

Description

voidmedia_devnode_remove(structmedia_intf_devnode * devnode)¶

removes a device node interface

Parameters

structmedia_intf_devnode*devnode

pointer tomedia_intf_devnode to be freed.

Description

When a device node interface is removed, all links to it are automaticallyremoved.

media_create_intf_link(structmedia_entity * entity, structmedia_interface * intf, u32 flags)¶

creates a link between an entity and an interface

Parameters

structmedia_entity*entity

pointer tomedia_entity

structmedia_interface*intf

pointer tomedia_interface

u32flags

Link flags, as defined ininclude/uapi/linux/media.h( seek forMEDIA_LNK_FL_*)

Description

Valid values for flags:

MEDIA_LNK_FL_ENABLED

Indicates that the interface is connected to the entity hardware.That’s the default value for interfaces. An interface may be disabled ifthe hardware is busy due to the usage of some other interface that it iscurrently controlling the hardware.

A typical example is an hybrid TV device that handle only one type ofstream on a given time. So, when the digital TV is streaming,the V4L2 interfaces won’t be enabled, as such device is not able toalso stream analog TV or radio.

void__media_remove_intf_link(structmedia_link * link)¶

remove a single interface link

Parameters

structmedia_link*link

pointer tomedia_link.

Description

voidmedia_remove_intf_link(structmedia_link * link)¶

remove a single interface link

Parameters

structmedia_link*link

pointer tomedia_link.

Description

void__media_remove_intf_links(structmedia_interface * intf)¶

remove all links associated with an interface

Parameters

structmedia_interface*intf

pointer tomedia_interface

Description

voidmedia_remove_intf_links(structmedia_interface * intf)¶

remove all links associated with an interface

Parameters

structmedia_interface*intf

pointer tomedia_interface

Description

media_entity_call(entity,operation,args)¶

Calls a struct media_entity_operations operation on an entity

Parameters

entity

entity where theoperation will be called

operation

type of the operation. Should be the name of a member ofstructmedia_entity_operations.

args

variable arguments

Description

This helper function will check ifoperation is notNULL. On such case,it will issue a call tooperation(entity,args).

enummedia_request_state¶

media request state

Constants

MEDIA_REQUEST_STATE_IDLE

Idle

MEDIA_REQUEST_STATE_VALIDATING

Validating the request, no state changesallowed

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, usedinternally for sanity check purposes

structmedia_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 ofstruct 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

intmedia_request_lock_for_access(structmedia_request * req)¶

Lock the request to access its objects

Parameters

structmedia_request*req

The media request

Description

Use before accessing a completed request. A reference to the request mustbe held during the access. This usually takes place automatically througha file handle. Usemedia_request_unlock_for_access when done.

voidmedia_request_unlock_for_access(structmedia_request * req)¶

Unlock a request previously locked for access

Parameters

structmedia_request*req

The media request

Description

Unlock a request that has previously been locked usingmedia_request_lock_for_access.

intmedia_request_lock_for_update(structmedia_request * req)¶

Lock the request for updating its objects

Parameters

structmedia_request*req

The media request

Description

Use before updating a request, i.e. adding, modifying or removing a requestobject in it. A reference to the request must be held during the update. Thisusually takes place automatically through a file handle. Usemedia_request_unlock_for_update when done.

voidmedia_request_unlock_for_update(structmedia_request * req)¶

Unlock a request previously locked for update

Parameters

structmedia_request*req

The media request

Description

Unlock a request that has previously been locked usingmedia_request_lock_for_update.

voidmedia_request_get(structmedia_request * req)¶

Get the media request

Parameters

structmedia_request*req

The media request

Description

Get the media request.

voidmedia_request_put(structmedia_request * req)¶

Put the media request

Parameters

structmedia_request*req

The media request

Description

Put the media request. The media request will be releasedwhen the refcount reaches 0.

structmedia_request *media_request_get_by_fd(structmedia_device * mdev, int request_fd)¶

Get a media request by fd

Parameters

structmedia_device*mdev

Media device this request belongs to

intrequest_fd

The file descriptor of the request

Description

Get the request represented byrequest_fd that is ownedby the media device.

Return a -EBADR error pointer if requests are not supportedby this driver. Return -EINVAL if the request was not found.Return the pointer to the request if found: the caller willhave to callmedia_request_put when it finished using therequest.

intmedia_request_alloc(structmedia_device * mdev, int * alloc_fd)¶

Allocate the media request

Parameters

structmedia_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 inalloc_fd.

structmedia_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.

structmedia_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 forstruct 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 inanother struct that contains the actual data for this request object.

voidmedia_request_object_get(structmedia_request_object * obj)¶

Get a media request object

Parameters

structmedia_request_object*obj

The object

Description

Get a media request object.

voidmedia_request_object_put(structmedia_request_object * obj)¶

Put a media request object

Parameters

structmedia_request_object*obj

The object

Description

Put a media request object. Once all references are gone, theobject’s memory is released.

structmedia_request_object *media_request_object_find(structmedia_request * req, const structmedia_request_object_ops * ops, void * priv)¶

Find an object in a request

Parameters

structmedia_request*req

The media request

conststructmedia_request_object_ops*ops

Find an object with this ops value

void*priv

Find an object with this priv value

Description

Bothops andpriv must be non-NULL.

Returns the object pointer or NULL if not found. The caller mustcallmedia_request_object_put() once it finished using the object.

Since this function needs to walk the list of objects it takesthereq->lock spin lock to make this safe.

voidmedia_request_object_init(structmedia_request_object * obj)¶

Initialise a media request object

Parameters

structmedia_request_object*obj

The object

Description

Initialise a media request object. The object will be released using therelease callback of the ops once it has no references (this functioninitialises references to one).

intmedia_request_object_bind(structmedia_request * req, const structmedia_request_object_ops * ops, void * priv, bool is_buffer, structmedia_request_object * obj)¶

Bind a media request object to a request

Parameters

structmedia_request*req

The media request

conststructmedia_request_object_ops*ops

The object ops for this object

void*priv

A driver-specific priv pointer associated with this object

boolis_buffer

Set to true if the object a buffer object.

structmedia_request_object*obj

The object

Description

Bind this object to the request and set the ops and priv values ofthe object so it can be found later withmedia_request_object_find().

Every bound object must be unbound or completed by the kernel at somepoint in time, otherwise the request will never complete. When therequest is released all completed objects will be unbound by therequest core code.

Buffer objects will be added to the end of the request’s objectlist, non-buffer objects will be added to the front of the list.This ensures that all buffer objects are at the end of the listand that all non-buffer objects that they depend on are processedfirst.

voidmedia_request_object_unbind(structmedia_request_object * obj)¶

Unbind a media request object

Parameters

structmedia_request_object*obj

The object

Description

Unbind the media request object from the request.

voidmedia_request_object_complete(structmedia_request_object * obj)¶

Mark the media request object as complete

Parameters

structmedia_request_object*obj

The object

Description

Mark the media request object as complete. Only bound objects canbe completed.

structmedia_device *media_device_usb_allocate(structusb_device * udev, const char * module_name, struct module * owner)¶

Allocate and return structmedia device

Parameters

structusb_device*udev

structusb_device pointer

constchar*module_name

should be filled withKBUILD_MODNAME

structmodule*owner

struct module pointerTHIS_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 multipledrivers share usb_device and the media device. This interface allocatesmedia_device structure and callsmedia_device_usb_init() to initializeit.

voidmedia_device_delete(structmedia_device * mdev, const char * module_name, struct module * owner)¶

Release media device. Calls kref_put().

Parameters

structmedia_device*mdev

structmedia_device pointer

constchar*module_name

should be filled withKBUILD_MODNAME

structmodule*owner

struct module pointerTHIS_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.