New manpage lirc.4 (Was: Possibly new manpages: lirc and lirc_ioctl)

New manpage lirc.4 (Was: Possibly new manpages: lirc and lirc_ioctl)

[Alec Leamas]

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-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
To: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org
CC: linux-man-4mT8j8lBKmdzeIdxy0IIJw@public.gmane.org

On 06/12/15 21:01, Michael Kerrisk (man-pages) wrote:
> Hi Alec,
> 
> On 6 December 2015 at 10:19, Alec Leamas <leamas.alec-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> 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-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
>>
>>> 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-4mT8j8lBKmdzeIdxy0IIJw@public.gmane.org

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-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
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-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: New manpage lirc.4 (Was: Possibly new manpages: lirc and lirc_ioctl)

[Alec Leamas]

On 06/12/15 22:41, Alec Leamas wrote:

Reviewing myself:

> Subject: New manpage lirc.4 (Was: Possibly new manpages: lirc and
> lirc_ioctl)

> +.\" Copyright (c) <year>, <copyright holder>

Oops... Should be  Copyright (c) 2015, Alec Leamas

"Blushes"

--alec

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: New manpage lirc.4 (Was: Possibly new manpages: lirc and lirc_ioctl)

[Alec Leamas]

On 06/12/15 22:41, Alec Leamas wrote:
>
> On 06/12/15 21:01, Michael Kerrisk (man-pages) wrote:
>> Hi Alec,
>>
>> On 6 December 2015 at 10:19, Alec Leamas <leamas.alec-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
>>> On 04/05/15 21:50, Alec Leamas wrote:

>>>
>>> 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?

That it's accepted into the media subsystem. It will enter the kernel in
the next merge window if I understand this correctly.


Cheers!

--alec

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: New manpage lirc.4 (Was: Possibly new manpages: lirc and lirc_ioctl)

[Alec Leamas]

On Fri, 11 Dec 2015 20:16:00 +0100
"Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:

> > +.TH LIRC 4 "Aug 2015" "Linux" "Linux Programmer's Manual"
> > +.\" Copyright (c) <year>, <copyright holder>
> 
> As you noted, this needs fixing.

Done
 
> Your mailer is wrapping text in your patches, Please fix.

Hm... claws-mail did the trick for the kernel patch, using that also 
for this which hopefully should fix it.

> > +.B LIRC_MODE_LIRCCODE.
> 
> .BR LIRC_MODE_LIRCCODE .

> Similarly, other cases below need fixing. 

Done (unless i missed something...)

> > +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.
> 
> .IR lirc_t .

Done

> > +Value reflects a pulse duration (us).
> 
> s/us/microseconds/
> (Many other instances in the page need fixing also)

Done.

> > +button presses. The length of each packet can be retrieved using
> 
> Please start new sentences on new source lines. (See man-pages(7).)

Done (again, unless I missed something).

> In all cases where you talk about a negative error code, change this
> to "returns an error". (By the time error numbers reach user space they
> are positive values in 'errno'.)

Oops... done.

> 
> > +.B LIRC_GET_REC_MODE
> 
> .BR LIRC_GET_REC_MODE ,

Done

> > +these  returns \fI-ENOIOCTLCMD\fR or \fI-ENOSYS\fR if the operation
> 
> fail with the error \fIENOIOCTLCMD\fR or \fIENOSYS\fR
> 
> > +isn't supported and \fI-EINVAL\fR if operation failed.
> 
> s/-EINVAL/EINQAL/
> 
> Likewise for various cases below.

Done

> reserved for future use == it is an error to specify 0 or 100?
> 
> If so, make that explicit. If it isn't an error, why not? If you
> want to reserve these value for future use, then the driver should
> error on them now.

Agreed, but I'm not the upstream for the driver. For now, specifying
that 0 < value < 100.

> > +Some devices have a fixed timeout, in that case both ioctls will
> 
> "both ioctls"? It's not clear which ioctls are being referred 
> to. List them explicitly.

Done

> > +Returns the driver resolution (us).
> 
> s/us/microseconds/

Done

> > +Note: wide band receiver might be implictly enabled if you enable
> 
> implicitly

Done


> > +is a bitmask combining the following bits.
> 
> s/\./:/

Done


> > +device does not have so many transmitters, returns the number of available
> > +transitters and does nothing otherwise.
> 
> transmitters

Done

Cheers!

--alec

Revised patch:

>From 68455824f90bc414f5091d9f8b1904e507ff036d Mon Sep 17 00:00:00 2001
From: Alec Leamas <leamas.alec-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
Date: Sun, 6 Dec 2015 22:20:07 +0100
Subject: [PATCH] doc: lirc.4 upstream review remarks fixes.

---
 doc/man-source/lirc.4 | 319 ++++++++++++++++++++++++++++----------------------
 1 file changed, 182 insertions(+), 137 deletions(-)

diff --git a/doc/man-source/lirc.4 b/doc/man-source/lirc.4
index 56d7f08..68685df 100644
--- a/doc/man-source/lirc.4
+++ b/doc/man-source/lirc.4
@@ -1,54 +1,80 @@
 .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 IR remotes.
-When receiving data the driver works in two different modes depending on the
-underlying hardware.
+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 works in
+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 e. g., a TV-card.
+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 works in
-.B LIRC_MODE_MODE2.
+Such drivers work in
+.BR LIRC_MODE_MODE2.
 Sometimes, this kind of hardware also supports
 sending IR data.
-It can be used with (almost) any kind of remote.
+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 (us) is encoded in the lower 24 bits.
+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
-.B LIRC_MODE2_SPACE
-Value reflects a space duration (us).
+.BR LIRC_MODE2_SPACE
+Value reflects a space duration (microseconds).
 .TP 4
-.B LIRC_MODE2_PULSE
-Value reflects a pulse duration (us).
+.BR LIRC_MODE2_PULSE
+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.
 .P
 In the \fBLIRC_MODE_LIRCCODE\fR
 mode, the data returned by read() reflects decoded
-button presses. The length of each packet could be retrieved using
+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.
@@ -57,15 +83,15 @@ the bit count, rounded up so it matches full bytes.
 .P
 When sending data, only the \fBLIRC_MODE_PULSE\fR
 mode is supported.
-The data written to the chardev using write() is a pulse/space sequence
-of integer values.
+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
+.BR EINVAL
 
 .SH SUPPORTED IOCTL COMMANDS
 .P
@@ -74,11 +100,11 @@ returns
 int ioctl(int fd, int cmd, ...);
 .fi
 .P
-The following ioctls can be used to to probe or change specific lirc
+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.
+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.
@@ -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
 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
+.BR LIRC_GET_REC_MODE void
 Returns the receive mode, one of
 .RS 4
 .TP
-.B LIRC_MODE_MODE2
+.BR LIRC_MODE_MODE2
 Driver return a sequence of pulse/space durations.
 .TP
-.B LIRC_MODE_LIRCCODE
+.BR 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
+If a device returns an error code  for
+.BR 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.
+Some lirc devices supports the following commands.
+Unless otherwise stated these returns \fIENOIOCTLCMD\fR
+or \fIENOSYS\fR if the operation
+isn't supported and \fIEINVAL\fR if operation failed.
 .TP
