summaryrefslogtreecommitdiff
path: root/Documentation/media/uapi/mediactl/media-ioc-device-info.rst
blob: 567f5515a79158d325ff4f96fcd7e254ae64aca9 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
.. -*- coding: utf-8; mode: rst -*-

.. _media_ioc_device_info:

***************************
ioctl MEDIA_IOC_DEVICE_INFO
***************************

Name
====

MEDIA_IOC_DEVICE_INFO - Query device information


Synopsis
========

.. cpp:function:: int ioctl( int fd, int request, struct media_device_info *argp )


Arguments
=========

``fd``
    File descriptor returned by :ref:`open() <media-func-open>`.

``request``
    MEDIA_IOC_DEVICE_INFO

``argp``


Description
===========

All media devices must support the ``MEDIA_IOC_DEVICE_INFO`` ioctl. To
query device information, applications call the ioctl with a pointer to
a struct :ref:`media_device_info <media-device-info>`. The driver
fills the structure and returns the information to the application. The
ioctl never fails.


.. _media-device-info:

.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|

.. flat-table:: struct media_device_info
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2


    -  .. row 1

       -  char

       -  ``driver``\ [16]

       -  Name of the driver implementing the media API as a NUL-terminated
	  ASCII string. The driver version is stored in the
	  ``driver_version`` field.

	  Driver specific applications can use this information to verify
	  the driver identity. It is also useful to work around known bugs,
	  or to identify drivers in error reports.

    -  .. row 2

       -  char

       -  ``model``\ [32]

       -  Device model name as a NUL-terminated UTF-8 string. The device
	  version is stored in the ``device_version`` field and is not be
	  appended to the model name.

    -  .. row 3

       -  char

       -  ``serial``\ [40]

       -  Serial number as a NUL-terminated ASCII string.

    -  .. row 4

       -  char

       -  ``bus_info``\ [32]

       -  Location of the device in the system as a NUL-terminated ASCII
	  string. This includes the bus type name (PCI, USB, ...) and a
	  bus-specific identifier.

    -  .. row 5

       -  __u32

       -  ``media_version``

       -  Media API version, formatted with the ``KERNEL_VERSION()`` macro.

    -  .. row 6

       -  __u32

       -  ``hw_revision``

       -  Hardware device revision in a driver-specific format.

    -  .. row 7

       -  __u32

       -  ``driver_version``

       -  Media device driver version, formatted with the
	  ``KERNEL_VERSION()`` macro. Together with the ``driver`` field
	  this identifies a particular driver.

    -  .. row 8

       -  __u32

       -  ``reserved``\ [31]

       -  Reserved for future extensions. Drivers and applications must set
	  this array to zero.


The ``serial`` and ``bus_info`` fields can be used to distinguish
between multiple instances of otherwise identical hardware. The serial
number takes precedence when provided and can be assumed to be unique.
If the serial number is an empty string, the ``bus_info`` field can be
used instead. The ``bus_info`` field is guaranteed to be unique, but can
vary across reboots or device unplug/replug.


Return Value
============

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.