include/media/v4l2-mc.h

   1 /*
   2  * v4l2-mc.h - Media Controller V4L2 types and prototypes
   3  *
   4  * Copyright (C) 2016 Mauro Carvalho Chehab <mchehab@kernel.org>
   5  * Copyright (C) 2006-2010 Nokia Corporation
   6  * Copyright (c) 2016 Intel Corporation.
   7  *
   8  * This program is free software; you can redistribute it and/or modify
   9  * it under the terms of the GNU General Public License as published by
  10  * the Free Software Foundation; either version 2 of the License, or
  11  * (at your option) any later version.
  12  *
  13  * This program is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16  * GNU General Public License for more details.
  17  */
  18
  19 #ifndef _V4L2_MC_H
  20 #define _V4L2_MC_H
  21
  22 #include <media/media-device.h>
  23 #include <media/v4l2-dev.h>
  24 #include <linux/types.h>
  25
  26 /* We don't need to include pci.h or usb.h here */
  27 struct pci_dev;
  28 struct usb_device;
  29
  30 #ifdef CONFIG_MEDIA_CONTROLLER
  31 /**
  32  * v4l2_mc_create_media_graph() - create Media Controller links at the graph.
  33  *
  34  * @mdev:       pointer to the &media_device struct.
  35  *
  36  * Add links between the entities commonly found on PC customer's hardware at
  37  * the V4L2 side: camera sensors, audio and video PLL-IF decoders, tuners,
  38  * analog TV decoder and I/O entities (video, VBI and Software Defined Radio).
  39  *
  40  * .. note::
  41  *
  42  *    Webcams are modelled on a very simple way: the sensor is
  43  *    connected directly to the I/O entity. All dirty details, like
  44  *    scaler and crop HW are hidden. While such mapping is enough for v4l2
  45  *    interface centric PC-consumer's hardware, V4L2 subdev centric camera
  46  *    hardware should not use this routine, as it will not build the right graph.
  47  */
  48 int v4l2_mc_create_media_graph(struct media_device *mdev);
  49
  50 /**
  51  * v4l_enable_media_source() -  Hold media source for exclusive use
  52  *                              if free
  53  *
  54  * @vdev:       pointer to struct video_device
  55  *
  56  * This interface calls enable_source handler to determine if
  57  * media source is free for use. The enable_source handler is
  58  * responsible for checking is the media source is free and
  59  * start a pipeline between the media source and the media
  60  * entity associated with the video device. This interface
  61  * should be called from v4l2-core and dvb-core interfaces
  62  * that change the source configuration.
  63  *
  64  * Return: returns zero on success or a negative error code.
  65  */
  66 int v4l_enable_media_source(struct video_device *vdev);
  67
  68 /**
  69  * v4l_disable_media_source() - Release media source
  70  *
  71  * @vdev:       pointer to struct video_device
  72  *
  73  * This interface calls disable_source handler to release
  74  * the media source. The disable_source handler stops the
  75  * active media pipeline between the media source and the
  76  * media entity associated with the video device.
  77  *
  78  * Return: returns zero on success or a negative error code.
  79  */
  80 void v4l_disable_media_source(struct video_device *vdev);
  81
  82 /*
  83  * v4l_vb2q_enable_media_tuner -  Hold media source for exclusive use
  84  *                                if free.
  85  * @q - pointer to struct vb2_queue
  86  *
  87  * Wrapper for v4l_enable_media_source(). This function should
  88  * be called from v4l2-core to enable the media source with
  89  * pointer to struct vb2_queue as the input argument. Some
  90  * v4l2-core interfaces don't have access to video device and
  91  * this interface finds the struct video_device for the q and
  92  * calls v4l_enable_media_source().
  93  */
  94 int v4l_vb2q_enable_media_source(struct vb2_queue *q);
  95
  96
  97 /**
  98  * v4l2_pipeline_pm_use - Update the use count of an entity
  99  * @entity: The entity
 100  * @use: Use (1) or stop using (0) the entity
 101  *
 102  * Update the use count of all entities in the pipeline and power entities on or
 103  * off accordingly.
 104  *
 105  * This function is intended to be called in video node open (use ==
 106  * 1) and release (use == 0). It uses struct media_entity.use_count to
 107  * track the power status. The use of this function should be paired
 108  * with v4l2_pipeline_link_notify().
 109  *
 110  * Return 0 on success or a negative error code on failure. Powering entities
 111  * off is assumed to never fail. No failure can occur when the use parameter is
 112  * set to 0.
 113  */
 114 int v4l2_pipeline_pm_use(struct media_entity *entity, int use);
 115
 116
 117 /**
 118  * v4l2_pipeline_link_notify - Link management notification callback
 119  * @link: The link
 120  * @flags: New link flags that will be applied
 121  * @notification: The link's state change notification type (MEDIA_DEV_NOTIFY_*)
 122  *
 123  * React to link management on powered pipelines by updating the use count of
 124  * all entities in the source and sink sides of the link. Entities are powered
 125  * on or off accordingly. The use of this function should be paired
 126  * with v4l2_pipeline_pm_use().
 127  *
 128  * Return 0 on success or a negative error code on failure. Powering entities
 129  * off is assumed to never fail. This function will not fail for disconnection
 130  * events.
 131  */
 132 int v4l2_pipeline_link_notify(struct media_link *link, u32 flags,
 133                               unsigned int notification);
 134
 135 #else /* CONFIG_MEDIA_CONTROLLER */
 136
 137 static inline int v4l2_mc_create_media_graph(struct media_device *mdev)
 138 {
 139         return 0;
 140 }
 141
 142 static inline int v4l_enable_media_source(struct video_device *vdev)
 143 {
 144         return 0;
 145 }
 146
 147 static inline void v4l_disable_media_source(struct video_device *vdev)
 148 {
 149 }
 150
 151 static inline int v4l_vb2q_enable_media_source(struct vb2_queue *q)
 152 {
 153         return 0;
 154 }
 155
 156 static inline int v4l2_pipeline_pm_use(struct media_entity *entity, int use)
 157 {
 158         return 0;
 159 }
 160
 161 static inline int v4l2_pipeline_link_notify(struct media_link *link, u32 flags,
 162                                             unsigned int notification)
 163 {
 164         return 0;
 165 }
 166
 167 #endif /* CONFIG_MEDIA_CONTROLLER */
 168 #endif /* _V4L2_MC_H */