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