0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: MC
0003
0004 .. _media_ioc_device_info:
0005
0006 ***************************
0007 ioctl MEDIA_IOC_DEVICE_INFO
0008 ***************************
0009
0010 Name
0011 ====
0012
0013 MEDIA_IOC_DEVICE_INFO - Query device information
0014
0015 Synopsis
0016 ========
0017
0018 .. c:macro:: MEDIA_IOC_DEVICE_INFO
0019
0020 ``int ioctl(int fd, MEDIA_IOC_DEVICE_INFO, struct media_device_info *argp)``
0021
0022 Arguments
0023 =========
0024
0025 ``fd``
0026 File descriptor returned by :c:func:`open()`.
0027
0028 ``argp``
0029 Pointer to struct :c:type:`media_device_info`.
0030
0031 Description
0032 ===========
0033
0034 All media devices must support the ``MEDIA_IOC_DEVICE_INFO`` ioctl. To
0035 query device information, applications call the ioctl with a pointer to
0036 a struct :c:type:`media_device_info`. The driver
0037 fills the structure and returns the information to the application. The
0038 ioctl never fails.
0039
0040 .. c:type:: media_device_info
0041
0042 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
0043
0044 .. flat-table:: struct media_device_info
0045 :header-rows: 0
0046 :stub-columns: 0
0047 :widths: 1 1 2
0048
0049 * - char
0050 - ``driver``\ [16]
0051 - Name of the driver implementing the media API as a NUL-terminated
0052 ASCII string. The driver version is stored in the
0053 ``driver_version`` field.
0054
0055 Driver specific applications can use this information to verify
0056 the driver identity. It is also useful to work around known bugs,
0057 or to identify drivers in error reports.
0058
0059 * - char
0060 - ``model``\ [32]
0061 - Device model name as a NUL-terminated UTF-8 string. The device
0062 version is stored in the ``device_version`` field and is not be
0063 appended to the model name.
0064
0065 * - char
0066 - ``serial``\ [40]
0067 - Serial number as a NUL-terminated ASCII string.
0068
0069 * - char
0070 - ``bus_info``\ [32]
0071 - Location of the device in the system as a NUL-terminated ASCII
0072 string. This includes the bus type name (PCI, USB, ...) and a
0073 bus-specific identifier.
0074
0075 * - __u32
0076 - ``media_version``
0077 - Media API version, formatted with the ``KERNEL_VERSION()`` macro.
0078
0079 * - __u32
0080 - ``hw_revision``
0081 - Hardware device revision in a driver-specific format.
0082
0083 * - __u32
0084 - ``driver_version``
0085 - Media device driver version, formatted with the
0086 ``KERNEL_VERSION()`` macro. Together with the ``driver`` field
0087 this identifies a particular driver.
0088
0089 * - __u32
0090 - ``reserved``\ [31]
0091 - Reserved for future extensions. Drivers and applications must set
0092 this array to zero.
0093
0094 The ``serial`` and ``bus_info`` fields can be used to distinguish
0095 between multiple instances of otherwise identical hardware. The serial
0096 number takes precedence when provided and can be assumed to be unique.
0097 If the serial number is an empty string, the ``bus_info`` field can be
0098 used instead. The ``bus_info`` field is guaranteed to be unique, but can
0099 vary across reboots or device unplug/replug.
0100
0101 Return Value
0102 ============
0103
0104 On success 0 is returned, on error -1 and the ``errno`` variable is set
0105 appropriately. The generic error codes are described at the
0106 :ref:`Generic Error Codes <gen-errors>` chapter.
