Documentation/media/uapi/cec/cec-ioc-adap-g-caps.rst

   1 .. Permission is granted to copy, distribute and/or modify this
   2 .. document under the terms of the GNU Free Documentation License,
   3 .. Version 1.1 or any later version published by the Free Software
   4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
   5 .. and no Back-Cover Texts. A copy of the license is included at
   6 .. Documentation/media/uapi/fdl-appendix.rst.
   7 ..
   8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
   9
  10 .. _CEC_ADAP_G_CAPS:
  11
  12 *********************
  13 ioctl CEC_ADAP_G_CAPS
  14 *********************
  15
  16 Name
  17 ====
  18
  19 CEC_ADAP_G_CAPS - Query device capabilities
  20
  21 Synopsis
  22 ========
  23
  24 .. c:function:: int ioctl( int fd, CEC_ADAP_G_CAPS, struct cec_caps *argp )
  25     :name: CEC_ADAP_G_CAPS
  26
  27 Arguments
  28 =========
  29
  30 ``fd``
  31     File descriptor returned by :c:func:`open() <cec-open>`.
  32
  33 ``argp``
  34
  35
  36 Description
  37 ===========
  38
  39 All cec devices must support :ref:`ioctl CEC_ADAP_G_CAPS <CEC_ADAP_G_CAPS>`. To query
  40 device information, applications call the ioctl with a pointer to a
  41 struct :c:type:`cec_caps`. The driver fills the structure and
  42 returns the information to the application. The ioctl never fails.
  43
  44 .. tabularcolumns:: |p{1.2cm}|p{2.5cm}|p{13.8cm}|
  45
  46 .. c:type:: cec_caps
  47
  48 .. flat-table:: struct cec_caps
  49     :header-rows:  0
  50     :stub-columns: 0
  51     :widths:       1 1 16
  52
  53     * - char
  54       - ``driver[32]``
  55       - The name of the cec adapter driver.
  56     * - char
  57       - ``name[32]``
  58       - The name of this CEC adapter. The combination ``driver`` and
  59         ``name`` must be unique.
  60     * - __u32
  61       - ``capabilities``
  62       - The capabilities of the CEC adapter, see
  63         :ref:`cec-capabilities`.
  64     * - __u32
  65       - ``version``
  66       - CEC Framework API version, formatted with the ``KERNEL_VERSION()``
  67         macro.
  68
  69
  70 .. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.6cm}|
  71
  72 .. _cec-capabilities:
  73
  74 .. flat-table:: CEC Capabilities Flags
  75     :header-rows:  0
  76     :stub-columns: 0
  77     :widths:       3 1 8
  78
  79     * .. _`CEC-CAP-PHYS-ADDR`:
  80
  81       - ``CEC_CAP_PHYS_ADDR``
  82       - 0x00000001
  83       - Userspace has to configure the physical address by calling
  84         :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>`. If
  85         this capability isn't set, then setting the physical address is
  86         handled by the kernel whenever the EDID is set (for an HDMI
  87         receiver) or read (for an HDMI transmitter).
  88     * .. _`CEC-CAP-LOG-ADDRS`:
  89
  90       - ``CEC_CAP_LOG_ADDRS``
  91       - 0x00000002
  92       - Userspace has to configure the logical addresses by calling
  93         :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`. If
  94         this capability isn't set, then the kernel will have configured
  95         this.
  96     * .. _`CEC-CAP-TRANSMIT`:
  97
  98       - ``CEC_CAP_TRANSMIT``
  99       - 0x00000004
 100       - Userspace can transmit CEC messages by calling
 101         :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. This implies that
 102         userspace can be a follower as well, since being able to transmit
 103         messages is a prerequisite of becoming a follower. If this
 104         capability isn't set, then the kernel will handle all CEC
 105         transmits and process all CEC messages it receives.
 106     * .. _`CEC-CAP-PASSTHROUGH`:
 107
 108       - ``CEC_CAP_PASSTHROUGH``
 109       - 0x00000008
 110       - Userspace can use the passthrough mode by calling
 111         :ref:`ioctl CEC_S_MODE <CEC_S_MODE>`.
 112     * .. _`CEC-CAP-RC`:
 113
 114       - ``CEC_CAP_RC``
 115       - 0x00000010
 116       - This adapter supports the remote control protocol.
 117     * .. _`CEC-CAP-MONITOR-ALL`:
 118
 119       - ``CEC_CAP_MONITOR_ALL``
 120       - 0x00000020
 121       - The CEC hardware can monitor all messages, not just directed and
 122         broadcast messages.
 123     * .. _`CEC-CAP-NEEDS-HPD`:
 124
 125       - ``CEC_CAP_NEEDS_HPD``
 126       - 0x00000040
 127       - The CEC hardware is only active if the HDMI Hotplug Detect pin is
 128         high. This makes it impossible to use CEC to wake up displays that
 129         set the HPD pin low when in standby mode, but keep the CEC bus
 130         alive.
 131     * .. _`CEC-CAP-MONITOR-PIN`:
 132
 133       - ``CEC_CAP_MONITOR_PIN``
 134       - 0x00000080
 135       - The CEC hardware can monitor CEC pin changes from low to high voltage
 136         and vice versa. When in pin monitoring mode the application will
 137         receive ``CEC_EVENT_PIN_CEC_LOW`` and ``CEC_EVENT_PIN_CEC_HIGH`` events.
 138
 139
 140
 141 Return Value
 142 ============
 143
 144 On success 0 is returned, on error -1 and the ``errno`` variable is set
 145 appropriately. The generic error codes are described at the
 146 :ref:`Generic Error Codes <gen-errors>` chapter.