Documentation/DocBook/media/v4l/cec-ioc-g-mode.xml

   1 <refentry id="cec-ioc-g-mode">
   2   <refmeta>
   3     <refentrytitle>ioctl CEC_G_MODE, CEC_S_MODE</refentrytitle>
   4     &manvol;
   5   </refmeta>
   6
   7   <refnamediv>
   8     <refname>CEC_G_MODE</refname>
   9     <refname>CEC_S_MODE</refname>
  10     <refpurpose>Get or set exclusive use of the CEC adapter</refpurpose>
  11   </refnamediv>
  12
  13   <refsynopsisdiv>
  14     <funcsynopsis>
  15       <funcprototype>
  16         <funcdef>int <function>ioctl</function></funcdef>
  17         <paramdef>int <parameter>fd</parameter></paramdef>
  18         <paramdef>int <parameter>request</parameter></paramdef>
  19         <paramdef>__u32 *<parameter>argp</parameter></paramdef>
  20       </funcprototype>
  21     </funcsynopsis>
  22   </refsynopsisdiv>
  23
  24   <refsect1>
  25     <title>Arguments</title>
  26
  27     <variablelist>
  28       <varlistentry>
  29         <term><parameter>fd</parameter></term>
  30         <listitem>
  31           <para>File descriptor returned by
  32           <link linkend='cec-func-open'><function>open()</function></link>.</para>
  33         </listitem>
  34       </varlistentry>
  35       <varlistentry>
  36         <term><parameter>request</parameter></term>
  37         <listitem>
  38           <para>CEC_G_MODE, CEC_S_MODE</para>
  39         </listitem>
  40       </varlistentry>
  41       <varlistentry>
  42         <term><parameter>argp</parameter></term>
  43         <listitem>
  44           <para></para>
  45         </listitem>
  46       </varlistentry>
  47     </variablelist>
  48   </refsect1>
  49
  50   <refsect1>
  51     <title>Description</title>
  52
  53     <para>
  54       Note: this documents the proposed CEC API. This API is not yet finalized and
  55       is currently only available as a staging kernel module.
  56     </para>
  57
  58     <para>By default any filehandle can use &CEC-TRANSMIT; and &CEC-RECEIVE;, but
  59 in order to prevent applications from stepping on each others toes it must be possible
  60 to obtain exclusive access to the CEC adapter. This ioctl sets the filehandle
  61 to initiator and/or follower mode which can be exclusive depending on the chosen
  62 mode. The initiator is the filehandle that is used
  63 to initiate messages, i.e. it commands other CEC devices. The follower is the filehandle
  64 that receives messages sent to the CEC adapter and processes them. The same filehandle
  65 can be both initiator and follower, or this role can be taken by two different
  66 filehandles.</para>
  67
  68     <para>When a CEC message is received, then the CEC framework will decide how
  69 it will be processed. If the message is a reply to an earlier transmitted message,
  70 then the reply is sent back to the filehandle that is waiting for it. In addition
  71 the CEC framework will process it.</para>
  72
  73     <para>If the message is not a reply, then the CEC framework will process it
  74 first. If there is no follower, then the message is just discarded and a feature
  75 abort is sent back to the initiator if the framework couldn't process it. If there
  76 is a follower, then the message is passed on to the follower who will use
  77 &CEC-RECEIVE; to dequeue the new message. The framework expects the follower to
  78 make the right decisions.</para>
  79
  80     <para>The CEC framework will process core messages unless requested otherwise
  81 by the follower. The follower can enable the passthrough mode. In that case, the
  82 CEC framework will pass on most core messages without processing them and
  83 the follower will have to implement those messages. There are some messages
  84 that the core will always process, regardless of the passthrough mode. See
  85 <xref linkend="cec-core-processing" /> for details.</para>
  86
  87     <para>If there is no initiator, then any CEC filehandle can use &CEC-TRANSMIT;.
  88 If there is an exclusive initiator then only that initiator can call &CEC-TRANSMIT;.
  89 The follower can of course always call &CEC-TRANSMIT;.</para>
  90
  91     <para>Available initiator modes are:</para>
  92
  93     <table pgwide="1" frame="none" id="cec-mode-initiator">
  94       <title>Initiator Modes</title>
  95       <tgroup cols="3">
  96         &cs-def;
  97         <tbody valign="top">
  98           <row>
  99             <entry><constant>CEC_MODE_NO_INITIATOR</constant></entry>
 100             <entry>0x0</entry>
 101             <entry>This is not an initiator, i.e. it cannot transmit CEC messages
 102             or make any other changes to the CEC adapter.</entry>
 103           </row>
 104           <row>
 105             <entry><constant>CEC_MODE_INITIATOR</constant></entry>
 106             <entry>0x1</entry>
 107             <entry>This is an initiator (the default when the device is opened) and it
 108             can transmit CEC messages and make changes to the CEC adapter, unless there
 109             is an exclusive initiator.</entry>
 110           </row>
 111           <row>
 112             <entry><constant>CEC_MODE_EXCL_INITIATOR</constant></entry>
 113             <entry>0x2</entry>
 114             <entry>This is an exclusive initiator and this file descriptor is the only one
 115             that can transmit CEC messages and make changes to the CEC adapter. If someone
 116             else is already the exclusive initiator then an attempt to become one will return
 117             the &EBUSY; error.</entry>
 118           </row>
 119         </tbody>
 120       </tgroup>
 121     </table>
 122
 123     <para>Available follower modes are:</para>
 124
 125     <table pgwide="1" frame="none" id="cec-mode-follower">
 126       <title>Follower Modes</title>
 127       <tgroup cols="3">
 128         &cs-def;
 129         <tbody valign="top">
 130           <row>
 131             <entry><constant>CEC_MODE_NO_FOLLOWER</constant></entry>
 132             <entry>0x00</entry>
 133             <entry>This is not a follower (the default when the device is opened).</entry>
 134           </row>
 135           <row>
 136             <entry><constant>CEC_MODE_FOLLOWER</constant></entry>
 137             <entry>0x10</entry>
 138             <entry>This is a follower and it will receive CEC messages unless there is
 139             an exclusive follower. You cannot become a follower if <constant>CEC_CAP_TRANSMIT</constant>
 140             is not set or if <constant>CEC_MODE_NO_INITIATOR</constant> was specified,
 141             &EINVAL; is returned in that case.</entry>
 142           </row>
 143           <row>
 144             <entry><constant>CEC_MODE_EXCL_FOLLOWER</constant></entry>
 145             <entry>0x20</entry>
 146             <entry>This is an exclusive follower and only this file descriptor will receive
 147             CEC messages for processing. If someone else is already the exclusive follower
 148             then an attempt to become one will return the &EBUSY; error. You cannot become
 149             a follower if <constant>CEC_CAP_TRANSMIT</constant> is not set or if
 150             <constant>CEC_MODE_NO_INITIATOR</constant> was specified, &EINVAL; is returned
 151             in that case.</entry>
 152           </row>
 153           <row>
 154             <entry><constant>CEC_MODE_EXCL_FOLLOWER_PASSTHRU</constant></entry>
 155             <entry>0x30</entry>
 156             <entry>This is an exclusive follower and only this file descriptor will receive
 157             CEC messages for processing. In addition it will put the CEC device into
 158             passthrough mode, allowing the exclusive follower to handle most core messages
 159             instead of relying on the CEC framework for that. If someone else is already the
 160             exclusive follower then an attempt to become one will return the &EBUSY; error.
 161             You cannot become a follower if <constant>CEC_CAP_TRANSMIT</constant>
 162             is not set or if <constant>CEC_MODE_NO_INITIATOR</constant> was specified,
 163             &EINVAL; is returned in that case.</entry>
 164           </row>
 165           <row>
 166             <entry><constant>CEC_MODE_MONITOR</constant></entry>
 167             <entry>0xe0</entry>
 168             <entry>Put the file descriptor into monitor mode. Can only be used in combination
 169             with <constant>CEC_MODE_NO_INITIATOR</constant>, otherwise &EINVAL; will be
 170             returned. In monitor mode all messages this CEC device transmits and all messages
 171             it receives (both broadcast messages and directed messages for one its logical
 172             addresses) will be reported. This is very useful for debugging. This is only
 173             allowed if the process has the <constant>CAP_NET_ADMIN</constant>
 174             capability. If that is not set, then &EPERM; is returned.</entry>
 175           </row>
 176           <row>
 177             <entry><constant>CEC_MODE_MONITOR_ALL</constant></entry>
 178             <entry>0xf0</entry>
 179             <entry>Put the file descriptor into 'monitor all' mode. Can only be used in combination
 180             with <constant>CEC_MODE_NO_INITIATOR</constant>, otherwise &EINVAL; will be
 181             returned. In 'monitor all' mode all messages this CEC device transmits and all messages
 182             it receives, including directed messages for other CEC devices will be reported. This
 183             is very useful for debugging, but not all devices support this. This mode requires that
 184             the <constant>CEC_CAP_MONITOR_ALL</constant> capability is set, otherwise &EINVAL; is
 185             returned. This is only allowed if the process has the <constant>CAP_NET_ADMIN</constant>
 186             capability. If that is not set, then &EPERM; is returned.</entry>
 187           </row>
 188         </tbody>
 189       </tgroup>
 190     </table>
 191
 192     <para>Core message processing details:</para>
 193
 194     <table pgwide="1" frame="none" id="cec-core-processing">
 195       <title>Core Message Processing</title>
 196       <tgroup cols="2">
 197         &cs-def;
 198         <tbody valign="top">
 199           <row>
 200             <entry><constant>CEC_MSG_GET_CEC_VERSION</constant></entry>
 201             <entry>When in passthrough mode this message has to be handled by userspace,
 202             otherwise the core will return the CEC version that was set with &CEC-ADAP-S-LOG-ADDRS;.</entry>
 203           </row>
 204           <row>
 205             <entry><constant>CEC_MSG_GIVE_DEVICE_VENDOR_ID</constant></entry>
 206             <entry>When in passthrough mode this message has to be handled by userspace,
 207             otherwise the core will return the vendor ID that was set with &CEC-ADAP-S-LOG-ADDRS;.</entry>
 208           </row>
 209           <row>
 210             <entry><constant>CEC_MSG_ABORT</constant></entry>
 211             <entry>When in passthrough mode this message has to be handled by userspace,
 212             otherwise the core will return a feature refused message as per the specification.</entry>
 213           </row>
 214           <row>
 215             <entry><constant>CEC_MSG_GIVE_PHYSICAL_ADDR</constant></entry>
 216             <entry>When in passthrough mode this message has to be handled by userspace,
 217             otherwise the core will report the current physical address.</entry>
 218           </row>
 219           <row>
 220             <entry><constant>CEC_MSG_GIVE_OSD_NAME</constant></entry>
 221             <entry>When in passthrough mode this message has to be handled by userspace,
 222             otherwise the core will report the current OSD name as was set with
 223             &CEC-ADAP-S-LOG-ADDRS;.</entry>
 224           </row>
 225           <row>
 226             <entry><constant>CEC_MSG_GIVE_FEATURES</constant></entry>
 227             <entry>When in passthrough mode this message has to be handled by userspace,
 228             otherwise the core will report the current features as was set with
 229             &CEC-ADAP-S-LOG-ADDRS; or the message is ignore if the CEC version was
 230             older than 2.0.</entry>
 231           </row>
 232           <row>
 233             <entry><constant>CEC_MSG_USER_CONTROL_PRESSED</constant></entry>
 234             <entry>If <constant>CEC_CAP_RC</constant> is set, then generate a remote control
 235             key press. This message is always passed on to userspace.</entry>
 236           </row>
 237           <row>
 238             <entry><constant>CEC_MSG_USER_CONTROL_RELEASED</constant></entry>
 239             <entry>If <constant>CEC_CAP_RC</constant> is set, then generate a remote control
 240             key release. This message is always passed on to userspace.</entry>
 241           </row>
 242           <row>
 243             <entry><constant>CEC_MSG_REPORT_PHYSICAL_ADDR</constant></entry>
 244             <entry>The CEC framework will make note of the reported physical address
 245             and then just pass the message on to userspace.</entry>
 246           </row>
 247         </tbody>
 248       </tgroup>
 249     </table>
 250   </refsect1>
 251
 252   <refsect1>
 253     &return-value;
 254   </refsect1>
 255 </refentry>