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