-.B LIRC_SET_REC_MODE  " (\fIint\fP)"
+.BR LIRC_SET_REC_MODE  " (\fIint\fP)"
 Set the receive mode, either
-.B LIRC_MODE_LIRCCODE
+.BR LIRC_MODE_LIRCCODE
 or
-.B LIRC_MODE_MODE2.
+.BR LIRC_MODE_MODE2.
 
 .TP
-.B LIRC_GET_LENGTH " (\fIvoid\fP)"
+.BR LIRC_GET_LENGTH " (\fIvoid\fP)"
 Return the positive  length of the returned codes for
-.B LIRC_LIRCCODE
+.BR LIRC_LIRCCODE
 type
 drivers, otherwise
-.B -ENOIOCTLCMD.
+.BR ENOIOCTLCMD.
 .TP
-.B  LIRC_GET_SEND_MODE " (\fIvoid\fP)"
+.BR  LIRC_GET_SEND_MODE " (\fIvoid\fP)"
 Returns the send mode; currently only
-.B LIRC_MODE_PULSE
+.BR LIRC_MODE_PULSE
 is supported.
 .TP
-.B LIRC_SET_SEND_MODE " (\fIint\fP)"
-Set the send mode.  Obsolete since only
-.B LIRC_MODE_PULSE
+.BR LIRC_SET_SEND_MODE " (\fIint\fP)"
+Set the send mode.
+Obsolete since only
+.BR LIRC_MODE_PULSE
 is supported.
 .TP
-.B LIRC_SET_SEND_CARRIER " (\fIint\fP)"
+.BR 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.
+.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
-.B LIRC_GET_MIN_TIMEOUT " (\fIvoid\fP)",  LIRC_GET_MAX_TIMEOUT " (\fIvoid\fP)"
+.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 both ioctls will
-return the same value even though the timeout cannot be changed.
+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
-.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
+.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
-.B LIRC_GET_MAX_TIMEOUT.
+.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)"
+.BR LIRC_SET_REC_TIMEOUT_REPORTS " (\fIint\fP)"
 Enables/disables (1/0) timeout packages in
-.B LIRC_MODE_MODE2.
+.BR LIRC_MODE_MODE2.
 By default, timeout reports should be turned off.
 .TP
-.B LIRC_SET_REC_CARRIER " (\fIint\fP)"
+.BR LIRC_SET_REC_CARRIER " (\fIint\fP)"
 Set the receive carrier frequency (Hz).
 .TP
-.B LIRC_SET_REC_CARRIER_RANGE " (\fIint\fP)"
+.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
-.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
+.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
-.B LIRC_GET_REC_RESOLUTION " (\fIvoid\fP)"
-Returns the driver resolution (us).
+.BR LIRC_GET_REC_RESOLUTION " (\fIvoid\fP)"
+Returns the driver resolution (microseconds).
 .TP
-.B LIRC_GET_MIN_FILTER_PULSE void, LIRC_GET_MAX_FILTER_PULSE void
+.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
@@ -201,21 +233,21 @@ 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)"
+.BR LIRC_GET_MIN_FILTER_SPACE " (\fIvoid\fP)", LIRC_GET_MAX_FILTER_SPACE " (\fIvoid\fP)"
 See
-.B LIRC_GET_MIN_FILTER_PULSE
+.BR LIRC_GET_MIN_FILTER_PULSE
 .TP
-.B LIRC_SET_REC_FILTER " (\fIint\fP)"
-Pulses/spaces shorter than this (us) are filtered out by hardware.
+.BR LIRC_SET_REC_FILTER " (\fIint\fP)"
+Pulses/spaces shorter than this (microseconds) 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
+.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
-.B LIRC_SET_REC_FILTER
+.BR LIRC_SET_REC_FILTER
 shall be used instead.
 .TP
-.B LIRC_SET_WIDEBAND_RECEIVER " (\fIint\fP)"
+.BR 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.
@@ -223,123 +255,136 @@ 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
+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
 
 .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
-.B LIRC_SETUP_START/LIRC_SETUP_END.
+.BR LIRC_SETUP_START/LIRC_SETUP_END.
 When a driver receives a
-.B LIRC_SETUP_START
+.BR LIRC_SETUP_START
 ioctl it can choose to not commit further setting changes to the hardware
 until a
-.B LIRC_SETUP_END
+.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
+.BR LIRC_SETUP_START
 and
-.B LIRC_SETUP_END.
+.BR LIRC_SETUP_END.
 Drivers can also choose to ignore these ioctls.
 
 .TP
-.B LIRC_NOTIFY_DECODE " (\fIvoid\fP)"
+.BR 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 e.g.,  by flashing a LED.
+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.
+.BR LIRC_GET_FEATURES
+is a bitmask combining the following bits:
 .TP 8
-.B LIRC_CAN_REC_RAW
-The driver is capable of receiving using LIRC_MODE_RAW
+.BR 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 LIRC_MODE_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 LIRC_MODE_MODE2
+.BR 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 LIRC_MODE_LIRCCODE
+The driver is capable of receiving using
+.BR LIRC_MODE_LIRCCODE
 .TP 8
-.B LIRC_CAN_SET_SEND_CARRIER
+.BR LIRC_CAN_SET_SEND_CARRIER
 Driver supports  changing the modulation frequency using
-.B LIRC_SET_SEND_CARRIER.
+.BR LIRC_SET_SEND_CARRIER.
 .TP 8
-.B LIRC_CAN_SET_SEND_DUTY_CYCLE
-Driver supports changing the duty cycle using LIRC_SET_SEND_DUTY_CYCLE.
+.BR 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
+.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 e. g.,  a bit is set even though the
+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.
+transmitters and does nothing otherwise.
 .TP 8
-.B LIRC_CAN_SET_REC_CARRIER
-Drvier supports setting the receive carrier frequency using
-.B LIRC_SET_REC_CARRIER.
+.BR 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 LIRC_SET_REC_DUTY_CYCLE_RANGE
+.BR 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 LIRC_SET_REC_CARRIER_RANGE
+.BR LIRC_CAN_SET_REC_CARRIER_RANGE
+Driver supports
+.BR LIRC_SET_REC_CARRIER_RANGE
 .TP 8
-.B LIRC_CAN_GET_REC_RESOLUTION
-Driver supports LIRC_GET_REC_RESOLUTION
+.BR LIRC_CAN_GET_REC_RESOLUTION
+Driver supports
+.BR LIRC_GET_REC_RESOLUTION
 .TP 8
-.B LIRC_CAN_SET_REC_TIMEOUT
-Driver supports LIRC_SET_REC_TIMEOUT
+.BR LIRC_CAN_SET_REC_TIMEOUT
+Driver supports
+.BR LIRC_SET_REC_TIMEOUT
 .TP 8
-.B LIRC_CAN_SET_REC_FILTER
-Driver supports LIRC_SET_REC_FILTER
+.BR LIRC_CAN_SET_REC_FILTER
+Driver supports
+.BR LIRC_SET_REC_FILTER
 .TP 8
