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