Documentation/DocBook/media/v4l/cec-ioc-adap-g-caps.xml

   1 <refentry id="cec-ioc-adap-g-caps">
   2   <refmeta>
   3     <refentrytitle>ioctl CEC_ADAP_G_CAPS</refentrytitle>
   4     &manvol;
   5   </refmeta>
   6
   7   <refnamediv>
   8     <refname>CEC_ADAP_G_CAPS</refname>
   9     <refpurpose>Query device capabilities</refpurpose>
  10   </refnamediv>
  11
  12   <refsynopsisdiv>
  13     <funcsynopsis>
  14       <funcprototype>
  15         <funcdef>int <function>ioctl</function></funcdef>
  16         <paramdef>int <parameter>fd</parameter></paramdef>
  17         <paramdef>int <parameter>request</parameter></paramdef>
  18         <paramdef>struct cec_caps *<parameter>argp</parameter></paramdef>
  19       </funcprototype>
  20     </funcsynopsis>
  21   </refsynopsisdiv>
  22
  23   <refsect1>
  24     <title>Arguments</title>
  25
  26     <variablelist>
  27       <varlistentry>
  28         <term><parameter>fd</parameter></term>
  29         <listitem>
  30           <para>File descriptor returned by
  31           <link linkend='cec-func-open'><function>open()</function></link>.</para>
  32         </listitem>
  33       </varlistentry>
  34       <varlistentry>
  35         <term><parameter>request</parameter></term>
  36         <listitem>
  37           <para>CEC_ADAP_G_CAPS</para>
  38         </listitem>
  39       </varlistentry>
  40       <varlistentry>
  41         <term><parameter>argp</parameter></term>
  42         <listitem>
  43           <para></para>
  44         </listitem>
  45       </varlistentry>
  46     </variablelist>
  47   </refsect1>
  48
  49   <refsect1>
  50     <title>Description</title>
  51
  52     <para>
  53       Note: this documents the proposed CEC API. This API is not yet finalized and
  54       is currently only available as a staging kernel module.
  55     </para>
  56
  57     <para>All cec devices must support the <constant>CEC_ADAP_G_CAPS</constant>
  58     ioctl. To query device information, applications call the ioctl with a
  59     pointer to a &cec-caps;. The driver fills the structure and returns
  60     the information to the application.
  61     The ioctl never fails.</para>
  62
  63     <table pgwide="1" frame="none" id="cec-caps">
  64       <title>struct <structname>cec_caps</structname></title>
  65       <tgroup cols="3">
  66         &cs-str;
  67         <tbody valign="top">
  68           <row>
  69             <entry>char</entry>
  70             <entry><structfield>driver[32]</structfield></entry>
  71             <entry>The name of the cec adapter driver.</entry>
  72           </row>
  73           <row>
  74             <entry>char</entry>
  75             <entry><structfield>name[32]</structfield></entry>
  76             <entry>The name of this CEC adapter. The combination <structfield>driver</structfield>
  77             and <structfield>name</structfield> must be unique.</entry>
  78           </row>
  79           <row>
  80             <entry>__u32</entry>
  81             <entry><structfield>capabilities</structfield></entry>
  82             <entry>The capabilities of the CEC adapter, see <xref
  83                 linkend="cec-capabilities" />.</entry>
  84           </row>
  85           <row>
  86             <entry>__u32</entry>
  87             <entry><structfield>version</structfield></entry>
  88             <entry>CEC Framework API version, formatted with the
  89             <constant>KERNEL_VERSION()</constant> macro.</entry>
  90           </row>
  91         </tbody>
  92       </tgroup>
  93     </table>
  94
  95     <table pgwide="1" frame="none" id="cec-capabilities">
  96       <title>CEC Capabilities Flags</title>
  97       <tgroup cols="3">
  98         &cs-def;
  99         <tbody valign="top">
 100           <row>
 101             <entry><constant>CEC_CAP_PHYS_ADDR</constant></entry>
 102             <entry>0x00000001</entry>
 103             <entry>Userspace has to configure the physical address by
 104             calling &CEC-ADAP-S-PHYS-ADDR;. If this capability isn't set,
 105             then setting the physical address is handled by the kernel
 106             whenever the EDID is set (for an HDMI receiver) or read (for
 107             an HDMI transmitter).</entry>
 108           </row>
 109           <row>
 110             <entry><constant>CEC_CAP_LOG_ADDRS</constant></entry>
 111             <entry>0x00000002</entry>
 112             <entry>Userspace has to configure the logical addresses by
 113             calling &CEC-ADAP-S-LOG-ADDRS;. If this capability isn't set,
 114             then the kernel will have configured this.</entry>
 115           </row>
 116           <row>
 117             <entry><constant>CEC_CAP_TRANSMIT</constant></entry>
 118             <entry>0x00000004</entry>
 119             <entry>Userspace can transmit CEC messages by calling &CEC-TRANSMIT;. This
 120             implies that userspace can be a follower as well, since being able to
 121             transmit messages is a prerequisite of becoming a follower. If this
 122             capability isn't set, then the kernel will handle all CEC transmits
 123             and process all CEC messages it receives.
 124             </entry>
 125           </row>
 126           <row>
 127             <entry><constant>CEC_CAP_PASSTHROUGH</constant></entry>
 128             <entry>0x00000008</entry>
 129             <entry>Userspace can use the passthrough mode by
 130             calling &CEC-S-MODE;.</entry>
 131           </row>
 132           <row>
 133             <entry><constant>CEC_CAP_RC</constant></entry>
 134             <entry>0x00000010</entry>
 135             <entry>This adapter supports the remote control protocol.</entry>
 136           </row>
 137           <row>
 138             <entry><constant>CEC_CAP_MONITOR_ALL</constant></entry>
 139             <entry>0x00000020</entry>
 140             <entry>The CEC hardware can monitor all messages, not just directed and
 141             broadcast messages.</entry>
 142           </row>
 143         </tbody>
 144       </tgroup>
 145     </table>
 146   </refsect1>
 147
 148   <refsect1>
 149     &return-value;
 150   </refsect1>
 151 </refentry>