tsc2000(4)

NAME
tsc2000 - device driver for TSC2000 touch screen controller

SYNOPSIS
#include <linux/tsc2000.h>

DESCRIPTION
The driver operates the A/D converter built into the TSC2000 touch screen controller. The following analogue channels are supported:
Temperature sensors
Contact temperature sensor
Differential pressure sensor connected to AUX2
Battery voltage
The A/D converter is controlled via the SPI bus. Additionally, the driver can be used to contol the brightness of the on-board touch screen. The driver performs a permanent polling of all 11 thermoelements, the contact temperature sensor and the differential pressure sensor. The results of the polling are latched in the driver. The poll interval is adjustable individually for each channel, with resolution of 1 clock tick (10 ms) and a minimum interval 100 ms. Both a /proc and a ioctl() interfaces are provided to adjust the poll interval and the metering range for each of the sensors. The normal application interface (using read() and a /proc file) reads only the latched values, thus being very fast. A separate interface, via an IOCTL command, is provided for time-critical applications, which triggers an additional, out-of-the-polling-sequence conversion for a single selected sensor, thus allowing to get very accurate results for one selected sensor. The battery voltage is not permanently polled, since this would cause excessive discharge. Instead, the battery voltage is measured only upon user request via a read() call or reading the /proc file. See below for details.
Also, automatic monitoring functions are implemented:

Min-max monitoring:
    It is possible to set a minimum and a maximum value for each of the channels.

Delta monitoring:
    It is possible to set a maximum delta value for each of the channels.

The tsc2000 driver is interfaced to the user space via device nodes and files in the /proc file system. The device nodes have the major number of 243 and minor numbers are constructed as follows:
    Name                 Minor number
    -------------        ------------
    /dev/battery         1
    /dev/pressure        2
    /dev/temp0           3
    /dev/temp1           4
    .....
    /dev/temp10          13
    /dev/contact_temp    14
    /dev/brightness      15
For description of the /proc filesystem interface, see below.

FUNCTIONS
In general, the TSC200 driver's functions behave as used with other drivers. A function return value of (-1) indicates an error, in which case an appropriate error code can be found in errno. The TSC2000 driver supports the following driver calls:

open()
    Every channel may be opened only for reading. The minor number of the device node indicates the sensor (see above).
    Error codes:
    ENXIO - no TSC2000 sensor correspond to this minor number.

close()
    Error codes:
    none

read()
    The behavior of read() depends on the minor number of the device node (that is, on which of the sensors is being read).
    If the device node corresponds to the battery sensor, read() works in the blocking mode. It initiates a read access to TSC2000 and copies the current reading of the BAT1 input to the buffer provided by the application. The buffer must be at least one word long (4 bytes).
    If the device node corresponds to a temperature or pressure sensor, then read() works in the non-blocking mode. It immediately returns with the reading of the sensor latched in the driver during the last periodic poll of the device.
    If the device node corresponds to the touch screen brightness, read() works in the blocking mode similar to the battery sensor. It initiates a read access to TSC2000 and copies the current value of the Digital-Analog Converter data register to the buffer provided by the application. The buffer must be at least one word long (4 bytes).
    In both blocking and non-blocking modes, read() returns 4 (the number of bytes read, one word), if no error occurs. Otherwise, it returns (-1) and sets an appropriate errno value.
    Error codes:
    ENOMEM - size of the provided buffer is less than 4 bytes.
    EINTR - the call was interrupted by a signal.

write()
    The write() call is not supported by the TSC2000 driver. It always returns (-1) with errno set to ENOSYS.

