From aa314c85b727b86edffb30a34e06bfa9a501d7c3 Mon Sep 17 00:00:00 2001 From: Anton Khirnov Date: Sat, 12 Feb 2022 21:56:54 +0100 Subject: Add licence and a readme. --- README | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 README (limited to 'README') diff --git a/README b/README new file mode 100644 index 0000000..ad4a96b --- /dev/null +++ b/README @@ -0,0 +1,59 @@ +Inputfwd is a set of Linux tools for creating virtual input devices (using +uinput) that mirror input from source devices. The source devices may be added +and removed dynamically during the virtual device lifetime. + +Inputfwd was developed for gaming in unprivileged LXC containers, when input +devices may appear and disappear dynamically. Statically mounting them on +container boot is then too limiting. The solution is then to +- create virtual devices that will exist throughout the containeer's lifetime +- start the container with those virtual devices +- dynamically forward real devices to those virtual devices, as they are added + and removed + +This also solves the problem of the container seeing input it shouldn't (e.g. +passwords entered on the host) - just disconnect the device temporarily. + +Inputfwd is written in Python 3 and depends on the evdev package. Due to that +dependency it can only run on Linux. It is licensed under GPL version 3. + +The project consists of the following tools: + +inputdev_describe +----------------- +Helper tool that creates input device descriptions from an existing input +device and prints them to stdout. Simply run it on a desired /dev/input/event* +node and redirect the output to ~/.local/var/inputfwd/.desc. + +uinput_mng +---------- +The main tool - it creates and manages a virtual (uinput) device based on a +description created by inputdev_describe. It accepts as argument the of +the device description, i.e. corresponding to a +~/.local/var/inputfwd/.desc file. You may also pass an absolute path to +the description, if you really want the files to live somewhere else. + +Binding and unbinding real devices to the virtual device is done through the +control fifo, which is created in ~/.cache/inputfwd/ (location may be +customized with the -c option). + +Simply write the commands to this FIFO, e.g. by + echo "command" > ~/.cache/inputfwd/ + +The commands are: +* add + Adds the corresponding device node (e.g. + /dev/input/eventxx). Input events from that device will be forwarded to the + virtual device. Force-feedback events sent to the virtual device will be + forwarded up to the real device. +* remove + Removes the previously added device node, i.e. events from it will no longer + be forwarded. Devices are also automatically removed from uinput_mng if they + are disconnected. +* list + Lists all currently bound device paths. + +dev_add +------- +A helper tool that accepts the name (or full path) of the control FIFO and a +real device node. It adds that device through the FIFO, then sleeps until +interrupted. On exit it removes the device it added. -- cgit v1.2.3