-.B LIRC_CAN_MEASURE_CARRIER
+.BR LIRC_CAN_MEASURE_CARRIER
 Driver supports measuring of the modulation frequency using
-.B LIRC_MEASURE_CARRIER
+.BR LIRC_MEASURE_CARRIER
 .TP 8
-.B LIRC_CAN_USE_WIDEBAND_RECEIVER
+.BR LIRC_CAN_USE_WIDEBAND_RECEIVER
 Driver supports learning mode using
-.B LIRC_SET_WIDEBAND_RECEIVER
+.BR LIRC_SET_WIDEBAND_RECEIVER
 .TP 8
-.B LIRC_CAN_NOTIFY_DECODE
-Driver supports LIRC_NOTIFY_DECODE.
+.BR LIRC_CAN_NOTIFY_DECODE
+Driver supports
+.BR LIRC_NOTIFY_DECODE.
 .TP 8
-.B LIRC_CAN_SEND_RAW
+.BR LIRC_CAN_SEND_RAW
 Driver supports sending using
-.B LIRC_SEND_RAW
+.BR LIRC_SEND_RAW
 .TP 8
-.B LIRC_CAN_SEND_PULSE
+.BR LIRC_CAN_SEND_PULSE
 Driver supports sending using
-.B LIRC_MODE_PULSE
+.BR LIRC_MODE_PULSE
 .TP 8
-.B LIRC_CAN_SEND_MODE2
+.BR LIRC_CAN_SEND_MODE2
 Driver supports sending using
-.B LIRC_SEND_MODE2
+.BR LIRC_SEND_MODE2
 .TP 8
-.B LIRC_CAN_SEND_LIRCCODE
+.BR LIRC_CAN_SEND_LIRCCODE
 Driver supports sending
-.B LIRC_SEND_LIRCCODE
+.BR LIRC_SEND_LIRCCODE
 (this is uncommon, since
-.B LIRCCODE
-drivers reflects hardware like TV-cards which usually does not support
+.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. 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.
+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.
 
-- 
2.4.3


--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: New manpage lirc.4 (Was: Possibly new manpages: lirc and lirc_ioctl)

[Michael Kerrisk (man-pages)]

Hello Alec,

On 12 December 2015 at 07:34, Alec Leamas <leamas.alec-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> On Fri, 11 Dec 2015 20:16:00 +0100
> "Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:

[Excellent walk though of fixes snipped]

> Revised patch:

Patches on top of patches is confusing. For the next round, just send
a fresh complete patch. A few more comments below.

> From 68455824f90bc414f5091d9f8b1904e507ff036d Mon Sep 17 00:00:00 2001
> From: Alec Leamas <leamas.alec-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
> Date: Sun, 6 Dec 2015 22:20:07 +0100
> Subject: [PATCH] doc: lirc.4 upstream review remarks fixes.
>
> ---
>  doc/man-source/lirc.4 | 319 ++++++++++++++++++++++++++++----------------------
>  1 file changed, 182 insertions(+), 137 deletions(-)
>
> diff --git a/doc/man-source/lirc.4 b/doc/man-source/lirc.4
> index 56d7f08..68685df 100644
> --- a/doc/man-source/lirc.4
> +++ b/doc/man-source/lirc.4
> @@ -1,54 +1,80 @@
>  .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 IR remotes.
> -When receiving data the driver works in two different modes depending on the
> -underlying hardware.
> +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 works in
> +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.

.BR LIRC_MODE_LIRCCODE .

(There are several other instances to fix also.

>  Such hardware usually does not support sending IR signals.
> -Furthermore, it usually only works with a specific remote which is bundled
> -with e. g., a TV-card.
> +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 works in
> -.B LIRC_MODE_MODE2.
> +Such drivers work in
> +.BR LIRC_MODE_MODE2.

.BR LIRC_MODE_MODE2 .

(i.e., add space before '.') Probably there are other instances to fix as well.

>  Sometimes, this kind of hardware also supports
>  sending IR data.
> -It can be used with (almost) any kind of remote.
> +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 (us) is encoded in the lower 24 bits.
> +representing a space or a pulse duration, by convention typed as
> +.IR lirc_t.

.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
> -.B LIRC_MODE2_SPACE
> -Value reflects a space duration (us).
> +.BR LIRC_MODE2_SPACE
> +Value reflects a space duration (microseconds).
>  .TP 4
> -.B LIRC_MODE2_PULSE
> -Value reflects a pulse duration (us).
> +.BR LIRC_MODE2_PULSE

s/$/ ./
(And at various other places below.)

> +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/.$//

>  .P
>  In the \fBLIRC_MODE_LIRCCODE\fR
>  mode, the data returned by read() reflects decoded
> -button presses. The length of each packet could be retrieved using
> +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.
> @@ -57,15 +83,15 @@ the bit count, rounded up so it matches full bytes.
>  .P
>  When sending data, only the \fBLIRC_MODE_PULSE\fR
>  mode is supported.
> -The data written to the chardev using write() is a pulse/space sequence
> -of integer values.
> +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

s/the driver/the write() call/

Start new sentence on new line.

>  returns

s/returns/fails with the error/

> -.B EINVAL
> +.BR EINVAL

.BR EINVAL .

>
>  .SH SUPPORTED IOCTL COMMANDS
>  .P
> @@ -74,11 +100,11 @@ returns
>  int ioctl(int fd, int cmd, ...);
>  .fi
>  .P
> -The following ioctls can be used to to probe or change specific lirc
> +The following ioctls can be used to probe or change specific lirc
>  hardware settings.
>  Many require a third argument, usually an int.

Put the"int" on a separate line as

.IR int .

>  .P
> -In general each driver should have a default set of 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 userspace, so that every application opening
>  the device can rely on working with the default settings initially.
> @@ -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
>  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
> +.BR LIRC_GET_REC_MODE void
>  Returns the receive mode, one of
>  .RS 4
>  .TP
> -.B LIRC_MODE_MODE2
> +.BR LIRC_MODE_MODE2
>  Driver return a sequence of pulse/space durations.
>  .TP
> -.B LIRC_MODE_LIRCCODE
> +.BR LIRC_MODE_LIRCCODE
>  Driver returns integer values, each of which representing a decoded button

s/representing/represents/

>  press.
>  .RE
>  .P
> -If a device returns a negative error code  for
> -.B LIRC_GET_REC_MODE
> +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.
>
>  .BR

Remove that last line.

>  .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.
> +Some lirc devices supports the following commands.

s/supports/supports/

> +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/operation/the operation/

>  .TP
> -.B LIRC_SET_REC_MODE  " (\fIint\fP)"
> +.BR LIRC_SET_REC_MODE  " (\fIint\fP)"
>  Set the receive mode, either
> -.B LIRC_MODE_LIRCCODE
> +.BR LIRC_MODE_LIRCCODE
>  or
> -.B LIRC_MODE_MODE2.
> +.BR LIRC_MODE_MODE2.

.BR LIRC_MODE_MODE2 .
(Fix other instances too please.)

>
>  .TP
> -.B LIRC_GET_LENGTH " (\fIvoid\fP)"
> +.BR LIRC_GET_LENGTH " (\fIvoid\fP)"
>  Return the positive  length of the returned codes for
> -.B LIRC_LIRCCODE
> +.BR LIRC_LIRCCODE
>  type
>  drivers, otherwise

s/$/ fail with the error/

> -.B -ENOIOCTLCMD.
> +.BR ENOIOCTLCMD.
>  .TP
> -.B  LIRC_GET_SEND_MODE " (\fIvoid\fP)"
> +.BR  LIRC_GET_SEND_MODE " (\fIvoid\fP)"
>  Returns the send mode; currently only
> -.B LIRC_MODE_PULSE
> +.BR LIRC_MODE_PULSE
>  is supported.
>  .TP
> -.B LIRC_SET_SEND_MODE " (\fIint\fP)"
> -Set the send mode.  Obsolete since only
> -.B LIRC_MODE_PULSE
> +.BR LIRC_SET_SEND_MODE " (\fIint\fP)"
> +Set the send mode.
> +Obsolete since only
> +.BR LIRC_MODE_PULSE
>  is supported.
>  .TP
> -.B LIRC_SET_SEND_CARRIER " (\fIint\fP)"
> +.BR 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.
> +.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
> -.B LIRC_GET_MIN_TIMEOUT " (\fIvoid\fP)",  LIRC_GET_MAX_TIMEOUT " (\fIvoid\fP)"
> +.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 both ioctls will
> -return the same value even though the timeout cannot be changed.
> +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
> -.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
> +.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
> -.B LIRC_GET_MAX_TIMEOUT.
> +.BR LIRC_GET_MAX_TIMEOUT.

s/.$/ .$/

>  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)"
> +.BR LIRC_SET_REC_TIMEOUT_REPORTS " (\fIint\fP)"
>  Enables/disables (1/0) timeout packages in
> -.B LIRC_MODE_MODE2.
> +.BR LIRC_MODE_MODE2.
>  By default, timeout reports should be turned off.
>  .TP
> -.B LIRC_SET_REC_CARRIER " (\fIint\fP)"
> +.BR LIRC_SET_REC_CARRIER " (\fIint\fP)"
>  Set the receive carrier frequency (Hz).
>  .TP
> -.B LIRC_SET_REC_CARRIER_RANGE " (\fIint\fP)"
> +.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
> -.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
> +.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
> -.B LIRC_GET_REC_RESOLUTION " (\fIvoid\fP)"
> -Returns the driver resolution (us).
> +.BR LIRC_GET_REC_RESOLUTION " (\fIvoid\fP)"
> +Returns the driver resolution (microseconds).
>  .TP
> -.B LIRC_GET_MIN_FILTER_PULSE void, LIRC_GET_MAX_FILTER_PULSE void
> +.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
> @@ -201,21 +233,21 @@ 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)"
> +.BR LIRC_GET_MIN_FILTER_SPACE " (\fIvoid\fP)", LIRC_GET_MAX_FILTER_SPACE " (\fIvoid\fP)"
>  See
> -.B LIRC_GET_MIN_FILTER_PULSE
> +.BR LIRC_GET_MIN_FILTER_PULSE
>  .TP
> -.B LIRC_SET_REC_FILTER " (\fIint\fP)"
> -Pulses/spaces shorter than this (us) are filtered out by hardware.
> +.BR LIRC_SET_REC_FILTER " (\fIint\fP)"
> +Pulses/spaces shorter than this (microseconds) 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
> +.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
> -.B LIRC_SET_REC_FILTER
> +.BR LIRC_SET_REC_FILTER
>  shall be used instead.
>  .TP
> -.B LIRC_SET_WIDEBAND_RECEIVER " (\fIint\fP)"
> +.BR 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.
> @@ -223,123 +255,136 @@ 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
> +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
>
>  .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
> -.B LIRC_SETUP_START/LIRC_SETUP_END.
> +.BR LIRC_SETUP_START/LIRC_SETUP_END.
>  When a driver receives a
> -.B LIRC_SETUP_START
> +.BR LIRC_SETUP_START
>  ioctl it can choose to not commit further setting changes to the hardware
>  until a
> -.B LIRC_SETUP_END
> +.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
> +.BR LIRC_SETUP_START
>  and
> -.B LIRC_SETUP_END.
> +.BR LIRC_SETUP_END.
>  Drivers can also choose to ignore these ioctls.
>
>  .TP
> -.B LIRC_NOTIFY_DECODE " (\fIvoid\fP)"
> +.BR 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 e.g.,  by flashing a LED.
> +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.
> +.BR LIRC_GET_FEATURES
> +is a bitmask combining the following bits:
>  .TP 8
> -.B LIRC_CAN_REC_RAW
> -The driver is capable of receiving using LIRC_MODE_RAW
> +.BR LIRC_CAN_REC_RAW
> +The driver is capable of receiving using
> +.BR LIRC_MODE_RAW