ioctl()
    The third argument to the ioctl() call (except for the TSC2000_IOCTL_SET_CORRECTION and TSC2000_IOCTL_GET_CORRECTION commands described below) must be a pointer to a variable of the tsc2000_data_t type, defined in linux/tsc2000.h as follows:
          typedef struct tsc2000_data_s
          {
              u32 value;
          }
          tsc2000_data_t;
    The following IOCTL commands are supported for device nodes corresponding to each TSC2000 sensor:
    TSC2000_IOCTL_SET_INTERVAL
    Sets the interval for polling the sensor by the driver to the value in clock ticks specified in the structure of the type tsc2000_data_t pointed to by the command argument. The new value has effect immediately. If the specified value is less than 10 ticks (100 ms), the polling interval is unchanged and an EINVAL error is reported.
    Note that this IOCTL command has no effect when issued for the device node corresponding to the battery input. It always returns success, but the battery voltage is never continuously polled.
    TSC2000_IOCTL_SET_MIN
    Sets the minimum range for readings of the sensor to the value specified in the structure of the type tsc2000_data_t pointed to by the command argument. The units of the value are hundreds of Celsius degrees in case of a temperature sensor and TBD in case of the pressure sensor.
    This command always succeeds.
    Note that this IOCTL command has no effect when issued for the device node corresponding to the battery input.
    TSC2000_IOCTL_SET_MAX
    Sets the maximum range for readings of the sensor to the value specified in the structure of the type tsc2000_data_t pointed to by the command argument. The units of the value are hundreds of Celsius degrees in case of a temperature sensor and TBD in case of the pressure sensor.
    This command always succeeds.
    Note that this IOCTL command has no effect when issued for the device node corresponding to the battery input.
    TSC2000_IOCTL_GET_CORRECTION
    TSC2000_IOCTL_SET_CORRECTION
    These commands can be used to obtain or set, respectively, error correction factors used by the driver while measuring the temperature and voltage. The argument of these commands is a pointer to a variable of the tsc2000_correction_t type, defined in linux/tsc2000.h as follows:
          typedef struct tsc2000_correction_s
          {
           /* aberration of the reference voltage
            * compared to nominal, ppm */
           __s32 error_vref;
           /* aberration of the op-amp amplification
            * factor compared to nominal, ppm */
           __s32 error_amp1;
           __s32 error_amp2;
           __s32 error_amp3;
           /* offset of the pt1000 reference bridge, uV */
           __s32 offset_pt1000;
           /* Correction factor for the battery voltage, o/oo */
           __s32 error_battery;
          }
          tsc2000_correction_t;
    These IOCTL commands fail with errno set to EINVAL when issued for any device node except those corresponding to the temperature and battery sensors.
    TSC2000_IOCTL_SET_DELTA
    Sets a value of difference between two subsequent readings of the sensor, which, if exceeded, would wake an application waiting on the driver's poll() function. The value to be set is specified in the structure of the type tsc2000_data_t pointed to by the command argument. The units of the value are hundreds of Celsius degrees in case of a temperature sensor and TBD in case of the pressure sensor.
    Note that this IOCTL command has no effect when issued for the device node corresponding to the battery input.
    TSC2000_IOCTL_GET_VALUE
    Initiates a read access to TSC2000 and copies the current reading of the sensor to the buffer of type tsc2000_data_t pointed to by the command argument. This command can also be used to obtain the current value (0-255) of the touch screen brightness.
    TSC2000_IOCTL_SET_BRIGHTNESS
    Sets the touch screen brightness to the new value (0-255) supplied in the buffer of type tsc2000_data_t pointed to by the command argument.
    TSC2000_IOCTL_GET_STATUS
    Returns information of the event (or events) that caused the last poll() or select() call to return exception status, and clears the inidication of the events. On retutn, the status information is encoded in the low order bits of the variable of type tsc2000_data_t pointed to by the command argument. The <linux/tsc2000.h> header file defines constant that can be used by the application for analizing the returned result. For instance,
    (data.value & TSC2000_STATUS_MIN) indicates that the minimum monitoring boundary for the sensor was exceeded.
    (data.value & TSC2000_STATUS_MAX) indicates that the maximum monitoring boundary for the sensor was exceeded.
    (data.value & TSC2000_STATUS_DELTA) indicates that the maximum monitoring difference between two subsequent readings of the sensor was exceeded.
    Error codes for all the IOCTL commands:
    EINVAL - attempted to set polling interval of less than 10 ticks.

poll()
    The poll() function implemented by the TSC2000 driver lets the application wait for an exception occurred on the file descriptor corresponding to the open path to a TSC2000 sensor. The exception is reported if one of the following conditions is met:
    The last reading of the sensor yielded the value which is less than or equal to that set with the most recent TSC2000_IOCTL_SET_MIN IOCTL command.
    The last reading of the sensor yielded the value which is greater than or equal to that set with the most recent TSC2000_IOCTL_SET_MAX IOCTL command.
    The difference between last two subsequent readings of the sensor was greater than or equal to the value set with the most recent TSC2000_IOCTL_SET_DELTA IOCTL command.
    To clear the indication of the event, the application must issue the TSC2000_IOCTL_GET_STATUS IOCTL command.

PROCFS INTERFACE
The /proc filesystem driver interface is via the following files:
   /proc/tsc2000/battery
   /proc/tsc2000/pressure
   /proc/tsc2000/temp0
   /proc/tsc2000/temp1
   ......
   /proc/tsc2000/temp10
   /proc/tsc2000/contact_temp
   /proc/tsc2000/brightness
Reading these files is similar to calling the read() function of the driver: it returns one line of text with ASCII representation of a value read from the corresponding TSC2000 input. Note that similar to the read() function, a read access to the /proc/tsc2000/battery and /proc/tsc2000/brightness file initiates access to TSC2000 to fetch the voltage data and brighness, respectively, while read accesses to /proc/tsc2000/pressure, /proc/tsc2000/contact_temp or any of the /proc/tsc2000/temp<N> files don't initiate access to TSC2000 but rather return the values latched in the driver during the last periodic poll of the device. Writing to the procfs files my be used to set the MIN, MAX, DELTA, and INTERVAL control values for monitoring the respective temperature sensor or the pressure sensor. As follows:

echo "min=<value>" > /proc/tsc2000/<sensor>
    Sets the minimum monitoring boundary for the sensor, similar to the TSC2000_IOCTL_SET_MIN IOCTL command.

echo "max=<value>" > /proc/tsc2000/<sensor>
    Sets the maximum monitoring boundary for the sensor, similar to the TSC2000_IOCTL_SET_MAX IOCTL command.

echo "delta=<value>" > /proc/tsc2000/<sensor>
    Sets the maximum difference of two subsequent readings monitoring for the sensor, similar to the TSC2000_IOCTL_SET_DELTA IOCTL command.

echo "interval=<interval>" > /proc/tsc2000/<sensor>
    Sets the polling interval for the sensor, similar to the TSC2000_IOCTL_SET_INTERVAL IOCTL command.

Writing to the /proc/tsc2000/brightness will set the new brightness of the on-board touch-screen, similar to the TSC2000_IOCTL_SET_BRIGHTNESS IOCTL command:
echo "brightness=<value>" > /proc/tsc2000/brightness

All attempts to write to the /proc files strings that do not match the patterns defined above are discarded by the driver. Any attempts to write to the /proc/tsc2000/battery file are always discarded by the driver.