media-ioc-device-info.rst

  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.