s/$/ ./
(And other instances below)

>  .TP 8
>  .B LIRC_CAN_REC_PULSE
> -The driver is capable of receiving using LIRC_MODE_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 LIRC_MODE_MODE2
> +.BR 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 LIRC_MODE_LIRCCODE
> +The driver is capable of receiving using
> +.BR LIRC_MODE_LIRCCODE
>  .TP 8
> -.B LIRC_CAN_SET_SEND_CARRIER
> +.BR LIRC_CAN_SET_SEND_CARRIER
>  Driver supports  changing the modulation frequency using
> -.B LIRC_SET_SEND_CARRIER.
> +.BR LIRC_SET_SEND_CARRIER.
>  .TP 8
> -.B LIRC_CAN_SET_SEND_DUTY_CYCLE
> -Driver supports changing the duty cycle using LIRC_SET_SEND_DUTY_CYCLE.
> +.BR 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
> +.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 e. g.,  a bit is set even though the
> +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.
> +transmitters and does nothing otherwise.
>  .TP 8
> -.B LIRC_CAN_SET_REC_CARRIER
> -Drvier supports setting the receive carrier frequency using
> -.B LIRC_SET_REC_CARRIER.
> +.BR 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 LIRC_SET_REC_DUTY_CYCLE_RANGE
> +.BR 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 LIRC_SET_REC_CARRIER_RANGE
> +.BR LIRC_CAN_SET_REC_CARRIER_RANGE
> +Driver supports
> +.BR LIRC_SET_REC_CARRIER_RANGE
>  .TP 8
> -.B LIRC_CAN_GET_REC_RESOLUTION
> -Driver supports LIRC_GET_REC_RESOLUTION
> +.BR LIRC_CAN_GET_REC_RESOLUTION
> +Driver supports
> +.BR LIRC_GET_REC_RESOLUTION
>  .TP 8
> -.B LIRC_CAN_SET_REC_TIMEOUT
> -Driver supports LIRC_SET_REC_TIMEOUT
> +.BR LIRC_CAN_SET_REC_TIMEOUT
> +Driver supports
> +.BR LIRC_SET_REC_TIMEOUT
>  .TP 8
> -.B LIRC_CAN_SET_REC_FILTER
> -Driver supports LIRC_SET_REC_FILTER
> +.BR LIRC_CAN_SET_REC_FILTER
> +Driver supports
> +.BR LIRC_SET_REC_FILTER
>  .TP 8
> -.B LIRC_CAN_MEASURE_CARRIER
> +.BR LIRC_CAN_MEASURE_CARRIER
>  Driver supports measuring of the modulation frequency using
> -.B LIRC_MEASURE_CARRIER
> +.BR LIRC_MEASURE_CARRIER
>  .TP 8
> -.B LIRC_CAN_USE_WIDEBAND_RECEIVER
> +.BR LIRC_CAN_USE_WIDEBAND_RECEIVER
>  Driver supports learning mode using
> -.B LIRC_SET_WIDEBAND_RECEIVER
> +.BR LIRC_SET_WIDEBAND_RECEIVER
>  .TP 8
> -.B LIRC_CAN_NOTIFY_DECODE
> -Driver supports LIRC_NOTIFY_DECODE.
> +.BR LIRC_CAN_NOTIFY_DECODE
> +Driver supports
> +.BR LIRC_NOTIFY_DECODE.
>  .TP 8
> -.B LIRC_CAN_SEND_RAW
> +.BR LIRC_CAN_SEND_RAW
>  Driver supports sending using
> -.B LIRC_SEND_RAW
> +.BR LIRC_SEND_RAW
>  .TP 8
> -.B LIRC_CAN_SEND_PULSE
> +.BR LIRC_CAN_SEND_PULSE
>  Driver supports sending using
> -.B LIRC_MODE_PULSE
> +.BR LIRC_MODE_PULSE
>  .TP 8
> -.B LIRC_CAN_SEND_MODE2
> +.BR LIRC_CAN_SEND_MODE2
>  Driver supports sending using
> -.B LIRC_SEND_MODE2
> +.BR LIRC_SEND_MODE2
>  .TP 8
> -.B LIRC_CAN_SEND_LIRCCODE
> +.BR LIRC_CAN_SEND_LIRCCODE
>  Driver supports sending
> -.B LIRC_SEND_LIRCCODE
> +.BR LIRC_SEND_LIRCCODE
>  (this is uncommon, since
> -.B LIRCCODE
> -drivers reflects hardware like TV-cards which usually does not support
> +.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. 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.
> +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.

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-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: New manpage lirc.4 (Was: Possibly new manpages: lirc and lirc_ioctl)

[J William Piggott]

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-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
>> On Fri, 11 Dec 2015 20:16:00 +0100
>> "Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> 
> [Excellent walk though of fixes snipped]
> 
>> Revised patch:
> 
> Patches on top of patches is confusing. For the next round, just send
> a fresh complete patch. A few more comments below.
> 
>> From 68455824f90bc414f5091d9f8b1904e507ff036d Mon Sep 17 00:00:00 2001
>> From: Alec Leamas <leamas.alec-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
>> Date: Sun, 6 Dec 2015 22:20:07 +0100
>> Subject: [PATCH] doc: lirc.4 upstream review remarks fixes.
>>
>> ---
>>  doc/man-source/lirc.4 | 319 ++++++++++++++++++++++++++++----------------------
>>  1 file changed, 182 insertions(+), 137 deletions(-)
>>
>> diff --git a/doc/man-source/lirc.4 b/doc/man-source/lirc.4
>> index 56d7f08..68685df 100644
>> --- a/doc/man-source/lirc.4
>> +++ b/doc/man-source/lirc.4
>> @@ -1,54 +1,80 @@
>>  .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 IR remotes.
>> -When receiving data the driver works in two different modes depending on the
>> -underlying hardware.
>> +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 works in
>> +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.
> 
> .BR LIRC_MODE_LIRCCODE .
> 
> (There are several other instances to fix also.
> 
>>  Such hardware usually does not support sending IR signals.
>> -Furthermore, it usually only works with a specific remote which is bundled
>> -with e. g., a TV-card.
>> +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 works in
>> -.B LIRC_MODE_MODE2.
>> +Such drivers work in
>> +.BR LIRC_MODE_MODE2.
> 
> .BR LIRC_MODE_MODE2 .
> 
> (i.e., add space before '.') Probably there are other instances to fix as well.
> 
>>  Sometimes, this kind of hardware also supports
>>  sending IR data.
>> -It can be used with (almost) any kind of remote.
>> +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

s/using/input with the/

>>  .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 (us) is encoded in the lower 24 bits.
>> +representing a space or a pulse duration, by convention typed as
>> +.IR lirc_t.
> 
> .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
>> -.B LIRC_MODE2_SPACE
>> -Value reflects a space duration (us).
>> +.BR LIRC_MODE2_SPACE
>> +Value reflects a space duration (microseconds).
>>  .TP 4
>> -.B LIRC_MODE2_PULSE
>> -Value reflects a pulse duration (us).
>> +.BR LIRC_MODE2_PULSE
> 
> s/$/ ./
> (And at various other places below.)
   s/below/above and below/
> 
>> +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/

>>  .P
>>  In the \fBLIRC_MODE_LIRCCODE\fR
>>  mode, the data returned by read() reflects decoded
>> -button presses. The length of each packet could be retrieved using
>> +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.

s/read() on the device must be done/Device input must be read/

>> @@ -57,15 +83,15 @@ the bit count, rounded up so it matches full bytes.
>>  .P
>>  When sending data, only the \fBLIRC_MODE_PULSE\fR
>>  mode is supported.
>> -The data written to the chardev using write() is a pulse/space sequence
>> -of integer values.
>> +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
> 
> s/the driver/the write() call/
> 
> Start new sentence on new line.
> 
>>  returns
> 
> s/returns/fails with the error/
> 
>> -.B EINVAL
>> +.BR EINVAL
> 
> .BR EINVAL .
> 
>>
>>  .SH SUPPORTED IOCTL COMMANDS
>>  .P
>> @@ -74,11 +100,11 @@ returns
>>  int ioctl(int fd, int cmd, ...);
>>  .fi
>>  .P
>> -The following ioctls can be used to to probe or change specific lirc
>> +The following ioctls can be used to probe or change specific lirc
>>  hardware settings.
>>  Many require a third argument, usually an int.
> 
> Put the"int" on a separate line as
> 
> .IR int .
> 
>>  .P
>> -In general each driver should have a default set of 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 userspace, so that every application opening
>>  the device can rely on working with the default settings initially.

Typically, the driver implementation is expected to have default
settings, and to re-apply them when the device is closed by userspace.
This allows future applications to open the device in a known state.

>> @@ -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)

>>  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
>> +.BR LIRC_GET_REC_MODE void
>>  Returns the receive mode, one of
>>  .RS 4
>>  .TP
>> -.B LIRC_MODE_MODE2
>> +.BR LIRC_MODE_MODE2
>>  Driver return a sequence of pulse/space durations.
>>  .TP
>> -.B LIRC_MODE_LIRCCODE
>> +.BR LIRC_MODE_LIRCCODE
>>  Driver returns integer values, each of which representing a decoded button
> 
> s/representing/represents/
> 
>>  press.
>>  .RE
>>  .P
>> -If a device returns a negative error code  for
>> -.B LIRC_GET_REC_MODE
>> +If a device returns an error code  for

s/  for/ for/

>> +.BR LIRC_GET_REC_MODE
> 
> s/$/ ,/
> 
>>  it is safe to assume it is not a lirc device.
>>
>>  .BR
> 
> Remove that last line.
> 
>>  .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.
>> +Some lirc devices supports the following commands.
> 
> s/supports/supports/

s/supports/support/

> 
>> +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/
> 
>>  .TP
>> -.B LIRC_SET_REC_MODE  " (\fIint\fP)"
>> +.BR LIRC_SET_REC_MODE  " (\fIint\fP)"
>>  Set the receive mode, either
>> -.B LIRC_MODE_LIRCCODE
>> +.BR LIRC_MODE_LIRCCODE
>>  or
>> -.B LIRC_MODE_MODE2.
>> +.BR LIRC_MODE_MODE2.
> 
> .BR LIRC_MODE_MODE2 .
> (Fix other instances too please.)
> 
>>
>>  .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
>>  type
>>  drivers, otherwise
> 
> s/$/ fail with the error/
> 
>> -.B -ENOIOCTLCMD.
>> +.BR ENOIOCTLCMD.
>>  .TP
>> -.B  LIRC_GET_SEND_MODE " (\fIvoid\fP)"
>> +.BR  LIRC_GET_SEND_MODE " (\fIvoid\fP)"
>>  Returns the send mode; currently only
>> -.B LIRC_MODE_PULSE
>> +.BR LIRC_MODE_PULSE
>>  is supported.
>>  .TP
>> -.B LIRC_SET_SEND_MODE " (\fIint\fP)"
>> -Set the send mode.  Obsolete since only
>> -.B LIRC_MODE_PULSE
>> +.BR LIRC_SET_SEND_MODE " (\fIint\fP)"
>> +Set the send mode.
>> +Obsolete since only
>> +.BR LIRC_MODE_PULSE
>>  is supported.
>>  .TP
>> -.B LIRC_SET_SEND_CARRIER " (\fIint\fP)"
>> +.BR 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.
>> +.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
>> -.B LIRC_GET_MIN_TIMEOUT " (\fIvoid\fP)",  LIRC_GET_MAX_TIMEOUT " (\fIvoid\fP)"
>> +.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 both ioctls will
>> -return the same value even though the timeout cannot be changed.
>> +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
>> -.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
>> +.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
>> -.B LIRC_GET_MAX_TIMEOUT.
>> +.BR LIRC_GET_MAX_TIMEOUT.
> 
> s/.$/ .$/
> 
>>  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)"
>> +.BR LIRC_SET_REC_TIMEOUT_REPORTS " (\fIint\fP)"
>>  Enables/disables (1/0) timeout packages in
>> -.B LIRC_MODE_MODE2.
>> +.BR LIRC_MODE_MODE2.
>>  By default, timeout reports should be turned off.
>>  .TP
>> -.B LIRC_SET_REC_CARRIER " (\fIint\fP)"
>> +.BR LIRC_SET_REC_CARRIER " (\fIint\fP)"
>>  Set the receive carrier frequency (Hz).
>>  .TP
>> -.B LIRC_SET_REC_CARRIER_RANGE " (\fIint\fP)"
>> +.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
>> -.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
>> +.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
>> -.B LIRC_GET_REC_RESOLUTION " (\fIvoid\fP)"
>> -Returns the driver resolution (us).
>> +.BR LIRC_GET_REC_RESOLUTION " (\fIvoid\fP)"
>> +Returns the driver resolution (microseconds).
>>  .TP
>> -.B LIRC_GET_MIN_FILTER_PULSE void, LIRC_GET_MAX_FILTER_PULSE void
>> +.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
>> @@ -201,21 +233,21 @@ 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)"
>> +.BR LIRC_GET_MIN_FILTER_SPACE " (\fIvoid\fP)", LIRC_GET_MAX_FILTER_SPACE " (\fIvoid\fP)"
>>  See
>> -.B LIRC_GET_MIN_FILTER_PULSE
>> +.BR LIRC_GET_MIN_FILTER_PULSE
>>  .TP
>> -.B LIRC_SET_REC_FILTER " (\fIint\fP)"
>> -Pulses/spaces shorter than this (us) are filtered out by hardware.
>> +.BR LIRC_SET_REC_FILTER " (\fIint\fP)"
>> +Pulses/spaces shorter than this (microseconds) 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
>> +.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
>> -.B LIRC_SET_REC_FILTER
>> +.BR LIRC_SET_REC_FILTER
>>  shall be used instead.
>>  .TP
>> -.B LIRC_SET_WIDEBAND_RECEIVER " (\fIint\fP)"
>> +.BR 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.

