[RFC] Touchscreen driver API


Jon Medhurst (Tixy) <tixy@...>
 

Hello all

Zephyr doesn't have any API defined for touchscreen devices so when
writing a driver for one I needed to design an API. Below is what I came
up with and I wanted to request comments about it, with the intent of it
becoming a generic API others could use.

The driver interface is basically 2 functions:
- touchscreen_set_callback() to register a callback for notification

when samples are available.
- touchscreen_get_sample() to get a sample
(X,Y,Z value).

I also wrote some helper functions to translate touchscreen coordinates
to display coordinates:
- touchscreen_set_calibration() initialise coordinate translation params
- touchscreen_translate() translate an X,Y point

The actual header file with the API...


/** A single sample of the touchscreen's state */
struct touchscreen_sample {
/** Sampled value for touchscreen X position */
u16_t x;
/** Sampled value for touchscreen Y position */
u16_t y;
/** Sampled value for touchscreen Z (pressure) position */
u16_t z;
/** Flags associated with this sample */
u16_t flags;
};

/* Following #defines are for flags in struct touchscreen_sample */

/** Touchscreen is being touched */
#define TOUCHSCREEN_TOUCHED (1 << 0)

/* API to be implemented by touchscreen drivers */
struct touchscreen_api {
/* Get the next sample of the touchscreen state */
int (*get_sample)(struct device *dev,
struct touchscreen_sample *sample);
/* Set the callback function to be called when a sample is available */
void (*set_callback)(struct device *dev,
void (*callback)(struct device *));
};

/**
* @brief Get a sample from the touchscreen.
*
* @param dev Pointer to the device structure for the driver instance.
* @param sample Pointer to the sample to update.
*
* @return 0 on success, -EAGAIN if no more samples available,
* otherwise negative error value.
*/
static inline int touchscreen_get_sample(struct device *dev,
struct touchscreen_sample *sample)
{
const struct touchscreen_api *api = dev->driver_api;

return api->get_sample(dev, sample);
}

/**
* @brief Set the callback function.
*
* The callback function will be called when one or more samples becomes
* available. It may be executed in any any context, e.g. ISR or thread context,
* or may be called during the execution of touchscreen_get_sample(). Therefore
* the function mustn't itself use touchscreen_get_sample() or make use of
* kernel services that aren't safe from interrupt context.
*
* A typical action for the callback is to simply signal a semaphore or trigger
* some work on a workqueue.
*
* The callback function won't be called again until all samples have been
* retrieved, i.e. until the call to touchscreen_get_sample() which returned
* -EAGAIN.
*
* @param dev Pointer to the device structure for the driver instance.
* @param callback Pointer to the callback function.
*/
static inline void touchscreen_set_callback(struct device *dev,
void (*callback)(struct device *))
{
const struct touchscreen_api *api = dev->driver_api;

api->set_callback(dev, callback);
}


#ifdef CONFIG_TOUCHSCREEN_HELPERS

/** X,Y coordinates for a point on the touchscreen or display. */
struct touchscreen_point {
u16_t x;
u16_t y;
};

/**
* @brief Touchscreen coordinate translation parameters
*
* These are initialised by calling touchscreen_set_calibration().
* Members should be considered private and not accessed directly.
*/
struct touchscreen_xlat {
s64_t A;
s64_t B;
s64_t C;
s64_t D;
s64_t E;
s64_t F;
};

/**
* @brief Initialise touchscreen coordinate translation parameters.
*
* This requires that three different and valid display/touchscreen coordinate
* pairs are known.
*
* @param xlat Translation parameters to be initialised.
* @param touchscreen Three touchscreen coordinates that correspond to the
* given display coordinates.
* @param display Three display coordinates that correspond to the given
* touchscreen coordinates.
*/
void touchscreen_set_calibration(struct touchscreen_xlat *xlat,
const struct touchscreen_point touchscreen[3],
const struct touchscreen_point display[3]);

/**
* @brief Translate touchscreen coordinates into screen coordinates.
*
* Convert a touchscreen X,Y sample into the corresponding display X,Y
* coordinates by using the previously initialised translation parameters.
*
* @param xlat Translation parameters.
* @param touch_x Touchscreen X sample
* @param touch_y Touchscreen Y sample
* @param dislpay_x Display X coordinate
* @param dislpay_x Display Y coordinate
*/
void touchscreen_translate(struct touchscreen_xlat *xlat,
int touch_x, int touch_y,
int *display_x, int *display_y);

#endif /* CONFIG_TOUCHSCREEN_HELPERS */

Join devel@lists.zephyrproject.org to automatically receive all group messages.