[PATCH libevdev 7/8] Document backwards-compatiblity behaviour

[David Herrmann]

Hi

On Mon, Oct 14, 2013 at 8:14 AM, Peter Hutterer
<peter.hutterer at who-t.net> wrote:
> Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
> ---
>  libevdev/libevdev.h | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 56 insertions(+)
>
> diff --git a/libevdev/libevdev.h b/libevdev/libevdev.h
> index 09934a2..e805cb1 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 requiredare not available, libevdev attempts to work around them

Missing space in "requiredare".
Apart from that:

Reviewed-by: David Herrmann <dh.herrmann at gmail.com>

Thanks
David

> + * 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.
> --
> 1.8.3.1
>
> _______________________________________________
> Input-tools mailing list
> Input-tools at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/input-tools