1/*
  2 * v4l2-mc.h - Media Controller V4L2 types and prototypes
  3 *
  4 * Copyright (C) 2016 Mauro Carvalho Chehab <mchehab@osg.samsung.com>
  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_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_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 * NOTE: webcams are modelled on a very simple way: the sensor is
118 * connected directly to the I/O entity. All dirty details, like
119 * scaler and crop HW are hidden. While such mapping is enough for v4l2
120 * interface centric PC-consumer's hardware, V4L2 subdev centric camera
121 * hardware should not use this routine, as it will not build the right graph.
122 */
123int v4l2_mc_create_media_graph(struct media_device *mdev);
124
125/**
126 * v4l_enable_media_source() -	Hold media source for exclusive use
127 *				if free
128 *
129 * @vdev:	pointer to struct video_device
130 *
131 * This interface calls enable_source handler to determine if
132 * media source is free for use. The enable_source handler is
133 * responsible for checking is the media source is free and
134 * start a pipeline between the media source and the media
135 * entity associated with the video device. This interface
136 * should be called from v4l2-core and dvb-core interfaces
137 * that change the source configuration.
138 *
139 * Return: returns zero on success or a negative error code.
140 */
141int v4l_enable_media_source(struct video_device *vdev);
142
143/**
144 * v4l_disable_media_source() -	Release media source
145 *
146 * @vdev:	pointer to struct video_device
147 *
148 * This interface calls disable_source handler to release
149 * the media source. The disable_source handler stops the
150 * active media pipeline between the media source and the
151 * media entity associated with the video device.
152 *
153 * Return: returns zero on success or a negative error code.
154 */
155void v4l_disable_media_source(struct video_device *vdev);
156
157/*
158 * v4l_vb2q_enable_media_tuner -  Hold media source for exclusive use
159 *				  if free.
160 * @q - pointer to struct vb2_queue
161 *
162 * Wrapper for v4l_enable_media_source(). This function should
163 * be called from v4l2-core to enable the media source with
164 * pointer to struct vb2_queue as the input argument. Some
165 * v4l2-core interfaces don't have access to video device and
166 * this interface finds the struct video_device for the q and
167 * calls v4l_enable_media_source().
168 */
169int v4l_vb2q_enable_media_source(struct vb2_queue *q);
170
171
172/**
173 * v4l2_pipeline_pm_use - Update the use count of an entity
174 * @entity: The entity
175 * @use: Use (1) or stop using (0) the entity
176 *
177 * Update the use count of all entities in the pipeline and power entities on or
178 * off accordingly.
179 *
180 * This function is intended to be called in video node open (use ==
181 * 1) and release (use == 0). It uses struct media_entity.use_count to
182 * track the power status. The use of this function should be paired
183 * with v4l2_pipeline_link_notify().
184 *
185 * Return 0 on success or a negative error code on failure. Powering entities
186 * off is assumed to never fail. No failure can occur when the use parameter is
187 * set to 0.
188 */
189int v4l2_pipeline_pm_use(struct media_entity *entity, int use);
190
191
192/**
193 * v4l2_pipeline_link_notify - Link management notification callback
194 * @link: The link
195 * @flags: New link flags that will be applied
196 * @notification: The link's state change notification type (MEDIA_DEV_NOTIFY_*)
197 *
198 * React to link management on powered pipelines by updating the use count of
199 * all entities in the source and sink sides of the link. Entities are powered
200 * on or off accordingly. The use of this function should be paired
201 * with v4l2_pipeline_pm_use().
202 *
203 * Return 0 on success or a negative error code on failure. Powering entities
204 * off is assumed to never fail. This function will not fail for disconnection
205 * events.
206 */
207int v4l2_pipeline_link_notify(struct media_link *link, u32 flags,
208			      unsigned int notification);
209
210#else /* CONFIG_MEDIA_CONTROLLER */
211
212static inline int v4l2_mc_create_media_graph(struct media_device *mdev)
213{
214	return 0;
215}
216
217static inline int v4l_enable_media_source(struct video_device *vdev)
218{
219	return 0;
220}
221
222static inline void v4l_disable_media_source(struct video_device *vdev)
223{
224}
225
226static inline int v4l_vb2q_enable_media_source(struct vb2_queue *q)
227{
228	return 0;
229}
230
231static inline int v4l2_pipeline_pm_use(struct media_entity *entity, int use)
232{
233	return 0;
234}
235
236static inline int v4l2_pipeline_link_notify(struct media_link *link, u32 flags,
237					    unsigned int notification)
238{
239	return 0;
240}
241
242#endif /* CONFIG_MEDIA_CONTROLLER */
243#endif /* _V4L2_MC_H */