s/receivers/devices/
s/receiver which is/receivers which are/
s/output/the output/
s/existing/an existing/

>>  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/

>>  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/

>>  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/$/.$/
>>
>>  .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?

>> -.B LIRC_SETUP_START/LIRC_SETUP_END.
>> +.BR LIRC_SETUP_START/LIRC_SETUP_END.
>>  When a driver receives a
>> -.B LIRC_SETUP_START
>> +.BR LIRC_SETUP_START
>>  ioctl it can choose to not commit further setting changes to the hardware
>>  until a
>> -.B LIRC_SETUP_END
>> +.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
>> +.BR LIRC_SETUP_START
>>  and
>> -.B LIRC_SETUP_END.
>> +.BR LIRC_SETUP_END.
>>  Drivers can also choose to ignore these ioctls.
>>
>>  .TP
>> -.B LIRC_NOTIFY_DECODE " (\fIvoid\fP)"
>> +.BR 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 e.g.,  by flashing a LED.
>> +incoming IR signal could be done.
s/could be done/is possible/
>> +This can be used by supporting hardware to give visual user feedback,
>> +for example by flashing a LED.

s/a/an/

>>
>>  .SH FEATURES
>>  .P
>>  The features returned by
>> -.B LIRC_GET_FEATURES
>> -is a bitmask combining the following bits.
>> +.BR LIRC_GET_FEATURES
>> +is a bitmask combining the following bits:
>>  .TP 8
>> -.B LIRC_CAN_REC_RAW
>> -The driver is capable of receiving using LIRC_MODE_RAW
>> +.BR LIRC_CAN_REC_RAW
>> +The driver is capable of receiving using
>> +.BR LIRC_MODE_RAW
> 
> s/$/ ./
> (And other instances below)
> 
>>  .TP 8
>>  .B LIRC_CAN_REC_PULSE
>> -The driver is capable of receiving using LIRC_MODE_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 LIRC_MODE_MODE2
>> +.BR 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 LIRC_MODE_LIRCCODE
>> +The driver is capable of receiving using
>> +.BR LIRC_MODE_LIRCCODE
>>  .TP 8
>> -.B LIRC_CAN_SET_SEND_CARRIER
>> +.BR LIRC_CAN_SET_SEND_CARRIER
>>  Driver supports  changing the modulation frequency using
>> -.B LIRC_SET_SEND_CARRIER.
>> +.BR LIRC_SET_SEND_CARRIER.
>>  .TP 8
>> -.B LIRC_CAN_SET_SEND_DUTY_CYCLE
>> -Driver supports changing the duty cycle using LIRC_SET_SEND_DUTY_CYCLE.
>> +.BR 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
>> +.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 e. g.,  a bit is set even though the
>> +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.
>> +transmitters and does nothing otherwise.
>>  .TP 8
>> -.B LIRC_CAN_SET_REC_CARRIER
>> -Drvier supports setting the receive carrier frequency using
>> -.B LIRC_SET_REC_CARRIER.
>> +.BR 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 LIRC_SET_REC_DUTY_CYCLE_RANGE
>> +.BR 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 LIRC_SET_REC_CARRIER_RANGE
>> +.BR LIRC_CAN_SET_REC_CARRIER_RANGE
>> +Driver supports
>> +.BR LIRC_SET_REC_CARRIER_RANGE
>>  .TP 8
>> -.B LIRC_CAN_GET_REC_RESOLUTION
>> -Driver supports LIRC_GET_REC_RESOLUTION
>> +.BR LIRC_CAN_GET_REC_RESOLUTION
>> +Driver supports
>> +.BR LIRC_GET_REC_RESOLUTION
>>  .TP 8
>> -.B LIRC_CAN_SET_REC_TIMEOUT
>> -Driver supports LIRC_SET_REC_TIMEOUT
>> +.BR LIRC_CAN_SET_REC_TIMEOUT
>> +Driver supports
>> +.BR LIRC_SET_REC_TIMEOUT
>>  .TP 8
>> -.B LIRC_CAN_SET_REC_FILTER
>> -Driver supports LIRC_SET_REC_FILTER
>> +.BR LIRC_CAN_SET_REC_FILTER
>> +Driver supports
>> +.BR LIRC_SET_REC_FILTER
>>  .TP 8
>> -.B LIRC_CAN_MEASURE_CARRIER
>> +.BR LIRC_CAN_MEASURE_CARRIER
>>  Driver supports measuring of the modulation frequency using
>> -.B LIRC_MEASURE_CARRIER
>> +.BR LIRC_MEASURE_CARRIER
>>  .TP 8
>> -.B LIRC_CAN_USE_WIDEBAND_RECEIVER
>> +.BR LIRC_CAN_USE_WIDEBAND_RECEIVER
>>  Driver supports learning mode using
>> -.B LIRC_SET_WIDEBAND_RECEIVER
>> +.BR LIRC_SET_WIDEBAND_RECEIVER
>>  .TP 8
>> -.B LIRC_CAN_NOTIFY_DECODE
>> -Driver supports LIRC_NOTIFY_DECODE.
>> +.BR LIRC_CAN_NOTIFY_DECODE
>> +Driver supports
>> +.BR LIRC_NOTIFY_DECODE.
>>  .TP 8
>> -.B LIRC_CAN_SEND_RAW
>> +.BR LIRC_CAN_SEND_RAW
>>  Driver supports sending using
>> -.B LIRC_SEND_RAW
>> +.BR LIRC_SEND_RAW
>>  .TP 8
>> -.B LIRC_CAN_SEND_PULSE
>> +.BR LIRC_CAN_SEND_PULSE
>>  Driver supports sending using
>> -.B LIRC_MODE_PULSE
>> +.BR LIRC_MODE_PULSE
>>  .TP 8
>> -.B LIRC_CAN_SEND_MODE2
>> +.BR LIRC_CAN_SEND_MODE2
>>  Driver supports sending using
>> -.B LIRC_SEND_MODE2
>> +.BR LIRC_SEND_MODE2
>>  .TP 8
>> -.B LIRC_CAN_SEND_LIRCCODE
>> +.BR LIRC_CAN_SEND_LIRCCODE
>>  Driver supports sending
>> -.B LIRC_SEND_LIRCCODE
>> +.BR LIRC_SEND_LIRCCODE
>>  (this is uncommon, since
>> -.B LIRCCODE
>> -drivers reflects hardware like TV-cards which usually does not support
>> +.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. 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.
>> +Using these devices requires the kernel source header file lirc.h.
>> +That this file is not public is a bug, see

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.
> 
> Thanks,
> 
> Michael.
> 
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: New manpage lirc.4 (Was: Possibly new manpages: lirc and lirc_ioctl)

[Alec Leamas]

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-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
>>> On Fri, 11 Dec 2015 20:16:00 +0100
>>> "Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> 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-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
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-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: New manpage lirc.4 (Was: Possibly new manpages: lirc and lirc_ioctl)

[Alec Leamas]

Dear list et. al.,

I missed it again... this time I think the patch is OK, but I 
forgot to use claws-mail so it's probably garbled. Re-sending last message,
please just drop the previous.

--alec

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-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
>>> On Fri, 11 Dec 2015 20:16:00 +0100
>>> "Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> 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-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
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-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: New manpage lirc.4 (Was: Possibly new manpages: lirc and lirc_ioctl)

[Michael Kerrisk (man-pages)]

On 12/14/2015 12:31 PM, Alec Leamas wrote:
> Dear list et. al.,
> 
> I missed it again... this time I think the patch is OK, but I 
> forgot to use claws-mail so it's probably garbled. Re-sending last message,
> please just drop the previous.

Too late. I already was offline for a bitand responding to the 
previous. Stand by :-).

