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

   1 <refentry id="cec-ioc-adap-g-log-addrs">
   2   <refmeta>
   3     <refentrytitle>ioctl CEC_ADAP_G_LOG_ADDRS, CEC_ADAP_S_LOG_ADDRS</refentrytitle>
   4     &manvol;
   5   </refmeta>
   6
   7   <refnamediv>
   8     <refname>CEC_ADAP_G_LOG_ADDRS</refname>
   9     <refname>CEC_ADAP_S_LOG_ADDRS</refname>
  10     <refpurpose>Get or set the logical addresses</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>struct cec_log_addrs *<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_ADAP_G_LOG_ADDRS, CEC_ADAP_S_LOG_ADDRS</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>To query the current CEC logical addresses, applications call the
  59 <constant>CEC_ADAP_G_LOG_ADDRS</constant> ioctl with a pointer to a
  60 <structname>cec_log_addrs</structname> structure where the drivers stores the
  61 logical addresses.</para>
  62
  63     <para>To set new logical addresses, applications fill in struct <structname>cec_log_addrs</structname>
  64 and call the <constant>CEC_ADAP_S_LOG_ADDRS</constant> ioctl with a pointer to this struct.
  65 The <constant>CEC_ADAP_S_LOG_ADDRS</constant> ioctl is only available if
  66 <constant>CEC_CAP_LOG_ADDRS</constant> is set (&ENOTTY; is returned otherwise). This ioctl will block until all
  67 requested logical addresses have been claimed. <constant>CEC_ADAP_S_LOG_ADDRS</constant>
  68 can only be called by a file handle in initiator mode (see &CEC-S-MODE;).</para>
  69
  70     <table pgwide="1" frame="none" id="cec-log-addrs">
  71       <title>struct <structname>cec_log_addrs</structname></title>
  72       <tgroup cols="3">
  73         &cs-str;
  74         <tbody valign="top">
  75           <row>
  76             <entry>__u8</entry>
  77             <entry><structfield>log_addr</structfield>[CEC_MAX_LOG_ADDRS]</entry>
  78             <entry>The actual logical addresses that were claimed. This is set by the
  79             driver. If no logical address could be claimed, then it is set to
  80             <constant>CEC_LOG_ADDR_INVALID</constant>. If this adapter is Unregistered,
  81             then <structfield>log_addr[0]</structfield> is set to 0xf and all others to
  82             <constant>CEC_LOG_ADDR_INVALID</constant>.</entry>
  83           </row>
  84           <row>
  85             <entry>__u16</entry>
  86             <entry><structfield>log_addr_mask</structfield></entry>
  87             <entry>The bitmask of all logical addresses this adapter has claimed.
  88             If this adapter is Unregistered then <structfield>log_addr_mask</structfield>
  89             sets bit 15 and clears all other bits. If this adapter is not configured at all, then
  90             <structfield>log_addr_mask</structfield> is set to 0. Set by the driver.</entry>
  91           </row>
  92           <row>
  93             <entry>__u8</entry>
  94             <entry><structfield>cec_version</structfield></entry>
  95             <entry>The CEC version that this adapter shall use. See
  96             <xref linkend="cec-versions" />.
  97             Used to implement the <constant>CEC_MSG_CEC_VERSION</constant> and
  98             <constant>CEC_MSG_REPORT_FEATURES</constant> messages. Note that
  99             <constant>CEC_OP_CEC_VERSION_1_3A</constant> is not allowed
 100             by the CEC framework.
 101             </entry>
 102           </row>
 103           <row>
 104             <entry>__u8</entry>
 105             <entry><structfield>num_log_addrs</structfield></entry>
 106             <entry>Number of logical addresses to set up. Must be &le;
 107             <structfield>available_log_addrs</structfield> as returned by
 108             &CEC-ADAP-G-CAPS;. All arrays in this structure are only filled up to
 109             index <structfield>available_log_addrs</structfield>-1. The remaining
 110             array elements will be ignored. Note that the CEC 2.0 standard allows
 111             for a maximum of 2 logical addresses, although some hardware has support
 112             for more. <constant>CEC_MAX_LOG_ADDRS</constant> is 4. The driver will
 113             return the actual number of logical addresses it could claim, which may
 114             be less than what was requested. If this field is set to 0, then the
 115             CEC adapter shall clear all claimed logical addresses and all other
 116             fields will be ignored.</entry>
 117           </row>
 118           <row>
 119             <entry>__u32</entry>
 120             <entry><structfield>vendor_id</structfield></entry>
 121             <entry>The vendor ID is a 24-bit number that identifies the specific
 122             vendor or entity. Based on this ID vendor specific commands may be
 123             defined. If you do not want a vendor ID then set it to
 124             <constant>CEC_VENDOR_ID_NONE</constant>.</entry>
 125           </row>
 126           <row>
 127             <entry>__u32</entry>
 128             <entry><structfield>flags</structfield></entry>
 129             <entry>Flags. No flags are defined yet, so set this to 0.</entry>
 130           </row>
 131           <row>
 132             <entry>char</entry>
 133             <entry><structfield>osd_name</structfield>[15]</entry>
 134             <entry>The On-Screen Display name as is returned by the
 135             <constant>CEC_MSG_SET_OSD_NAME</constant> message.</entry>
 136           </row>
 137           <row>
 138             <entry>__u8</entry>
 139             <entry><structfield>primary_device_type</structfield>[CEC_MAX_LOG_ADDRS]</entry>
 140             <entry>Primary device type for each logical address. See
 141             <xref linkend="cec-prim-dev-types" /> for possible types.</entry>
 142           </row>
 143           <row>
 144             <entry>__u8</entry>
 145             <entry><structfield>log_addr_type</structfield>[CEC_MAX_LOG_ADDRS]</entry>
 146             <entry>Logical address types. See <xref linkend="cec-log-addr-types" /> for
 147             possible types. The driver will update this with the actual logical address
 148             type that it claimed (e.g. it may have to fallback to
 149             <constant>CEC_LOG_ADDR_TYPE_UNREGISTERED</constant>).</entry>
 150           </row>
 151           <row>
 152             <entry>__u8</entry>
 153             <entry><structfield>all_device_types</structfield>[CEC_MAX_LOG_ADDRS]</entry>
 154             <entry>CEC 2.0 specific: all device types. See <xref linkend="cec-all-dev-types-flags" />.
 155             Used to implement the <constant>CEC_MSG_REPORT_FEATURES</constant> message.
 156             This field is ignored if <structfield>cec_version</structfield> &lt;
 157             <constant>CEC_OP_CEC_VERSION_2_0</constant>.</entry>
 158           </row>
 159           <row>
 160             <entry>__u8</entry>
 161             <entry><structfield>features</structfield>[CEC_MAX_LOG_ADDRS][12]</entry>
 162             <entry>Features for each logical address. Used to implement the
 163             <constant>CEC_MSG_REPORT_FEATURES</constant> message. The 12 bytes include
 164             both the RC Profile and the Device Features.
 165             This field is ignored if <structfield>cec_version</structfield> &lt;
 166             <constant>CEC_OP_CEC_VERSION_2_0</constant>.</entry>
 167           </row>
 168         </tbody>
 169       </tgroup>
 170     </table>
 171
 172     <table pgwide="1" frame="none" id="cec-versions">
 173       <title>CEC Versions</title>
 174       <tgroup cols="3">
 175         &cs-def;
 176         <tbody valign="top">
 177           <row>
 178             <entry><constant>CEC_OP_CEC_VERSION_1_3A</constant></entry>
 179             <entry>4</entry>
 180             <entry>CEC version according to the HDMI 1.3a standard.</entry>
 181           </row>
 182           <row>
 183             <entry><constant>CEC_OP_CEC_VERSION_1_4B</constant></entry>
 184             <entry>5</entry>
 185             <entry>CEC version according to the HDMI 1.4b standard.</entry>
 186           </row>
 187           <row>
 188             <entry><constant>CEC_OP_CEC_VERSION_2_0</constant></entry>
 189             <entry>6</entry>
 190             <entry>CEC version according to the HDMI 2.0 standard.</entry>
 191           </row>
 192         </tbody>
 193       </tgroup>
 194     </table>
 195
 196     <table pgwide="1" frame="none" id="cec-prim-dev-types">
 197       <title>CEC Primary Device Types</title>
 198       <tgroup cols="3">
 199         &cs-def;
 200         <tbody valign="top">
 201           <row>
 202             <entry><constant>CEC_OP_PRIM_DEVTYPE_TV</constant></entry>
 203             <entry>0</entry>
 204             <entry>Use for a TV.</entry>
 205           </row>
 206           <row>
 207             <entry><constant>CEC_OP_PRIM_DEVTYPE_RECORD</constant></entry>
 208             <entry>1</entry>
 209             <entry>Use for a recording device.</entry>
 210           </row>
 211           <row>
 212             <entry><constant>CEC_OP_PRIM_DEVTYPE_TUNER</constant></entry>
 213             <entry>3</entry>
 214             <entry>Use for a device with a tuner.</entry>
 215           </row>
 216           <row>
 217             <entry><constant>CEC_OP_PRIM_DEVTYPE_PLAYBACK</constant></entry>
 218             <entry>4</entry>
 219             <entry>Use for a playback device.</entry>
 220           </row>
 221           <row>
 222             <entry><constant>CEC_OP_PRIM_DEVTYPE_AUDIOSYSTEM</constant></entry>
 223             <entry>5</entry>
 224             <entry>Use for an audio system (e.g. an audio/video receiver).</entry>
 225           </row>
 226           <row>
 227             <entry><constant>CEC_OP_PRIM_DEVTYPE_SWITCH</constant></entry>
 228             <entry>6</entry>
 229             <entry>Use for a CEC switch.</entry>
 230           </row>
 231           <row>
 232             <entry><constant>CEC_OP_PRIM_DEVTYPE_VIDEOPROC</constant></entry>
 233             <entry>7</entry>
 234             <entry>Use for a video processor device.</entry>
 235           </row>
 236         </tbody>
 237       </tgroup>
 238     </table>
 239
 240     <table pgwide="1" frame="none" id="cec-log-addr-types">
 241       <title>CEC Logical Address Types</title>
 242       <tgroup cols="3">
 243         &cs-def;
 244         <tbody valign="top">
 245           <row>
 246             <entry><constant>CEC_LOG_ADDR_TYPE_TV</constant></entry>
 247             <entry>0</entry>
 248             <entry>Use for a TV.</entry>
 249           </row>
 250           <row>
 251             <entry><constant>CEC_LOG_ADDR_TYPE_RECORD</constant></entry>
 252             <entry>1</entry>
 253             <entry>Use for a recording device.</entry>
 254           </row>
 255           <row>
 256             <entry><constant>CEC_LOG_ADDR_TYPE_TUNER</constant></entry>
 257             <entry>2</entry>
 258             <entry>Use for a tuner device.</entry>
 259           </row>
 260           <row>
 261             <entry><constant>CEC_LOG_ADDR_TYPE_PLAYBACK</constant></entry>
 262             <entry>3</entry>
 263             <entry>Use for a playback device.</entry>
 264           </row>
 265           <row>
 266             <entry><constant>CEC_LOG_ADDR_TYPE_AUDIOSYSTEM</constant></entry>
 267             <entry>4</entry>
 268             <entry>Use for an audio system device.</entry>
 269           </row>
 270           <row>
 271             <entry><constant>CEC_LOG_ADDR_TYPE_SPECIFIC</constant></entry>
 272             <entry>5</entry>
 273             <entry>Use for a second TV or for a video processor device.</entry>
 274           </row>
 275           <row>
 276             <entry><constant>CEC_LOG_ADDR_TYPE_UNREGISTERED</constant></entry>
 277             <entry>6</entry>
 278             <entry>Use this if you just want to remain unregistered.
 279             Used for pure CEC switches or CDC-only devices (CDC:
 280             Capability Discovery and Control).</entry>
 281           </row>
 282         </tbody>
 283       </tgroup>
 284     </table>
 285
 286     <table pgwide="1" frame="none" id="cec-all-dev-types-flags">
 287       <title>CEC All Device Types Flags</title>
 288       <tgroup cols="3">
 289         &cs-def;
 290         <tbody valign="top">
 291           <row>
 292             <entry><constant>CEC_OP_ALL_DEVTYPE_TV</constant></entry>
 293             <entry>0x80</entry>
 294             <entry>This supports the TV type.</entry>
 295           </row>
 296           <row>
 297             <entry><constant>CEC_OP_ALL_DEVTYPE_RECORD</constant></entry>
 298             <entry>0x40</entry>
 299             <entry>This supports the Recording type.</entry>
 300           </row>
 301           <row>
 302             <entry><constant>CEC_OP_ALL_DEVTYPE_TUNER</constant></entry>
 303             <entry>0x20</entry>
 304             <entry>This supports the Tuner type.</entry>
 305           </row>
 306           <row>
 307             <entry><constant>CEC_OP_ALL_DEVTYPE_PLAYBACK</constant></entry>
 308             <entry>0x10</entry>
 309             <entry>This supports the Playback type.</entry>
 310           </row>
 311           <row>
 312             <entry><constant>CEC_OP_ALL_DEVTYPE_AUDIOSYSTEM</constant></entry>
 313             <entry>0x08</entry>
 314             <entry>This supports the Audio System type.</entry>
 315           </row>
 316           <row>
 317             <entry><constant>CEC_OP_ALL_DEVTYPE_SWITCH</constant></entry>
 318             <entry>0x04</entry>
 319             <entry>This supports the CEC Switch or Video Processing type.</entry>
 320           </row>
 321         </tbody>
 322       </tgroup>
 323     </table>
 324   </refsect1>
 325
 326   <refsect1>
 327     &return-value;
 328   </refsect1>
 329 </refentry>