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 ja...@redhat.com
---
.../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 @@
+titleLIRC Device Interface/title
+
+
+section id=lirc_dev_intro
+titleIntroduction/title
+
+paraThe 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./para
+
+paraExample dmesg output upon a driver registering w/LIRC:/para
+ blockquote
+para$ dmesg |grep lirc_dev/para
+paralirc_dev: IR Remote Control driver registered, major 248/para
+pararc rc0: lirc_dev: driver ir-lirc-codec (mceusb) registered at minor
= 0/para
+ /blockquote
+para
+
+paraWhat you should see for a chardev:/para
+ blockquote
+para$ ls -l /dev/lirc*/para
+paracrw-rw 1 root root 248, 0 Jul 2 22:20 /dev/lirc0/para
+ /blockquote
+/para
+
+
+section id=lirc_read
+titleLIRC read fop/title
+
+paraThe 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 xref linkend=lirc_ioctl. The
generally
+preferred mode is LIRC_MODE_MODE2, in which packets containing an int value
+describing an IR signal are read from the chardev./para
+
+paraSee also ulink
url=http://www.lirc.org/html/technical.html;http://www.lirc.org/html/technical.html/
for more info./para
+
+
+section id=lirc_write
+titleLIRC write fop/title
+
+paraThe 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./para
+
+
+section id=lirc_ioctl
+title LIRC ioctl fop/title
+
+paraThe 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./para
+
+paraThe 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./para
+
+variablelist
+ varlistentry
+termLIRC_GET_FEATURES/term
+listitem
+ toObviously, get the underlying hardware device's features. If a
driver
+ does not announce support of certain features, calling of the
corresponding
+ ioctls is undefined./to
+/listitem
+ /varlistentry
+ varlistentry
+termLIRC_GET_SEND_MODE/term
+listitem
+ toGet supported transmit mode. Only LIRC_MODE_PULSE is supported by
lircd./to
+/listitem
+ /varlistentry
+ varlistentry
+termLIRC_GET_REC_MODE/term
+listitem
+ toGet supported receive modes. Only LIRC_MODE_MODE2 and
LIRC_MODE_LIRCCODE
+ are supported by lircd./to
+/listitem
+ /varlistentry
+ varlistentry
+termLIRC_GET_SEND_CARRIER/term
+listitem
+ toGet carrier frequency (in Hz) currently used for transmit./to
+/listitem
+ /varlistentry
+ varlistentry
+termLIRC_GET_REC_CARRIER/term
+listitem
+ toGet carrier frequency (in Hz) currently used for IR reception./to
+/listitem
+ /varlistentry
+ varlistentry
+termLIRC_{G,S}ET_{SEND,REC}_DUTY_CYCLE/term
+listitem
+ toGet/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./to
+/listitem
+ /varlistentry
+ varlistentry
+termLIRC_GET_REC_RESOLUTION/term
+listitem
+ toSome receiver have maximum
