Alec, On 12/14/2015 09:49 PM, Alec Leamas wrote: > On Mon, 14 Dec 2015 21:40:04 +0100 > "Michael Kerrisk (man-pages)" <mtk.manpages@xxxxxxxxx> wrote: > >> Hi Alec, >> >>> Revised patch below. In case of troubles, a fresh copy is available at >>> http://paste.fedoraproject.org/300732/45011842 >> >> The version inline, and at that URL seems to be an old version of the page where >> the fixes just discussed have not been made.... > > Sigh... What's happening, really? Making a new try: correct mailer, the right patch?! > > http://paste.fedoraproject.org/300790/25945145 Yes, we're good this time. I've applied your patch in a public branch (http://git.kernel.org/cgit/docs/man-pages/man-pages.git/log/?h=draft_lirc ) and done a few light edits. I haven't yet merged this into 'master' because the corresponding kernel patch is not yet in mainline (right)? Thanks for all of your effort pulling this page together! Cheers, Michael > From 5c3191b29a81e202ecc59e967cb2c508ece3e855 Mon Sep 17 00:00:00 2001 > From: Alec Leamas <leamas.alec@xxxxxxxxx> > Date: Mon, 14 Dec 2015 21:44:39 +0100 > Subject: [PATCH] Adding new lirc.4 manpage. > > --- > doc/man-source/lirc.4 | 446 ++++++++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 446 insertions(+) > create mode 100644 doc/man-source/lirc.4 > > diff --git a/doc/man-source/lirc.4 b/doc/man-source/lirc.4 > new file mode 100644 > index 0000000..4b72463 > --- /dev/null > +++ b/doc/man-source/lirc.4 > @@ -0,0 +1,446 @@ > +.TH LIRC 4 "Aug 2015" "Linux" "Linux Programmer's Manual" > + > + > +.\" Copyright (c) 2015, Alec Leamas > +.\" > +.\" %%%LICENSE_START(GPLv2+_DOC_FULL) > +.\" This is free documentation; you can redistribute it and/or > +.\" modify it under the terms of the GNU General Public License as > +.\" published by the Free Software Foundation; either version 2 of > +.\" the License, or (at your option) any later version. > +.\" > +.\" The GNU General Public License's references to "object code" > +.\" and "executables" are to be interpreted as the output of any > +.\" document formatting or typesetting system, including > +.\" intermediate and printed output. > +.\" > +.\" This manual is distributed in the hope that it will be useful, > +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of > +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the > +.\" GNU General Public License for more details. > +.\" > +.\" You should have received a copy of the GNU General Public > +.\" License along with this manual; if not, see > +.\" <http://www.gnu.org/licenses/>. > +.\" %%%LICENSE_END > +.SH NAME > +lirc \- lirc devices > +.SH DESCRIPTION > +.P > +\fB/dev/lirc*\fR are character devices providing a low-level > +bi-directional interface to infra-red (IR) remotes. > +When receiving data, the driver works in two different modes depending > +on the underlying hardware. > +.P > +Some hardware (typically TV-cards) decodes the IR signal internally > +and just provides decoded button presses as integer values. > +Drivers for this kind of hardware work in > +.BR LIRC_MODE_LIRCCODE . > +Such hardware usually does not support sending IR signals. > +Furthermore, it usually only works with a specific remote which is > +bundled with, for example, a TV-card. > +.P > +Other hardware provides a stream of pulse/space durations. > +Such drivers work in > +.BR LIRC_MODE_MODE2 . > +Sometimes, this kind of hardware also supports > +sending IR data. > +Such hardware can be used with (almost) any kind of remote. > +.P > +The \fBLIRC_GET_REC_MODE\fR ioctl (see below) allows probing for the > +mode. > + > +.SS Reading input with the LIRC_MODE_MODE2 drivers > +.P > +In the \fBLIRC_MODE_MODE2 mode\fR, the data returned by > +.BR read (2) > +provides 32-bit values representing a space or a pulse duration, by > +convention typed as > +.IR lirc_t . > +The time of the duration (microseonds) is encoded in the lower 24 bits. > +The upper 8 bit reflects the type of package: > +.TP 4 > +.BR LIRC_MODE2_SPACE . > +Value reflects a space duration (microseconds). > +.TP 4 > +.BR LIRC_MODE2_PULSE . > +Value reflects a pulse duration (microseconds). > +.TP 4 > +.BR LIRC_MODE2_FREQUENCY . > +Value reflects a frequency (hz), see the > +.B LIRC_SET_MEASURE_CARRIER > +ioctl. > +.TP 4 > +.BR LIRC_MODE2_TIMEOUT . > +The package reflects a timeout, see the > +.B LIRC_SET_REC_TIMEOUT_REPORTS > +ioctl. > + > +.SS Reading input with the > +.B LIRC_MODE_LIRCCODE > +drivers > +.P > +In the \fBLIRC_MODE_LIRCCODE\fR > +mode, the data returned by > +.BR read2() > +reflects decoded button presses. > +The length of each packet can be retrieved using > +the \fBLIRC_GET_LENGTH\fR ioctl. > +Reads must be done in blocks matching > +the bit count returned by the \fBLIRC_GET_LENGTH\fR ioctl, rounded > +up so it matches full bytes. > + > +.SS Sending data > +.P > +When sending data, only the \fBLIRC_MODE_PULSE\fR > +mode is supported. > +The data written to the character device using > +.BR write(2) > +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, thus it must always include > +an odd number of samples. > +The > +.BR write(2) > +function blocks until the data has been transmitted by the > +hardware. > +If more data is provided than the hardware can send, the > +.BR write(2) > +call fails with the error > +.BR EINVAL > + > +.SH SUPPORTED IOCTL COMMANDS > +.P > +.nf > +#include " (\fIlirc/include/media/lirc.h\fP) " /* But see BUGS */ > +int ioctl(int fd, int cmd, ...); > +.fi > +.P > +The following ioctls can be used to probe or change specific lirc > +hardware settings. > +Many require a third argument, usually an > +.IR int . > +referred to below as > +.I val . > +.P > +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 userspace, so that every application > +opening the device can rely on working with the default settings > +initially. > + > +.BR > +.SS Always Supported Commands > +.P > +\fI/dev/lirc*\fR devices always support the following commands: > +.TP 4 > +.BR LIRC_GET_FEATURES " (\fIvoid\fP)" > +Returns a bitmask of combined features bits, see FEATURES. > +Some drivers have dynamic features which are not updated until after > +an init() command. > +.TP > +.BR LIRC_GET_REC_MODE , > +Returns the receive mode, which will be one of: > +.RS 4 > +.TP > +.BR LIRC_MODE_MODE2 " (\fIvoid\fP)" > +Driver returns a sequence of pulse/space durations. > +.TP > +.BR LIRC_MODE_LIRCCODE > +Driver returns integer values, each of which represents a decoded > +button press. > +.RE > +.P > +If a device returns an error code for > +.BR LIRC_GET_REC_MODE > +it is safe to assume it is not a lirc device. > + > +.SS Optional Commands > +.P > +Some lirc devices support commands listed below. > +Unless otherwise stated, these fail with the error \fBENOIOCTLCMD\fR > +or with the error \fBENOSYS\fR if the operation > +isn't supported, or with the error \fBEINVAL\fR if the operation > +failed. > +.TP > +.BR LIRC_SET_REC_MODE " (\fIint\fP)" > +Set the receive mode. > +.IR val > +is either > +.BR LIRC_MODE_LIRCCODE > +or > +.BR LIRC_MODE_MODE2 . > + > +.TP > +.BR LIRC_GET_LENGTH " (\fIvoid\fP)" > +Return the length of the returned codes for > +.BR LIRC_LIRCCODE > +type > +drivers, otherwise fail with the error > +.BR ENOIOCTLCMD . > +.TP > +.BR LIRC_GET_SEND_MODE " (\fIvoid\fP)" > +Returns the send mode; currently only > +.BR LIRC_MODE_PULSE > +is supported. > +.TP > +.BR LIRC_SET_SEND_MODE " (\fIint\fP)" > +Set the send mode. > +Currently serves no purpose since only > +.BR LIRC_MODE_PULSE > +is supported. > +.TP > +.BR LIRC_SET_SEND_CARRIER " (\fIint\fP)" > +Set the modulation frequency. The argument is the frequency (Hz). > +.TP > +.BR SET_SEND_DUTY_CYCLE " (\fIint\fP)" > +Set the carrier duty cycle. > +The argument is an int (0 < value < 100) which > +describes the pulse width in percent of the total cycle. > +Currently, no special meaning is defined for 0 or 100, but the values > +are reserved for future use. > +.TP > +.BR LIRC_GET_MIN_TIMEOUT " (\fIvoid\fP)", " "\ > +LIRC_GET_MAX_TIMEOUT " (\fIvoid\fP)" > +Some devices have internal timers that can be used to detect when > +there's no IR activity for a long time. > +This can help > +.BR lircd(8) > +in detecting that an IR signal is finished and can speed up the > +decoding process. > +Returns an integer value with the minimum/maximum timeout that can be > +set (microseconds). > +Some devices have a fixed timeout. For such drivers, > +.BR LIRC_GET_MIN_TIMEOUT > +and > +.BR LIRC_GET_MAX_TIMEOUT > +will return the same value. > +.TP > +.BR LIRC_SET_REC_TIMEOUT " (\fIint\fP)" > +Sets the integer value for IR inactivity timeout (microseconds). > +To be accepted, the value must be within the limits defined by > +.BR LIRC_GET_MIN_TIMEOUT > +and > +.BR LIRC_GET_MAX_TIMEOUT . > +A value of 0 (if supported by the hardware) disables all hardware > +timeouts and data should be reported as soon as possible. > +If the exact value cannot be set, then the next possible value > +.I greater > +than the given value should be set. > +.TP > +.BR LIRC_SET_REC_TIMEOUT_REPORTS " (\fIint\fP)" > +Enables > +.RI ( val > +is 1) or disables > +.RI (val > +is 0) timeout packages in > +.BR LIRC_MODE_MODE2 . > +By default, timeout reports should be turned off. > +.TP > +.BR LIRC_SET_REC_CARRIER " (\fIint\fP)" > +Set the receive carrier frequency (Hz). > +.TP > +After opening device, the first use of > +.BR LIRC_SET_REC_CARRIER_RANGE " (\fIint\fP)" > +sets the lower bound of the carrier range, second time the upper > +bound (Hz). > +.TP > +.BR LIRC_SET_MEASURE_CARRIER " (\fIint\fP)" > +Enables > +.RI ( val > +is 1) or disables > +.RI (val > +is 0) the measure mode > +If enabled, from the next key press on, the driver will send > +.BR LIRC_MODE2_FREQUENCY > +packets. By default this should be turned off. > +.TP > +.BR LIRC_GET_REC_RESOLUTION " (\fIvoid\fP)" > +Returns the driver resolution (microseconds). > +.TP > +.BR LIRC_GET_MIN_FILTER_PULSE " (\fIvoid\fP)", " " \ > +LIRC_GET_MAX_FILTER_PULSE " (\fIvoid\fP)" > +Some devices are able to filter out spikes in the incoming signal > +using given filter rules. > +These ioctls return the hardware capabilities that describe the bounds > +of the possible filters. > +Filter settings depend on the IR protocols that are expected. > +lircd derives the settings from all protocols definitions found in its > +.BR lircd.conf (5) > +config file. > +.TP > +.BR LIRC_GET_MIN_FILTER_SPACE " (\fIvoid\fP)", " " \ > +LIRC_GET_MAX_FILTER_SPACE " (\fIvoid\fP)" > +See > +.BR LIRC_GET_MIN_FILTER_PULSE . > +.TP > +.BR LIRC_SET_REC_FILTER " (\fIint\fP)" > +Pulses/spaces shorter than this (microseconds) are filtered out by > +hardware. > +.TP > +.BR LIRC_SET_REC_FILTER_PULSE " (\fIint\fP)", " " \ > +LIRC_SET_REC_FILTER_SPACE " (\fIint\fP)" > +Pulses/spaces shorter than this (microseconds) are filtered out by > +hardware. > +If filters cannot be set independently for pulse/space, the > +corresponding ioctls must return an error and > +.BR LIRC_SET_REC_FILTER > +should be used instead. > +.TP > +.BR LIRC_SET_TRANSMITTER_MASK > +Enables the given set of transmitters. > +.RI val > +contains a bitmask where each enabled transmitter is a 1. > +The first transmitter is encoded by the least significant bit, etc. > +When an invalid bit mask is given, for example a bit is set even > +though the device does not have so many transmitters, returns the > +number of available transmitters and does nothing otherwise. > +.TP > +.BR LIRC_SET_WIDEBAND_RECEIVER " (\fIint\fP)" > +Some devices are equipped with a special wide band receiver which are > +intended to be used to learn the output of an existing remote. > +This ioctl can be used to enable > +.RI ( val > +equals 1) or disable > +.RI ( val > +equals 0) this functionality. > +This might be useful for devices that otherwise have narrow band > +receivers that prevent them to be used with certain remotes. > +Wide band receivers may also be more precise. > +On the other hand its disadvantage usually is reduced range of > +reception. > +.IP > +Note: wide band receiver may be implicitly enabled if you enable > +carrier reports. > +In that case it will be disabled as soon as you disable carrier reports. > +Trying to disable a wide band receiver while carrier reports are active > +will do nothing. > + > +.TP > +.BR LIRC_SETUP_START " (\fIvoid\fP)", " "LIRC_SETUP_END " (\fIvoid\fP)" > +Setting of several driver parameters can be optimized by encapsulating > +the actual ioctl calls with > +.BR LIRC_SETUP_START/LIRC_SETUP_END . > +When a driver receives a > +.BR LIRC_SETUP_START > +ioctl it can choose to not commit further setting changes to the > +hardware until a > +.BR LIRC_SETUP_END > +is received. > +But this is open to the driver implementation and every driver > +must also handle parameter changes which are not encapsulated by > +.BR LIRC_SETUP_START > +and > +.BR LIRC_SETUP_END . > +Drivers can also choose to ignore these ioctls. > + > +.TP > +.BR LIRC_NOTIFY_DECODE " (\fIvoid\fP)" > +This ioctl is called by > +.BR lircd(8) > +whenever a successful decoding of an incoming IR signal is possible. > +This can be used by supporting hardware to give visual user > +feedback, for example by flashing an LED. > + > +.SH FEATURES > +.P > +The features returned by > +.BR LIRC_GET_FEATURES > +is a bitmask combining the following bits: > +.TP 8 > +.BR LIRC_CAN_REC_RAW > +The driver is capable of receiving using > +.BR LIRC_MODE_RAW . > +.TP 8 > +.BR LIRC_CAN_REC_PULSE > +The driver is capable of receiving using > +.BR LIRC_MODE_PULSE . > +.TP 8 > +.BR LIRC_CAN_REC_MODE2 > +The driver is capable of receiving using > +.BR LIRC_MODE_MODE2 . > +.TP 8 > +.BR LIRC_CAN_REC_LIRCCODE > +The driver is capable of receiving using > +.BR LIRC_MODE_LIRCCODE . > +.TP 8 > +.BR LIRC_CAN_SET_SEND_CARRIER > +Driver supports changing the modulation frequency using > +.BR LIRC_SET_SEND_CARRIER . > +.TP 8 > +.BR LIRC_CAN_SET_SEND_DUTY_CYCLE > +Driver supports changing the duty cycle using > +.BR LIRC_SET_SEND_DUTY_CYCLE . > +.TP 8 > +.BR LIRC_CAN_SET_TRANSMITTER_MASK > +Driver supports changing the active transmitter(s) using > +.BR LIRC_SET_TRANSMITTER_MASK . > +.TP 8 > +.BR LIRC_CAN_SET_REC_CARRIER > +Driver supports setting the receive carrier frequency using > +.BR LIRC_SET_REC_CARRIER . > +.TP 8 > +.BR LIRC_CAN_SET_REC_DUTY_CYCLE_RANGE > +Driver supports > +.BR LIRC_SET_REC_DUTY_CYCLE_RANGE . > +.TP 8 > +.BR LIRC_CAN_SET_REC_CARRIER_RANGE > +Driver supports > +.BR LIRC_SET_REC_CARRIER_RANGE . > +.TP 8 > +.BR LIRC_CAN_GET_REC_RESOLUTION > +Driver supports > +.BR LIRC_GET_REC_RESOLUTION . > +.TP 8 > +.BR LIRC_CAN_SET_REC_TIMEOUT > +Driver supports > +.BR LIRC_SET_REC_TIMEOUT . > +.TP 8 > +.BR LIRC_CAN_SET_REC_FILTER > +Driver supports > +.BR LIRC_SET_REC_FILTER . > +.TP 8 > +.BR LIRC_CAN_MEASURE_CARRIER > +Driver supports measuring of the modulation frequency using > +.BR LIRC_MEASURE_CARRIER . > +.TP 8 > +.BR LIRC_CAN_USE_WIDEBAND_RECEIVER > +Driver supports learning mode using > +.BR LIRC_SET_WIDEBAND_RECEIVER . > +.TP 8 > +.BR LIRC_CAN_NOTIFY_DECODE > +Driver supports > +.BR LIRC_NOTIFY_DECODE . > +.TP 8 > +.BR LIRC_CAN_SEND_RAW > +Driver supports sending using > +.BR LIRC_SEND_RAW . > +.TP 8 > +.BR LIRC_CAN_SEND_PULSE > +Driver supports sending using > +.BR LIRC_MODE_PULSE . > +.TP 8 > +.BR LIRC_CAN_SEND_MODE2 > +Driver supports sending using > +.BR LIRC_SEND_MODE2 . > +.TP 8 > +.BR LIRC_CAN_SEND_LIRCCODE > +Driver supports sending. > +.BR LIRC_SEND_LIRCCODE > +(this is uncommon, since > +.BR LIRCCODE > +drivers reflect hardware like TV-cards which usually does not support > +sending.) > + > +.SH BUGS > +.P > +Using these devices requires the kernel source header file lirc.h. > +This file not being public is a bug, see > +https://bugzilla.kernel.org/show_bug.cgi?id=75751. > +For the time being the file is bundled in the lirc package, > +see http://www.lirc.org. > + > + > +.SH SEE ALSO > +.P > +https://www.kernel.org/doc/htmldocs/media_api/lirc_dev.html > -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
