summaryrefslogtreecommitdiff
path: root/tools/libinput-record.man
blob: 8f9787f477b8c43a262ee28462f5d56204505959 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
.TH libinput-record "1"
.SH NAME
libinput\-record \- record kernel events
.SH SYNOPSIS
.B libinput record [options] [\fI/dev/input/event0\fB]
.SH DESCRIPTION
.PP
The \fBlibinput record\fR tool records kernel events from a device and
prints them in a format that can later be replayed with the \fBlibinput
replay(1)\fR tool.  This tool needs to run as root to read from the device.
.PP
The output of this tool is YAML, see \fBFILE FORMAT\fR for more details.
By default it prints to stdout unless the \fB-o\fR option is given.
.PP
The events recorded are independent of libinput itself, updating or
removing libinput will not change the event stream.
.SH OPTIONS
If a device node is given, this tool opens that device node. Otherwise,
a list of devices is presented and the user can select the device to record.
If unsure, run without any arguments.
.TP 8
.B \-\-help
Print help
.TP 8
.B \-\-all
Record all \fI/dev/input/event*\fR devices available on the system. This
option should be used in exceptional cases only, the output file is almost
always too noisy and replaying the recording may not be possible. Use
\fB\-\-multiple\fR instead.
This option requires that a \fB\-\-output-file\fR is specified and may not
be used together with \fB\-\-multiple\fR.
.TP 8
.B \-\-autorestart=s
Terminate the current recording after
.I s
seconds of device inactivity. This option requires that a
\fB\-\-output-file\fR is specified. The output filename is used as prefix,
suffixed with the date and time of the recording. The timeout must be
greater than 0.
.TP 8
.B \-o filename
.PD 0
.TP 8
.B \-\-output-file=filename
.PD 1
Specifies the output file to use. If \fB\-\-autorestart\fR or
\fB\-\-multiple\fR is given, the filename is used as prefix only.
.TP 8
.B \-\-multiple
Record multiple devices at once, see section
.B RECORDING MULTIPLE DEVICES
This option requires that a
\fB\-\-output-file\fR is specified and that all devices to be recorded are
given on the commandline.

.SH RECORDING MULTIPLE DEVICES
Sometimes it is necessary to record the events from multiple devices
simultaneously, e.g.  when an interaction between a touchpad and a keyboard
causes a bug. The \fB\-\-multiple\fR option records multiple devices with
an identical time offset, allowing for correct replay of the interaction.
.PP
The \fB\-\-multiple\fR option requires that an output filename is given.
This filename is used as prefix, with the event node number appended.
.PP
All devices to be recorded must be provided on the commandline, an example
invocation is:

.B libinput record \-\-multiple \-o tap-bug /dev/input/event3 /dev/input/event7

Note that when recording multiple devices, only the first device is printed
immediately, all other devices and their events are printed on exit.

.SH FILE FORMAT
The output file format is in YAML and intended to be both human-readable and
machine-parseable. Below is a short example YAML file, all keys are detailed
further below.
.PP
Any parsers must ignore keys not specified in the file format description.
The version number field is only used for backwards-incompatible changes.
.PP
.nf
.sp
version: 1
ndevices: 2
libinput:
  version: 1.10.0
system:
  kernel: "4.13.9-200.fc26.x86_64"
  dmi: "dmi:bvnLENOVO:bvrGJET72WW(2.22):bd02/21/2014:svnLENOVO:..."
