Skip to contentSkip to conversation

lirc.4: document lirc changes in the kernel

PATCH Applied Sean Young 2 participants 4 messages May 23, 2022 – Aug 16, 2022 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore

Sean Young

author
#0 lore raw

PATCH 1/1 lirc.4: document lirc changes in the kernel

Linux 5.17 makes LIRC_SET_REC_TIMEOUT_REPORTS an no-op and 5.18 introduces LIRC_OVERFLOW. Also some rewording to clarify.

---
 man4/lirc.4 | 51 +++++++++++++++++++++++++--------------------------
 1 file changed, 25 insertions(+), 26 deletions(-)
man4/lirc.4 +25 -26
index 8bc8a95cf..eb3c8d141 100644
@@ -47,8 +47,6 @@ Other hardware provides a stream of pulse/space durations.
 Such drivers work in
 .BR LIRC_MODE_MODE2
 mode.
-Sometimes, this kind of hardware also supports
-sending IR data.
 Such hardware can be used with (almost) any kind of remote.
 This type of hardware can also be used in
 .BR LIRC_MODE_SCANCODE
@@ -58,6 +56,8 @@ These decoders can be written in extended BPF (see
 and attached to the
 .B lirc
 device.
+Sometimes, this kind of hardware also supports
+sending IR data.
 .PP
 The \fBLIRC_GET_FEATURES\fR ioctl (see below) allows probing for whether
 receiving and sending is supported, and in which modes, amongst other
@@ -68,6 +68,11 @@ 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.
 The time of the duration (microseconds) is encoded in the lower 24 bits.
+Pulse (also known as flash) indicates a duration of infrared light being
+detected, and space (also known as gap) indicates a duration with no infrared.
+If the duration of space exceeds the inactivity timeout,
+a special timeout package is delivered, which marks the end of
+a message.
 The upper 8 bits indicate the type of package:
 .TP 4
 .BR LIRC_MODE2_SPACE
@@ -87,6 +92,10 @@ The package reflects a timeout; see the
 .B LIRC_SET_REC_TIMEOUT_REPORTS
 ioctl.
 .\"
+.TP 4
+.BR LIRC_MODE2_OVERFLOW
+The IR receiver encountered an overflow, and as a result data is missing
+(since Linux 5.18).
 .SS Reading input with the LIRC_MODE_SCANCODE mode
 In the \fBLIRC_MODE_SCANCODE\fR
 mode, the data returned by
@@ -122,30 +131,17 @@ The protocol or scancode is invalid, or the
 .B lirc
 device cannot transmit.
 .SH IOCTL COMMANDS
-The LIRC device's ioctl definition is bound by the ioctl function
-definition of
-.IR "struct file_operations" ,
-leaving us with an
-.IR "unsigned int"
-for the ioctl command and an
-.IR "unsigned long"
-for the argument.
-For the purposes of ioctl portability across 32-bit and 64-bit architectures,
-these values are capped to their 32-bit sizes.
-.PP
 .nf
 #include <linux/lirc.h>    /* But see BUGS */
-int ioctl(int fd, int cmd, ...);
+
+int ioctl(int fd, int cmd, int *val);
 .fi
 .PP
-The following ioctls can be used to probe or change specific
+The following \fBioctl\fR(2) operations are provided by the
+.B lirc
+character device to probe or change specific
 .B lirc
 hardware settings.
-Many require a third argument, usually an
-.IR int ,
-referred to below as
-.IR val .
-.\"
 .SS Always Supported Commands
 \fI/dev/lirc*\fR devices always support the following commands:
 .TP 4
@@ -280,16 +276,19 @@ is 0) timeout packages in
 The behavior of this operation has varied across kernel versions:
 .RS
 .IP * 3
