diff options
Diffstat (limited to 'Documentation/DocBook/media/v4l/lirc_device_interface.xml')
-rw-r--r-- | Documentation/DocBook/media/v4l/lirc_device_interface.xml | 253 |
1 files changed, 253 insertions, 0 deletions
diff --git a/Documentation/DocBook/media/v4l/lirc_device_interface.xml b/Documentation/DocBook/media/v4l/lirc_device_interface.xml new file mode 100644 index 000000000000..8d7eb6bf6312 --- /dev/null +++ b/Documentation/DocBook/media/v4l/lirc_device_interface.xml | |||
@@ -0,0 +1,253 @@ | |||
1 | <section id="lirc_dev"> | ||
2 | <title>LIRC Device Interface</title> | ||
3 | |||
4 | |||
5 | <section id="lirc_dev_intro"> | ||
6 | <title>Introduction</title> | ||
7 | |||
8 | <para>The LIRC device interface is a bi-directional interface for | ||
9 | transporting raw IR data between userspace and kernelspace. Fundamentally, | ||
10 | it is just a chardev (/dev/lircX, for X = 0, 1, 2, ...), with a number | ||
11 | of standard struct file_operations defined on it. With respect to | ||
12 | transporting raw IR data to and fro, the essential fops are read, write | ||
13 | and ioctl.</para> | ||
14 | |||
15 | <para>Example dmesg output upon a driver registering w/LIRC:</para> | ||
16 | <blockquote> | ||
17 | <para>$ dmesg |grep lirc_dev</para> | ||
18 | <para>lirc_dev: IR Remote Control driver registered, major 248</para> | ||
19 | <para>rc rc0: lirc_dev: driver ir-lirc-codec (mceusb) registered at minor = 0</para> | ||
20 | </blockquote> | ||
21 | |||
22 | <para>What you should see for a chardev:</para> | ||
23 | <blockquote> | ||
24 | <para>$ ls -l /dev/lirc*</para> | ||
25 | <para>crw-rw---- 1 root root 248, 0 Jul 2 22:20 /dev/lirc0</para> | ||
26 | </blockquote> | ||
27 | </section> | ||
28 | |||
29 | <section id="lirc_read"> | ||
30 | <title>LIRC read fop</title> | ||
31 | |||
32 | <para>The lircd userspace daemon reads raw IR data from the LIRC chardev. The | ||
33 | exact format of the data depends on what modes a driver supports, and what | ||
34 | mode has been selected. lircd obtains supported modes and sets the active mode | ||
35 | via the ioctl interface, detailed at <xref linkend="lirc_ioctl"/>. The generally | ||
36 | preferred mode is LIRC_MODE_MODE2, in which packets containing an int value | ||
37 | describing an IR signal are read from the chardev.</para> | ||
38 | |||
39 | <para>See also <ulink url="http://www.lirc.org/html/technical.html">http://www.lirc.org/html/technical.html</ulink> for more info.</para> | ||
40 | </section> | ||
41 | |||
42 | <section id="lirc_write"> | ||
43 | <title>LIRC write fop</title> | ||
44 | |||
45 | <para>The data written to the chardev is a pulse/space sequence of integer | ||
46 | values. Pulses and spaces are only marked implicitly by their position. The | ||
47 | data must start and end with a pulse, therefore, the data must always include | ||
48 | an uneven number of samples. The write function must block until the data has | ||
49 | been transmitted by the hardware.</para> | ||
50 | </section> | ||
51 | |||
52 | <section id="lirc_ioctl"> | ||
53 | <title>LIRC ioctl fop</title> | ||
54 | |||
55 | <para>The LIRC device's ioctl definition is bound by the ioctl function | ||
56 | definition of struct file_operations, leaving us with an unsigned int | ||
57 | for the ioctl command and an unsigned long for the arg. For the purposes | ||
58 | of ioctl portability across 32-bit and 64-bit, these values are capped | ||
59 | to their 32-bit sizes.</para> | ||
60 | |||
61 | <para>The following ioctls can be used to change specific hardware settings. | ||
62 | In general each driver should have a default set of settings. The driver | ||
63 | implementation is expected to re-apply the default settings when the device | ||
64 | is closed by user-space, so that every application opening the device can rely | ||
65 | on working with the default settings initially.</para> | ||
66 | |||
67 | <variablelist> | ||
68 | <varlistentry> | ||
69 | <term>LIRC_GET_FEATURES</term> | ||
70 | <listitem> | ||
71 | <para>Obviously, get the underlying hardware device's features. If a driver | ||
72 | does not announce support of certain features, calling of the corresponding | ||
73 | ioctls is undefined.</para> | ||
74 | </listitem> | ||
75 | </varlistentry> | ||
76 | <varlistentry> | ||
77 | <term>LIRC_GET_SEND_MODE</term> | ||
78 | <listitem> | ||
79 | <para>Get supported transmit mode. Only LIRC_MODE_PULSE is supported by lircd.</para> | ||
80 | </listitem> | ||
81 | </varlistentry> | ||
82 | <varlistentry> | ||
83 | <term>LIRC_GET_REC_MODE</term> | ||
84 | <listitem> | ||
85 | <para>Get supported receive modes. Only LIRC_MODE_MODE2 and LIRC_MODE_LIRCCODE | ||
86 | are supported by lircd.</para> | ||
87 | </listitem> | ||
88 | </varlistentry> | ||
89 | <varlistentry> | ||
90 | <term>LIRC_GET_SEND_CARRIER</term> | ||
91 | <listitem> | ||
92 | <para>Get carrier frequency (in Hz) currently used for transmit.</para> | ||
93 | </listitem> | ||
94 | </varlistentry> | ||
95 | <varlistentry> | ||
96 | <term>LIRC_GET_REC_CARRIER</term> | ||
97 | <listitem> | ||
98 | <para>Get carrier frequency (in Hz) currently used for IR reception.</para> | ||
99 | </listitem> | ||
100 | </varlistentry> | ||
101 | <varlistentry> | ||
102 | <term>LIRC_{G,S}ET_{SEND,REC}_DUTY_CYCLE</term> | ||
103 | <listitem> | ||
104 | <para>Get/set the duty cycle (from 0 to 100) of the carrier signal. Currently, | ||
105 | no special meaning is defined for 0 or 100, but this could be used to switch | ||
106 | off carrier generation in the future, so these values should be reserved.</para> | ||
107 | </listitem> | ||
108 | </varlistentry> | ||
109 | <varlistentry> | ||
110 | <term>LIRC_GET_REC_RESOLUTION</term> | ||
111 | <listitem> | ||
112 | <para>Some receiver have maximum resolution which is defined by internal | ||
113 | sample rate or data format limitations. E.g. it's common that signals can | ||
114 | only be reported in 50 microsecond steps. This integer value is used by | ||
115 | lircd to automatically adjust the aeps tolerance value in the lircd | ||
116 | config file.</para> | ||
117 | </listitem> | ||
118 | </varlistentry> | ||
119 | <varlistentry> | ||
120 | <term>LIRC_GET_M{IN,AX}_TIMEOUT</term> | ||
121 | <listitem> | ||
122 | <para>Some devices have internal timers that can be used to detect when | ||
123 | there's no IR activity for a long time. This can help lircd in detecting | ||
124 | that a IR signal is finished and can speed up the decoding process. | ||
125 | Returns an integer value with the minimum/maximum timeout that can be | ||
126 | set. Some devices have a fixed timeout, in that case both ioctls will | ||
127 | return the same value even though the timeout cannot be changed.</para> | ||
128 | </listitem> | ||
129 | </varlistentry> | ||
130 | <varlistentry> | ||
131 | <term>LIRC_GET_M{IN,AX}_FILTER_{PULSE,SPACE}</term> | ||
132 | <listitem> | ||
133 | <para>Some devices are able to filter out spikes in the incoming signal | ||
134 | using given filter rules. These ioctls return the hardware capabilities | ||
135 | that describe the bounds of the possible filters. Filter settings depend | ||
136 | on the IR protocols that are expected. lircd derives the settings from | ||
137 | all protocols definitions found in its config file.</para> | ||
138 | </listitem> | ||
139 | </varlistentry> | ||
140 | <varlistentry> | ||
141 | <term>LIRC_GET_LENGTH</term> | ||
142 | <listitem> | ||
143 | <para>Retrieves the code length in bits (only for LIRC_MODE_LIRCCODE). | ||
144 | Reads on the device must be done in blocks matching the bit count. | ||
145 | The bit could should be rounded up so that it matches full bytes.</para> | ||
146 | </listitem> | ||
147 | </varlistentry> | ||
148 | <varlistentry> | ||
149 | <term>LIRC_SET_{SEND,REC}_MODE</term> | ||
150 | <listitem> | ||
151 | <para>Set send/receive mode. Largely obsolete for send, as only | ||
152 | LIRC_MODE_PULSE is supported.</para> | ||
153 | </listitem> | ||
154 | </varlistentry> | ||
155 | <varlistentry> | ||
156 | <term>LIRC_SET_{SEND,REC}_CARRIER</term> | ||
157 | <listitem> | ||
158 | <para>Set send/receive carrier (in Hz).</para> | ||
159 | </listitem> | ||
160 | </varlistentry> | ||
161 | <varlistentry> | ||
162 | <term>LIRC_SET_TRANSMITTER_MASK</term> | ||
163 | <listitem> | ||
164 | <para>This enables the given set of transmitters. The first transmitter | ||
165 | is encoded by the least significant bit, etc. When an invalid bit mask | ||
166 | is given, i.e. a bit is set, even though the device does not have so many | ||
167 | transitters, then this ioctl returns the number of available transitters | ||
168 | and does nothing otherwise.</para> | ||
169 | </listitem> | ||
170 | </varlistentry> | ||
171 | <varlistentry> | ||
172 | <term>LIRC_SET_REC_TIMEOUT</term> | ||
173 | <listitem> | ||
174 | <para>Sets the integer value for IR inactivity timeout (cf. | ||
175 | LIRC_GET_MIN_TIMEOUT and LIRC_GET_MAX_TIMEOUT). A value of 0 (if | ||
176 | supported by the hardware) disables all hardware timeouts and data should | ||
177 | be reported as soon as possible. If the exact value cannot be set, then | ||
178 | the next possible value _greater_ than the given value should be set.</para> | ||
179 | </listitem> | ||
180 | </varlistentry> | ||
181 | <varlistentry> | ||
182 | <term>LIRC_SET_REC_TIMEOUT_REPORTS</term> | ||
183 | <listitem> | ||
184 | <para>Enable (1) or disable (0) timeout reports in LIRC_MODE_MODE2. By | ||
185 | default, timeout reports should be turned off.</para> | ||
186 | </listitem> | ||
187 | </varlistentry> | ||
188 | <varlistentry> | ||
189 | <term>LIRC_SET_REC_FILTER_{,PULSE,SPACE}</term> | ||
190 | <listitem> | ||
191 | <para>Pulses/spaces shorter than this are filtered out by hardware. If | ||
192 | filters cannot be set independently for pulse/space, the corresponding | ||
193 | ioctls must return an error and LIRC_SET_REC_FILTER shall be used instead.</para> | ||
194 | </listitem> | ||
195 | </varlistentry> | ||
196 | <varlistentry> | ||
197 | <term>LIRC_SET_MEASURE_CARRIER_MODE</term> | ||
198 | <listitem> | ||
199 | <para>Enable (1)/disable (0) measure mode. If enabled, from the next key | ||
200 | press on, the driver will send LIRC_MODE2_FREQUENCY packets. By default | ||
201 | this should be turned off.</para> | ||
202 | </listitem> | ||
203 | </varlistentry> | ||
204 | <varlistentry> | ||
205 | <term>LIRC_SET_REC_{DUTY_CYCLE,CARRIER}_RANGE</term> | ||
206 | <listitem> | ||
207 | <para>To set a range use LIRC_SET_REC_DUTY_CYCLE_RANGE/LIRC_SET_REC_CARRIER_RANGE | ||
208 | with the lower bound first and later LIRC_SET_REC_DUTY_CYCLE/LIRC_SET_REC_CARRIER | ||
209 | with the upper bound.</para> | ||
210 | </listitem> | ||
211 | </varlistentry> | ||
212 | <varlistentry> | ||
213 | <term>LIRC_NOTIFY_DECODE</term> | ||
214 | <listitem> | ||
215 | <para>This ioctl is called by lircd whenever a successful decoding of an | ||
216 | incoming IR signal could be done. This can be used by supporting hardware | ||
217 | to give visual feedback to the user e.g. by flashing a LED.</para> | ||
218 | </listitem> | ||
219 | </varlistentry> | ||
220 | <varlistentry> | ||
221 | <term>LIRC_SETUP_{START,END}</term> | ||
222 | <listitem> | ||
223 | <para>Setting of several driver parameters can be optimized by encapsulating | ||
224 | the according ioctl calls with LIRC_SETUP_START/LIRC_SETUP_END. When a | ||
225 | driver receives a LIRC_SETUP_START ioctl it can choose to not commit | ||
226 | further setting changes to the hardware until a LIRC_SETUP_END is received. | ||
227 | But this is open to the driver implementation and every driver must also | ||
228 | handle parameter changes which are not encapsulated by LIRC_SETUP_START | ||
229 | and LIRC_SETUP_END. Drivers can also choose to ignore these ioctls.</para> | ||
230 | </listitem> | ||
231 | </varlistentry> | ||
232 | <varlistentry> | ||
233 | <term>LIRC_SET_WIDEBAND_RECEIVER</term> | ||
234 | <listitem> | ||
235 | <para>Some receivers are equipped with special wide band receiver which is intended | ||
236 | to be used to learn output of existing remote. | ||
237 | Calling that ioctl with (1) will enable it, and with (0) disable it. | ||
238 | This might be useful of receivers that have otherwise narrow band receiver | ||
239 | that prevents them to be used with some remotes. | ||
240 | Wide band receiver might also be more precise | ||
241 | On the other hand its disadvantage it usually reduced range of reception. | ||
242 | Note: wide band receiver might be implictly enabled if you enable | ||
243 | carrier reports. In that case it will be disabled as soon as you disable | ||
244 | carrier reports. Trying to disable wide band receiver while carrier | ||
245 | reports are active will do nothing.</para> | ||
246 | </listitem> | ||
247 | </varlistentry> | ||
248 | </variablelist> | ||
249 | <section id="lirc_dev_errors"> | ||
250 | &return-value; | ||
251 | </section> | ||
252 | </section> | ||
253 | </section> | ||