include/linux/rmi.h

   1 /*
   2  * Copyright (c) 2011 Synaptics Incorporated
   3  * Copyright (c) 2011 Unixphere
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License
  16  * along with this program; if not, write to the Free Software
  17  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  18  */
  19 #ifndef _RMI_H
  20 #define _RMI_H
  21 #include <linux/kernel.h>
  22 #include <linux/lockdep.h>
  23 #include <linux/module.h>
  24 #include <linux/types.h>
  25 #include <linux/device.h>
  26 #include <linux/cdev.h>
  27 #include <linux/mutex.h>
  28 #include <linux/stat.h>
  29 #include <linux/wait.h>
  30 #include <linux/list.h>
  31 #include <linux/interrupt.h>
  32
  33 #ifdef CONFIG_RMI_DEBUG
  34 #include <linux/debugfs.h>
  35 #endif
  36
  37 #ifdef CONFIG_HAS_EARLYSUSPEND
  38 #include <linux/earlysuspend.h>
  39 #endif
  40
  41
  42 /* Permissions for sysfs attributes.  Since the permissions policy will change
  43  * on a global basis in the future, rather than edit all sysfs attrs everywhere
  44  * in the driver (and risk screwing that up in the process), we use this handy
  45  * set of #defines.  That way when we change the policy for sysfs permissions,
  46  * we only need to change them here.
  47  */
  48 #define RMI_RO_ATTR S_IRUGO
  49 #define RMI_RW_ATTR (S_IRUGO | S_IWUGO)
  50 #define RMI_WO_ATTR S_IWUGO
  51
  52 #define PDT_START_SCAN_LOCATION 0x00e9
  53
  54 enum rmi_attn_polarity {
  55         RMI_ATTN_ACTIVE_LOW = 0,
  56         RMI_ATTN_ACTIVE_HIGH = 1
  57 };
  58
  59 /**
  60  * struct rmi_f11_axis_alignment - target axis alignment
  61  * @swap_axes: set to TRUE if desired to swap x- and y-axis
  62  * @flip_x: set to TRUE if desired to flip direction on x-axis
  63  * @flip_y: set to TRUE if desired to flip direction on y-axis
  64  */
  65 struct rmi_f11_2d_axis_alignment {
  66         bool swap_axes;
  67         bool flip_x;
  68         bool flip_y;
  69         int clip_X_low;
  70         int clip_Y_low;
  71         int clip_X_high;
  72         int clip_Y_high;
  73         int offset_X;
  74         int offset_Y;
  75         int rel_report_enabled;
  76 };
  77
  78 /**
  79  * struct rmi_f01_power - override default power management settings.
  80  *
  81  */
  82 enum rmi_f01_nosleep {
  83         RMI_F01_NOSLEEP_DEFAULT = 0,
  84         RMI_F01_NOSLEEP_OFF = 1,
  85         RMI_F01_NOSLEEP_ON = 2
  86 };
  87
  88 struct rmi_f01_power_management {
  89         enum rmi_f01_nosleep nosleep;
  90         u8 wakeup_threshold;
  91         u8 doze_holdoff;
  92         u8 doze_interval;
  93 };
  94
  95 struct rmi_f19_button_map {
  96         unsigned char nbuttons;
  97         unsigned char *map;
  98 };
  99
 100 struct rmi_f1a_button_map {
 101         unsigned char nbuttons;
 102         unsigned char *map;
 103 };
 104
 105 struct virtualbutton_map {
 106         u16 x;
 107         u16 y;
 108         u16 width;
 109         u16 height;
 110         u16 code;
 111 };
 112
 113 struct rmi_f11_virtualbutton_map {
 114         u8 buttons;
 115         struct virtualbutton_map *map;
 116 };
 117 struct rmi_device_platform_data_spi {
 118         int block_delay_us;
 119         int split_read_block_delay_us;
 120         int read_delay_us;
 121         int write_delay_us;
 122         int split_read_byte_delay_us;
 123         int pre_delay_us;
 124         int post_delay_us;
 125
 126         void *cs_assert_data;
 127         int (*cs_assert) (const void *cs_assert_data, const bool assert);
 128 };
 129
 130 struct rmi_device_platform_data {
 131         char *driver_name;
 132         char *sensor_name;      /* Used for diagnostics. */
 133
 134         int attn_gpio;
 135         enum rmi_attn_polarity attn_polarity;
 136         bool level_triggered;
 137         void *gpio_data;
 138         int (*gpio_config)(void *gpio_data, bool configure);
 139
 140         int reset_delay_ms;
 141
 142         struct rmi_device_platform_data_spi spi_data;
 143
 144         /* function handler pdata */
 145         struct rmi_f01_power_management power_management;
 146         struct rmi_f11_2d_axis_alignment axis_align;
 147         struct rmi_f19_button_map *button_map;
 148         struct rmi_f1a_button_map *f1a_button_map;
 149         struct rmi_f11_virtualbutton_map *virtualbutton_map;
 150         int (*init_hw)(void);
 151 #ifdef  CONFIG_PM
 152         void *pm_data;
 153         int (*pre_suspend) (const void *pm_data);
 154         int (*post_resume) (const void *pm_data);
 155 #endif
 156 };
 157
 158 /**
 159  * struct rmi_function_descriptor - RMI function base addresses
 160  * @query_base_addr: The RMI Query base address
 161  * @command_base_addr: The RMI Command base address
 162  * @control_base_addr: The RMI Control base address
 163  * @data_base_addr: The RMI Data base address
 164  * @interrupt_source_count: The number of irqs this RMI function needs
 165  * @function_number: The RMI function number
 166  *
 167  * This struct is used when iterating the Page Description Table. The addresses
 168  * are 16-bit values to include the current page address.
 169  *
 170  */
 171 struct rmi_function_descriptor {
 172         u16 query_base_addr;
 173         u16 command_base_addr;
 174         u16 control_base_addr;
 175         u16 data_base_addr;
 176         u8 interrupt_source_count;
 177         u8 function_number;
 178         u8 function_version;
 179 };
 180
 181 struct rmi_function_container;
 182 struct rmi_device;
 183
 184 /**
 185  * struct rmi_function_handler - an RMI function handler
 186  * @func: The RMI function number
 187  * @init: Callback for RMI function init
 188  * @attention: Callback for RMI function attention
 189  * @suspend: Callback for function suspend, returns 0 for success.
 190  * @resume: Callback for RMI function resume, returns 0 for success.
 191  * @remove: Callback for RMI function removal
 192  *
 193  * This struct describes the interface of an RMI function. These are
 194  * registered to the bus using the rmi_register_function_driver() call.
 195  *
 196  */
 197 struct rmi_function_handler {
 198         int func;
 199         int (*init)(struct rmi_function_container *fc);
 200         int (*config)(struct rmi_function_container *fc);
 201         int (*reset)(struct rmi_function_container *fc);
 202         int (*attention)(struct rmi_function_container *fc, u8 *irq_bits);
 203 #ifdef CONFIG_PM
 204         int (*suspend)(struct rmi_function_container *fc);
 205         int (*resume)(struct rmi_function_container *fc);
 206 #ifdef CONFIG_HAS_EARLYSUSPEND
 207         int (*early_suspend)(struct rmi_function_container *fc);
 208         int (*late_resume)(struct rmi_function_container *fc);
 209 #endif
 210 #endif
 211         void (*remove)(struct rmi_function_container *fc);
 212 };
 213
 214 /**
 215  * struct rmi_function_container - an element in a function handler list
 216  * @list: The list
 217  * @fd: The function descriptor of the RMI function
 218  * @rmi_dev: Pointer to the RMI device associated with this function container
 219  * @fh: The callbacks connected to this function
 220  * @num_of_irqs: The number of irqs needed by this function
 221  * @irq_pos: The position in the irq bitfield this function holds
 222  * @data: Private data pointer
 223  *
 224  */
 225 struct rmi_function_container {
 226         struct list_head list;
 227
 228         struct rmi_function_descriptor fd;
 229         struct rmi_device *rmi_dev;
 230         struct rmi_function_handler *fh;
 231         struct device dev;
 232
 233 #ifdef CONFIG_RMI4_DEBUG
 234         struct dentry *debugfs_root;
 235 #endif
 236
 237         int num_of_irqs;
 238         int irq_pos;
 239         u8 *irq_mask;
 240
 241         void *data;
 242 };
 243 #define to_rmi_function_container(d) \
 244                 container_of(d, struct rmi_function_container, dev);
 245
 246
 247 /**
 248  * struct rmi_driver - represents an RMI driver
 249  * @driver: Device driver model driver
 250  * @probe: Callback for device probe
 251  * @remove: Callback for device removal
 252  * @shutdown: Callback for device shutdown
 253  * @irq_handler: Callback for handling irqs
 254  * @fh_add: Callback for function handler add
 255  * @fh_remove: Callback for function handler remove
 256  * @get_func_irq_mask: Callback for calculating interrupt mask
 257  * @store_irq_mask: Callback for storing and replacing interrupt mask
 258  * @restore_irq_mask: Callback for restoring previously stored interrupt mask
 259  * @data: Private data pointer
 260  *
 261  * The RMI driver implements a driver on the RMI bus.
 262  *
 263  */
 264 struct rmi_driver {
 265         struct device_driver driver;
 266
 267         int (*probe)(struct rmi_device *rmi_dev);
 268         int (*remove)(struct rmi_device *rmi_dev);
 269         void (*shutdown)(struct rmi_device *rmi_dev);
 270         int (*irq_handler)(struct rmi_device *rmi_dev, int irq);
 271         int (*reset_handler)(struct rmi_device *rmi_dev);
 272         void (*fh_add)(struct rmi_device *rmi_dev,
 273                        struct rmi_function_handler *fh);
 274         void (*fh_remove)(struct rmi_device *rmi_dev,
 275                           struct rmi_function_handler *fh);
 276         u8* (*get_func_irq_mask)(struct rmi_device *rmi_dev,
 277                             struct rmi_function_container *fc);
 278         int (*store_irq_mask)(struct rmi_device *rmi_dev, u8* new_interupts);
 279         int (*restore_irq_mask)(struct rmi_device *rmi_dev);
 280         void *data;
 281 };
 282 #define to_rmi_driver(d) \
 283         container_of(d, struct rmi_driver, driver);
 284
 285 /** struct rmi_phys_info - diagnostic information about the RMI physical
 286  * device, used in the phys sysfs file.
 287  * @proto String indicating the protocol being used.
 288  * @tx_count Number of transmit operations.
 289  * @tx_bytes Number of bytes transmitted.
 290  * @tx_errs  Number of errors encountered during transmit operations.
 291  * @rx_count Number of receive operations.
 292  * @rx_bytes Number of bytes received.
 293  * @rx_errs  Number of errors encountered during receive operations.
 294  * @att_count Number of times ATTN assertions have been handled.
 295  */
 296 struct rmi_phys_info {
 297         char *proto;
 298         long tx_count;
 299         long tx_bytes;
 300         long tx_errs;
 301         long rx_count;
 302         long rx_bytes;
 303         long rx_errs;
 304         long attn_count;
 305 };
 306
 307 /**
 308  * struct rmi_phys_device - represent an RMI physical device
 309  * @dev: Pointer to the communication device, e.g. i2c or spi
 310  * @rmi_dev: Pointer to the RMI device
 311  * @write: Callback for write
 312  * @write_block: Callback for writing a block of data
 313  * @read: Callback for read
 314  * @read_block: Callback for reading a block of data
 315  * @data: Private data pointer
 316  *
 317  * The RMI physical device implements the glue between different communication
 318  * buses such as I2C and SPI.
 319  *
 320  */
 321 struct rmi_phys_device {
 322         struct device *dev;
 323         struct rmi_device *rmi_dev;
 324
 325         int (*write)(struct rmi_phys_device *phys, u16 addr, u8 data);
 326         int (*write_block)(struct rmi_phys_device *phys, u16 addr, u8 *buf,
 327                            int len);
 328         int (*read)(struct rmi_phys_device *phys, u16 addr, u8 *buf);
 329         int (*read_block)(struct rmi_phys_device *phys, u16 addr, u8 *buf,
 330                           int len);
 331
 332         int (*enable_device) (struct rmi_phys_device *phys);
 333         void (*disable_device) (struct rmi_phys_device *phys);
 334
 335         void *data;
 336
 337         struct rmi_phys_info info;
 338 };
 339
 340 /**
 341  * struct rmi_device - represents an RMI device
 342  * @dev: The device created for the RMI bus
 343  * @number: Unique number for the device on the bus.
 344  * @driver: Pointer to associated driver
 345  * @phys: Pointer to the physical interface
 346  * @early_suspend_handler: Pointers to early_suspend and late_resume, if
 347  * configured.
 348  *
 349  * This structs represent an RMI device.
 350  *
 351  */
 352 struct rmi_device {
 353         struct device dev;
 354         int number;
 355
 356         struct rmi_driver *driver;
 357         struct rmi_phys_device *phys;
 358
 359 #ifdef CONFIG_HAS_EARLYSUSPEND
 360         struct early_suspend early_suspend_handler;
 361 #endif
 362 #ifdef CONFIG_RMI4_DEBUG
 363         struct dentry *debugfs_root;
 364 #endif
 365 };
 366 #define to_rmi_device(d) container_of(d, struct rmi_device, dev);
 367 #define to_rmi_platform_data(d) ((d)->phys->dev->platform_data);
 368
 369 static inline void rmi_set_driverdata(struct rmi_device *d, void *data)
 370 {
 371         dev_set_drvdata(&d->dev, data);
 372 }
 373
 374 static inline void *rmi_get_driverdata(struct rmi_device *d)
 375 {
 376         return dev_get_drvdata(&d->dev);
 377 }
 378
 379 /**
 380  * rmi_read - RMI read byte
 381  * @d: Pointer to an RMI device
 382  * @addr: The address to read from
 383  * @buf: The read buffer
 384  *
 385  * Reads a byte of data using the underlaying physical protocol in to buf. It
 386  * returns zero or a negative error code.
 387  */
 388 static inline int rmi_read(struct rmi_device *d, u16 addr, u8 *buf)
 389 {
 390         return d->phys->read(d->phys, addr, buf);
 391 }
 392
 393 /**
 394  * rmi_read_block - RMI read block
 395  * @d: Pointer to an RMI device
 396  * @addr: The start address to read from
 397  * @buf: The read buffer
 398  * @len: Length of the read buffer
 399  *
 400  * Reads a block of byte data using the underlaying physical protocol in to buf.
 401  * It returns the amount of bytes read or a negative error code.
 402  */
 403 static inline int rmi_read_block(struct rmi_device *d, u16 addr, u8 *buf,
 404                                  int len)
 405 {
 406         return d->phys->read_block(d->phys, addr, buf, len);
 407 }
 408
 409 /**
 410  * rmi_write - RMI write byte
 411  * @d: Pointer to an RMI device
 412  * @addr: The address to write to
 413  * @data: The data to write
 414  *
 415  * Writes a byte from buf using the underlaying physical protocol. It
 416  * returns zero or a negative error code.
 417  */
 418 static inline int rmi_write(struct rmi_device *d, u16 addr, u8 data)
 419 {
 420         return d->phys->write(d->phys, addr, data);
 421 }
 422
 423 /**
 424  * rmi_write_block - RMI write block
 425  * @d: Pointer to an RMI device
 426  * @addr: The start address to write to
 427  * @buf: The write buffer
 428  * @len: Length of the write buffer
 429  *
 430  * Writes a block of byte data from buf using the underlaying physical protocol.
 431  * It returns the amount of bytes written or a negative error code.
 432  */
 433 static inline int rmi_write_block(struct rmi_device *d, u16 addr, u8 *buf,
 434                                   int len)
 435 {
 436         return d->phys->write_block(d->phys, addr, buf, len);
 437 }
 438
 439 /**
 440  * rmi_register_driver - register rmi driver
 441  * @driver: the driver to register
 442  *
 443  * This function registers an RMI driver to the RMI bus.
 444  */
 445 int rmi_register_driver(struct rmi_driver *driver);
 446
 447 /**
 448  * rmi_unregister_driver - unregister rmi driver
 449  * @driver: the driver to unregister
 450  *
 451  * This function unregisters an RMI driver to the RMI bus.
 452  */
 453 void rmi_unregister_driver(struct rmi_driver *driver);
 454
 455 /**
 456  * rmi_register_phys_device - register a physical device connection
 457  * @phys: the physical driver to register
 458  *
 459  * This function registers a physical driver to the RMI bus. These drivers
 460  * provide a communication layer for the drivers connected to the bus, e.g.
 461  * I2C, SPI and so on.
 462  */
 463 int rmi_register_phys_device(struct rmi_phys_device *phys);
 464
 465 /**
 466  * rmi_unregister_phys_device - unregister a physical device connection
 467  * @phys: the physical driver to unregister
 468  *
 469  * This function unregisters a physical driver from the RMI bus.
 470  */
 471 void rmi_unregister_phys_device(struct rmi_phys_device *phys);
 472
 473 /**
 474  * rmi_register_function_driver - register an RMI function driver
 475  * @fh: the function handler to register
 476  *
 477  * This function registers support for a new RMI function to the bus. All
 478  * drivers on the bus will be notified of the presence of the new function
 479  * driver.
 480  */
 481 int rmi_register_function_driver(struct rmi_function_handler *fh);
 482
 483 /**
 484  * rmi_unregister_function_driver - unregister an RMI function driver
 485  * @fh: the function handler to unregister
 486  *
 487  * This function unregisters a RMI function from the RMI bus. All drivers on
 488  * the bus will be notified of the removal of a function driver.
 489  */
 490 void rmi_unregister_function_driver(struct rmi_function_handler *fh);
 491
 492 /**
 493  * rmi_get_function_handler - get a pointer to specified RMI function
 494  * @id: the RMI function id
 495  *
 496  * This function gets the specified RMI function handler from the list of
 497  * supported functions.
 498  */
 499 struct rmi_function_handler *rmi_get_function_handler(int id);
 500
 501
 502 struct rmi_char_device;
 503
 504 /**
 505  * rmi_char_driver - a general driver that doesn't handle specific functions,
 506  * operating outside the bus::sensor::functions
 507  * @match: returns 1 if the driver wants to talk to the specified rmi_dev.
 508  *
 509  * All of the above are optional except driver and init which are required.
 510  *
 511  */
 512 struct rmi_char_driver {
 513         struct device_driver driver;
 514
 515         int (*match)(struct rmi_device *rmi_dev);
 516         int (*init)(struct rmi_char_device *cd);
 517         int (*attention)(struct rmi_char_device *cd, u8 *irq_bits);
 518 #ifdef CONFIG_PM
 519         int (*suspend)(struct rmi_char_device *cd);
 520         int (*resume)(struct rmi_char_device *cd);
 521 #ifdef CONFIG_HAS_EARLYSUSPEND
 522         int (*early_suspend)(struct rmi_char_device *cd);
 523         int (*late_resume)(struct rmi_char_device *cd);
 524 #endif
 525 #endif
 526         void (*remove)(struct rmi_char_device *cd);
 527
 528         struct list_head devices;
 529 };
 530
 531 struct rmi_char_device {
 532         struct list_head list;
 533
 534         struct rmi_device *rmi_dev;
 535         struct rmi_char_driver *driver;
 536         struct device dev;
 537
 538 #ifdef CONFIG_RMI4_DEBUG
 539         struct dentry *debugfs_root;
 540 #endif
 541
 542         void *data;
 543 };
 544 #define to_rmi_char_device(d) \
 545                 container_of(d, struct rmi_char_device, dev)
 546
 547 int rmi_register_character_driver(struct rmi_char_driver *char_driver);
 548 int rmi_unregister_character_driver(struct rmi_char_driver *char_driver);
 549
 550
 551 /* Helper fn to convert a byte array representing a short in the RMI
 552  * endian-ness to a short in the native processor's specific endianness.
 553  * We don't use ntohs/htons here because, well, we're not dealing with
 554  * a pair of shorts. And casting dest to short* wouldn't work, because
 555  * that would imply knowing the byte order of short in the first place.
 556  */
 557 static inline void batohs(unsigned short *dest, unsigned char *src)
 558 {
 559         *dest = src[1] * 0x100 + src[0];
 560 }
 561
 562 /* Helper function to convert a short (in host processor endianess) to
 563  * a byte array in the RMI endianess for shorts.  See above comment for
 564  * why we dont us htons or something like that.
 565  */
 566 static inline void hstoba(unsigned char *dest, unsigned short src)
 567 {
 568         dest[0] = src % 0x100;
 569         dest[1] = src / 0x100;
 570 }
 571
 572 /* Utility routine to handle writes to read-only attributes.  Hopefully
 573  * this will never happen, but if the user does something stupid, we don't
 574  * want to accept it quietly (which is what can happen if you just put NULL
 575  * for the attribute's store function).
 576  */
 577 static inline ssize_t rmi_store_error(struct device *dev,
 578                         struct device_attribute *attr,
 579                         const char *buf, size_t count)
 580 {
 581         dev_warn(dev,
 582                  "RMI4 WARNING: Attempt to write %d characters to read-only "
 583                  "attribute %s.", count, attr->attr.name);
 584         return -EPERM;
 585 }
 586
 587 /* Utility routine to handle reads of write-only attributes.  Hopefully
 588  * this will never happen, but if the user does something stupid, we don't
 589  * want to accept it quietly (which is what can happen if you just put NULL
 590  * for the attribute's show function).
 591  */
 592 static inline ssize_t rmi_show_error(struct device *dev,
 593                        struct device_attribute *attr,
 594                        char *buf)
 595 {
 596         dev_warn(dev,
 597                  "RMI4 WARNING: Attempt to read from write-only attribute %s.",
 598                  attr->attr.name);
 599         return -EPERM;
 600 }
 601
 602 /* utility function for bit access of u8*'s */
 603 void u8_set_bit(u8 *target, int pos);
 604 void u8_clear_bit(u8 *target, int pos);
 605 bool u8_is_set(u8 *target, int pos);
 606 bool u8_is_any_set(u8 *target, int size);
 607 void u8_or(u8 *dest, u8* target1, u8* target2, int size);
 608 void u8_and(u8 *dest, u8* target1, u8* target2, int size);
 609 #endif