devices:
  - node: /dev/input/event9
    evdev:
      # Name: Synaptics TM2668-002
      # ID: bus 0x1d vendor 0x6cb product 00 version 00
      # Size in mm: 97x68
      # Supported Events:
      # Event type 0 (EV_SYN)

      #.. abbreviated for man page ...

      #
      name: Synaptics TM2668-002
      id: [29, 1739, 0, 0]
      codes:
        0: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15] # EV_SYN
        1: [272, 325, 328, 330, 333, 334, 335] # EV_KEY
        3: [0, 1, 24, 47, 48, 49, 52, 53, 54, 55, 57, 58] # EV_ABS
      absinfo:
        0: [0, 4089, 0, 0, 42]
        1: [0, 2811, 0, 0, 41]
        24: [0, 255, 0, 0, 0]
        47: [0, 4, 0, 0, 0]
        48: [0, 15, 0, 0, 0]
        49: [0, 15, 0, 0, 0]
        52: [0, 1, 0, 0, 0]
        53: [0, 4089, 0, 0, 42]
        54: [0, 2811, 0, 0, 41]
        55: [0, 2, 0, 0, 0]
        57: [0, 65535, 0, 0, 0]
        58: [0, 255, 0, 0, 0]
      properties: [0, 2, 4]
    events:
      - evdev:
        - [  0,      0,   3,  57,  1420] # EV_ABS / ABS_MT_TRACKING_ID   1420
        - [  0,      0,   3,  53,  1218] # EV_ABS / ABS_MT_POSITION_X    1218
        - [  0,      0,   3,  54,  1922] # EV_ABS / ABS_MT_POSITION_Y    1922
        - [  0,      0,   3,  52,     0] # EV_ABS / ABS_MT_ORIENTATION      0
        - [  0,      0,   3,  58,    47] # EV_ABS / ABS_MT_PRESSURE        47
        - [  0,      0,   1, 330,     1] # EV_KEY / BTN_TOUCH               1
        - [  0,      0,   1, 325,     1] # EV_KEY / BTN_TOOL_FINGER         1
        - [  0,      0,   3,   0,  1218] # EV_ABS / ABS_X                1218
        - [  0,      0,   3,   1,  1922] # EV_ABS / ABS_Y                1922
        - [  0,      0,   3,  24,    47] # EV_ABS / ABS_PRESSURE           47
        - [  0,      0,   0,   0,     0] # ------------ SYN_REPORT (0) ------- +0ms
      - evdev:
        - [  0,  11879,   3,  53,  1330] # EV_ABS / ABS_MT_POSITION_X    1330
        - [  0,  11879,   3,  54,  1928] # EV_ABS / ABS_MT_POSITION_Y    1928
        - [  0,  11879,   3,  58,    46] # EV_ABS / ABS_MT_PRESSURE        46
        - [  0,  11879,   3,   0,  1330] # EV_ABS / ABS_X                1330
        - [  0,  11879,   3,   1,  1928] # EV_ABS / ABS_Y                1928
        - [  0,  11879,   3,  24,    46] # EV_ABS / ABS_PRESSURE           46
        - [  0,  11879,   0,   0,     0] # ------------ SYN_REPORT (0) ------- +0ms
  # second device (if any)
  - node: /dev/input/event9
    evdev: ...
.PP
.fi
.in
Top-level keys are listed below, see the respective
subsection for details on each key.
.PP

.TP 8
.B version: int
The file format version. This version is only increased for
backwards-incompatible changes. A parser must ignore unknown keys to be
forwards-compatible.
.TP 8
.B ndevices: int
The number of device recordings in this file. Always 1 unless recorded with
.B --multiple
.TP 8
.B libinput: {...}
A dictionary with libinput-specific information.
.TP 8
.B system: {...}
A dictionary with system information.
.TP 8
.B devices: {...}
A list of devices containing the description and and events of each device.

.SS libinput
.TP 8
.B version: string
libinput version

.SS system
Information about the system
.TP 8
.B kernel: string
Kernel version, see \fIuname(1)\fR
.TP 8
.B dmi: string
DMI modalias, see \fI/sys/class/dmi/id/modalias\fR

.SS devices
Information about and events from the recorded device nodes
.TP 8
.B node: string
the device node recorded
.TP 8
.B evdev
A dictionary with the evdev device information.
.TP 8
.B events
A list of dictionaries with the recorded events
.SS evdev
.TP 8
.B name: string
The device name
.TP 8
.B id: [bustype, vendor, product, version]
The data from the \fBstruct input_id\fR, bustype, vendor, product, version.
.TP 8
.B codes: {type: [a, b, c ], ...}
All evdev types and codes as nested dictionary. The evdev type is the key,
the codes are a list.
.TP 8
.B absinfo: {code: [min, max, fuzz, flat, resolution], ...}
An array of arrays with 6 decimal elements each, denoting the contents of a
\fBstruct input_absinfo\fR. The first element is the code (e.g. \fBABS_X\fR)
in decimal format.
.TP 8
.B properties: [0, 1, ...]
Array with all \fBINPUT_PROP_FOO\fR constants. May be an empty array.

.SS events
A list of the recorded events. The list contains dictionaries
Information about the events. The content is a list of dictionaries, with
the string identifying the type of event sequence.
.TP 8
.B { evdev: [ {"data": [sec, usec, type, code, value]}, ...] }
Each \fBinput_event\fR dictionary contains the contents of a \fBstruct
input_event\fR in decimal format. The last item in the list is always the
\fBSYN_REPORT\fR of this event frame. The next event frame starts a new
\fBevdev\fR dictionary entry in the parent \fBevents\fR list.

.SH NOTES
.PP
This tool records events from the kernel and is independent of libinput. In
other words, updating or otherwise changing libinput will not alter the
output from this tool. libinput itself does not need to be in use to record
events.
.SH LIBINPUT
.PP
Part of the
.B libinput(1)
suite