← Back to branch summary

~ubuntu-branches/ubuntu/precise/linux-ti-omap4/precise

« back to all changes in this revision

Viewing changes to Documentation/DocBook/v4l/media-ioc-device-info.xml

  • Committer: Bazaar Package Importer
  • Author(s): Paolo Pisati
  • Date: 2011-06-29 15:23:51 UTC
  • mfrom: (26.1.1 natty-proposed)
  • Revision ID: james.westby@ubuntu.com-20110629152351-xs96tm303d95rpbk
Tags: 3.0.0-1200.2
* Rebased against 3.0.0-6.7
* BSP from TI based on 3.0.0

Show diffs side-by-side

added added

removed removed

Lines of Context:
Documentation/DocBook/v4l/media-ioc-device-info.xml
 
1
<refentry id="media-ioc-device-info">
 
2
  <refmeta>
 
3
    <refentrytitle>ioctl MEDIA_IOC_DEVICE_INFO</refentrytitle>
 
4
    &manvol;
 
5
  </refmeta>
 
6
 
 
7
  <refnamediv>
 
8
    <refname>MEDIA_IOC_DEVICE_INFO</refname>
 
9
    <refpurpose>Query device information</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 media_device_info *<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='media-func-open'><function>open()</function></link>.</para>
 
32
        </listitem>
 
33
      </varlistentry>
 
34
      <varlistentry>
 
35
        <term><parameter>request</parameter></term>
 
36
        <listitem>
 
37
          <para>MEDIA_IOC_DEVICE_INFO</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>All media devices must support the <constant>MEDIA_IOC_DEVICE_INFO</constant>
 
53
    ioctl. To query device information, applications call the ioctl with a
 
54
    pointer to a &media-device-info;. The driver fills the structure and returns
 
55
    the information to the application.
 
56
    The ioctl never fails.</para>
 
57
 
 
58
    <table pgwide="1" frame="none" id="media-device-info">
 
59
      <title>struct <structname>media_device_info</structname></title>
 
60
      <tgroup cols="3">
 
61
        &cs-str;
 
62
        <tbody valign="top">
 
63
          <row>
 
64
            <entry>char</entry>
 
65
            <entry><structfield>driver</structfield>[16]</entry>
 
66
            <entry><para>Name of the driver implementing the media API as a
 
67
            NUL-terminated ASCII string. The driver version is stored in the
 
68
            <structfield>driver_version</structfield> field.</para>
 
69
            <para>Driver specific applications can use this information to
 
70
            verify the driver identity. It is also useful to work around
 
71
            known bugs, or to identify drivers in error reports.</para></entry>
 
72
          </row>
 
73
          <row>
 
74
            <entry>char</entry>
 
75
            <entry><structfield>model</structfield>[32]</entry>
 
76
            <entry>Device model name as a NUL-terminated UTF-8 string. The
 
77
            device version is stored in the <structfield>device_version</structfield>
 
78
            field and is not be appended to the model name.</entry>
 
79
          </row>
 
80
          <row>
 
81
            <entry>char</entry>
 
82
            <entry><structfield>serial</structfield>[40]</entry>
 
83
            <entry>Serial number as a NUL-terminated ASCII string.</entry>
 
84
          </row>
 
85
          <row>
 
86
            <entry>char</entry>
 
87
            <entry><structfield>bus_info</structfield>[32]</entry>
 
88
            <entry>Location of the device in the system as a NUL-terminated
 
89
            ASCII string. This includes the bus type name (PCI, USB, ...) and a
 
90
            bus-specific identifier.</entry>
 
91
          </row>
 
92
          <row>
 
93
            <entry>__u32</entry>
 
94
            <entry><structfield>media_version</structfield></entry>
 
95
            <entry>Media API version, formatted with the
 
96
            <constant>KERNEL_VERSION()</constant> macro.</entry>
 
97
          </row>
 
98
          <row>
 
99
            <entry>__u32</entry>
 
100
            <entry><structfield>hw_revision</structfield></entry>
 
101
            <entry>Hardware device revision in a driver-specific format.</entry>
 
102
          </row>
 
103
          <row>
 
104
            <entry>__u32</entry>
 
105
            <entry><structfield>media_version</structfield></entry>
 
106
            <entry>Media device driver version, formatted with the
 
107
            <constant>KERNEL_VERSION()</constant> macro. Together with the
 
108
            <structfield>driver</structfield> field this identifies a particular
 
109
            driver.</entry>
 
110
          </row>
 
111
          <row>
 
112
            <entry>__u32</entry>
 
113
            <entry><structfield>reserved</structfield>[31]</entry>
 
114
            <entry>Reserved for future extensions. Drivers and applications must
 
115
            set this array to zero.</entry>
 
116
          </row>
 
117
        </tbody>
 
118
      </tgroup>
 
119
    </table>
 
120
    <para>The <structfield>serial</structfield> and <structfield>bus_info</structfield>
 
121
    fields can be used to distinguish between multiple instances of otherwise
 
122
    identical hardware. The serial number takes precedence when provided and can
 
123
    be assumed to be unique. If the serial number is an empty string, the
 
124
    <structfield>bus_info</structfield> field can be used instead. The
 
125
    <structfield>bus_info</structfield> field is guaranteed to be unique, but
 
126
    can vary across reboots or device unplug/replug.</para>
 
127
  </refsect1>
 
128
 
 
129
  <refsect1>
 
130
    <title>Return value</title>
 
131
    <para>This function doesn't return specific error codes.</para>
 
132
  </refsect1>
 
133
</refentry>