On 13/12/15 19:34, J William Piggott wrote: > > > On 12/13/2015 03:23 AM, Michael Kerrisk (man-pages) wrote: >> Hello Alec, >> >> On 12 December 2015 at 07:34, Alec Leamas <leamas.alec@xxxxxxxxx> wrote: >>> On Fri, 11 Dec 2015 20:16:00 +0100 >>> "Michael Kerrisk (man-pages)" <mtk.manpages@xxxxxxxxx> wrote: >> >> [Excellent walk though of fixes snipped] And a not so excellent patch... somethinh wnt terribly wromg when I generated the patch - it seems like most of my changes wasn't included. Making a fresh retry, please ignore the last, broken patch. >> >>> 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... >>> +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. >>> .SH Reading using LIRC_MODE_MODE2 drivers > > s/using/input with the/ Fixed. >>> +.IR lirc_t. >> >> .IR lirc_t . Fixed. >>> -Value reflects a pulse duration (us). >>> +.BR LIRC_MODE2_PULSE >> >> s/$/ ./ >> (And at various other places below.) > s/below/above and below/ Fixed four occurences, unsure where to apply this. >> >>> +Value reflects a pulse duration (microseconds). >>> .TP 4 >>> -.B LIRC_MODE2_FREQUENCY >>> +.BR LIRC_MODE2_FREQUENCY >>> Value reflects a frequency (hz), see the LIRC_SET_MEASURE_CARRIER ioctl. >>> .TP 4 >>> -.B LIRC_MODE2_TIMEOUT >>> +.BR LIRC_MODE2_TIMEOUT >>> The package reflects a timeout, see the LIRC_SET_REC_TIMEOUT_REPORTS ioctl. >>> >>> .SH Reading using LIRC_MODE_LIRCCODE drivers. >> >> s/.$// >> > s/using/input with the/ Fixed > > s/read() on the device must be done/Device input must be read/ fixed >> s/the driver/the write() call/ >> >> Start new sentence on new line. Fixed >> >>> returns >> >> s/returns/fails with the error/ >> >>> -.B EINVAL >>> +.BR EINVAL >> >> .BR EINVAL . >> Fixed >>> Many require a third argument, usually an int. >> >> Put the"int" on a separate line as >> >> .IR int . Fixed > >>> @@ -88,111 +114,117 @@ the device can rely on working with the default settings initially. >>> .P >>> \fI/dev/lirc*\fR devices always supports the following commands: >>> .TP 4 >>> -.B LIRC_GET_FEATURES void >>> +.BR LIRC_GET_FEATURES void > > Why? (and others below) Don't know, I have read your remarks as 's/^\.B /\.BR /' When should it be .BR, and when .B ? >>> Driver returns integer values, each of which representing a decoded button >> >> s/representing/represents/ Fixed >>> +If a device returns an error code for > > s/ for/ for/ > Fixed >>> +.BR LIRC_GET_REC_MODE >> >> s/$/ ,/ >> >>> it is safe to assume it is not a lirc device. >>> >>> .BR >> >> Remove that last line. fixed >> >>> .SH Optional Commands >>> .Ped. >>> +Some lirc devices supports the following commands. >> >> s/supports/supports/ > > s/supports/support/ > Fixed >> >>> +Unless otherwise stated these returns \fIENOIOCTLCMD\fR >> >> s/returns/fail with the error/ >> >>> +or \fIENOSYS\fR if the operation >>> +isn't supported and \fIEINVAL\fR if operation failed. >> >> s/and/or with the error/ > > s/ and/, or with the error/ > >> s/operation/the operation/ Fixed (?) >>> .TP >>> -.B LIRC_GET_LENGTH " (\fIvoid\fP)" >>> +.BR LIRC_GET_LENGTH " (\fIvoid\fP)" >>> Return the positive length of the returned codes for > > s/ length/ length/ > >>> -.B LIRC_LIRCCODE >>> +.BR LIRC_LIRCCODE See above. When is using .BR right, and when .B? >>> type >>> drivers, otherwise >> >> s/$/ fail with the error/ Fixed >>> -.B LIRC_GET_MAX_TIMEOUT. >>> +.BR LIRC_GET_MAX_TIMEOUT. >> >> s/.$/ .$/ Fixed >>> Some receivers are equipped with special wide band receiver which is >>> intended to be used to learn output of existing remote. > > s/receivers/devices/ > s/receiver which is/receivers which are/ > s/output/the output/ > s/existing/an existing/ Fixed >>> Calling that ioctl with (1) will enable it, and with (0) disable it. >>> @@ -223,123 +255,136 @@ This might be useful of receivers that have otherwise narrow band receiver > > s/useful of receivers/useful for devices/ > s/have otherwise/otherwise have/ > s/receiver/receivers/ Fixed > >>> that prevents them to be used with some remotes. > > which prevent them from being used with certain remotes. > >>> Wide band receiver might also be more precise. > > s/receiver/receivers/ > s/might/may/ Fixed > >>> On the other hand its disadvantage usually is reduced range of reception. >>> -Note: wide band receiver might be implictly enabled if you enable >>> +Note: wide band receiver might 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 wide band receiver while carrier reports are active will >>> do nothing > > s/wide/a wide/ > s/$/.$/ Fixed. >>> >>> .TP >>> -.B LIRC_SETUP_START " (\fIvoid\fP)", LIRC_SETUP_END " (\fIvoid\fP)" >>> +.BR LIRC_SETUP_START " (\fIvoid\fP)", LIRC_SETUP_END " (\fIvoid\fP)" >>> Setting of several driver parameters can be optimized by encapsulating >>> the according ioctl calls with > > does 'according' make sense here? accompanying? Fixed (usinng 'actual') > >>> +for example by flashing a LED. > > s/a/an/ Fixed >>> +.BR LIRC_MODE_RAW >> >> s/$/ ./ >> (And other instances below) Fixed >>> +That this file is not public is a bug, see > > This file not being public is a bug, see Fixed On 13/12/15 19:34, J William Piggott wrote: > >> .SH Reading using LIRC_MODE_MODE2 drivers > s/using/input with the/ Fixed >> read() on the device must be done in blocks matching >> the bit count, rounded up so it matches full bytes. > s/read() on the device must be done/Device input must be read/ Fixed > Driver returns integer values, each of which representing a decoded button > s/representing/represents/ Fixed >> +If a device returns an error code for > s/ for/ for/ Fixed >> +Some lirc devices supports the following commands. >s/supports/support/ Fixed > Unless otherwise stated these returns \fIENOIOCTLCMD\fR> > s/returns/fail with the error/ Fixed >> Return the positive length of the returned codes for > s/ length/ length/ Fixed together with some other double spaces. >> Some receivers are equipped with special wide band receiver which is >> intended to be used to learn output of existing remote. > s/receivers/devices/ > s/receiver which is/receivers which are/ > s/output/the output/ > s/existing/an existing/ Fixed >> Calling that ioctl with (1) will enable it, and with (0) disable it. >> @@ -223,123 +255,136 @@ This might be useful of receivers that have otherwise narrow band receiver > s/useful of receivers/useful for devices/ > s/have otherwise/otherwise have/ > s/receiver/receivers/ Fixed >> that prevents them to be used with some remotes. > which prevent them from being used with certain remotes. Fixed >> Wide band receiver might also be more precise. > s/receiver/receivers/ > s/might/may/ Fixed >> Trying to disable wide band receiver while carrier reports are active will >> do nothing > s/wide/a wide/ > s/$/.$/ Fixed >> etting of several driver parameters can be optimized by encapsulating >> the according ioctl calls with > does 'according' make sense here? accompanying? Fixed, (usingf 'actual') >> -to give visual user feedback e.g., by flashing a LED. >> +incoming IR signal could be done. > s/could be done/is possible/ Fixed >> or example by flashing a LED. > s/a/an/ Fixed >> +That this file is not public is a bug, see > This file not being public is a bug, see Fixed New patch (hopefully in better shape...) >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. + +.SH Reading input with the LIRC_MODE_MODE2 drivers +.P +In the \fBLIRC_MODE_MODE2 mode\fR, the driver read() 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 LIRC_SET_MEASURE_CARRIER ioctl. +.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 +.P +In the \fBLIRC_MODE_LIRCCODE\fR +mode, the data returned by read() reflects decoded +button presses. +The length of each packet can be retrieved using +the \fBLIRC_GET_LENGTH\fR ioctl. +Device must be read in blocks matching +the bit count, rounded up so it matches full bytes. + +.SH Sending data. +.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 +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 +hardware. +If more data is provided than the hardware can send, the write() call +fails with the error +.BR EINVAL + +.SH SUPPORTED IOCTL COMMANDS +.P +.nf +#include " (\fIuapi/lirc.h\fP)" +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 . +.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: +.TP 4 +.BR LIRC_GET_FEATURES void +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 +Returns the receive mode, one of +.RS 4 +.TP +.BR LIRC_MODE_MODE2 +Driver return 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. + +.SH Optional Commands +.P +Some lirc devices support the following commands. +Unless otherwise stated these fails with the error \fIENOIOCTLCMD\fR +or with the error\fIENOSYS\fR if the operation +isn't supported, or with the error \fIEINVAL\fR if the operation failed. +.TP +.BR LIRC_SET_REC_MODE " (\fIint\fP)" +Set the receive mode, 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 +.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 +.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 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 +.BR LIRC_GET_MIN_TIMEOUT +and +.BR LIRC_GET_MAX_TIMEOUT +will return the same value even though the timeout cannot be changed. +.TP +.BR LIRC_SET_REC_TIMEOUT " (\fIint\fP)" +Sets the integer value for IR inactivity timeout. +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 +.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). +.TP +.BR LIRC_SET_MEASURE_CARRIER " (\fIint\fP)" +Enable/disable (1/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 +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 +shall be used instead. +.TP +.BR LIRC_SET_WIDEBAND_RECEIVER " (\fIint\fP)" +Some devices are equipped with special wide band receiver which are +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. +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. +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 +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 +Enables the given set of 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 +.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. + + +.SH SEE ALSO +.P +https://www.kernel.org/doc/htmldocs/media_api/lirc_dev.html -- 2.4.3 -- 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
