1.. Permission is granted to copy, distribute and/or modify this
2.. document under the terms of the GNU Free Documentation License,
3.. Version 1.1 or any later version published by the Free Software
4.. Foundation, with no Invariant Sections, no Front-Cover Texts
5.. and no Back-Cover Texts. A copy of the license is included at
6.. Documentation/userspace-api/media/fdl-appendix.rst.
7..
8.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
9
10.. _media_ioc_device_info:
11
12***************************
13ioctl MEDIA_IOC_DEVICE_INFO
14***************************
15
16Name
17====
18
19MEDIA_IOC_DEVICE_INFO - Query device information
20
21
22Synopsis
23========
24
25.. c:function:: int ioctl( int fd, MEDIA_IOC_DEVICE_INFO, struct media_device_info *argp )
26    :name: MEDIA_IOC_DEVICE_INFO
27
28
29Arguments
30=========
31
32``fd``
33    File descriptor returned by :ref:`open() <media-func-open>`.
34
35``argp``
36    Pointer to struct :c:type:`media_device_info`.
37
38
39Description
40===========
41
42All media devices must support the ``MEDIA_IOC_DEVICE_INFO`` ioctl. To
43query device information, applications call the ioctl with a pointer to
44a struct :c:type:`media_device_info`. The driver
45fills the structure and returns the information to the application. The
46ioctl never fails.
47
48
49.. c:type:: media_device_info
50
51.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
52
53.. flat-table:: struct media_device_info
54    :header-rows:  0
55    :stub-columns: 0
56    :widths:       1 1 2
57
58
59    *  -  char
60       -  ``driver``\ [16]
61       -  Name of the driver implementing the media API as a NUL-terminated
62	  ASCII string. The driver version is stored in the
63	  ``driver_version`` field.
64
65	  Driver specific applications can use this information to verify
66	  the driver identity. It is also useful to work around known bugs,
67	  or to identify drivers in error reports.
68
69    *  -  char
70       -  ``model``\ [32]
71       -  Device model name as a NUL-terminated UTF-8 string. The device
72	  version is stored in the ``device_version`` field and is not be
73	  appended to the model name.
74
75    *  -  char
76       -  ``serial``\ [40]
77       -  Serial number as a NUL-terminated ASCII string.
78
79    *  -  char
80       -  ``bus_info``\ [32]
81       -  Location of the device in the system as a NUL-terminated ASCII
82	  string. This includes the bus type name (PCI, USB, ...) and a
83	  bus-specific identifier.
84
85    *  -  __u32
86       -  ``media_version``
87       -  Media API version, formatted with the ``KERNEL_VERSION()`` macro.
88
89    *  -  __u32
90       -  ``hw_revision``
91       -  Hardware device revision in a driver-specific format.
92
93    *  -  __u32
94       -  ``driver_version``
95       -  Media device driver version, formatted with the
96	  ``KERNEL_VERSION()`` macro. Together with the ``driver`` field
97	  this identifies a particular driver.
98
99    *  -  __u32
100       -  ``reserved``\ [31]
101       -  Reserved for future extensions. Drivers and applications must set
102	  this array to zero.
103
104
105The ``serial`` and ``bus_info`` fields can be used to distinguish
106between multiple instances of otherwise identical hardware. The serial
107number takes precedence when provided and can be assumed to be unique.
108If the serial number is an empty string, the ``bus_info`` field can be
109used instead. The ``bus_info`` field is guaranteed to be unique, but can
110vary across reboots or device unplug/replug.
111
112
113Return Value
114============
115
116On success 0 is returned, on error -1 and the ``errno`` variable is set
117appropriately. The generic error codes are described at the
118:ref:`Generic Error Codes <gen-errors>` chapter.
119