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 */ 48 enum 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 */ 64 enum 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 */ 81 enum 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 */ 96 enum 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 */ 105 struct pci_dev; 106 struct 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 */ 126 int 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 */ 144 int 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 */ 158 void 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 */ 172 int 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 */ 192 int 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 */ 210 int v4l2_pipeline_link_notify(struct media_link *link, u32 flags, 211 unsigned int notification); 212 213 #else /* CONFIG_MEDIA_CONTROLLER */ 214 215 static inline int v4l2_mc_create_media_graph(struct media_device *mdev) 216 { 217 return 0; 218 } 219 220 static inline int v4l_enable_media_source(struct video_device *vdev) 221 { 222 return 0; 223 } 224 225 static inline void v4l_disable_media_source(struct video_device *vdev) 226 { 227 } 228 229 static inline int v4l_vb2q_enable_media_source(struct vb2_queue *q) 230 { 231 return 0; 232 } 233 234 static inline int v4l2_pipeline_pm_use(struct media_entity *entity, int use) 235 { 236 return 0; 237 } 238 239 static 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 */ 247