Cheers,

Michael

> 
> --alec
> 
> 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-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
>>>> On Fri, 11 Dec 2015 20:16:00 +0100
>>>> "Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> 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-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
> 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
> 


-- 
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-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: New manpage lirc.4 (Was: Possibly new manpages: lirc and lirc_ioctl)

[Michael Kerrisk (man-pages)]

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-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
> 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-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: New manpage lirc.4 (Was: Possibly new manpages: lirc and lirc_ioctl)

[Christoph Hellwig]

On Sun, Dec 06, 2015 at 10:41:39PM +0100, Alec Leamas wrote:
> +#include " (\fIuapi/lirc.h\fP)"

Where is that header supposed to come from?
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: New manpage lirc.4 (Was: Possibly new manpages: lirc and lirc_ioctl)

[Alec Leamas]

On Mon, 14 Dec 2015 17:48:53 +0100
"Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:

> Hello Alec, 

> 
> Thanks, better, but your mailer is still wrapping patches...

Re-trying with claws-mail. It has worked before... 

> > +The \fBLIRC_GET_REC_MODE\fR ioctl allows probing for the mode.
> 
> s/ioctl/ioctl (described below)/

Fixed

> > +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
> ]]

Fixed

> > +.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

Fixed

> Various other places need fixing below.

Fixed two.

