xref: /linux/include/linux/iio/iio-gts-helper.h (revision 1ac731c529cd4d6adbce134754b51ff7d822b145)
1 /* SPDX-License-Identifier: GPL-2.0-only */
2 /* gain-time-scale conversion helpers for IIO light sensors
3  *
4  * Copyright (c) 2023 Matti Vaittinen <mazziesaccount@gmail.com>
5  */
6 
7 #ifndef __IIO_GTS_HELPER__
8 #define __IIO_GTS_HELPER__
9 
10 #include <linux/types.h>
11 
12 struct device;
13 
14 /**
15  * struct iio_gain_sel_pair - gain - selector values
16  *
17  * In many cases devices like light sensors allow setting signal amplification
18  * (gain) using a register interface. This structure describes amplification
19  * and corresponding selector (register value)
20  *
21  * @gain:	Gain (multiplication) value. Gain must be positive, negative
22  *		values are reserved for error handling.
23  * @sel:	Selector (usually register value) used to indicate this gain.
24  *		NOTE: Only selectors >= 0 supported.
25  */
26 struct iio_gain_sel_pair {
27 	int gain;
28 	int sel;
29 };
30 
31 /**
32  * struct iio_itime_sel_mul - integration time description
33  *
34  * In many cases devices like light sensors allow setting the duration of
35  * collecting data. Typically this duration has also an impact to the magnitude
36  * of measured values (gain). This structure describes the relation of
37  * integration time and amplification as well as corresponding selector
38  * (register value).
39  *
40  * An example could be a sensor allowing 50, 100, 200 and 400 mS times. The
41  * respective multiplication values could be 50 mS => 1, 100 mS => 2,
42  * 200 mS => 4 and 400 mS => 8 assuming the impact of integration time would be
43  * linear in a way that when collecting data for 50 mS caused value X, doubling
44  * the data collection time caused value 2X etc.
45  *
46  * @time_us:	Integration time in microseconds. Time values must be positive,
47  *		negative values are reserved for error handling.
48  * @sel:	Selector (usually register value) used to indicate this time
49  *		NOTE: Only selectors >= 0 supported.
50  * @mul:	Multiplication to the values caused by this time.
51  *		NOTE: Only multipliers > 0 supported.
52  */
53 struct iio_itime_sel_mul {
54 	int time_us;
55 	int sel;
56 	int mul;
57 };
58 
59 struct iio_gts {
60 	u64 max_scale;
61 	const struct iio_gain_sel_pair *hwgain_table;
62 	int num_hwgain;
63 	const struct iio_itime_sel_mul *itime_table;
64 	int num_itime;
65 	int **per_time_avail_scale_tables;
66 	int *avail_all_scales_table;
67 	int num_avail_all_scales;
68 	int *avail_time_tables;
69 	int num_avail_time_tables;
70 };
71 
72 #define GAIN_SCALE_GAIN(_gain, _sel)			\
73 {							\
74 	.gain = (_gain),				\
75 	.sel = (_sel),					\
76 }
77 
78 #define GAIN_SCALE_ITIME_US(_itime, _sel, _mul)		\
79 {							\
80 	.time_us = (_itime),				\
81 	.sel = (_sel),					\
82 	.mul = (_mul),					\
83 }
84 
85 static inline const struct iio_itime_sel_mul *
iio_gts_find_itime_by_time(struct iio_gts * gts,int time)86 iio_gts_find_itime_by_time(struct iio_gts *gts, int time)
87 {
88 	int i;
89 
90 	if (!gts->num_itime)
91 		return NULL;
92 
93 	for (i = 0; i < gts->num_itime; i++)
94 		if (gts->itime_table[i].time_us == time)
95 			return &gts->itime_table[i];
96 
97 	return NULL;
98 }
99 
100 static inline const struct iio_itime_sel_mul *
iio_gts_find_itime_by_sel(struct iio_gts * gts,int sel)101 iio_gts_find_itime_by_sel(struct iio_gts *gts, int sel)
102 {
103 	int i;
104 
105 	for (i = 0; i < gts->num_itime; i++)
106 		if (gts->itime_table[i].sel == sel)
107 			return &gts->itime_table[i];
108 
109 	return NULL;
110 }
111 
112 int devm_iio_init_iio_gts(struct device *dev, int max_scale_int, int max_scale_nano,
113 			  const struct iio_gain_sel_pair *gain_tbl, int num_gain,
114 			  const struct iio_itime_sel_mul *tim_tbl, int num_times,
115 			  struct iio_gts *gts);
116 /**
117  * iio_gts_find_int_time_by_sel - find integration time matching a selector
118  * @gts:	Gain time scale descriptor
119  * @sel:	selector for which matching integration time is searched for
120  *
121  * Return:	integration time matching given selector or -EINVAL if
122  *		integration time was not found.
123  */
iio_gts_find_int_time_by_sel(struct iio_gts * gts,int sel)124 static inline int iio_gts_find_int_time_by_sel(struct iio_gts *gts, int sel)
125 {
126 	const struct iio_itime_sel_mul *itime;
127 
128 	itime = iio_gts_find_itime_by_sel(gts, sel);
129 	if (!itime)
130 		return -EINVAL;
131 
132 	return itime->time_us;
133 }
134 
135 /**
136  * iio_gts_find_sel_by_int_time - find selector matching integration time
137  * @gts:	Gain time scale descriptor
138  * @time:	Integration time for which matching selector is searched for
139  *
140  * Return:	a selector matching given integration time or -EINVAL if
141  *		selector was not found.
142  */
iio_gts_find_sel_by_int_time(struct iio_gts * gts,int time)143 static inline int iio_gts_find_sel_by_int_time(struct iio_gts *gts, int time)
144 {
145 	const struct iio_itime_sel_mul *itime;
146 
147 	itime = iio_gts_find_itime_by_time(gts, time);
148 	if (!itime)
149 		return -EINVAL;
150 
151 	return itime->sel;
152 }
153 
154 /**
155  * iio_gts_valid_time - check if given integration time is valid
156  * @gts:	Gain time scale descriptor
157  * @time_us:	Integration time to check
158  *
159  * Return:	True if given time is supported by device. False if not.
160  */
iio_gts_valid_time(struct iio_gts * gts,int time_us)161 static inline bool iio_gts_valid_time(struct iio_gts *gts, int time_us)
162 {
163 	return iio_gts_find_itime_by_time(gts, time_us) != NULL;
164 }
165 
166 int iio_gts_find_sel_by_gain(struct iio_gts *gts, int gain);
167 
168 /**
169  * iio_gts_valid_gain - check if given HW-gain is valid
170  * @gts:	Gain time scale descriptor
171  * @gain:	HW-gain to check
172  *
173  * Return:	True if given time is supported by device. False if not.
174  */
iio_gts_valid_gain(struct iio_gts * gts,int gain)175 static inline bool iio_gts_valid_gain(struct iio_gts *gts, int gain)
176 {
177 	return iio_gts_find_sel_by_gain(gts, gain) >= 0;
178 }
179 
180 int iio_find_closest_gain_low(struct iio_gts *gts, int gain, bool *in_range);
181 int iio_gts_find_gain_by_sel(struct iio_gts *gts, int sel);
182 int iio_gts_get_min_gain(struct iio_gts *gts);
183 int iio_gts_find_int_time_by_sel(struct iio_gts *gts, int sel);
184 int iio_gts_find_sel_by_int_time(struct iio_gts *gts, int time);
185 
186 int iio_gts_total_gain_to_scale(struct iio_gts *gts, int total_gain,
187 				int *scale_int, int *scale_nano);
188 int iio_gts_find_gain_sel_for_scale_using_time(struct iio_gts *gts, int time_sel,
189 					       int scale_int, int scale_nano,
190 					       int *gain_sel);
191 int iio_gts_get_scale(struct iio_gts *gts, int gain, int time, int *scale_int,
192 		      int *scale_nano);
193 int iio_gts_find_new_gain_sel_by_old_gain_time(struct iio_gts *gts,
194 					       int old_gain, int old_time_sel,
195 					       int new_time_sel, int *new_gain);
196 int iio_gts_find_new_gain_by_old_gain_time(struct iio_gts *gts, int old_gain,
197 					   int old_time, int new_time,
198 					   int *new_gain);
199 int iio_gts_avail_times(struct iio_gts *gts,  const int **vals, int *type,
200 			int *length);
201 int iio_gts_all_avail_scales(struct iio_gts *gts, const int **vals, int *type,
202 			     int *length);
203 int iio_gts_avail_scales_for_time(struct iio_gts *gts, int time,
204 				  const int **vals, int *type, int *length);
205 
206 #endif
207