include/linux/rmi.h

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