> > +.SH Reading input with the LIRC_MODE_LIRCCODE drivers
> 
> For all of the ".SH" lines that use lower-case titles, change
> ".SH" to ".SS".

Fixed
> 
> (Many instances to change below.)
> 
> > +.P
> > +In the \fBLIRC_MODE_LIRCCODE\fR
> > +mode, the data returned by read() reflects decoded
> 
> .BR read (2)

Fixed

> > +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.

Fixed (IMHO, text becomes somewhat heavy here).

> > +.SH Sending data.
> 
> s/.$//

Fixed

> > +.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)

Fixed

> > +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)

Fixed

> > +.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 */

Fixed (lirc/include/media/lirc.h)

> > +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 .
> ]]

Fixed

> > +.P
> > +\fI/dev/lirc*\fR devices always supports the following commands:
> 
> s/supports/support/

Fixed

> 
> > +.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)"

Fixed

> > +Returns the receive mode, one of
> 
> a/one of/which will be one of:/

Fixed
 
> > +Driver return a sequence of pulse/space durations.
> 
> s/return/returns

Fixed

> > +.P
> > +If a device returns an error code for
> > +.BR LIRC_GET_REC_MODE
> 
> s/$/ ,/

Fixed

> > +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/

Fixed
> 
> > +Unless otherwise stated these fails with the error \fIENOIOCTLCMD\fR
> 
> s/stated/stated,/
> s/fails/fail/

