include/media/v4l2-mc.h

0001 /* SPDX-License-Identifier: GPL-2.0-or-later */
0002 /*
0003  * v4l2-mc.h - Media Controller V4L2 types and prototypes
0004  *
0005  * Copyright (C) 2016 Mauro Carvalho Chehab <mchehab@kernel.org>
0006  * Copyright (C) 2006-2010 Nokia Corporation
0007  * Copyright (c) 2016 Intel Corporation.
0008  */
0009
0010 #ifndef _V4L2_MC_H
0011 #define _V4L2_MC_H
0012
0013 #include <media/media-device.h>
0014 #include <media/v4l2-dev.h>
0015 #include <media/v4l2-subdev.h>
0016 #include <linux/types.h>
0017
0018 /* We don't need to include pci.h or usb.h here */
0019 struct pci_dev;
0020 struct usb_device;
0021
0022 #ifdef CONFIG_MEDIA_CONTROLLER
0023 /**
0024  * v4l2_mc_create_media_graph() - create Media Controller links at the graph.
0025  *
0026  * @mdev:   pointer to the &media_device struct.
0027  *
0028  * Add links between the entities commonly found on PC customer's hardware at
0029  * the V4L2 side: camera sensors, audio and video PLL-IF decoders, tuners,
0030  * analog TV decoder and I/O entities (video, VBI and Software Defined Radio).
0031  *
0032  * .. note::
0033  *
0034  *    Webcams are modelled on a very simple way: the sensor is
0035  *    connected directly to the I/O entity. All dirty details, like
0036  *    scaler and crop HW are hidden. While such mapping is enough for v4l2
0037  *    interface centric PC-consumer's hardware, V4L2 subdev centric camera
0038  *    hardware should not use this routine, as it will not build the right graph.
0039  */
0040 int v4l2_mc_create_media_graph(struct media_device *mdev);
0041
0042 /**
0043  * v4l_enable_media_source() -  Hold media source for exclusive use
0044  *              if free
0045  *
0046  * @vdev:   pointer to struct video_device
0047  *
0048  * This interface calls enable_source handler to determine if
0049  * media source is free for use. The enable_source handler is
0050  * responsible for checking is the media source is free and
0051  * start a pipeline between the media source and the media
0052  * entity associated with the video device. This interface
0053  * should be called from v4l2-core and dvb-core interfaces
0054  * that change the source configuration.
0055  *
0056  * Return: returns zero on success or a negative error code.
0057  */
0058 int v4l_enable_media_source(struct video_device *vdev);
0059
0060 /**
0061  * v4l_disable_media_source() - Release media source
0062  *
0063  * @vdev:   pointer to struct video_device
0064  *
0065  * This interface calls disable_source handler to release
0066  * the media source. The disable_source handler stops the
0067  * active media pipeline between the media source and the
0068  * media entity associated with the video device.
0069  *
0070  * Return: returns zero on success or a negative error code.
0071  */
0072 void v4l_disable_media_source(struct video_device *vdev);
0073
0074 /*
0075  * v4l_vb2q_enable_media_tuner -  Hold media source for exclusive use
0076  *                if free.
0077  * @q - pointer to struct vb2_queue
0078  *
0079  * Wrapper for v4l_enable_media_source(). This function should
0080  * be called from v4l2-core to enable the media source with
0081  * pointer to struct vb2_queue as the input argument. Some
0082  * v4l2-core interfaces don't have access to video device and
0083  * this interface finds the struct video_device for the q and
0084  * calls v4l_enable_media_source().
0085  */
0086 int v4l_vb2q_enable_media_source(struct vb2_queue *q);
0087
0088 /**
0089  * v4l2_create_fwnode_links_to_pad - Create fwnode-based links from a
0090  *                                   source subdev to a sink subdev pad.
0091  *
0092  * @src_sd: pointer to a source subdev
0093  * @sink:  pointer to a subdev sink pad
0094  * @flags: the link flags
0095  *
0096  * This function searches for fwnode endpoint connections from a source
0097  * subdevice to a single sink pad, and if suitable connections are found,
0098  * translates them into media links to that pad. The function can be
0099  * called by the sink subdevice, in its v4l2-async notifier subdev bound
0100  * callback, to create links from a bound source subdevice.
0101  *
0102  * The @flags argument specifies the link flags. The caller shall ensure that
0103  * the flags are valid regardless of the number of links that may be created.
0104  * For instance, setting the MEDIA_LNK_FL_ENABLED flag will cause all created
0105  * links to be enabled, which isn't valid if more than one link is created.
0106  *
0107  * .. note::
0108  *
0109  *    Any sink subdevice that calls this function must implement the
0110  *    .get_fwnode_pad media operation in order to verify endpoints passed
0111  *    to the sink are owned by the sink.
0112  *
0113  * Return 0 on success or a negative error code on failure.
0114  */
0115 int v4l2_create_fwnode_links_to_pad(struct v4l2_subdev *src_sd,
0116                     struct media_pad *sink, u32 flags);
0117
0118 /**
0119  * v4l2_create_fwnode_links - Create fwnode-based links from a source
0120  *                            subdev to a sink subdev.
0121  *
0122  * @src_sd: pointer to a source subdevice
0123  * @sink_sd: pointer to a sink subdevice
0124  *
0125  * This function searches for any and all fwnode endpoint connections
0126  * between source and sink subdevices, and translates them into media
0127  * links. The function can be called by the sink subdevice, in its
0128  * v4l2-async notifier subdev bound callback, to create all links from
0129  * a bound source subdevice.
0130  *
0131  * .. note::
0132  *
0133  *    Any sink subdevice that calls this function must implement the
0134  *    .get_fwnode_pad media operation in order to verify endpoints passed
0135  *    to the sink are owned by the sink.
0136  *
0137  * Return 0 on success or a negative error code on failure.
0138  */
0139 int v4l2_create_fwnode_links(struct v4l2_subdev *src_sd,
0140                  struct v4l2_subdev *sink_sd);
0141
0142 /**
0143  * v4l2_pipeline_pm_get - Increase the use count of a pipeline
0144  * @entity: The root entity of a pipeline
0145  *
0146  * Update the use count of all entities in the pipeline and power entities on.
0147  *
0148  * This function is intended to be called in video node open. It uses
0149  * struct media_entity.use_count to track the power status. The use
0150  * of this function should be paired with v4l2_pipeline_link_notify().
0151  *
0152  * Return 0 on success or a negative error code on failure.
0153  */
0154 int v4l2_pipeline_pm_get(struct media_entity *entity);
0155
0156 /**
0157  * v4l2_pipeline_pm_put - Decrease the use count of a pipeline
0158  * @entity: The root entity of a pipeline
0159  *
0160  * Update the use count of all entities in the pipeline and power entities off.
0161  *
0162  * This function is intended to be called in video node release. It uses
0163  * struct media_entity.use_count to track the power status. The use
0164  * of this function should be paired with v4l2_pipeline_link_notify().
0165  */
0166 void v4l2_pipeline_pm_put(struct media_entity *entity);
0167
0168
0169 /**
0170  * v4l2_pipeline_link_notify - Link management notification callback
0171  * @link: The link
0172  * @flags: New link flags that will be applied
0173  * @notification: The link's state change notification type (MEDIA_DEV_NOTIFY_*)
0174  *
0175  * React to link management on powered pipelines by updating the use count of
0176  * all entities in the source and sink sides of the link. Entities are powered
0177  * on or off accordingly. The use of this function should be paired
0178  * with v4l2_pipeline_pm_{get,put}().
0179  *
0180  * Return 0 on success or a negative error code on failure. Powering entities
0181  * off is assumed to never fail. This function will not fail for disconnection
0182  * events.
0183  */
0184 int v4l2_pipeline_link_notify(struct media_link *link, u32 flags,
0185                   unsigned int notification);
0186
0187 #else /* CONFIG_MEDIA_CONTROLLER */
0188
0189 static inline int v4l2_mc_create_media_graph(struct media_device *mdev)
0190 {
0191     return 0;
0192 }
0193
0194 static inline int v4l_enable_media_source(struct video_device *vdev)
0195 {
0196     return 0;
0197 }
0198
0199 static inline void v4l_disable_media_source(struct video_device *vdev)
0200 {
0201 }
0202
0203 static inline int v4l_vb2q_enable_media_source(struct vb2_queue *q)
0204 {
0205     return 0;
0206 }
0207
0208 static inline int v4l2_pipeline_pm_get(struct media_entity *entity)
0209 {
0210     return 0;
0211 }
0212
0213 static inline void v4l2_pipeline_pm_put(struct media_entity *entity)
0214 {}
0215
0216 static inline int v4l2_pipeline_link_notify(struct media_link *link, u32 flags,
0217                         unsigned int notification)
0218 {
0219     return 0;
0220 }
0221
0222 #endif /* CONFIG_MEDIA_CONTROLLER */
0223 #endif /* _V4L2_MC_H */