From 346e3eed6aa353c371aed0bf0f4a5571f9b8cfca Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Thu, 10 Oct 2013 11:22:48 +1000 Subject: [PATCH] Document backwards-compatibility behaviour Signed-off-by: Peter Hutterer --- libevdev/libevdev.h | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) diff --git a/libevdev/libevdev.h b/libevdev/libevdev.h index 09934a2..426e9c8 100644 --- a/libevdev/libevdev.h +++ b/libevdev/libevdev.h @@ -135,6 +135,12 @@ extern "C" { * A more complete example is available with the libevdev-events tool here: * http://cgit.freedesktop.org/libevdev/tree/tools/libevdev-events.c * + * Backwards compatibility with older kernel + * ========================================= + * libevdev attempts to build and run correctly on a number of kernel versions. + * If features required are not available, libevdev attempts to work around them + * in the most reasonable way. For more details see \ref backwardscompatibility. + * * libevdev internal test suite * ============================ * @@ -190,6 +196,56 @@ extern "C" { */ /** + * @page backwardscompatibility Compatibility and Behavior across kernel versions + * + * This page describes libevdev's behavior when the build-time kernel and the + * run-time kernel differ in their feature set. + * + * With the exception of event names, libevdev defines features that may be + * missing on older kernels and building on such kernels will not disable + * features. Running libevdev on a kernel that is missing some feature will + * change libevdev's behavior. In most cases, the new behavior should be + * obvious, but it is spelled out below in detail. + * + * Minimum requirements + * ==================== + * libevdev requires a 2.6.36 kernel as minimum. Specifically, it requires + * ABS_MT_SLOT and the matching behavior. + * + * Event and input property names + * ============================== + * Event names and input property names are defined at build-time by the + * linux/input.h shipped with libevedv. + * The list of event names is compiled at build-time and thus any events not defined + * at build time will not resolve. Specifically, + * libevdev_event_code_get_name(type, code) for an undefined type or code will + * always return NULL. Likewise, libevdev_property_get_name() will return NULL + * for properties undefined on the build system. + * + * Input properties + * ================ + * If the kernel does not support input properties, specifically the + * EVIOCGPROPS ioclt, libevdev does not expose input properties to the caller. + * Specifically, libevdev_has_property() will always return 0 unless the + * property has been manually set with libevdev_enable_property(). + * + * This also applies to the libevdev-uinput code. If uinput does not honor + * UI_SET_PROPBIT, libevdev will continue without setting the properties on + * the device. + * + * MT slot behavior + * ================= + * If the kernel does not support the EVIOCGMTSLOTS ioctl, libevdev continues + * as normal and assumes all values in all slots to be 0. + * + * SYN_DROPPED behavior + * ==================== + * A kernel without SYN_DROPPED, won't send the event. libevdev_next_event() + * will never require the switch to sync mode. + * + */ + +/** * @defgroup init Initialization and setup * * Initialization, initial setup and file descriptor handling. -- 2.7.4