xref: /openbmc/linux/include/linux/rmi.h (revision 261bfb33)
1 /* SPDX-License-Identifier: GPL-2.0-only */
2 /*
3  * Copyright (c) 2011-2016 Synaptics Incorporated
4  * Copyright (c) 2011 Unixphere
5  */
6 
7 #ifndef _RMI_H
8 #define _RMI_H
9 #include <linux/kernel.h>
10 #include <linux/device.h>
11 #include <linux/interrupt.h>
12 #include <linux/input.h>
13 #include <linux/kfifo.h>
14 #include <linux/list.h>
15 #include <linux/module.h>
16 #include <linux/types.h>
17 
18 #define NAME_BUFFER_SIZE 256
19 
20 /**
21  * struct rmi_2d_axis_alignment - target axis alignment
22  * @swap_axes: set to TRUE if desired to swap x- and y-axis
23  * @flip_x: set to TRUE if desired to flip direction on x-axis
24  * @flip_y: set to TRUE if desired to flip direction on y-axis
25  * @clip_x_low - reported X coordinates below this setting will be clipped to
26  *               the specified value
27  * @clip_x_high - reported X coordinates above this setting will be clipped to
28  *               the specified value
29  * @clip_y_low - reported Y coordinates below this setting will be clipped to
30  *               the specified value
31  * @clip_y_high - reported Y coordinates above this setting will be clipped to
32  *               the specified value
33  * @offset_x - this value will be added to all reported X coordinates
34  * @offset_y - this value will be added to all reported Y coordinates
35  * @rel_report_enabled - if set to true, the relative reporting will be
36  *               automatically enabled for this sensor.
37  */
38 struct rmi_2d_axis_alignment {
39 	bool swap_axes;
40 	bool flip_x;
41 	bool flip_y;
42 	u16 clip_x_low;
43 	u16 clip_y_low;
44 	u16 clip_x_high;
45 	u16 clip_y_high;
46 	u16 offset_x;
47 	u16 offset_y;
48 	u8 delta_x_threshold;
49 	u8 delta_y_threshold;
50 };
51 
52 /** This is used to override any hints an F11 2D sensor might have provided
53  * as to what type of sensor it is.
54  *
55  * @rmi_f11_sensor_default - do not override, determine from F11_2D_QUERY14 if
56  * available.
57  * @rmi_f11_sensor_touchscreen - treat the sensor as a touchscreen (direct
58  * pointing).
59  * @rmi_f11_sensor_touchpad - thread the sensor as a touchpad (indirect
60  * pointing).
61  */
62 enum rmi_sensor_type {
63 	rmi_sensor_default = 0,
64 	rmi_sensor_touchscreen,
65 	rmi_sensor_touchpad
66 };
67 
68 #define RMI_F11_DISABLE_ABS_REPORT      BIT(0)
69 
70 /**
71  * struct rmi_2d_sensor_data - overrides defaults for a 2D sensor.
72  * @axis_align - provides axis alignment overrides (see above).
73  * @sensor_type - Forces the driver to treat the sensor as an indirect
74  * pointing device (touchpad) rather than a direct pointing device
75  * (touchscreen).  This is useful when F11_2D_QUERY14 register is not
76  * available.
77  * @disable_report_mask - Force data to not be reported even if it is supported
78  * by the firware.
79  * @topbuttonpad - Used with the "5 buttons touchpads" found on the Lenovo 40
80  * series
81  * @kernel_tracking - most moderns RMI f11 firmwares implement Multifinger
82  * Type B protocol. However, there are some corner cases where the user
83  * triggers some jumps by tapping with two fingers on the touchpad.
84  * Use this setting and dmax to filter out these jumps.
85  * Also, when using an old sensor using MF Type A behavior, set to true to
86  * report an actual MT protocol B.
87  * @dmax - the maximum distance (in sensor units) the kernel tracking allows two
88  * distincts fingers to be considered the same.
89  */
90 struct rmi_2d_sensor_platform_data {
91 	struct rmi_2d_axis_alignment axis_align;
92 	enum rmi_sensor_type sensor_type;
93 	int x_mm;
94 	int y_mm;
95 	int disable_report_mask;
96 	u16 rezero_wait;
97 	bool topbuttonpad;
98 	bool kernel_tracking;
99 	int dmax;
100 	int dribble;
101 	int palm_detect;
102 };
103 
104 /**
105  * struct rmi_gpio_data - overrides defaults for a single F30/F3A GPIOs/LED
106  * chip.
107  * @buttonpad - the touchpad is a buttonpad, so enable only the first actual
108  * button that is found.
109  * @trackstick_buttons - Set when the function 30 or 3a is handling the physical
110  * buttons of the trackstick (as a PS/2 passthrough device).
111  * @disable - the touchpad incorrectly reports F30/F3A and it should be ignored.
112  * This is a special case which is due to misconfigured firmware.
113  */
114 struct rmi_gpio_data {
115 	bool buttonpad;
116 	bool trackstick_buttons;
117 	bool disable;
118 };
119 
120 
121 /*
122  * Set the state of a register
123  *	DEFAULT - use the default value set by the firmware config
124  *	OFF - explicitly disable the register
125  *	ON - explicitly enable the register
126  */
127 enum rmi_reg_state {
128 	RMI_REG_STATE_DEFAULT = 0,
129 	RMI_REG_STATE_OFF = 1,
130 	RMI_REG_STATE_ON = 2
131 };
132 
133 /**
134  * struct rmi_f01_power_management -When non-zero, these values will be written
135  * to the touch sensor to override the default firmware settigns.  For a
136  * detailed explanation of what each field does, see the corresponding
137  * documention in the RMI4 specification.
138  *
139  * @nosleep - specifies whether the device is permitted to sleep or doze (that
140  * is, enter a temporary low power state) when no fingers are touching the
141  * sensor.
142  * @wakeup_threshold - controls the capacitance threshold at which the touch
143  * sensor will decide to wake up from that low power state.
144  * @doze_holdoff - controls how long the touch sensor waits after the last
145  * finger lifts before entering the doze state, in units of 100ms.
146  * @doze_interval - controls the interval between checks for finger presence
147  * when the touch sensor is in doze mode, in units of 10ms.
148  */
149 struct rmi_f01_power_management {
150 	enum rmi_reg_state nosleep;
151 	u8 wakeup_threshold;
152 	u8 doze_holdoff;
153 	u8 doze_interval;
154 };
155 
156 /**
157  * struct rmi_device_platform_data_spi - provides parameters used in SPI
158  * communications.  All Synaptics SPI products support a standard SPI
159  * interface; some also support what is called SPI V2 mode, depending on
160  * firmware and/or ASIC limitations.  In V2 mode, the touch sensor can
161  * support shorter delays during certain operations, and these are specified
162  * separately from the standard mode delays.
163  *
164  * @block_delay - for standard SPI transactions consisting of both a read and
165  * write operation, the delay (in microseconds) between the read and write
166  * operations.
167  * @split_read_block_delay_us - for V2 SPI transactions consisting of both a
168  * read and write operation, the delay (in microseconds) between the read and
169  * write operations.
170  * @read_delay_us - the delay between each byte of a read operation in normal
171  * SPI mode.
172  * @write_delay_us - the delay between each byte of a write operation in normal
173  * SPI mode.
174  * @split_read_byte_delay_us - the delay between each byte of a read operation
175  * in V2 mode.
176  * @pre_delay_us - the delay before the start of a SPI transaction.  This is
177  * typically useful in conjunction with custom chip select assertions (see
178  * below).
179  * @post_delay_us - the delay after the completion of an SPI transaction.  This
180  * is typically useful in conjunction with custom chip select assertions (see
181  * below).
182  * @cs_assert - For systems where the SPI subsystem does not control the CS/SSB
183  * line, or where such control is broken, you can provide a custom routine to
184  * handle a GPIO as CS/SSB.  This routine will be called at the beginning and
185  * end of each SPI transaction.  The RMI SPI implementation will wait
186  * pre_delay_us after this routine returns before starting the SPI transfer;
187  * and post_delay_us after completion of the SPI transfer(s) before calling it
188  * with assert==FALSE.
189  */
190 struct rmi_device_platform_data_spi {
191 	u32 block_delay_us;
192 	u32 split_read_block_delay_us;
193 	u32 read_delay_us;
194 	u32 write_delay_us;
195 	u32 split_read_byte_delay_us;
196 	u32 pre_delay_us;
197 	u32 post_delay_us;
198 	u8 bits_per_word;
199 	u16 mode;
200 
201 	void *cs_assert_data;
202 	int (*cs_assert)(const void *cs_assert_data, const bool assert);
203 };
204 
205 /**
206  * struct rmi_device_platform_data - system specific configuration info.
207  *
208  * @reset_delay_ms - after issuing a reset command to the touch sensor, the
209  * driver waits a few milliseconds to give the firmware a chance to
210  * re-initialize.  You can override the default wait period here.
211  * @irq: irq associated with the attn gpio line, or negative
212  */
213 struct rmi_device_platform_data {
214 	int reset_delay_ms;
215 	int irq;
216 
217 	struct rmi_device_platform_data_spi spi_data;
218 
219 	/* function handler pdata */
220 	struct rmi_2d_sensor_platform_data sensor_pdata;
221 	struct rmi_f01_power_management power_management;
222 	struct rmi_gpio_data gpio_data;
223 };
224 
225 /**
226  * struct rmi_function_descriptor - RMI function base addresses
227  *
228  * @query_base_addr: The RMI Query base address
229  * @command_base_addr: The RMI Command base address
230  * @control_base_addr: The RMI Control base address
231  * @data_base_addr: The RMI Data base address
232  * @interrupt_source_count: The number of irqs this RMI function needs
233  * @function_number: The RMI function number
234  *
235  * This struct is used when iterating the Page Description Table. The addresses
236  * are 16-bit values to include the current page address.
237  *
238  */
239 struct rmi_function_descriptor {
240 	u16 query_base_addr;
241 	u16 command_base_addr;
242 	u16 control_base_addr;
243 	u16 data_base_addr;
244 	u8 interrupt_source_count;
245 	u8 function_number;
246 	u8 function_version;
247 };
248 
249 struct rmi_device;
250 
251 /**
252  * struct rmi_transport_dev - represent an RMI transport device
253  *
254  * @dev: Pointer to the communication device, e.g. i2c or spi
255  * @rmi_dev: Pointer to the RMI device
256  * @proto_name: name of the transport protocol (SPI, i2c, etc)
257  * @ops: pointer to transport operations implementation
258  *
259  * The RMI transport device implements the glue between different communication
260  * buses such as I2C and SPI.
261  *
262  */
263 struct rmi_transport_dev {
264 	struct device *dev;
265 	struct rmi_device *rmi_dev;
266 
267 	const char *proto_name;
268 	const struct rmi_transport_ops *ops;
269 
270 	struct rmi_device_platform_data pdata;
271 
272 	struct input_dev *input;
273 };
274 
275 /**
276  * struct rmi_transport_ops - defines transport protocol operations.
277  *
278  * @write_block: Writing a block of data to the specified address
279  * @read_block: Read a block of data from the specified address.
280  */
281 struct rmi_transport_ops {
282 	int (*write_block)(struct rmi_transport_dev *xport, u16 addr,
283 			   const void *buf, size_t len);
284 	int (*read_block)(struct rmi_transport_dev *xport, u16 addr,
285 			  void *buf, size_t len);
286 	int (*reset)(struct rmi_transport_dev *xport, u16 reset_addr);
287 };
288 
289 /**
290  * struct rmi_driver - driver for an RMI4 sensor on the RMI bus.
291  *
292  * @driver: Device driver model driver
293  * @reset_handler: Called when a reset is detected.
294  * @clear_irq_bits: Clear the specified bits in the current interrupt mask.
295  * @set_irq_bist: Set the specified bits in the current interrupt mask.
296  * @store_productid: Callback for cache product id from function 01
297  * @data: Private data pointer
298  *
299  */
300 struct rmi_driver {
301 	struct device_driver driver;
302 
303 	int (*reset_handler)(struct rmi_device *rmi_dev);
304 	int (*clear_irq_bits)(struct rmi_device *rmi_dev, unsigned long *mask);
305 	int (*set_irq_bits)(struct rmi_device *rmi_dev, unsigned long *mask);
306 	int (*store_productid)(struct rmi_device *rmi_dev);
307 	int (*set_input_params)(struct rmi_device *rmi_dev,
308 			struct input_dev *input);
309 	void *data;
310 };
311 
312 /**
313  * struct rmi_device - represents an RMI4 sensor device on the RMI bus.
314  *
315  * @dev: The device created for the RMI bus
316  * @number: Unique number for the device on the bus.
317  * @driver: Pointer to associated driver
318  * @xport: Pointer to the transport interface
319  *
320  */
321 struct rmi_device {
322 	struct device dev;
323 	int number;
324 
325 	struct rmi_driver *driver;
326 	struct rmi_transport_dev *xport;
327 
328 };
329 
330 struct rmi4_attn_data {
331 	unsigned long irq_status;
332 	size_t size;
333 	void *data;
334 };
335 
336 struct rmi_driver_data {
337 	struct list_head function_list;
338 
339 	struct rmi_device *rmi_dev;
340 
341 	struct rmi_function *f01_container;
342 	struct rmi_function *f34_container;
343 	bool bootloader_mode;
344 
345 	int num_of_irq_regs;
346 	int irq_count;
347 	void *irq_memory;
348 	unsigned long *irq_status;
349 	unsigned long *fn_irq_bits;
350 	unsigned long *current_irq_mask;
351 	unsigned long *new_irq_mask;
352 	struct mutex irq_mutex;
353 	struct input_dev *input;
354 
355 	struct irq_domain *irqdomain;
356 
357 	u8 pdt_props;
358 
359 	u8 num_rx_electrodes;
360 	u8 num_tx_electrodes;
361 
362 	bool enabled;
363 	struct mutex enabled_mutex;
364 
365 	struct rmi4_attn_data attn_data;
366 	DECLARE_KFIFO(attn_fifo, struct rmi4_attn_data, 16);
367 };
368 
369 int rmi_register_transport_device(struct rmi_transport_dev *xport);
370 void rmi_unregister_transport_device(struct rmi_transport_dev *xport);
371 
372 void rmi_set_attn_data(struct rmi_device *rmi_dev, unsigned long irq_status,
373 		       void *data, size_t size);
374 
375 int rmi_driver_suspend(struct rmi_device *rmi_dev, bool enable_wake);
376 int rmi_driver_resume(struct rmi_device *rmi_dev, bool clear_wake);
377 #endif
378