[ANNOUNCE] libinputmapper - Linux input-event mapping library

[David Herrmann]

Hi

On Thu, Aug 22, 2013 at 8:53 AM, Peter Hutterer
<peter.hutterer at who-t.net> wrote:
> On Thu, Aug 15, 2013 at 07:07:01PM +0200, David Herrmann wrote:
>> Hi
>>
>> Following previous discussions, I pushed some initial work for the
>> libinputmapper library to github. You can find the repository at:
>>   https://github.com/dvdhrm/libinputmapper
>>
>> At the library's core, there is one important function:
>>   void inmap_mapping_map(struct inmap_mapping *mapping,
>>                                      const struct input_event *in,
>>                                      struct input_event *out,
>>                                      enum inmap_mapping_map_flags flags);
>> As one might guess, this function takes a linux "struct input_event",
>> performs some conversions/translations/.. and outputs it again. The
>> supported operations are currently limited to simple "ev->code" to
>> "ev->code" conversions. So for instance KEY_UNKNOWN can be remapped to
>> KEY_BACKSPACE. But this is not limited to keys, you can also remap
>> ABS_X to ABS_Y.
>
> I strongly recommend to do this as a N:M mapping, to allow for a set of
> events in and a set of events out. this would allow more complex conversion
> of events than just a simple 1:1 mapping. The real use-case I can see here
> is hiding mtdev behind libinputmapper, a theoretical use-case is a known
> broken device that requires adding e.g. BTN_TOOL_FINGER before the actual
> converted event.

How do you think N:M mappings work? A 1:N mapping is possible, but if
I have more than one source value, which value do I copy to the
destination? Note that libinputmapper is really just a trivial mapper
so far. It just maps input_event "code" entries from one to another.

I am open for suggestions, I can change the mapping function to:

unsigned int inmap_mapping_map(struct inmap_mapping *mapping,
                                      const struct input_event *in,
                                      size_t in_num,
                                      struct input_event *out,
                                      size_t out_num,
                                      enum inmap_mapping_map_flags flags);

This allows a caller to collect input_events until the next
SYN_REPORT. These are then passed to inmap_mapping_map() with "in_num"
set to the number of events. It then writes the corresponding events
to @out and returns the number of events written. Obviously, there
must be a way for the caller to calculate a sane @out_num value so we
don't need any dynamic allocation here.
I want the standard event-path to work without any allocations or
error-codes. It should be fail-safe and fast.

Note that I don't think passing more events than until the next
SYN_REPORT makes sense. I guess we agree here?

Furthermore, I can imagine 1:N mappings which just generates N events
out of 1. Though, I currently lack any proper use-case for that. For
any other mappings, M:1 or M:N I have no idea what it is useful for
without a backing state-machine? Or do you intend to allow adding
state-machines? I'm not opposed in general, I just haven't thought
about it much.

Hm, I will think about it some more. It does indeed sound appealing to
allow state-machines behind this. We could seamlessly implement any
input_event->input_event transformation/channel here without
applications having to bother at all. Hm..

> that's my only comment so far, haven't had the time to look at the code yet
> :)

That's fine. It's nothing special. Mostly boilerplate so far.

>> However, it does not support remapping across a single "ev->type". So
>> KEY_UNKNOWN cannot be remapped to LED_XY (which also wouldn't make
>> sense).
>>
>> The main purpose is to fix broken keymaps in the kernel. We often
>> cannot fix them upstream for backwards compatibility reasons.
>> Furthermore, mapping-tables can be used to avoid cross-device
>> incompatibilities:
>>   Many Gamepads report the DPad buttons via different KEY_* codes.
>> Newer kernels provide BTN_DPAD_* so we could provide mapping-tables
>> for older gamepads to remap their DPads accordingly. Hence,
>> applications would no longer have to special-case old broken gamepads.
>>
>> The library is supposed to be very small and efficient. Mappings other
>> than "code->code" can be easily added without breaking backwards
>> compatibility.
>>
>> The library allows applications to create their own mappings
>> dynamically. However, it also comes with a parser for udev's hwdb.
>> This allows us to store any known mapping in hwdb and libinputmapper
>> can fetch it from there (matching is currently done via kernel
>> modaliases).
>>
>> Note that I haven't really tested the code, yet. I wanted to push this
>> out so people can comment on the idea and we have something to point
>> to. I will pick this up after I come back from XDC. Until then I will
>> probably not add much to it.
>>
>> Side-note: Is it ok to use "input-tools at fdo" as official mailing-list for this?
>
> yes. this library will likely end up being used alongside libevdev and
> others as the base layer between kernel and real userspace, so this is the
> right list for it.

Cool, I will add it then.

Thanks
David