Documentation/linux_tv/media/v4l/lirc_ioctl.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _lirc_ioctl:
   4
   5 **************
   6 LIRC ioctl fop
   7 **************
   8
   9 The LIRC device's ioctl definition is bound by the ioctl function
  10 definition of struct file_operations, leaving us with an unsigned int
  11 for the ioctl command and an unsigned long for the arg. For the purposes
  12 of ioctl portability across 32-bit and 64-bit, these values are capped
  13 to their 32-bit sizes.
  14
  15 The following ioctls can be used to change specific hardware settings.
  16 In general each driver should have a default set of settings. The driver
  17 implementation is expected to re-apply the default settings when the
  18 device is closed by user-space, so that every application opening the
  19 device can rely on working with the default settings initially.
  20
  21 LIRC_GET_FEATURES
  22     Obviously, get the underlying hardware device's features. If a
  23     driver does not announce support of certain features, calling of the
  24     corresponding ioctls is undefined.
  25
  26 LIRC_GET_SEND_MODE
  27     Get supported transmit mode. Only LIRC_MODE_PULSE is supported by
  28     lircd.
  29
  30 LIRC_GET_REC_MODE
  31     Get supported receive modes. Only LIRC_MODE_MODE2 and
  32     LIRC_MODE_LIRCCODE are supported by lircd.
  33
  34 LIRC_GET_SEND_CARRIER
  35     Get carrier frequency (in Hz) currently used for transmit.
  36
  37 LIRC_GET_REC_CARRIER
  38     Get carrier frequency (in Hz) currently used for IR reception.
  39
  40 LIRC_{G,S}ET_{SEND,REC}_DUTY_CYCLE
  41     Get/set the duty cycle (from 0 to 100) of the carrier signal.
  42     Currently, no special meaning is defined for 0 or 100, but this
  43     could be used to switch off carrier generation in the future, so
  44     these values should be reserved.
  45
  46 LIRC_GET_REC_RESOLUTION
  47     Some receiver have maximum resolution which is defined by internal
  48     sample rate or data format limitations. E.g. it's common that
  49     signals can only be reported in 50 microsecond steps. This integer
  50     value is used by lircd to automatically adjust the aeps tolerance
  51     value in the lircd config file.
  52
  53 LIRC_GET_M{IN,AX}_TIMEOUT
  54     Some devices have internal timers that can be used to detect when
  55     there's no IR activity for a long time. This can help lircd in
  56     detecting that a IR signal is finished and can speed up the decoding
  57     process. Returns an integer value with the minimum/maximum timeout
  58     that can be set. Some devices have a fixed timeout, in that case
  59     both ioctls will return the same value even though the timeout
  60     cannot be changed.
  61
  62 LIRC_GET_M{IN,AX}_FILTER_{PULSE,SPACE}
  63     Some devices are able to filter out spikes in the incoming signal
  64     using given filter rules. These ioctls return the hardware
  65     capabilities that describe the bounds of the possible filters.
  66     Filter settings depend on the IR protocols that are expected. lircd
  67     derives the settings from all protocols definitions found in its
  68     config file.
  69
  70 LIRC_GET_LENGTH
  71     Retrieves the code length in bits (only for LIRC_MODE_LIRCCODE).
  72     Reads on the device must be done in blocks matching the bit count.
  73     The bit could should be rounded up so that it matches full bytes.
  74
  75 LIRC_SET_{SEND,REC}_MODE
  76     Set send/receive mode. Largely obsolete for send, as only
  77     LIRC_MODE_PULSE is supported.
  78
  79 LIRC_SET_{SEND,REC}_CARRIER
  80     Set send/receive carrier (in Hz).
  81
  82 LIRC_SET_TRANSMITTER_MASK
  83     This enables the given set of transmitters. The first transmitter is
  84     encoded by the least significant bit, etc. When an invalid bit mask
  85     is given, i.e. a bit is set, even though the device does not have so
  86     many transitters, then this ioctl returns the number of available
  87     transitters and does nothing otherwise.
  88
  89 LIRC_SET_REC_TIMEOUT
  90     Sets the integer value for IR inactivity timeout (cf.
  91     LIRC_GET_MIN_TIMEOUT and LIRC_GET_MAX_TIMEOUT). A value of 0
  92     (if supported by the hardware) disables all hardware timeouts and
  93     data should be reported as soon as possible. If the exact value
  94     cannot be set, then the next possible value _greater_ than the
  95     given value should be set.
  96
  97 LIRC_SET_REC_TIMEOUT_REPORTS
  98     Enable (1) or disable (0) timeout reports in LIRC_MODE_MODE2. By
  99     default, timeout reports should be turned off.
 100
 101 LIRC_SET_REC_FILTER_{,PULSE,SPACE}
 102     Pulses/spaces shorter than this are filtered out by hardware. If
 103     filters cannot be set independently for pulse/space, the
 104     corresponding ioctls must return an error and LIRC_SET_REC_FILTER
 105     shall be used instead.
 106
 107 LIRC_SET_MEASURE_CARRIER_MODE
 108     Enable (1)/disable (0) measure mode. If enabled, from the next key
 109     press on, the driver will send LIRC_MODE2_FREQUENCY packets. By
 110     default this should be turned off.
 111
 112 LIRC_SET_REC_{DUTY_CYCLE,CARRIER}_RANGE
 113     To set a range use
 114     LIRC_SET_REC_DUTY_CYCLE_RANGE/LIRC_SET_REC_CARRIER_RANGE
 115     with the lower bound first and later
 116     LIRC_SET_REC_DUTY_CYCLE/LIRC_SET_REC_CARRIER with the upper
 117     bound.
 118
 119 LIRC_NOTIFY_DECODE
 120     This ioctl is called by lircd whenever a successful decoding of an
 121     incoming IR signal could be done. This can be used by supporting
 122     hardware to give visual feedback to the user e.g. by flashing a LED.
 123
 124 LIRC_SETUP_{START,END}
 125     Setting of several driver parameters can be optimized by
 126     encapsulating the according ioctl calls with
 127     LIRC_SETUP_START/LIRC_SETUP_END. When a driver receives a
 128     LIRC_SETUP_START ioctl it can choose to not commit further setting
 129     changes to the hardware until a LIRC_SETUP_END is received. But
 130     this is open to the driver implementation and every driver must also
 131     handle parameter changes which are not encapsulated by
 132     LIRC_SETUP_START and LIRC_SETUP_END. Drivers can also choose to
 133     ignore these ioctls.
 134
 135 LIRC_SET_WIDEBAND_RECEIVER
 136     Some receivers are equipped with special wide band receiver which is
 137     intended to be used to learn output of existing remote. Calling that
 138     ioctl with (1) will enable it, and with (0) disable it. This might
 139     be useful of receivers that have otherwise narrow band receiver that
 140     prevents them to be used with some remotes. Wide band receiver might
 141     also be more precise On the other hand its disadvantage it usually
 142     reduced range of reception. Note: wide band receiver might be
 143     implictly enabled if you enable carrier reports. In that case it
 144     will be disabled as soon as you disable carrier reports. Trying to
 145     disable wide band receiver while carrier reports are active will do
 146     nothing.
 147
 148
 149 .. _lirc_dev_errors:
 150
 151 Return Value
 152 ============
 153
 154 On success 0 is returned, on error -1 and the ``errno`` variable is set
 155 appropriately. The generic error codes are described at the
 156 :ref:`Generic Error Codes <gen-errors>` chapter.
 157
 158
 159 .. ------------------------------------------------------------------------------
 160 .. This file was automatically converted from DocBook-XML with the dbxml
 161 .. library (https://github.com/return42/sphkerneldoc). The origin XML comes
 162 .. from the linux kernel, refer to:
 163 ..
 164 .. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
 165 .. ------------------------------------------------------------------------------