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_AUDIO_OUT: Audio output source pad. 93 * @DEMOD_NUM_PADS: Maximum number of output pads. 94 */ 95 enum demod_pad_index { 96 DEMOD_PAD_IF_INPUT, 97 DEMOD_PAD_VID_OUT, 98 DEMOD_PAD_AUDIO_OUT, 99 DEMOD_NUM_PADS 100 }; 101 102 /* We don't need to include pci.h or usb.h here */ 103 struct pci_dev; 104 struct usb_device; 105 106 #ifdef CONFIG_MEDIA_CONTROLLER 107 /** 108 * v4l2_mc_create_media_graph() - create Media Controller links at the graph. 109 * 110 * @mdev: pointer to the &media_device struct. 111 * 112 * Add links between the entities commonly found on PC customer's hardware at 113 * the V4L2 side: camera sensors, audio and video PLL-IF decoders, tuners, 114 * analog TV decoder and I/O entities (video, VBI and Software Defined Radio). 115 * 116 * .. note:: 117 * 118 * Webcams are modelled on a very simple way: the sensor is 119 * connected directly to the I/O entity. All dirty details, like 120 * scaler and crop HW are hidden. While such mapping is enough for v4l2 121 * interface centric PC-consumer's hardware, V4L2 subdev centric camera 122 * hardware should not use this routine, as it will not build the right graph. 123 */ 124 int v4l2_mc_create_media_graph(struct media_device *mdev); 125 126 /** 127 * v4l_enable_media_source() - Hold media source for exclusive use 128 * if free 129 * 130 * @vdev: pointer to struct video_device 131 * 132 * This interface calls enable_source handler to determine if 133 * media source is free for use. The enable_source handler is 134 * responsible for checking is the media source is free and 135 * start a pipeline between the media source and the media 136 * entity associated with the video device. This interface 137 * should be called from v4l2-core and dvb-core interfaces 138 * that change the source configuration. 139 * 140 * Return: returns zero on success or a negative error code. 141 */ 142 int v4l_enable_media_source(struct video_device *vdev); 143 144 /** 145 * v4l_disable_media_source() - Release media source 146 * 147 * @vdev: pointer to struct video_device 148 * 149 * This interface calls disable_source handler to release 150 * the media source. The disable_source handler stops the 151 * active media pipeline between the media source and the 152 * media entity associated with the video device. 153 * 154 * Return: returns zero on success or a negative error code. 155 */ 156 void v4l_disable_media_source(struct video_device *vdev); 157 158 /* 159 * v4l_vb2q_enable_media_tuner - Hold media source for exclusive use 160 * if free. 161 * @q - pointer to struct vb2_queue 162 * 163 * Wrapper for v4l_enable_media_source(). This function should 164 * be called from v4l2-core to enable the media source with 165 * pointer to struct vb2_queue as the input argument. Some 166 * v4l2-core interfaces don't have access to video device and 167 * this interface finds the struct video_device for the q and 168 * calls v4l_enable_media_source(). 169 */ 170 int v4l_vb2q_enable_media_source(struct vb2_queue *q); 171 172 173 /** 174 * v4l2_pipeline_pm_use - Update the use count of an entity 175 * @entity: The entity 176 * @use: Use (1) or stop using (0) the entity 177 * 178 * Update the use count of all entities in the pipeline and power entities on or 179 * off accordingly. 180 * 181 * This function is intended to be called in video node open (use == 182 * 1) and release (use == 0). It uses struct media_entity.use_count to 183 * track the power status. The use of this function should be paired 184 * with v4l2_pipeline_link_notify(). 185 * 186 * Return 0 on success or a negative error code on failure. Powering entities 187 * off is assumed to never fail. No failure can occur when the use parameter is 188 * set to 0. 189 */ 190 int v4l2_pipeline_pm_use(struct media_entity *entity, int use); 191 192 193 /** 194 * v4l2_pipeline_link_notify - Link management notification callback 195 * @link: The link 196 * @flags: New link flags that will be applied 197 * @notification: The link's state change notification type (MEDIA_DEV_NOTIFY_*) 198 * 199 * React to link management on powered pipelines by updating the use count of 200 * all entities in the source and sink sides of the link. Entities are powered 201 * on or off accordingly. The use of this function should be paired 202 * with v4l2_pipeline_pm_use(). 203 * 204 * Return 0 on success or a negative error code on failure. Powering entities 205 * off is assumed to never fail. This function will not fail for disconnection 206 * events. 207 */ 208 int v4l2_pipeline_link_notify(struct media_link *link, u32 flags, 209 unsigned int notification); 210 211 #else /* CONFIG_MEDIA_CONTROLLER */ 212 213 static inline int v4l2_mc_create_media_graph(struct media_device *mdev) 214 { 215 return 0; 216 } 217 218 static inline int v4l_enable_media_source(struct video_device *vdev) 219 { 220 return 0; 221 } 222 223 static inline void v4l_disable_media_source(struct video_device *vdev) 224 { 225 } 226 227 static inline int v4l_vb2q_enable_media_source(struct vb2_queue *q) 228 { 229 return 0; 230 } 231 232 static inline int v4l2_pipeline_pm_use(struct media_entity *entity, int use) 233 { 234 return 0; 235 } 236 237 static inline int v4l2_pipeline_link_notify(struct media_link *link, u32 flags, 238 unsigned int notification) 239 { 240 return 0; 241 } 242 243 #endif /* CONFIG_MEDIA_CONTROLLER */ 244 #endif /* _V4L2_MC_H */ 245