Hello Alec, Thanks for the revised page. See below for comments. >>>> Revised patch: >>> >>> Patches on top of patches is confusing. For the next round, just send >>> a fresh complete patch. A few more comments below. > > Indeed, and that's what I thought I did... Okay :-) >>>> +Drivers for this kind of hardware work in >>>> .B LIRC_MODE_LIRCCODE. >>> >>> .BR LIRC_MODE_LIRCCODE . > > All '^\.B ' fixed > >>> .BR LIRC_MODE_MODE2 . >>> >>> (i.e., add space before '.') Probably there are other instances to fix as well. > > Hopefully found and fixed them all. [...] > New patch (hopefully in better shape...) Thanks, better, but your mailer is still wrapping patches... >>From 0864603b5f912be5e9b43dc690b313e1ba83b0f5 Mon Sep 17 00:00:00 2001 > From: Alec Leamas <leamas.alec@xxxxxxxxx> > Date: Mon, 14 Dec 2015 10:47:08 +0100 > Subject: [PATCH] Adding new lirc.4 manpage > > --- > doc/man-source/lirc.4 | 396 > ++++++++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 396 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..f468364 > --- /dev/null > +++ b/doc/man-source/lirc.4 > @@ -0,0 +1,396 @@ > +.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 allows probing for the mode. s/ioctl/ioctl (described below)/ > + > +.SH Reading input with the LIRC_MODE_MODE2 drivers > +.P > +In the \fBLIRC_MODE_MODE2 mode\fR, the driver read() provides 32-bit values s/ mode\fR/\fR mode/ Change "the driver read() provides" to [[ the data returned by .BR read (2) consists of ]] > +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 LIRC_SET_MEASURE_CARRIER ioctl. Constants should generally always be bolded, so: .B LIRC_SET_MEASURE_CARRIER Various other places need fixing below. > +.TP 4 > +.BR LIRC_MODE2_TIMEOUT . > +The package reflects a timeout, see the LIRC_SET_REC_TIMEOUT_REPORTS ioctl. > + > +.SH Reading input with the LIRC_MODE_LIRCCODE drivers For all of the ".SH" lines that use lower-case titles, change ".SH" to ".SS". (Many instances to change below.) > +.P > +In the \fBLIRC_MODE_LIRCCODE\fR > +mode, the data returned by read() reflects decoded .BR read (2) > +button presses. > +The length of each packet can be retrieved using > +the \fBLIRC_GET_LENGTH\fR ioctl. > +Device must be read in blocks matching s/Device must be read/Reads must be/ > +the bit count, rounded up so it matches full bytes. What bit count is this? This needs clarifying. > + > +.SH Sending data. s/.$// > +.P > +When sending data, only the \fBLIRC_MODE_PULSE\fR > +mode is supported. > +The data written to the character device using write() is a pulse/space .BR write (2) > +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 write() function blocks until the data has been transmitted by the Change "The write() function" to [[ A .BR write (2) ]] > +hardware. > +If more data is provided than the hardware can send, the write() call .BR write (2) > +fails with the error > +.BR EINVAL > + > +.SH SUPPORTED IOCTL COMMANDS > +.P > +.nf > +#include " (\fIuapi/lirc.h\fP)" So, presumably this is not the correct path, as noted in BUGS. Where does the "lirc" package put it? Use that path here, and write: #include <path.h> /* 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 . Replace last line with [[ .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 > +.SH Always Supported Commands > +.P > +\fI/dev/lirc*\fR devices always supports the following commands: s/supports/support/ > +.TP 4 > +.BR LIRC_GET_FEATURES void s/void/" (\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 4 > +.BR LIRC_GET_REC_MODE void s/void/" (\fIvoid\fP)" > +Returns the receive mode, one of a/one of/which will be one of:/ > +.RS 4 > +.TP > +.BR LIRC_MODE_MODE2 > +Driver return a sequence of pulse/space durations. s/return/returns > +.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 s/$/ ,/ > +it is safe to assume it is not a lirc device. > + > +.SH Optional Commands > +.P > +Some lirc devices support the following commands. s/following commands/commands listed below/ > +Unless otherwise stated these fails with the error \fIENOIOCTLCMD\fR s/stated/stated,/ s/fails/fail/ Formatting of ENOIOCTLCMD should be \fB, not \fI > +or with the error\fIENOSYS\fR if the operation s/error/error / \fI ==> \fB > +isn't supported, or with the error \fIEINVAL\fR if the operation failed. \fI ==> \fB > +.TP > +.BR LIRC_SET_REC_MODE " (\fIint\fP)" > +Set the receive mode, either Change ", either" to [[ ; .IR val is either ]] > +.BR LIRC_MODE_LIRCCODE > +or > +.BR LIRC_MODE_MODE2 . > + > +.TP > +.BR LIRC_GET_LENGTH " (\fIvoid\fP)" > +Return the positive length of the returned codes for s/positive // > +.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. > +Obsolete since only I think the word "Obsolete" isn't right here. Change to "Currently serves no purpose"? > +.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 .I int > +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)" Formatting problems here. Make these last two (wrapped) lines: +.BR LIRC_GET_MIN_TIMEOUT " (\fIvoid\fP), " LIRC_GET_MAX_TIMEOUT " (\fIvoid\fP)" The same kind of change is required at various points below where you put two constants on one line after .TP > +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 .BR lircd (8) s/a IR/an IR/ > +can speed up the decoding process. > +Returns an integer value with the minimum/maximum timeout that can be > +set. Note the unit that is used here for measuring the timeout. Microseconds? > +Some devices have a fixed timeout, in that case s/, in that case/. For such drivers,/ > +.BR LIRC_GET_MIN_TIMEOUT > +and > +.BR LIRC_GET_MAX_TIMEOUT > +will return the same value even though the timeout cannot be changed. s/ even though the timeout cannot be changed// > +.TP > +.BR LIRC_SET_REC_TIMEOUT " (\fIint\fP)" > +Sets the integer value for IR inactivity timeout. It seems to me that the unit of measurement for this timeout should be specified. Is it microseconds? Make it explicit. > +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/disables (1/0) timeout packages in Change that last line to [[ 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 > +.BR LIRC_SET_REC_CARRIER_RANGE " (\fIint\fP)" > +First time called sets the lower bound of the carrier range, second time > +the upper bound (Hz). Really? What an odd API! But this sentence could be clearer. "First time called"... since when? System boot? Open of the device? Make it explicit. Also, I'd word something like After [some explicit point in time], the first use of .BR LIRC_SET_REC_CARRIER_RANGE sets the lower bound of the carrier range, and the second use sets the upper bound (hz). > +the upper bound (Hz). > +.TP > +.BR LIRC_SET_MEASURE_CARRIER " (\fIint\fP)" > +Enable/disable (1/0) the measure mode. [[ 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 void, LIRC_GET_MAX_FILTER_PULSE void > +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 (8) > +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 s/$/ ./ > +.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 > +shall be used instead. s/shall/should/ (I think). > +.TP > +.BR LIRC_SET_WIDEBAND_RECEIVER " (\fIint\fP)" > +Some devices are equipped with special wide band receiver which are s/special/a special/ > +intended to be used to learn the output of an existing remote. > +Calling that ioctl with (1) will enable it, and with (0) disable it. Better for the last sentence would I think be: [[ 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. Insert a ".IP" line here > +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 lircd whenever a successful decoding of an .BR lircd (8) > +incoming IR signal is possible.. s/..$/./ > +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 > +Enables the given set of transmitters. I don't understand that last sentence. this bit mask is being used to return some information to us. How can it be enabling something. Should this be something like: "The bits covered by this mask return the set of currently enabled transmitters." ? > +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 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 s/$/ ./ (And various cases below) > +.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. > +.P > +This manual page should really be part of the upstream man-pages project. You can remove that last line. It will soon cease to be true ;-). > + > + > +.SH SEE ALSO > +.P > +https://www.kernel.org/doc/htmldocs/media_api/lirc_dev.html Thanks Michael -- 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
