aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook
diff options
context:
space:
mode:
authorLaurent Pinchart <laurent.pinchart@ideasonboard.com>2010-08-18 10:41:22 -0400
committerMauro Carvalho Chehab <mchehab@redhat.com>2011-03-22 03:53:13 -0400
commit140d88165c25137e871f9559e67986ed89251105 (patch)
treec02891d72b0b85c03d4f493da4c5f37923c836c6 /Documentation/DocBook
parent503c3d829eaf48837dd5bff5d97ad66369bb955a (diff)
[media] media: Media device information query
Create the following ioctl and implement it at the media device level to query device information. - MEDIA_IOC_DEVICE_INFO: Query media device information The ioctl and its data structure are defined in the new kernel header linux/media.h available to userspace applications. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Acked-by: Hans Verkuil <hverkuil@xs4all.nl> Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
Diffstat (limited to 'Documentation/DocBook')
-rw-r--r--Documentation/DocBook/media-entities.tmpl12
-rw-r--r--Documentation/DocBook/v4l/media-controller.xml10
-rw-r--r--Documentation/DocBook/v4l/media-func-close.xml59
-rw-r--r--Documentation/DocBook/v4l/media-func-ioctl.xml116
-rw-r--r--Documentation/DocBook/v4l/media-func-open.xml94
-rw-r--r--Documentation/DocBook/v4l/media-ioc-device-info.xml132
6 files changed, 423 insertions, 0 deletions
diff --git a/Documentation/DocBook/media-entities.tmpl b/Documentation/DocBook/media-entities.tmpl
index c47897f046b1..034f891399ed 100644
--- a/Documentation/DocBook/media-entities.tmpl
+++ b/Documentation/DocBook/media-entities.tmpl
@@ -11,6 +11,10 @@
11<!ENTITY func-select "<link linkend='func-select'><function>select()</function></link>"> 11<!ENTITY func-select "<link linkend='func-select'><function>select()</function></link>">
12<!ENTITY func-write "<link linkend='func-write'><function>write()</function></link>"> 12<!ENTITY func-write "<link linkend='func-write'><function>write()</function></link>">
13 13
14<!ENTITY media-func-close "<link linkend='media-func-close'><function>close()</function></link>">
15<!ENTITY media-func-ioctl "<link linkend='media-func-ioctl'><function>ioctl()</function></link>">
16<!ENTITY media-func-open "<link linkend='media-func-open'><function>open()</function></link>">
17
14<!-- Ioctls --> 18<!-- Ioctls -->
15<!ENTITY VIDIOC-CROPCAP "<link linkend='vidioc-cropcap'><constant>VIDIOC_CROPCAP</constant></link>"> 19<!ENTITY VIDIOC-CROPCAP "<link linkend='vidioc-cropcap'><constant>VIDIOC_CROPCAP</constant></link>">
16<!ENTITY VIDIOC-DBG-G-CHIP-IDENT "<link linkend='vidioc-dbg-g-chip-ident'><constant>VIDIOC_DBG_G_CHIP_IDENT</constant></link>"> 20<!ENTITY VIDIOC-DBG-G-CHIP-IDENT "<link linkend='vidioc-dbg-g-chip-ident'><constant>VIDIOC_DBG_G_CHIP_IDENT</constant></link>">
@@ -87,6 +91,8 @@
87<!ENTITY VIDIOC-TRY-FMT "<link linkend='vidioc-g-fmt'><constant>VIDIOC_TRY_FMT</constant></link>"> 91<!ENTITY VIDIOC-TRY-FMT "<link linkend='vidioc-g-fmt'><constant>VIDIOC_TRY_FMT</constant></link>">
88<!ENTITY VIDIOC-UNSUBSCRIBE-EVENT "<link linkend='vidioc-subscribe-event'><constant>VIDIOC_UNSUBSCRIBE_EVENT</constant></link>"> 92<!ENTITY VIDIOC-UNSUBSCRIBE-EVENT "<link linkend='vidioc-subscribe-event'><constant>VIDIOC_UNSUBSCRIBE_EVENT</constant></link>">
89 93
94<!ENTITY MEDIA-IOC-DEVICE-INFO "<link linkend='media-ioc-device-info'><constant>MEDIA_IOC_DEVICE_INFO</constant></link>">
95
90<!-- Types --> 96<!-- Types -->
91<!ENTITY v4l2-std-id "<link linkend='v4l2-std-id'>v4l2_std_id</link>"> 97<!ENTITY v4l2-std-id "<link linkend='v4l2-std-id'>v4l2_std_id</link>">
92 98
@@ -184,6 +190,8 @@
184<!ENTITY v4l2-vbi-format "struct&nbsp;<link linkend='v4l2-vbi-format'>v4l2_vbi_format</link>"> 190<!ENTITY v4l2-vbi-format "struct&nbsp;<link linkend='v4l2-vbi-format'>v4l2_vbi_format</link>">
185<!ENTITY v4l2-window "struct&nbsp;<link linkend='v4l2-window'>v4l2_window</link>"> 191<!ENTITY v4l2-window "struct&nbsp;<link linkend='v4l2-window'>v4l2_window</link>">
186 192
193<!ENTITY media-device-info "struct&nbsp;<link linkend='media-device-info'>media_device_info</link>">
194
187<!-- Error Codes --> 195<!-- Error Codes -->
188<!ENTITY EACCES "<errorcode>EACCES</errorcode> error code"> 196<!ENTITY EACCES "<errorcode>EACCES</errorcode> error code">
189<!ENTITY EAGAIN "<errorcode>EAGAIN</errorcode> error code"> 197<!ENTITY EAGAIN "<errorcode>EAGAIN</errorcode> error code">
@@ -328,6 +336,10 @@
328<!ENTITY sub-media-indices SYSTEM "media-indices.tmpl"> 336<!ENTITY sub-media-indices SYSTEM "media-indices.tmpl">
329 337
330<!ENTITY sub-media-controller SYSTEM "v4l/media-controller.xml"> 338<!ENTITY sub-media-controller SYSTEM "v4l/media-controller.xml">
339<!ENTITY sub-media-open SYSTEM "v4l/media-func-open.xml">
340<!ENTITY sub-media-close SYSTEM "v4l/media-func-close.xml">
341<!ENTITY sub-media-ioctl SYSTEM "v4l/media-func-ioctl.xml">
342<!ENTITY sub-media-ioc-device-info SYSTEM "v4l/media-ioc-device-info.xml">
331 343
332<!-- Function Reference --> 344<!-- Function Reference -->
333<!ENTITY close SYSTEM "v4l/func-close.xml"> 345<!ENTITY close SYSTEM "v4l/func-close.xml">
diff --git a/Documentation/DocBook/v4l/media-controller.xml b/Documentation/DocBook/v4l/media-controller.xml
index f89228d3ec2a..a46b786e9f2b 100644
--- a/Documentation/DocBook/v4l/media-controller.xml
+++ b/Documentation/DocBook/v4l/media-controller.xml
@@ -74,3 +74,13 @@
74 pad to a sink pad.</para> 74 pad to a sink pad.</para>
75 </section> 75 </section>
76</chapter> 76</chapter>
77
78<appendix id="media-user-func">
79 <title>Function Reference</title>
80 <!-- Keep this alphabetically sorted. -->
81 &sub-media-open;
82 &sub-media-close;
83 &sub-media-ioctl;
84 <!-- All ioctls go here. -->
85 &sub-media-ioc-device-info;
86</appendix>
diff --git a/Documentation/DocBook/v4l/media-func-close.xml b/Documentation/DocBook/v4l/media-func-close.xml
new file mode 100644
index 000000000000..be149c802aeb
--- /dev/null
+++ b/Documentation/DocBook/v4l/media-func-close.xml
@@ -0,0 +1,59 @@
1<refentry id="media-func-close">
2 <refmeta>
3 <refentrytitle>media close()</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>media-close</refname>
9 <refpurpose>Close a media device</refpurpose>
10 </refnamediv>
11
12 <refsynopsisdiv>
13 <funcsynopsis>
14 <funcsynopsisinfo>#include &lt;unistd.h&gt;</funcsynopsisinfo>
15 <funcprototype>
16 <funcdef>int <function>close</function></funcdef>
17 <paramdef>int <parameter>fd</parameter></paramdef>
18 </funcprototype>
19 </funcsynopsis>
20 </refsynopsisdiv>
21
22 <refsect1>
23 <title>Arguments</title>
24
25 <variablelist>
26 <varlistentry>
27 <term><parameter>fd</parameter></term>
28 <listitem>
29 <para>&fd;</para>
30 </listitem>
31 </varlistentry>
32 </variablelist>
33 </refsect1>
34
35 <refsect1>
36 <title>Description</title>
37
38 <para>Closes the media device. Resources associated with the file descriptor
39 are freed. The device configuration remain unchanged.</para>
40 </refsect1>
41
42 <refsect1>
43 <title>Return Value</title>
44
45 <para><function>close</function> returns 0 on success. On error, -1 is
46 returned, and <varname>errno</varname> is set appropriately. Possible error
47 codes are:</para>
48
49 <variablelist>
50 <varlistentry>
51 <term><errorcode>EBADF</errorcode></term>
52 <listitem>
53 <para><parameter>fd</parameter> is not a valid open file descriptor.
54 </para>
55 </listitem>
56 </varlistentry>
57 </variablelist>
58 </refsect1>
59</refentry>
diff --git a/Documentation/DocBook/v4l/media-func-ioctl.xml b/Documentation/DocBook/v4l/media-func-ioctl.xml
new file mode 100644
index 000000000000..bda8604de15c
--- /dev/null
+++ b/Documentation/DocBook/v4l/media-func-ioctl.xml
@@ -0,0 +1,116 @@
1<refentry id="media-func-ioctl">
2 <refmeta>
3 <refentrytitle>media ioctl()</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>media-ioctl</refname>
9 <refpurpose>Control a media device</refpurpose>
10 </refnamediv>
11
12 <refsynopsisdiv>
13 <funcsynopsis>
14 <funcsynopsisinfo>#include &lt;sys/ioctl.h&gt;</funcsynopsisinfo>
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>void *<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>&fd;</para>
32 </listitem>
33 </varlistentry>
34 <varlistentry>
35 <term><parameter>request</parameter></term>
36 <listitem>
37 <para>Media ioctl request code as defined in the media.h header file,
38 for example MEDIA_IOC_SETUP_LINK.</para>
39 </listitem>
40 </varlistentry>
41 <varlistentry>
42 <term><parameter>argp</parameter></term>
43 <listitem>
44 <para>Pointer to a request-specific structure.</para>
45 </listitem>
46 </varlistentry>
47 </variablelist>
48 </refsect1>
49
50 <refsect1>
51 <title>Description</title>
52 <para>The <function>ioctl()</function> function manipulates media device
53 parameters. The argument <parameter>fd</parameter> must be an open file
54 descriptor.</para>
55 <para>The ioctl <parameter>request</parameter> code specifies the media
56 function to be called. It has encoded in it whether the argument is an
57 input, output or read/write parameter, and the size of the argument
58 <parameter>argp</parameter> in bytes.</para>
59 <para>Macros and structures definitions specifying media ioctl requests and
60 their parameters are located in the media.h header file. All media ioctl
61 requests, their respective function and parameters are specified in
62 <xref linkend="media-user-func" />.</para>
63 </refsect1>
64
65 <refsect1>
66 <title>Return Value</title>
67
68 <para><function>ioctl()</function> returns <returnvalue>0</returnvalue> on
69 success. On failure, <returnvalue>-1</returnvalue> is returned, and the
70 <varname>errno</varname> variable is set appropriately. Generic error codes
71 are listed below, and request-specific error codes are listed in the
72 individual requests descriptions.</para>
73 <para>When an ioctl that takes an output or read/write parameter fails,
74 the parameter remains unmodified.</para>
75
76 <variablelist>
77 <varlistentry>
78 <term><errorcode>EBADF</errorcode></term>
79 <listitem>
80 <para><parameter>fd</parameter> is not a valid open file descriptor.
81 </para>
82 </listitem>
83 </varlistentry>
84 <varlistentry>
85 <term><errorcode>EFAULT</errorcode></term>
86 <listitem>
87 <para><parameter>argp</parameter> references an inaccessible memory
88 area.</para>
89 </listitem>
90 </varlistentry>
91 <varlistentry>
92 <term><errorcode>EINVAL</errorcode></term>
93 <listitem>
94 <para>The <parameter>request</parameter> or the data pointed to by
95 <parameter>argp</parameter> is not valid. This is a very common error
96 code, see the individual ioctl requests listed in
97 <xref linkend="media-user-func" /> for actual causes.</para>
98 </listitem>
99 </varlistentry>
100 <varlistentry>
101 <term><errorcode>ENOMEM</errorcode></term>
102 <listitem>
103 <para>Insufficient kernel memory was available to complete the
104 request.</para>
105 </listitem>
106 </varlistentry>
107 <varlistentry>
108 <term><errorcode>ENOTTY</errorcode></term>
109 <listitem>
110 <para><parameter>fd</parameter> is not associated with a character
111 special device.</para>
112 </listitem>
113 </varlistentry>
114 </variablelist>
115 </refsect1>
116</refentry>
diff --git a/Documentation/DocBook/v4l/media-func-open.xml b/Documentation/DocBook/v4l/media-func-open.xml
new file mode 100644
index 000000000000..f7df034dc9ed
--- /dev/null
+++ b/Documentation/DocBook/v4l/media-func-open.xml
@@ -0,0 +1,94 @@
1<refentry id="media-func-open">
2 <refmeta>
3 <refentrytitle>media open()</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>media-open</refname>
9 <refpurpose>Open a media device</refpurpose>
10 </refnamediv>
11
12 <refsynopsisdiv>
13 <funcsynopsis>
14 <funcsynopsisinfo>#include &lt;fcntl.h&gt;</funcsynopsisinfo>
15 <funcprototype>
16 <funcdef>int <function>open</function></funcdef>
17 <paramdef>const char *<parameter>device_name</parameter></paramdef>
18 <paramdef>int <parameter>flags</parameter></paramdef>
19 </funcprototype>
20 </funcsynopsis>
21 </refsynopsisdiv>
22
23 <refsect1>
24 <title>Arguments</title>
25
26 <variablelist>
27 <varlistentry>
28 <term><parameter>device_name</parameter></term>
29 <listitem>
30 <para>Device to be opened.</para>
31 </listitem>
32 </varlistentry>
33 <varlistentry>
34 <term><parameter>flags</parameter></term>
35 <listitem>
36 <para>Open flags. Access mode must be either <constant>O_RDONLY</constant>
37 or <constant>O_RDWR</constant>. Other flags have no effect.</para>
38 </listitem>
39 </varlistentry>
40 </variablelist>
41 </refsect1>
42 <refsect1>
43 <title>Description</title>
44 <para>To open a media device applications call <function>open()</function>
45 with the desired device name. The function has no side effects; the device
46 configuration remain unchanged.</para>
47 <para>When the device is opened in read-only mode, attemps to modify its
48 configuration will result in an error, and <varname>errno</varname> will be
49 set to <errorcode>EBADF</errorcode>.</para>
50 </refsect1>
51 <refsect1>
52 <title>Return Value</title>
53
54 <para><function>open</function> returns the new file descriptor on success.
55 On error, -1 is returned, and <varname>errno</varname> is set appropriately.
56 Possible error codes are:</para>
57
58 <variablelist>
59 <varlistentry>
60 <term><errorcode>EACCES</errorcode></term>
61 <listitem>
62 <para>The requested access to the file is not allowed.</para>
63 </listitem>
64 </varlistentry>
65 <varlistentry>
66 <term><errorcode>EMFILE</errorcode></term>
67 <listitem>
68 <para>The process already has the maximum number of files open.
69 </para>
70 </listitem>
71 </varlistentry>
72 <varlistentry>
73 <term><errorcode>ENFILE</errorcode></term>
74 <listitem>
75 <para>The system limit on the total number of open files has been
76 reached.</para>
77 </listitem>
78 </varlistentry>
79 <varlistentry>
80 <term><errorcode>ENOMEM</errorcode></term>
81 <listitem>
82 <para>Insufficient kernel memory was available.</para>
83 </listitem>
84 </varlistentry>
85 <varlistentry>
86 <term><errorcode>ENXIO</errorcode></term>
87 <listitem>
88 <para>No device corresponding to this device special file exists.
89 </para>
90 </listitem>
91 </varlistentry>
92 </variablelist>
93 </refsect1>
94</refentry>
diff --git a/Documentation/DocBook/v4l/media-ioc-device-info.xml b/Documentation/DocBook/v4l/media-ioc-device-info.xml
new file mode 100644
index 000000000000..278a3120ee2e
--- /dev/null
+++ b/Documentation/DocBook/v4l/media-ioc-device-info.xml
@@ -0,0 +1,132 @@
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>&fd;</para>
31 </listitem>
32 </varlistentry>
33 <varlistentry>
34 <term><parameter>request</parameter></term>
35 <listitem>
36 <para>MEDIA_IOC_DEVICE_INFO</para>
37 </listitem>
38 </varlistentry>
39 <varlistentry>
40 <term><parameter>argp</parameter></term>
41 <listitem>
42 <para></para>
43 </listitem>
44 </varlistentry>
45 </variablelist>
46 </refsect1>
47
48 <refsect1>
49 <title>Description</title>
50
51 <para>All media devices must support the <constant>MEDIA_IOC_DEVICE_INFO</constant>
52 ioctl. To query device information, applications call the ioctl with a
53 pointer to a &media-device-info;. The driver fills the structure and returns
54 the information to the application.
55 The ioctl never fails.</para>
56
57 <table pgwide="1" frame="none" id="media-device-info">
58 <title>struct <structname>media_device_info</structname></title>
59 <tgroup cols="3">
60 &cs-str;
61 <tbody valign="top">
62 <row>
63 <entry>char</entry>
64 <entry><structfield>driver</structfield>[16]</entry>
65 <entry><para>Name of the driver implementing the media API as a
66 NUL-terminated ASCII string. The driver version is stored in the
67 <structfield>driver_version</structfield> field.</para>
68 <para>Driver specific applications can use this information to
69 verify the driver identity. It is also useful to work around
70 known bugs, or to identify drivers in error reports.</para></entry>
71 </row>
72 <row>
73 <entry>char</entry>
74 <entry><structfield>model</structfield>[32]</entry>
75 <entry>Device model name as a NUL-terminated UTF-8 string. The
76 device version is stored in the <structfield>device_version</structfield>
77 field and is not be appended to the model name.</entry>
78 </row>
79 <row>
80 <entry>char</entry>
81 <entry><structfield>serial</structfield>[40]</entry>
82 <entry>Serial number as a NUL-terminated ASCII string.</entry>
83 </row>
84 <row>
85 <entry>char</entry>
86 <entry><structfield>bus_info</structfield>[32]</entry>
87 <entry>Location of the device in the system as a NUL-terminated
88 ASCII string. This includes the bus type name (PCI, USB, ...) and a
89 bus-specific identifier.</entry>
90 </row>
91 <row>
92 <entry>__u32</entry>
93 <entry><structfield>media_version</structfield></entry>
94 <entry>Media API version, formatted with the
95 <constant>KERNEL_VERSION()</constant> macro.</entry>
96 </row>
97 <row>
98 <entry>__u32</entry>
99 <entry><structfield>hw_revision</structfield></entry>
100 <entry>Hardware device revision in a driver-specific format.</entry>
101 </row>
102 <row>
103 <entry>__u32</entry>
104 <entry><structfield>media_version</structfield></entry>
105 <entry>Media device driver version, formatted with the
106 <constant>KERNEL_VERSION()</constant> macro. Together with the
107 <structfield>driver</structfield> field this identifies a particular
108 driver.</entry>
109 </row>
110 <row>
111 <entry>__u32</entry>
112 <entry><structfield>reserved</structfield>[31]</entry>
113 <entry>Reserved for future extensions. Drivers and applications must
114 set this array to zero.</entry>
115 </row>
116 </tbody>
117 </tgroup>
118 </table>
119 <para>The <structfield>serial</structfield> and <structfield>bus_info</structfield>
120 fields can be used to distinguish between multiple instances of otherwise
121 identical hardware. The serial number takes precedence when provided and can
122 be assumed to be unique. If the serial number is an empty string, the
123 <structfield>bus_info</structfield> field can be used instead. The
124 <structfield>bus_info</structfield> field is guaranteed to be unique, but
125 can vary across reboots or device unplug/replug.</para>
126 </refsect1>
127
128 <refsect1>
129 <title>Return value</title>
130 <para>This function doesn't return specific error codes.</para>
131 </refsect1>
132</refentry>
generated by cgit v1.2.2 (git 2.25.0) at 2024-11-23 07:04:59 -0500