The Linux mainline kernel since v2.6.36 has contained a driver for maXTouch chips that uses I2C-based communication. It was called qt602240 from v2.6.36 until v2.6.38 and then renamed atmel_mxt_ts in v2.6.39. This driver was originally contributed by Samsung and written for the mXT224 chip.

Atmel has made many improvements to this driver since 2011 to fix bugs, add support for userspace tools, and improve support for other chips. These improvements are available through this repository.

This is our primary development focus and we are able to provide much more comprehensive support to customers using this driver. Most of the tools referenced in the remainder of this document will only work with this driver.

The reference driver is available from github, at this URL:

https://github.com/atmel-maxtouch/linux

Each driver patch is tested against a particular kernel version and Atmel maXTouch chip, however our drivers are not chip-specific.

Each individual tested release is given a tag, for example maxtouch-v3.14-20140619 which would be a driver for Linux v3.14, tested on 19th June.

The particular changes leading to that release could be seen at:

https://github.com/atmel-maxtouch/linux/commits/maxtouch-v3.14-20140619

Several branches are provided, to allow for API changes across versions of the kernel:

maxtouch-v3.0

• Use on Linux v2.6.39 to v3.5
• Has early suspend

maxtouch-v3.10

• Use on Linux v3.7 to v3.12
• print_hex_dump() added
• input_mt_init_slots() requires
• INPUT_MT_DIRECT added
• INPUT_MT_POINTER added

maxtouch-v3.14

• Use on Linux v3.13 on
• irq_get_trigger_type()
• set_bit(EV_ABS, input_dev->evbit) due to https://github.com/torvalds/linux/commit/2c9a9cfec
• .owner = THIS_MODULE removed due to https://github.com/torvalds/linux/commit/800e3b9a680

These branches are never rebased, and apart from API changes they track our development targeted for the mainline kernel.

The individual driver files for a tagged release can be downloaded from eg:

• https://github.com/atmel-maxtouch/linux/raw/maxtouch-v3.14/drivers/input/touchscreen/atmel_mxt_ts.c
• https://github.com/atmel-maxtouch/linux/raw/maxtouch-v3.14/include/linux/platform_data/atmel_mxt_ts.h
• https://github.com/atmel-maxtouch/linux/raw/maxtouch-v3.14/include/dt-bindings/input/atmel_mxt_ts.h

replace maxtouch-v3.14 with the branch or tag that you wish to use.

These files should be placed in the equivalent directories of your kernel tree, replacing any existing versions.

A suitable Kconfig configuration is:

config TOUCHSCREEN_ATMEL_MXT
    tristate "Atmel mXT I2C Touchscreen"
    depends on I2C && m
    select FW_LOADER
    help
      Atmel mXT series touch controller.

      The driver will be compiled as a module called atmel_mxt_ts

A suitable Makefile configuration is:

obj-$(CONFIG_TOUCHSCREEN_ATMEL_MXT)     += atmel_mxt_ts.o

If you are using the exact version as a branch or tag, changes from our repository can be merged into your kernel tree using git.

To add the remote configuration:

git remote add atmel-maxtouch https://github.com/atmel-maxtouch/linux.git

To merge changes:

git fetch atmel-maxtouch --tags
git merge <tag>

For git documentation, see http://git-scm.com/book.

The driver may either be configured via device tree, or a board file.

To enable the driver on device tree systems, a configuration should be added to the appropriate device tree file, located under arch/arm/boot/dts/ on ARM systems:

       touch@4a {
                 compatible = "atmel,maxtouch";
                 reg = <0x4a>;
                 interrupt-parent = <&gpio5>;
                 interrupts = <11 IRQ_TYPE_LEVEL_LOW>;
       };

The i2c address should be changed from 0x4a to the appropriate address, see the data sheet for the device. Any GPIOs used must be multiplexed correctly.

For additional documentation of the device tree parameters, see

https://github.com/atmel-maxtouch/linux/blob/maxtouch-v3.14/Documentation/devicetree/bindings/input/atmel%2Cmaxtouch.txt

To initialise the driver, code must be added to the platform initialisation functions. This will be in a board file under the relevant architecture and platform tree, for instance arch/arm/mach-tegra/.

Include header files:

#include <linux/interrupt.h>
#include <linux/i2c/atmel_mxt_ts.h>

Define various parameters dependent on the board/platform and chip being used:

#define ATMEL_MXT_GPIO          139
#define ATMEL_MXT_I2C_ADAPTER   2
#define ATMEL_MXT_I2C_ADDR      0x4A

The following structures set up the platform data:

static struct mxt_platform_data mxt_data = {
    .irqflags = IRQF_TRIGGER_LOW,
};

static struct i2c_board_info __initdata i2c2_boardinfo[] = {
    {
        I2C_BOARD_INFO("atmel_mxt_ts", ATMEL_MXT_I2C_ADDR),
        .platform_data = &mxt_data,
    },
};

These lines are added to an init function. They initialise the GPIO for the CHG line, and register I2C bus 2 at 400kHz.

gpio_request_one(ATMEL_MXT_GPIO, GPIOF_IN, “atmel_mxt_ts CHG”);

i2c_boardinfo[0].irq = gpio_to_irq(ATMEL_MXT_GPIO);

omap_register_i2c_bus(ATMEL_MXT_I2C_ADAPTER,
                      400, /* bus clock rate */
                      i2c2_boardinfo,
                      ARRAY_SIZE(i2c2_boardinfo));

The parameters t15_num_keys and t15_keymap may be used to define the keys to be used with the T15 key array object.

The parameters t19_num_keys and t19_keymap may be used to map keys to T19 GPIO inputs, for example to provide a power button, or mouse button if the device is being used as a touchpad.

Touch acquisition is controlled by the driver by altering parameters in the T7 Power Configuration object. On driver probe, the running configuration is cached. When the system is suspended, or there are no active users of the input device, a zero configuration is written to the active and idle times. This puts the maXTouch chip into a deep sleep mode.

Regulator support may be enabled by defining the parameter gpio_reset and two regulators for vdd and avdd. This will then power off the chip entirely instead of using the deep sleep feature.

Versions of Android using kernel versions prior to 3.4 have a feature called Earlysuspend/Lateresume which provides hooks which the touch controller device driver can use to disable touch processing when the screen is blank. It has been removed from later versions, so it is only present in the maxtouch-v3.0 branch.

The IRQ line is referred to in Atmel maXTouch documentation as the CHG line.

It is recommended to use IRQF_TRIGGER_LOW for the CHG line. However, this causes performance issues on some platforms (for instance OMAP) that only support level triggering in a polled mode.

It is possible to use the driver in IRQF_TRIGGER_FALLING mode, but for this to work correctly the configuration should enable the RETRIGEN feature in T18 COMMSCONFIG.