From 234bf1faa9d291a7c8d53e183a6e5bd210198317 Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Fri, 28 Jun 2013 09:31:55 +1000 Subject: [PATCH] Expand main documentation to explain libevdev a bit more Signed-off-by: Peter Hutterer --- libevdev/libevdev.h | 45 +++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 43 insertions(+), 2 deletions(-) diff --git a/libevdev/libevdev.h b/libevdev/libevdev.h index 7e48354..0cf6295 100644 --- a/libevdev/libevdev.h +++ b/libevdev/libevdev.h @@ -30,20 +30,61 @@ /** * @mainpage * - * libevdev is a library for handling evdev kernel devices. It abstracts + * **libevdev** is a library for handling evdev kernel devices. It abstracts * the ioctls through type-safe interfaces and provides functions to change * the appearance of the device. * + * Handling events and SYN_DROPPED + * =============================== + * * libevdev provides an interface for handling events, including most notably - * SYN_DROPPED events. + * SYN_DROPPED events. SYN_DROPPED events are sent by the kernel when the + * process does not read events fast enough and the kernel is forced to drop + * some events. This causes the device to get out of sync with the process' + * view of it. libevdev handles this by telling the caller that a SYN_DROPPED + * has been received and that the state of the device is different to what is + * to be expected. It then provides the delta between the previous state and + * the actual state of the device as a set of events. See + * libevdev_next_event() for more information. + * + * Signal safety + * ============= * * libevdev is signal-safe for the majority of its operations. Check the API * documentation to make sure, unless explicitly stated a call is not * signal safe. * + * Device handling + * =============== + * * libevdev does not attempt duplicate detection. Initializing two libevdev * devices for the same fd is valid and behaves the same as for two different * devices. + * + * libevdev does not handle the file descriptors directly, it merely uses + * them. The caller is responsible for opening the file descriptors, setting + * them to O_NONBLOCK and handling permissions. + * + * Where does libevdev sit? + * ======================== + * + * libevdev is essentially a read(2) on steroids for /dev/input/eventX + * devices. It sits below the process that handles input events, in between + * the kernel and that process. In the simplest case, e.g. an evtest-like tool + * the stack would look like this: + * + * kernel → libevdev → evtest + * + * For X.Org input modules, the stack would look like this: + * + * kernel → libevdev → xf86-input-evdev → X server → X client + * + * For Weston/Wayland, the stack would look like this: + * + * kernel → libevdev → Weston → Wayland client + * + * libevdev does **not** have knowledge of X clients or Wayland clients, it is + * too low in the stack. */ /**