First ever crack at creating docbook documentation... Contains a bevy of
information on the various lirc device interface ioctls, as well as a
bit about the read and write interfaces.
Forgot about this in 0/3, so this is patch 4/3. Oops.
Signed-off-by: Jarod Wilson
---
.../DocBook/v4l/lirc_device_interface.xml | 235
1 files changed, 235 insertions(+), 0 deletions(-)
create mode 100644 Documentation/DocBook/v4l/lirc_device_interface.xml
diff --git a/Documentation/DocBook/v4l/lirc_device_interface.xml
b/Documentation/DocBook/v4l/lirc_device_interface.xml
new file mode 100644
index 000..a6244ed
--- /dev/null
+++ b/Documentation/DocBook/v4l/lirc_device_interface.xml
@@ -0,0 +1,235 @@
+LIRC Device Interface
+
+
+
+Introduction
+
+The LIRC device interface is a bi-directional interface for
+transporting raw IR data between userspace and kernelspace. Fundamentally,
+it is just a chardev (/dev/lircX, for X = 0, 1, 2, ...), with a number
+of standard struct file_operations defined on it. With respect to
+transporting raw IR data to and fro, the essential fops are read, write
+and ioctl.
+
+Example dmesg output upon a driver registering w/LIRC:
+
+$ dmesg |grep lirc_dev
+lirc_dev: IR Remote Control driver registered, major 248
+rc rc0: lirc_dev: driver ir-lirc-codec (mceusb) registered at minor
= 0
+
+
+
+What you should see for a chardev:
+
+$ ls -l /dev/lirc*
+crw-rw 1 root root 248, 0 Jul 2 22:20 /dev/lirc0
+
+
+
+
+
+LIRC read fop
+
+The lircd userspace daemon reads raw IR data from the LIRC chardev. The
+exact format of the data depends on what modes a driver supports, and what
+mode has been selected. lircd obtains supported modes and sets the active mode
+via the ioctl interface, detailed at . The
generally
+preferred mode is LIRC_MODE_MODE2, in which packets containing an int value
+describing an IR signal are read from the chardev.
+
+See also http://www.lirc.org/html/technical.html";>http://www.lirc.org/html/technical.html
for more info.
+
+
+
+LIRC write fop
+
+The data written to the chardev is a pulse/space sequence of integer
+values. Pulses and spaces are only marked implicitly by their position. The
+data must start and end with a pulse, therefore, the data must always include
+an unevent number of samples. The write function must block until the data has
+been transmitted by the hardware.
+
+
+
+ LIRC ioctl fop
+
+The LIRC device's ioctl definition is bound by the ioctl function
+definition of struct file_operations, leaving us with an unsigned int
+for the ioctl command and an unsigned long for the arg. For the purposes
+of ioctl portability across 32-bit and 64-bit, these values are capped
+to their 32-bit sizes.
+
+The following ioctls can be used to change specific hardware settings.
+In general each driver should have a default set of settings. The driver
+implementation is expected to re-apply the default settings when the device
+is closed by user-space, so that every application opening the device can rely
+on working with the default settings initially.
+
+
+
+LIRC_GET_FEATURES
+
+ Obviously, get the underlying hardware device's features. If a
driver
+ does not announce support of certain features, calling of the
corresponding
+ ioctls is undefined.
+
+
+
+LIRC_GET_SEND_MODE
+
+ Get supported transmit mode. Only LIRC_MODE_PULSE is supported by
lircd.
+
+
+
+LIRC_GET_REC_MODE
+
+ Get supported receive modes. Only LIRC_MODE_MODE2 and
LIRC_MODE_LIRCCODE
+ are supported by lircd.
+
+
+
+LIRC_GET_SEND_CARRIER
+
+ Get carrier frequency (in Hz) currently used for transmit.
+
+
+
+LIRC_GET_REC_CARRIER
+
+ Get carrier frequency (in Hz) currently used for IR reception.
+
+
+
+LIRC_{G,S}ET_{SEND,REC}_DUTY_CYCLE
+
+ Get/set the duty cycle (from 0 to 100) of the carrier signal.
Currently,
+ no special meaning is defined for 0 or 100, but this could be used to
switch
+ off carrier generation in the future, so these values should be
reserved.
+
+
+
+LIRC_GET_REC_RESOLUTION
+
+ Some receiver have maximum resolution which is defined by internal
+ sample rate or data format limitations. E.g. it's common that signals
can
+ only be reported in 50 microsecond steps. This integer value is used by
+ lircd to automatically adjust the aeps tolerance value in the lircd
+ config file.
+
+
+
+LIRC_GET_M{IN,AX}_TIMEOUT
+
+ Some devices have internal timers that can be used to detect when
+ there's no IR activity for a long time. This can help lircd in detecting
+ that a IR signal is finished and can speed up the decoding process.
+ Returns an integer value with the minimum/maximum timeout that can be
+ set. Some devices have a fixed timeout, in that case both ioctls will
+
