include/linux/rmi.h

0001 /* SPDX-License-Identifier: GPL-2.0-only */
0002 /*
0003  * Copyright (c) 2011-2016 Synaptics Incorporated
0004  * Copyright (c) 2011 Unixphere
0005  */
0006
0007 #ifndef _RMI_H
0008 #define _RMI_H
0009 #include <linux/kernel.h>
0010 #include <linux/device.h>
0011 #include <linux/interrupt.h>
0012 #include <linux/input.h>
0013 #include <linux/kfifo.h>
0014 #include <linux/list.h>
0015 #include <linux/module.h>
0016 #include <linux/types.h>
0017
0018 #define NAME_BUFFER_SIZE 256
0019
0020 /**
0021  * struct rmi_2d_axis_alignment - target axis alignment
0022  * @swap_axes: set to TRUE if desired to swap x- and y-axis
0023  * @flip_x: set to TRUE if desired to flip direction on x-axis
0024  * @flip_y: set to TRUE if desired to flip direction on y-axis
0025  * @clip_x_low - reported X coordinates below this setting will be clipped to
0026  *               the specified value
0027  * @clip_x_high - reported X coordinates above this setting will be clipped to
0028  *               the specified value
0029  * @clip_y_low - reported Y coordinates below this setting will be clipped to
0030  *               the specified value
0031  * @clip_y_high - reported Y coordinates above this setting will be clipped to
0032  *               the specified value
0033  * @offset_x - this value will be added to all reported X coordinates
0034  * @offset_y - this value will be added to all reported Y coordinates
0035  * @rel_report_enabled - if set to true, the relative reporting will be
0036  *               automatically enabled for this sensor.
0037  */
0038 struct rmi_2d_axis_alignment {
0039     bool swap_axes;
0040     bool flip_x;
0041     bool flip_y;
0042     u16 clip_x_low;
0043     u16 clip_y_low;
0044     u16 clip_x_high;
0045     u16 clip_y_high;
0046     u16 offset_x;
0047     u16 offset_y;
0048     u8 delta_x_threshold;
0049     u8 delta_y_threshold;
0050 };
0051
0052 /** This is used to override any hints an F11 2D sensor might have provided
0053  * as to what type of sensor it is.
0054  *
0055  * @rmi_f11_sensor_default - do not override, determine from F11_2D_QUERY14 if
0056  * available.
0057  * @rmi_f11_sensor_touchscreen - treat the sensor as a touchscreen (direct
0058  * pointing).
0059  * @rmi_f11_sensor_touchpad - thread the sensor as a touchpad (indirect
0060  * pointing).
0061  */
0062 enum rmi_sensor_type {
0063     rmi_sensor_default = 0,
0064     rmi_sensor_touchscreen,
0065     rmi_sensor_touchpad
0066 };
0067
0068 #define RMI_F11_DISABLE_ABS_REPORT      BIT(0)
0069
0070 /**
0071  * struct rmi_2d_sensor_data - overrides defaults for a 2D sensor.
0072  * @axis_align - provides axis alignment overrides (see above).
0073  * @sensor_type - Forces the driver to treat the sensor as an indirect
0074  * pointing device (touchpad) rather than a direct pointing device
0075  * (touchscreen).  This is useful when F11_2D_QUERY14 register is not
0076  * available.
0077  * @disable_report_mask - Force data to not be reported even if it is supported
0078  * by the firware.
0079  * @topbuttonpad - Used with the "5 buttons touchpads" found on the Lenovo 40
0080  * series
0081  * @kernel_tracking - most moderns RMI f11 firmwares implement Multifinger
0082  * Type B protocol. However, there are some corner cases where the user
0083  * triggers some jumps by tapping with two fingers on the touchpad.
0084  * Use this setting and dmax to filter out these jumps.
0085  * Also, when using an old sensor using MF Type A behavior, set to true to
0086  * report an actual MT protocol B.
0087  * @dmax - the maximum distance (in sensor units) the kernel tracking allows two
0088  * distincts fingers to be considered the same.
0089  */
0090 struct rmi_2d_sensor_platform_data {
0091     struct rmi_2d_axis_alignment axis_align;
0092     enum rmi_sensor_type sensor_type;
0093     int x_mm;
0094     int y_mm;
0095     int disable_report_mask;
0096     u16 rezero_wait;
0097     bool topbuttonpad;
0098     bool kernel_tracking;
0099     int dmax;
0100     int dribble;
0101     int palm_detect;
0102 };
0103
0104 /**
0105  * struct rmi_gpio_data - overrides defaults for a single F30/F3A GPIOs/LED
0106  * chip.
0107  * @buttonpad - the touchpad is a buttonpad, so enable only the first actual
0108  * button that is found.
0109  * @trackstick_buttons - Set when the function 30 or 3a is handling the physical
0110  * buttons of the trackstick (as a PS/2 passthrough device).
0111  * @disable - the touchpad incorrectly reports F30/F3A and it should be ignored.
0112  * This is a special case which is due to misconfigured firmware.
0113  */
0114 struct rmi_gpio_data {
0115     bool buttonpad;
0116     bool trackstick_buttons;
0117     bool disable;
0118 };
0119
0120
0121 /*
0122  * Set the state of a register
0123  *  DEFAULT - use the default value set by the firmware config
0124  *  OFF - explicitly disable the register
0125  *  ON - explicitly enable the register
0126  */
0127 enum rmi_reg_state {
0128     RMI_REG_STATE_DEFAULT = 0,
0129     RMI_REG_STATE_OFF = 1,
0130     RMI_REG_STATE_ON = 2
0131 };
0132
0133 /**
0134  * struct rmi_f01_power_management -When non-zero, these values will be written
0135  * to the touch sensor to override the default firmware settigns.  For a
0136  * detailed explanation of what each field does, see the corresponding
0137  * documention in the RMI4 specification.
0138  *
0139  * @nosleep - specifies whether the device is permitted to sleep or doze (that
0140  * is, enter a temporary low power state) when no fingers are touching the
0141  * sensor.
0142  * @wakeup_threshold - controls the capacitance threshold at which the touch
0143  * sensor will decide to wake up from that low power state.
0144  * @doze_holdoff - controls how long the touch sensor waits after the last
0145  * finger lifts before entering the doze state, in units of 100ms.
0146  * @doze_interval - controls the interval between checks for finger presence
0147  * when the touch sensor is in doze mode, in units of 10ms.
0148  */
0149 struct rmi_f01_power_management {
0150     enum rmi_reg_state nosleep;
0151     u8 wakeup_threshold;
0152     u8 doze_holdoff;
0153     u8 doze_interval;
0154 };
0155
0156 /**
0157  * struct rmi_device_platform_data_spi - provides parameters used in SPI
0158  * communications.  All Synaptics SPI products support a standard SPI
0159  * interface; some also support what is called SPI V2 mode, depending on
0160  * firmware and/or ASIC limitations.  In V2 mode, the touch sensor can
0161  * support shorter delays during certain operations, and these are specified
0162  * separately from the standard mode delays.
0163  *
0164  * @block_delay - for standard SPI transactions consisting of both a read and
0165  * write operation, the delay (in microseconds) between the read and write
0166  * operations.
0167  * @split_read_block_delay_us - for V2 SPI transactions consisting of both a
0168  * read and write operation, the delay (in microseconds) between the read and
0169  * write operations.
0170  * @read_delay_us - the delay between each byte of a read operation in normal
0171  * SPI mode.
0172  * @write_delay_us - the delay between each byte of a write operation in normal
0173  * SPI mode.
0174  * @split_read_byte_delay_us - the delay between each byte of a read operation
0175  * in V2 mode.
0176  * @pre_delay_us - the delay before the start of a SPI transaction.  This is
0177  * typically useful in conjunction with custom chip select assertions (see
0178  * below).
0179  * @post_delay_us - the delay after the completion of an SPI transaction.  This
0180  * is typically useful in conjunction with custom chip select assertions (see
0181  * below).
0182  * @cs_assert - For systems where the SPI subsystem does not control the CS/SSB
0183  * line, or where such control is broken, you can provide a custom routine to
0184  * handle a GPIO as CS/SSB.  This routine will be called at the beginning and
0185  * end of each SPI transaction.  The RMI SPI implementation will wait
0186  * pre_delay_us after this routine returns before starting the SPI transfer;
0187  * and post_delay_us after completion of the SPI transfer(s) before calling it
0188  * with assert==FALSE.
0189  */
0190 struct rmi_device_platform_data_spi {
0191     u32 block_delay_us;
0192     u32 split_read_block_delay_us;
0193     u32 read_delay_us;
0194     u32 write_delay_us;
0195     u32 split_read_byte_delay_us;
0196     u32 pre_delay_us;
0197     u32 post_delay_us;
0198     u8 bits_per_word;
0199     u16 mode;
0200
0201     void *cs_assert_data;
0202     int (*cs_assert)(const void *cs_assert_data, const bool assert);
0203 };
0204
0205 /**
0206  * struct rmi_device_platform_data - system specific configuration info.
0207  *
0208  * @reset_delay_ms - after issuing a reset command to the touch sensor, the
0209  * driver waits a few milliseconds to give the firmware a chance to
0210  * re-initialize.  You can override the default wait period here.
0211  * @irq: irq associated with the attn gpio line, or negative
0212  */
0213 struct rmi_device_platform_data {
0214     int reset_delay_ms;
0215     int irq;
0216
0217     struct rmi_device_platform_data_spi spi_data;
0218
0219     /* function handler pdata */
0220     struct rmi_2d_sensor_platform_data sensor_pdata;
0221     struct rmi_f01_power_management power_management;
0222     struct rmi_gpio_data gpio_data;
0223 };
0224
0225 /**
0226  * struct rmi_function_descriptor - RMI function base addresses
0227  *
0228  * @query_base_addr: The RMI Query base address
0229  * @command_base_addr: The RMI Command base address
0230  * @control_base_addr: The RMI Control base address
0231  * @data_base_addr: The RMI Data base address
0232  * @interrupt_source_count: The number of irqs this RMI function needs
0233  * @function_number: The RMI function number
0234  *
0235  * This struct is used when iterating the Page Description Table. The addresses
0236  * are 16-bit values to include the current page address.
0237  *
0238  */
0239 struct rmi_function_descriptor {
0240     u16 query_base_addr;
0241     u16 command_base_addr;
0242     u16 control_base_addr;
0243     u16 data_base_addr;
0244     u8 interrupt_source_count;
0245     u8 function_number;
0246     u8 function_version;
0247 };
0248
0249 struct rmi_device;
0250
0251 /**
0252  * struct rmi_transport_dev - represent an RMI transport device
0253  *
0254  * @dev: Pointer to the communication device, e.g. i2c or spi
0255  * @rmi_dev: Pointer to the RMI device
0256  * @proto_name: name of the transport protocol (SPI, i2c, etc)
0257  * @ops: pointer to transport operations implementation
0258  *
0259  * The RMI transport device implements the glue between different communication
0260  * buses such as I2C and SPI.
0261  *
0262  */
0263 struct rmi_transport_dev {
0264     struct device *dev;
0265     struct rmi_device *rmi_dev;
0266
0267     const char *proto_name;
0268     const struct rmi_transport_ops *ops;
0269
0270     struct rmi_device_platform_data pdata;
0271
0272     struct input_dev *input;
0273 };
0274
0275 /**
0276  * struct rmi_transport_ops - defines transport protocol operations.
0277  *
0278  * @write_block: Writing a block of data to the specified address
0279  * @read_block: Read a block of data from the specified address.
0280  */
0281 struct rmi_transport_ops {
0282     int (*write_block)(struct rmi_transport_dev *xport, u16 addr,
0283                const void *buf, size_t len);
0284     int (*read_block)(struct rmi_transport_dev *xport, u16 addr,
0285               void *buf, size_t len);
0286     int (*reset)(struct rmi_transport_dev *xport, u16 reset_addr);
0287 };
0288
0289 /**
0290  * struct rmi_driver - driver for an RMI4 sensor on the RMI bus.
0291  *
0292  * @driver: Device driver model driver
0293  * @reset_handler: Called when a reset is detected.
0294  * @clear_irq_bits: Clear the specified bits in the current interrupt mask.
0295  * @set_irq_bist: Set the specified bits in the current interrupt mask.
0296  * @store_productid: Callback for cache product id from function 01
0297  * @data: Private data pointer
0298  *
0299  */
0300 struct rmi_driver {
0301     struct device_driver driver;
0302
0303     int (*reset_handler)(struct rmi_device *rmi_dev);
0304     int (*clear_irq_bits)(struct rmi_device *rmi_dev, unsigned long *mask);
0305     int (*set_irq_bits)(struct rmi_device *rmi_dev, unsigned long *mask);
0306     int (*store_productid)(struct rmi_device *rmi_dev);
0307     int (*set_input_params)(struct rmi_device *rmi_dev,
0308             struct input_dev *input);
0309     void *data;
0310 };
0311
0312 /**
0313  * struct rmi_device - represents an RMI4 sensor device on the RMI bus.
0314  *
0315  * @dev: The device created for the RMI bus
0316  * @number: Unique number for the device on the bus.
0317  * @driver: Pointer to associated driver
0318  * @xport: Pointer to the transport interface
0319  *
0320  */
0321 struct rmi_device {
0322     struct device dev;
0323     int number;
0324
0325     struct rmi_driver *driver;
0326     struct rmi_transport_dev *xport;
0327
0328 };
0329
0330 struct rmi4_attn_data {
0331     unsigned long irq_status;
0332     size_t size;
0333     void *data;
0334 };
0335
0336 struct rmi_driver_data {
0337     struct list_head function_list;
0338
0339     struct rmi_device *rmi_dev;
0340
0341     struct rmi_function *f01_container;
0342     struct rmi_function *f34_container;
0343     bool bootloader_mode;
0344
0345     int num_of_irq_regs;
0346     int irq_count;
0347     void *irq_memory;
0348     unsigned long *irq_status;
0349     unsigned long *fn_irq_bits;
0350     unsigned long *current_irq_mask;
0351     unsigned long *new_irq_mask;
0352     struct mutex irq_mutex;
0353     struct input_dev *input;
0354
0355     struct irq_domain *irqdomain;
0356
0357     u8 pdt_props;
0358
0359     u8 num_rx_electrodes;
0360     u8 num_tx_electrodes;
0361
0362     bool enabled;
0363     struct mutex enabled_mutex;
0364
0365     struct rmi4_attn_data attn_data;
0366     DECLARE_KFIFO(attn_fifo, struct rmi4_attn_data, 16);
0367 };
0368
0369 int rmi_register_transport_device(struct rmi_transport_dev *xport);
0370 void rmi_unregister_transport_device(struct rmi_transport_dev *xport);
0371
0372 void rmi_set_attn_data(struct rmi_device *rmi_dev, unsigned long irq_status,
0373                void *data, size_t size);
0374
0375 int rmi_driver_suspend(struct rmi_device *rmi_dev, bool enable_wake);
0376 int rmi_driver_resume(struct rmi_device *rmi_dev, bool clear_wake);
0377 #endif