Fixed

> 
> Formatting of ENOIOCTLCMD should be \fB, not \fI
> 
> > +or with the error\fIENOSYS\fR if the operation
> 
> s/error/error /

Fixed

> 
> \fI ==> \fB
> 
> > +isn't supported, or with the error \fIEINVAL\fR if the operation failed.
> 
> \fI ==> \fB

Fixed

> > +.TP
> > +.BR LIRC_SET_REC_MODE " (\fIint\fP)"
> > +Set the receive mode, either
> 
> Change ", either" to
> 
> [[
> ;
> .IR val
> is either
> ]]

Fixed

> > +.TP
> > +.BR LIRC_GET_LENGTH " (\fIvoid\fP)"
> > +Return the positive length of the returned codes for
> 
> s/positive //

Fixed


> > +.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"?

Yep. Fixed

> > +.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

hm... splitting line to two physical lines. And trimming all lines to < 72 
characters to avoid mailer headaches. Also, see link before patch.

> > +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 > 
> s/a IR/an IR/(8)

Fixed

> > +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,/

Fixed

> > +.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.

Indeed. Fixed.


> > +.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
> ]]

Fixed

> 
> > +.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!

Don't blame me ;)

> 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).

Fixed

> > +.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
> ]]

Fixed
> 

> > +lircd derives the settings from all protocols definitions found in its
> 
> .BR lircd (8)

Fixed (lircd.conf (5))
 

> > +See
> > +.BR LIRC_GET_MIN_FILTER_PULSE
> 
> s/$/ ./

Fixed

> > +ioctls must return an error and
> > +.BR LIRC_SET_REC_FILTER
> > +shall be used instead.
> 
> s/shall/should/ (I think).

I'm not a native speaker, so... Fixed.

> > +Some devices are equipped with special wide band receiver which are
> 
> s/special/a special/

Fixed

> 
> > +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.

Fixed

> 
> > +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

Done

> > +This ioctl is called by lircd whenever a successful decoding of an
> 
> .BR lircd (8)
> 
> > +incoming IR signal is possible..
> 
> s/..$/./

Fixed

> > +.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:

This is bad, really bad. Changed to correct two ioctls
LIRC_CAN_SET_TRANSMITTER_MASK and LIRC_SET_TRANSMITTER_MASK

> > +.TP 8
> > +.BR LIRC_CAN_SET_REC_DUTY_CYCLE_RANGE
> > +Driver supports
> > +.BR LIRC_SET_REC_DUTY_CYCLE_RANGE
> 
> s/$/ ./
> (And various cases below)

Adding lot's of dots.

> > +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 ;-).


Done

Cheers!


Revised patch below. In case of troubles, a fresh copy is available at 
http://paste.fedoraproject.org/300732/45011842

>From 46308403b9cbd2286078934c697a38937fbe4b1f Mon Sep 17 00:00:00 2001
From: Alec Leamas <leamas.alec-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
Date: Mon, 14 Dec 2015 19:38:58 +0100
Subject: [PATCH] Add 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
-- 
2.4.3




--alec
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: New manpage lirc.4 (Was: Possibly new manpages: lirc and lirc_ioctl)

[Alec Leamas]

On 14/12/15 18:15, Christoph Hellwig wrote:
> On Sun, Dec 06, 2015 at 10:41:39PM +0100, Alec Leamas wrote:
>> +#include " (\fIuapi/lirc.h\fP)"
> 
> Where is that header supposed to come from?
> 

kernel-headers, once the media subsystem patch is merged.

Cheers!

--alec
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: New manpage lirc.4 (Was: Possibly new manpages: lirc and lirc_ioctl)

[Michael Kerrisk (man-pages)]

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....

Cheers,

Michael

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: New manpage lirc.4 (Was: Possibly new manpages: lirc and lirc_ioctl)

[Alec Leamas]

On Mon, 14 Dec 2015 21:40:04 +0100
"Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> 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

>From 5c3191b29a81e202ecc59e967cb2c508ece3e855 Mon Sep 17 00:00:00 2001
From: Alec Leamas <leamas.alec-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
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
-- 
2.4.3



--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: New manpage lirc.4 (Was: Possibly new manpages: lirc and lirc_ioctl)

[Christoph Hellwig]

On Mon, Dec 14, 2015 at 07:51:45PM +0100, Alec Leamas wrote:
> On 14/12/15 18:15, Christoph Hellwig wrote:
> > On Sun, Dec 06, 2015 at 10:41:39PM +0100, Alec Leamas wrote:
> >> +#include " (\fIuapi/lirc.h\fP)"
> > 
> > Where is that header supposed to come from?
> > 
> 
> kernel-headers, once the media subsystem patch is merged.

Can you show me the piece of code that mangles the hierachy generated in
the kernel into a flat namespace?  The include path just doesn't seem
to fit our normal patterns.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: New manpage lirc.4 (Was: Possibly new manpages: lirc and lirc_ioctl)

[Michael Kerrisk (man-pages)]

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-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> 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-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
> 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-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: New manpage lirc.4 (Was: Possibly new manpages: lirc and lirc_ioctl)

[Alec Leamas]

On 15/12/15 09:02, Christoph Hellwig wrote:
> On Mon, Dec 14, 2015 at 07:51:45PM +0100, Alec Leamas wrote:
>> On 14/12/15 18:15, Christoph Hellwig wrote:
>>> On Sun, Dec 06, 2015 at 10:41:39PM +0100, Alec Leamas wrote:
>>>> +#include " (\fIuapi/lirc.h\fP)"
>>> Where is that header supposed to come from?
>>>
>> kernel-headers, once the media subsystem patch is merged.
> Can you show me the piece of code that mangles the hierachy generated in
> the kernel into a flat namespace?  The include path just doesn't seem
> to fit our normal patterns.

Hm... this might be silly me. Anyway, during the review process the path 
has been changed to use the bundled copy in the lirc package, with a 
reference to the kernel bug. Let's wait until the kernel patch is merged 
before we resolve this.

Thanks for heads-up!

--alec



--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html