-Since Linux 4.16: each time the
-.B lirc device is opened,
-timeout reports are by default enabled for the resulting file descriptor.
-The
+Since Linux 5.17: timeout packages are always enabled and this ioctl
+is a no-op.
+.IP *
+Since Linux 4.16: timeout packages are enabled by default.
+Each time the
+.B lirc
+device is opened, the
 .B LIRC_SET_REC_TIMEOUT
 operation can be used to disable (and, if desired, to later re-enable)
 the timeout on the file descriptor.
 .IP *
 In Linux 4.15 and earlier:
-timeout reports are disabled by default, and enabling them (via
+timeout packages are disabled by default, and enabling them (via
 .BR LIRC_SET_REC_TIMEOUT )
 on any file descriptor associated with the
 .B lirc
@@ -434,4 +433,4 @@ Users of older kernels could use the file bundled in
 .SH SEE ALSO
 \fBir\-ctl\fP(1), \fBlircd\fP(8),\ \fBbpf\fP(2)
 .PP
-https://www.kernel.org/doc/html/latest/media/uapi/rc/lirc-dev.html
+https://www.kernel.org/doc/html/latest/userspace-api/media/rc/lirc-dev.html
Signature · 1 line
2.36.1
#1 lore raw

Hi Sean,

Quoted 4 lines · Sean Young

Linux 5.17 makes LIRC_SET_REC_TIMEOUT_REPORTS an no-op and 5.18 introduces LIRC_OVERFLOW. Also some rewording to clarify.

Could you please provide some kernel commits that show these changes? It would be nice to be able to easily check.

Cheers,

Alex

Quoted 116 lines
---
  man4/lirc.4 | 51 +++++++++++++++++++++++++--------------------------
  1 file changed, 25 insertions(+), 26 deletions(-)
man4/lirc.4 +25 -26
index 8bc8a95cf..eb3c8d141 100644
@@ -47,8 +47,6 @@ Other hardware provides a stream of pulse/space durations.
  Such drivers work in
  .BR LIRC_MODE_MODE2
  mode.
-Sometimes, this kind of hardware also supports
-sending IR data.
  Such hardware can be used with (almost) any kind of remote.
  This type of hardware can also be used in
  .BR LIRC_MODE_SCANCODE
@@ -58,6 +56,8 @@ These decoders can be written in extended BPF (see
  and attached to the
  .B lirc
  device.
+Sometimes, this kind of hardware also supports
+sending IR data.
  .PP
  The \fBLIRC_GET_FEATURES\fR ioctl (see below) allows probing for whether
  receiving and sending is supported, and in which modes, amongst other
@@ -68,6 +68,11 @@ 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.
  The time of the duration (microseconds) is encoded in the lower 24 bits.
+Pulse (also known as flash) indicates a duration of infrared light being
+detected, and space (also known as gap) indicates a duration with no infrared.
+If the duration of space exceeds the inactivity timeout,
+a special timeout package is delivered, which marks the end of
+a message.
  The upper 8 bits indicate the type of package:
  .TP 4
  .BR LIRC_MODE2_SPACE
@@ -87,6 +92,10 @@ The package reflects a timeout; see the
  .B LIRC_SET_REC_TIMEOUT_REPORTS
  ioctl.
  .\"
+.TP 4
+.BR LIRC_MODE2_OVERFLOW
+The IR receiver encountered an overflow, and as a result data is missing
+(since Linux 5.18).
  .SS Reading input with the LIRC_MODE_SCANCODE mode
  In the \fBLIRC_MODE_SCANCODE\fR
  mode, the data returned by
@@ -122,30 +131,17 @@ The protocol or scancode is invalid, or the
  .B lirc
  device cannot transmit.
  .SH IOCTL COMMANDS
-The LIRC device's ioctl definition is bound by the ioctl function
-definition of
-.IR "struct file_operations" ,
-leaving us with an
-.IR "unsigned int"
-for the ioctl command and an
-.IR "unsigned long"
-for the argument.
-For the purposes of ioctl portability across 32-bit and 64-bit architectures,
-these values are capped to their 32-bit sizes.
-.PP
  .nf
  #include <linux/lirc.h>    /* But see BUGS */
-int ioctl(int fd, int cmd, ...);
+
+int ioctl(int fd, int cmd, int *val);
  .fi
  .PP
-The following ioctls can be used to probe or change specific
+The following \fBioctl\fR(2) operations are provided by the
+.B lirc
+character device to probe or change specific
  .B lirc
  hardware settings.
-Many require a third argument, usually an
-.IR int ,
-referred to below as
-.IR val .
-.\"
  .SS Always Supported Commands
  \fI/dev/lirc*\fR devices always support the following commands:
  .TP 4
@@ -280,16 +276,19 @@ is 0) timeout packages in
  The behavior of this operation has varied across kernel versions:
  .RS
  .IP * 3
-Since Linux 4.16: each time the
-.B lirc device is opened,
-timeout reports are by default enabled for the resulting file descriptor.
-The
+Since Linux 5.17: timeout packages are always enabled and this ioctl
+is a no-op.
+.IP *
+Since Linux 4.16: timeout packages are enabled by default.
+Each time the
+.B lirc
+device is opened, the
  .B LIRC_SET_REC_TIMEOUT
  operation can be used to disable (and, if desired, to later re-enable)
  the timeout on the file descriptor.
  .IP *
  In Linux 4.15 and earlier:
-timeout reports are disabled by default, and enabling them (via
+timeout packages are disabled by default, and enabling them (via
  .BR LIRC_SET_REC_TIMEOUT )
  on any file descriptor associated with the
  .B lirc
@@ -434,4 +433,4 @@ Users of older kernels could use the file bundled in
  .SH SEE ALSO
  \fBir\-ctl\fP(1), \fBlircd\fP(8),\ \fBbpf\fP(2)
  .PP
-https://www.kernel.org/doc/html/latest/media/uapi/rc/lirc-dev.html
+https://www.kernel.org/doc/html/latest/userspace-api/media/rc/lirc-dev.html
Signature · 2 lines
Alejandro Colomar
<http://www.alejandro-colomar.es/>
author
#2 lore raw

Hi Alex,

Quoted 8 lines · Alejandro Colomar
Quoted 4 lines · Sean Young

Linux 5.17 makes LIRC_SET_REC_TIMEOUT_REPORTS an no-op and 5.18 introduces LIRC_OVERFLOW. Also some rewording to clarify.

Could you please provide some kernel commits that show these changes? It would be nice to be able to easily check.

Of course, I should have included that in the first place

68a99f6a0ebfe media: lirc: report ir receiver overflow 74747dda582dc media: lirc: always send timeout reports

Thanks,
Sean

#3 lore raw
In reply to Sean Young

Hi Sean,

I'm very sorry for the long delay.

Quoted 4 lines · Sean Young

Linux 5.17 makes LIRC_SET_REC_TIMEOUT_REPORTS an no-op and 5.18 introduces LIRC_OVERFLOW. Also some rewording to clarify.

I've applied this patch, and applied some minor formatting changes to it.

<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=266a3390f758734f1a6975286fcbde78a7793f89>

Thanks,

Alex

Quoted 116 lines
---
  man4/lirc.4 | 51 +++++++++++++++++++++++++--------------------------
  1 file changed, 25 insertions(+), 26 deletions(-)
man4/lirc.4 +25 -26
index 8bc8a95cf..eb3c8d141 100644
@@ -47,8 +47,6 @@ Other hardware provides a stream of pulse/space durations.
  Such drivers work in
  .BR LIRC_MODE_MODE2
  mode.
-Sometimes, this kind of hardware also supports
-sending IR data.
  Such hardware can be used with (almost) any kind of remote.
  This type of hardware can also be used in
  .BR LIRC_MODE_SCANCODE
@@ -58,6 +56,8 @@ These decoders can be written in extended BPF (see
  and attached to the
  .B lirc
  device.
+Sometimes, this kind of hardware also supports
+sending IR data.
  .PP
  The \fBLIRC_GET_FEATURES\fR ioctl (see below) allows probing for whether
  receiving and sending is supported, and in which modes, amongst other
@@ -68,6 +68,11 @@ 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.
  The time of the duration (microseconds) is encoded in the lower 24 bits.
+Pulse (also known as flash) indicates a duration of infrared light being
+detected, and space (also known as gap) indicates a duration with no infrared.
+If the duration of space exceeds the inactivity timeout,
+a special timeout package is delivered, which marks the end of
+a message.
  The upper 8 bits indicate the type of package:
  .TP 4
  .BR LIRC_MODE2_SPACE
@@ -87,6 +92,10 @@ The package reflects a timeout; see the
  .B LIRC_SET_REC_TIMEOUT_REPORTS
  ioctl.
  .\"
+.TP 4
+.BR LIRC_MODE2_OVERFLOW
+The IR receiver encountered an overflow, and as a result data is missing
+(since Linux 5.18).
  .SS Reading input with the LIRC_MODE_SCANCODE mode
  In the \fBLIRC_MODE_SCANCODE\fR
  mode, the data returned by
@@ -122,30 +131,17 @@ The protocol or scancode is invalid, or the
  .B lirc
  device cannot transmit.
  .SH IOCTL COMMANDS
-The LIRC device's ioctl definition is bound by the ioctl function
-definition of
-.IR "struct file_operations" ,
-leaving us with an
-.IR "unsigned int"
-for the ioctl command and an
-.IR "unsigned long"
-for the argument.
-For the purposes of ioctl portability across 32-bit and 64-bit architectures,
-these values are capped to their 32-bit sizes.
-.PP
  .nf
  #include <linux/lirc.h>    /* But see BUGS */
-int ioctl(int fd, int cmd, ...);
+
+int ioctl(int fd, int cmd, int *val);
  .fi
  .PP
-The following ioctls can be used to probe or change specific
+The following \fBioctl\fR(2) operations are provided by the
+.B lirc
+character device to probe or change specific
  .B lirc
  hardware settings.
-Many require a third argument, usually an
-.IR int ,
-referred to below as
-.IR val .
-.\"
  .SS Always Supported Commands
  \fI/dev/lirc*\fR devices always support the following commands:
  .TP 4
@@ -280,16 +276,19 @@ is 0) timeout packages in
  The behavior of this operation has varied across kernel versions:
  .RS
  .IP * 3
-Since Linux 4.16: each time the
-.B lirc device is opened,
-timeout reports are by default enabled for the resulting file descriptor.
-The
+Since Linux 5.17: timeout packages are always enabled and this ioctl
+is a no-op.
+.IP *
+Since Linux 4.16: timeout packages are enabled by default.
+Each time the
+.B lirc
+device is opened, the
  .B LIRC_SET_REC_TIMEOUT
  operation can be used to disable (and, if desired, to later re-enable)
  the timeout on the file descriptor.
  .IP *
  In Linux 4.15 and earlier:
-timeout reports are disabled by default, and enabling them (via
+timeout packages are disabled by default, and enabling them (via
  .BR LIRC_SET_REC_TIMEOUT )
  on any file descriptor associated with the
  .B lirc
@@ -434,4 +433,4 @@ Users of older kernels could use the file bundled in
  .SH SEE ALSO
  \fBir\-ctl\fP(1), \fBlircd\fP(8),\ \fBbpf\fP(2)
  .PP
-https://www.kernel.org/doc/html/latest/media/uapi/rc/lirc-dev.html
+https://www.kernel.org/doc/html/latest/userspace-api/media/rc/lirc-dev.html
Signature · 2 lines
Alejandro Colomar
<http://www.alejandro-colomar.es/>