Subject: New manpage lirc.4 (Was: Possibly new manpages: lirc and lirc_ioctl) Date: Sun, 6 Dec 2015 22:37:41 +0100 From: Alec Leamas <leamas.alec@xxxxxxxxx> To: mtk.manpages@xxxxxxxxx CC: linux-man@xxxxxxxxxxxxxxxx On 06/12/15 21:01, Michael Kerrisk (man-pages) wrote: > Hi Alec, > > On 6 December 2015 at 10:19, Alec Leamas <leamas.alec@xxxxxxxxx> wrote: >> On 04/05/15 21:50, Alec Leamas wrote: >>> On 04/05/15 20:22, Michael Kerrisk (man-pages) wrote: >>>> On 05/04/2015 06:43 PM, Alec Leamas wrote: >>>>> >>>>> They are basically blocked on >>>>> https://bugzilla.kernel.org/show_bug.cgi?id=75751 >>>>> >>>>> No idea how to make this rolling, there's no feedback whatsoever. Ideas? >>>> >>>> I think the best approach might be to send the page source inline >>>> as a patch for man-pages. When doing so, please CC >>>> >>>> me >>>> linux-man@xxxxxxxxxxxxxxx >> >>> The problem is just that before that I need to have that patch accepted >>> - you can't use this interface without the information available in >>> public header files. That's what the bug is about, it's not the manpages >>> as such. But a pre-requisite. >>> >> >> Hi again! >> >> After too long time (mostly my bad, doing other things) it seems that >> the interface is becoming public since my patch is accepted [1] It's >> still not merged in the kernel tree, though. > > I'm confused. What does accepted mean here? TBH, I'm not completely sure...stay tuned. >> Enclosing current manpage, which is a merge of lirc and lirc_ioctl as >> you proposed. I have also made a fist round with updates according to >> your suggestions. Hopefully, it is reviewable. >> >> Now, what's the next step? > > You need a license for the page. See > https://www.kernel.org/doc/man-pages/licenses.html > > For the next round, please: > > CC linux-man@xxxxxxxxxxxxxxxx Done. Thanks for your review work! That said, I choose to exclude your remarks to trim the mailing list message. >From 97fbcb12b7c0871fad324e622f144c93d57b26ab Mon Sep 17 00:00:00 2001 From: Alec Leamas <leamas.alec@xxxxxxxxx> Date: Sun, 6 Dec 2015 22:30:50 +0100 Subject: [PATCH] Adding new lirc.4 page. --- man4/lirc.4 | 382 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 382 insertions(+) create mode 100644 man4/lirc.4 diff --git a/man4/lirc.4 b/man4/lirc.4 new file mode 100644 index 0000000..b4b84af --- /dev/null +++ b/man4/lirc.4 @@ -0,0 +1,382 @@ +.TH LIRC 4 "Aug 2015" "Linux" "Linux Programmer's Manual" +.\" Copyright (c) <year>, <copyright holder> +.\" +.\" %%%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 +.B 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 +.B 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 using 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 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 +.B LIRC_MODE2_SPACE +Value reflects a space duration (microseconds). +.TP 4 +.B LIRC_MODE2_PULSE +Value reflects a pulse duration (us). +.TP 4 +.B LIRC_MODE2_FREQUENCY +Value reflects a frequency (hz), see the LIRC_SET_MEASURE_CARRIER ioctl. +.TP 4 +.B LIRC_MODE2_TIMEOUT +The package reflects a timeout, see the LIRC_SET_REC_TIMEOUT_REPORTS ioctl. + +.SH Reading using 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. +read() on the device must be done 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 driver +returns +.B 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 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 +.B 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 +.B 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 +.B LIRC_MODE_LIRCCODE +Driver returns integer values, each of which representing a decoded button +press. +.RE +.P +If a device returns a negative error code for +.B LIRC_GET_REC_MODE +it is safe to assume it is not a lirc device. + +.BR +.SH Optional Commands +.P +Some lirc devices supports the following commands. Unless otherwise stated +these returns \fI-ENOIOCTLCMD\fR or \fI-ENOSYS\fR if the operation +isn't supported and \fI-EINVAL\fR if operation failed. +.TP +.B LIRC_SET_REC_MODE " (\fIint\fP)" +Set the receive mode, either +.B LIRC_MODE_LIRCCODE +or +.B LIRC_MODE_MODE2. + +.TP +.B LIRC_GET_LENGTH " (\fIvoid\fP)" +Return the positive length of the returned codes for +.B LIRC_LIRCCODE +type +drivers, otherwise +.B -ENOIOCTLCMD. +.TP +.B LIRC_GET_SEND_MODE " (\fIvoid\fP)" +Returns the send mode; currently only +.B LIRC_MODE_PULSE +is supported. +.TP +.B LIRC_SET_SEND_MODE " (\fIint\fP)" +Set the send mode. Obsolete since only +.B LIRC_MODE_PULSE +is supported. +.TP +.B LIRC_SET_SEND_CARRIER " (\fIint\fP)" +Set the modulation frequency. The argument is the frequency (Hz). +.TP +.B 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 +.B 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 both ioctls will +return the same value even though the timeout cannot be changed. +.TP +.B 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 +.B 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 +.B LIRC_SET_REC_TIMEOUT_REPORTS " (\fIint\fP)" +Enables/disables (1/0) timeout packages in +.B LIRC_MODE_MODE2. +By default, timeout reports should be turned off. +.TP +.B LIRC_SET_REC_CARRIER " (\fIint\fP)" +Set the receive carrier frequency (Hz). +.TP +.B 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 +.B 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 +.B LIRC_MODE2_FREQUENCY +packets. By default this should be turned off. +.TP +.B LIRC_GET_REC_RESOLUTION " (\fIvoid\fP)" +Returns the driver resolution (us). +.TP +.B 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 +.B LIRC_GET_MIN_FILTER_SPACE " (\fIvoid\fP)", LIRC_GET_MAX_FILTER_SPACE " (\fIvoid\fP)" +See +.B LIRC_GET_MIN_FILTER_PULSE +.TP +.B LIRC_SET_REC_FILTER " (\fIint\fP)" +Pulses/spaces shorter than this (us) are filtered out by hardware. +.TP +.B LIRC_SET_REC_FILTER_PULSE " (\fIint\fP)", LIRC_SET_REC_FILTER_SPACE " (\fIint\fP)" +Pulses/spaces shorter than this (us) are filtered out by hardware. If +filters cannot be set independently for pulse/space, the corresponding +ioctls must return an error and +.B LIRC_SET_REC_FILTER +shall be used instead. +.TP +.B LIRC_SET_WIDEBAND_RECEIVER " (\fIint\fP)" +Some receivers are equipped with special wide band receiver which is +intended to be used to learn output of existing remote. +Calling that ioctl with (1) will enable it, and with (0) disable it. +This might be useful of receivers that have otherwise narrow band receiver +that prevents them to be used with some remotes. +Wide band receiver might also be more precise. +On the other hand its disadvantage usually is reduced range of reception. +Note: wide band receiver might be implictly 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 + +.TP +.B 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 +.B LIRC_SETUP_START/LIRC_SETUP_END. +When a driver receives a +.B 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 +.B LIRC_SETUP_START +and +.B LIRC_SETUP_END. +Drivers can also choose to ignore these ioctls. + +.TP +.B LIRC_NOTIFY_DECODE " (\fIvoid\fP)" +This ioctl is called by lircd whenever a successful decoding of an +incoming IR signal could be done. This can be used by supporting hardware +to give visual user feedback, for example by flashing a LED. + +.SH FEATURES +.P +The features returned by +.B LIRC_GET_FEATURES +is a bitmask combining the following bits. +.TP 8 +.B LIRC_CAN_REC_RAW +The driver is capable of receiving using +.BR LIRC_MODE_RAW +.TP 8 +.B LIRC_CAN_REC_PULSE +The driver is capable of receiving using +.BR LIRC_MODE_PULSE +.TP 8 +.B LIRC_CAN_REC_MODE2 +The driver is capable of receiving using +.BR LIRC_MODE_MODE2 +.TP 8 +.B LIRC_CAN_REC_LIRCCODE +The driver is capable of receiving using +.BR LIRC_MODE_LIRCCODE +.TP 8 +.B LIRC_CAN_SET_SEND_CARRIER +Driver supports changing the modulation frequency using +.B LIRC_SET_SEND_CARRIER. +.TP 8 +.B LIRC_CAN_SET_SEND_DUTY_CYCLE +Driver supports changing the duty cycle using +.BR LIRC_SET_SEND_DUTY_CYCLE. +.TP 8 +.B 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 +transitters and does nothing otherwise. +.TP 8 +.B LIRC_CAN_SET_REC_CARRIER +Driver supports setting the receive carrier frequency using +.BR LIRC_SET_REC_CARRIER. +.TP 8 +.B LIRC_CAN_SET_REC_DUTY_CYCLE_RANGE +Driver supports +.BR LIRC_SET_REC_DUTY_CYCLE_RANGE +.TP 8 +.B LIRC_CAN_SET_REC_CARRIER_RANGE +Driver supports +.BR LIRC_SET_REC_CARRIER_RANGE +.TP 8 +.B LIRC_CAN_GET_REC_RESOLUTION +Driver supports +.BR LIRC_GET_REC_RESOLUTION +.TP 8 +.B LIRC_CAN_SET_REC_TIMEOUT +Driver supports +.BR LIRC_SET_REC_TIMEOUT +.TP 8 +.B LIRC_CAN_SET_REC_FILTER +Driver supports +.BR LIRC_SET_REC_FILTER +.TP 8 +.B LIRC_CAN_MEASURE_CARRIER +Driver supports measuring of the modulation frequency using +.B LIRC_MEASURE_CARRIER +.TP 8 +.B LIRC_CAN_USE_WIDEBAND_RECEIVER +Driver supports learning mode using +.B LIRC_SET_WIDEBAND_RECEIVER +.TP 8 +.B LIRC_CAN_NOTIFY_DECODE +Driver supports +.BR LIRC_NOTIFY_DECODE. +.TP 8 +.B LIRC_CAN_SEND_RAW +Driver supports sending using +.B LIRC_SEND_RAW +.TP 8 +.B LIRC_CAN_SEND_PULSE +Driver supports sending using +.B LIRC_MODE_PULSE +.TP 8 +.B LIRC_CAN_SEND_MODE2 +Driver supports sending using +.B LIRC_SEND_MODE2 +.TP 8 +.B LIRC_CAN_SEND_LIRCCODE +Driver supports sending +.B LIRC_SEND_LIRCCODE +(this is uncommon, since +.B 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. That this +file is not 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
