1 /*
2  * v4l2-dv-timings - Internal header with dv-timings helper functions
3  *
4  * Copyright 2013 Cisco Systems, Inc. and/or its affiliates. All rights reserved.
5  *
6  * This program is free software; you may redistribute it and/or modify
7  * it under the terms of the GNU General Public License as published by
8  * the Free Software Foundation; version 2 of the License.
9  *
10  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
11  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
12  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
13  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
14  * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
15  * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
16  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
17  * SOFTWARE.
18  *
19  */
20 
21 #ifndef __V4L2_DV_TIMINGS_H
22 #define __V4L2_DV_TIMINGS_H
23 
24 #include <linux/videodev2.h>
25 
26 /*
27  * v4l2_dv_timings_presets: list of all dv_timings presets.
28  */
29 extern const struct v4l2_dv_timings v4l2_dv_timings_presets[];
30 
31 /**
32  * typedef v4l2_check_dv_timings_fnc - timings check callback
33  *
34  * @t: the v4l2_dv_timings struct.
35  * @handle: a handle from the driver.
36  *
37  * Returns true if the given timings are valid.
38  */
39 typedef bool v4l2_check_dv_timings_fnc(const struct v4l2_dv_timings *t, void *handle);
40 
41 /**
42  * v4l2_valid_dv_timings() - are these timings valid?
43  *
44  * @t:	  the v4l2_dv_timings struct.
45  * @cap: the v4l2_dv_timings_cap capabilities.
46  * @fnc: callback to check if this timing is OK. May be NULL.
47  * @fnc_handle: a handle that is passed on to @fnc.
48  *
49  * Returns true if the given dv_timings struct is supported by the
50  * hardware capabilities and the callback function (if non-NULL), returns
51  * false otherwise.
52  */
53 bool v4l2_valid_dv_timings(const struct v4l2_dv_timings *t,
54 			   const struct v4l2_dv_timings_cap *cap,
55 			   v4l2_check_dv_timings_fnc fnc,
56 			   void *fnc_handle);
57 
58 /**
59  * v4l2_enum_dv_timings_cap() - Helper function to enumerate possible DV
60  *	 timings based on capabilities
61  *
62  * @t:	  the v4l2_enum_dv_timings struct.
63  * @cap: the v4l2_dv_timings_cap capabilities.
64  * @fnc: callback to check if this timing is OK. May be NULL.
65  * @fnc_handle: a handle that is passed on to @fnc.
66  *
67  * This enumerates dv_timings using the full list of possible CEA-861 and DMT
68  * timings, filtering out any timings that are not supported based on the
69  * hardware capabilities and the callback function (if non-NULL).
70  *
71  * If a valid timing for the given index is found, it will fill in @t and
72  * return 0, otherwise it returns -EINVAL.
73  */
74 int v4l2_enum_dv_timings_cap(struct v4l2_enum_dv_timings *t,
75 			     const struct v4l2_dv_timings_cap *cap,
76 			     v4l2_check_dv_timings_fnc fnc,
77 			     void *fnc_handle);
78 
79 /**
80  * v4l2_find_dv_timings_cap() - Find the closest timings struct
81  *
82  * @t:	  the v4l2_enum_dv_timings struct.
83  * @cap: the v4l2_dv_timings_cap capabilities.
84  * @pclock_delta: maximum delta between t->pixelclock and the timing struct
85  *		under consideration.
86  * @fnc: callback to check if a given timings struct is OK. May be NULL.
87  * @fnc_handle: a handle that is passed on to @fnc.
88  *
89  * This function tries to map the given timings to an entry in the
90  * full list of possible CEA-861 and DMT timings, filtering out any timings
91  * that are not supported based on the hardware capabilities and the callback
92  * function (if non-NULL).
93  *
94  * On success it will fill in @t with the found timings and it returns true.
95  * On failure it will return false.
96  */
97 bool v4l2_find_dv_timings_cap(struct v4l2_dv_timings *t,
98 			      const struct v4l2_dv_timings_cap *cap,
99 			      unsigned pclock_delta,
100 			      v4l2_check_dv_timings_fnc fnc,
101 			      void *fnc_handle);
102 
103 /**
104  * v4l2_find_dv_timings_cea861_vic() - find timings based on CEA-861 VIC
105  * @t:		the timings data.
106  * @vic:	CEA-861 VIC code
107  *
108  * On success it will fill in @t with the found timings and it returns true.
109  * On failure it will return false.
110  */
111 bool v4l2_find_dv_timings_cea861_vic(struct v4l2_dv_timings *t, u8 vic);
112 
113 /**
114  * v4l2_match_dv_timings() - do two timings match?
115  *
116  * @measured:	  the measured timings data.
117  * @standard:	  the timings according to the standard.
118  * @pclock_delta: maximum delta in Hz between standard->pixelclock and
119  *		the measured timings.
120  * @match_reduced_fps: if true, then fail if V4L2_DV_FL_REDUCED_FPS does not
121  * match.
122  *
123  * Returns true if the two timings match, returns false otherwise.
124  */
125 bool v4l2_match_dv_timings(const struct v4l2_dv_timings *measured,
126 			   const struct v4l2_dv_timings *standard,
127 			   unsigned pclock_delta, bool match_reduced_fps);
128 
129 /**
130  * v4l2_print_dv_timings() - log the contents of a dv_timings struct
131  * @dev_prefix:device prefix for each log line.
132  * @prefix:	additional prefix for each log line, may be NULL.
133  * @t:		the timings data.
134  * @detailed:	if true, give a detailed log.
135  */
136 void v4l2_print_dv_timings(const char *dev_prefix, const char *prefix,
137 			   const struct v4l2_dv_timings *t, bool detailed);
138 
139 /**
140  * v4l2_detect_cvt - detect if the given timings follow the CVT standard
141  *
142  * @frame_height: the total height of the frame (including blanking) in lines.
143  * @hfreq: the horizontal frequency in Hz.
144  * @vsync: the height of the vertical sync in lines.
145  * @active_width: active width of image (does not include blanking). This
146  * information is needed only in case of version 2 of reduced blanking.
147  * In other cases, this parameter does not have any effect on timings.
148  * @polarities: the horizontal and vertical polarities (same as struct
149  *		v4l2_bt_timings polarities).
150  * @interlaced: if this flag is true, it indicates interlaced format
151  * @fmt: the resulting timings.
152  *
153  * This function will attempt to detect if the given values correspond to a
154  * valid CVT format. If so, then it will return true, and fmt will be filled
155  * in with the found CVT timings.
156  */
157 bool v4l2_detect_cvt(unsigned frame_height, unsigned hfreq, unsigned vsync,
158 		unsigned active_width, u32 polarities, bool interlaced,
159 		struct v4l2_dv_timings *fmt);
160 
161 /**
162  * v4l2_detect_gtf - detect if the given timings follow the GTF standard
163  *
164  * @frame_height: the total height of the frame (including blanking) in lines.
165  * @hfreq: the horizontal frequency in Hz.
166  * @vsync: the height of the vertical sync in lines.
167  * @polarities: the horizontal and vertical polarities (same as struct
168  *		v4l2_bt_timings polarities).
169  * @interlaced: if this flag is true, it indicates interlaced format
170  * @aspect: preferred aspect ratio. GTF has no method of determining the
171  *		aspect ratio in order to derive the image width from the
172  *		image height, so it has to be passed explicitly. Usually
173  *		the native screen aspect ratio is used for this. If it
174  *		is not filled in correctly, then 16:9 will be assumed.
175  * @fmt: the resulting timings.
176  *
177  * This function will attempt to detect if the given values correspond to a
178  * valid GTF format. If so, then it will return true, and fmt will be filled
179  * in with the found GTF timings.
180  */
181 bool v4l2_detect_gtf(unsigned frame_height, unsigned hfreq, unsigned vsync,
182 		u32 polarities, bool interlaced, struct v4l2_fract aspect,
183 		struct v4l2_dv_timings *fmt);
184 
185 /**
186  * v4l2_calc_aspect_ratio - calculate the aspect ratio based on bytes
187  *	0x15 and 0x16 from the EDID.
188  *
189  * @hor_landscape: byte 0x15 from the EDID.
190  * @vert_portrait: byte 0x16 from the EDID.
191  *
192  * Determines the aspect ratio from the EDID.
193  * See VESA Enhanced EDID standard, release A, rev 2, section 3.6.2:
194  * "Horizontal and Vertical Screen Size or Aspect Ratio"
195  */
196 struct v4l2_fract v4l2_calc_aspect_ratio(u8 hor_landscape, u8 vert_portrait);
197 
198 /**
199  * v4l2_dv_timings_aspect_ratio - calculate the aspect ratio based on the
200  *	v4l2_dv_timings information.
201  *
202  * @t: the timings data.
203  */
204 struct v4l2_fract v4l2_dv_timings_aspect_ratio(const struct v4l2_dv_timings *t);
205 
206 /*
207  * reduce_fps - check if conditions for reduced fps are true.
208  * bt - v4l2 timing structure
209  * For different timings reduced fps is allowed if following conditions
210  * are met -
211  * For CVT timings: if reduced blanking v2 (vsync == 8) is true.
212  * For CEA861 timings: if V4L2_DV_FL_CAN_REDUCE_FPS flag is true.
213  */
214 static inline  bool can_reduce_fps(struct v4l2_bt_timings *bt)
215 {
216 	if ((bt->standards & V4L2_DV_BT_STD_CVT) && (bt->vsync == 8))
217 		return true;
218 
219 	if ((bt->standards & V4L2_DV_BT_STD_CEA861) &&
220 	    (bt->flags & V4L2_DV_FL_CAN_REDUCE_FPS))
221 		return true;
222 
223 	return false;
224 }
225 
226 
227 #endif
228