media-ioc-device-info.rst (3123B)
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2.. c:namespace:: MC 3 4.. _media_ioc_device_info: 5 6*************************** 7ioctl MEDIA_IOC_DEVICE_INFO 8*************************** 9 10Name 11==== 12 13MEDIA_IOC_DEVICE_INFO - Query device information 14 15Synopsis 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 22Arguments 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 31Description 32=========== 33 34All media devices must support the ``MEDIA_IOC_DEVICE_INFO`` ioctl. To 35query device information, applications call the ioctl with a pointer to 36a struct :c:type:`media_device_info`. The driver 37fills the structure and returns the information to the application. The 38ioctl 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 94The ``serial`` and ``bus_info`` fields can be used to distinguish 95between multiple instances of otherwise identical hardware. The serial 96number takes precedence when provided and can be assumed to be unique. 97If the serial number is an empty string, the ``bus_info`` field can be 98used instead. The ``bus_info`` field is guaranteed to be unique, but can 99vary across reboots or device unplug/replug. 100 101Return Value 102============ 103 104On success 0 is returned, on error -1 and the ``errno`` variable is set 105appropriately. The generic error codes are described at the 106:ref:`Generic Error Codes <gen-errors>` chapter.