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/**
 27 * enum tuner_pad_index - tuner pad index for MEDIA_ENT_F_TUNER
 28 *
 29 * @TUNER_PAD_RF_INPUT:	Radiofrequency (RF) sink pad, usually linked to a
 30 *			RF connector entity.
 31 * @TUNER_PAD_OUTPUT:	Tuner video output source pad. Contains the video
 32 *			chrominance and luminance or the hole bandwidth
 33 *			of the signal converted to an Intermediate Frequency
 34 *			(IF) or to baseband (on zero-IF tuners).
 35 * @TUNER_PAD_AUD_OUT:	Tuner audio output source pad. Tuners used to decode
 36 *			analog TV signals have an extra pad for audio output.
 37 *			Old tuners use an analog stage with a saw filter for
 38 *			the audio IF frequency. The output of the pad is, in
 39 *			this case, the audio IF, with should be decoded either
 40 *			by the bridge chipset (that's the case of cx2388x
 41 *			chipsets) or may require an external IF sound
 42 *			processor, like msp34xx. On modern silicon tuners,
 43 *			the audio IF decoder is usually incorporated at the
 44 *			tuner. On such case, the output of this pad is an
 45 *			audio sampled data.
 46 * @TUNER_NUM_PADS:	Number of pads of the tuner.
 47 */
 48enum tuner_pad_index {
 49	TUNER_PAD_RF_INPUT,
 50	TUNER_PAD_OUTPUT,
 51	TUNER_PAD_AUD_OUT,
 52	TUNER_NUM_PADS
 53};
 54
 55/**
 56 * enum if_vid_dec_pad_index - video IF-PLL pad index for
 57 *			   MEDIA_ENT_F_IF_VID_DECODER
 58 *
 59 * @IF_VID_DEC_PAD_IF_INPUT:	video Intermediate Frequency (IF) sink pad
 60 * @IF_VID_DEC_PAD_OUT:		IF-PLL video output source pad. Contains the
 61 *				video chrominance and luminance IF signals.
 62 * @IF_VID_DEC_PAD_NUM_PADS:	Number of pads of the video IF-PLL.
 63 */
 64enum if_vid_dec_pad_index {
 65	IF_VID_DEC_PAD_IF_INPUT,
 66	IF_VID_DEC_PAD_OUT,
 67	IF_VID_DEC_PAD_NUM_PADS
 68};
 69
 70/**
 71 * enum if_aud_dec_pad_index - audio/sound IF-PLL pad index for
 72 *			   MEDIA_ENT_F_IF_AUD_DECODER
 73 *
 74 * @IF_AUD_DEC_PAD_IF_INPUT:	audio Intermediate Frequency (IF) sink pad
 75 * @IF_AUD_DEC_PAD_OUT:		IF-PLL audio output source pad. Contains the
 76 *				audio sampled stream data, usually connected
 77 *				to the bridge bus via an Inter-IC Sound (I2S)
 78 *				bus.
 79 * @IF_AUD_DEC_PAD_NUM_PADS:	Number of pads of the audio IF-PLL.
 80 */
 81enum if_aud_dec_pad_index {
 82	IF_AUD_DEC_PAD_IF_INPUT,
 83	IF_AUD_DEC_PAD_OUT,
 84	IF_AUD_DEC_PAD_NUM_PADS
 85};
 86
 87/**
 88 * enum demod_pad_index - analog TV pad index for MEDIA_ENT_F_ATV_DECODER
 89 *
 90 * @DEMOD_PAD_IF_INPUT:	IF input sink pad.
 91 * @DEMOD_PAD_VID_OUT:	Video output source pad.
 92 * @DEMOD_PAD_VBI_OUT:	Vertical Blank Interface (VBI) output source pad.
 93 * @DEMOD_PAD_AUDIO_OUT: Audio output source pad.
 94 * @DEMOD_NUM_PADS:	Maximum number of output pads.
 95 */
 96enum demod_pad_index {
 97	DEMOD_PAD_IF_INPUT,
 98	DEMOD_PAD_VID_OUT,
 99	DEMOD_PAD_VBI_OUT,
100	DEMOD_PAD_AUDIO_OUT,
101	DEMOD_NUM_PADS
102};
103
104/* We don't need to include pci.h or usb.h here */
105struct pci_dev;
106struct usb_device;
107
108#ifdef CONFIG_MEDIA_CONTROLLER
109/**
110 * v4l2_mc_create_media_graph() - create Media Controller links at the graph.
111 *
112 * @mdev:	pointer to the &media_device struct.
113 *
114 * Add links between the entities commonly found on PC customer's hardware at
115 * the V4L2 side: camera sensors, audio and video PLL-IF decoders, tuners,
116 * analog TV decoder and I/O entities (video, VBI and Software Defined Radio).
117 *
118 * .. note::
119 *
120 *    Webcams are modelled on a very simple way: the sensor is
121 *    connected directly to the I/O entity. All dirty details, like
122 *    scaler and crop HW are hidden. While such mapping is enough for v4l2
123 *    interface centric PC-consumer's hardware, V4L2 subdev centric camera
124 *    hardware should not use this routine, as it will not build the right graph.
125 */
126int v4l2_mc_create_media_graph(struct media_device *mdev);
127
128/**
129 * v4l_enable_media_source() -	Hold media source for exclusive use
130 *				if free
131 *
132 * @vdev:	pointer to struct video_device
133 *
134 * This interface calls enable_source handler to determine if
135 * media source is free for use. The enable_source handler is
136 * responsible for checking is the media source is free and
137 * start a pipeline between the media source and the media
138 * entity associated with the video device. This interface
139 * should be called from v4l2-core and dvb-core interfaces
140 * that change the source configuration.
141 *
142 * Return: returns zero on success or a negative error code.
143 */
144int v4l_enable_media_source(struct video_device *vdev);
145
146/**
147 * v4l_disable_media_source() -	Release media source
148 *
149 * @vdev:	pointer to struct video_device
150 *
151 * This interface calls disable_source handler to release
152 * the media source. The disable_source handler stops the
153 * active media pipeline between the media source and the
154 * media entity associated with the video device.
155 *
156 * Return: returns zero on success or a negative error code.
157 */
158void v4l_disable_media_source(struct video_device *vdev);
159
160/*
161 * v4l_vb2q_enable_media_tuner -  Hold media source for exclusive use
162 *				  if free.
163 * @q - pointer to struct vb2_queue
164 *
165 * Wrapper for v4l_enable_media_source(). This function should
166 * be called from v4l2-core to enable the media source with
167 * pointer to struct vb2_queue as the input argument. Some
168 * v4l2-core interfaces don't have access to video device and
169 * this interface finds the struct video_device for the q and
170 * calls v4l_enable_media_source().
171 */
172int v4l_vb2q_enable_media_source(struct vb2_queue *q);
173
174
175/**
176 * v4l2_pipeline_pm_use - Update the use count of an entity
177 * @entity: The entity
178 * @use: Use (1) or stop using (0) the entity
179 *
180 * Update the use count of all entities in the pipeline and power entities on or
181 * off accordingly.
182 *
183 * This function is intended to be called in video node open (use ==
184 * 1) and release (use == 0). It uses struct media_entity.use_count to
185 * track the power status. The use of this function should be paired
186 * with v4l2_pipeline_link_notify().
187 *
188 * Return 0 on success or a negative error code on failure. Powering entities
189 * off is assumed to never fail. No failure can occur when the use parameter is
190 * set to 0.
191 */
192int v4l2_pipeline_pm_use(struct media_entity *entity, int use);
193
194
195/**
196 * v4l2_pipeline_link_notify - Link management notification callback
197 * @link: The link
198 * @flags: New link flags that will be applied
199 * @notification: The link's state change notification type (MEDIA_DEV_NOTIFY_*)
200 *
201 * React to link management on powered pipelines by updating the use count of
202 * all entities in the source and sink sides of the link. Entities are powered
203 * on or off accordingly. The use of this function should be paired
204 * with v4l2_pipeline_pm_use().
205 *
206 * Return 0 on success or a negative error code on failure. Powering entities
207 * off is assumed to never fail. This function will not fail for disconnection
208 * events.
209 */
210int v4l2_pipeline_link_notify(struct media_link *link, u32 flags,
211			      unsigned int notification);
212
213#else /* CONFIG_MEDIA_CONTROLLER */
214
215static inline int v4l2_mc_create_media_graph(struct media_device *mdev)
216{
217	return 0;
218}
219
220static inline int v4l_enable_media_source(struct video_device *vdev)
221{
222	return 0;
223}
224
225static inline void v4l_disable_media_source(struct video_device *vdev)
226{
227}
228
229static inline int v4l_vb2q_enable_media_source(struct vb2_queue *q)
230{
231	return 0;
232}
233
234static inline int v4l2_pipeline_pm_use(struct media_entity *entity, int use)
235{
236	return 0;
237}
238
239static inline int v4l2_pipeline_link_notify(struct media_link *link, u32 flags,
240					    unsigned int notification)
241{
242	return 0;
243}
244
245#endif /* CONFIG_MEDIA_CONTROLLER */
246#endif /* _V4L2_MC_H */