Documentation/userspace-api/media/mediactl/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 ***************************
   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.7cm}|
  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.