Documentation/media/uapi/mediactl/media-ioc-device-info.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _media_ioc_device_info:
   4
   5 ***************************
   6 ioctl MEDIA_IOC_DEVICE_INFO
   7 ***************************
   8
   9 Name
  10 ====
  11
  12 MEDIA_IOC_DEVICE_INFO - Query device information
  13
  14
  15 Synopsis
  16 ========
  17
  18 .. c:function:: int ioctl( int fd, int request, struct media_device_info *argp )
  19
  20
  21 Arguments
  22 =========
  23
  24 ``fd``
  25     File descriptor returned by :ref:`open() <media-func-open>`.
  26
  27 ``request``
  28     MEDIA_IOC_DEVICE_INFO
  29
  30 ``argp``
  31
  32
  33 Description
  34 ===========
  35
  36 All media devices must support the ``MEDIA_IOC_DEVICE_INFO`` ioctl. To
  37 query device information, applications call the ioctl with a pointer to
  38 a struct :ref:`media_device_info <media-device-info>`. The driver
  39 fills the structure and returns the information to the application. The
  40 ioctl never fails.
  41
  42
  43 .. _media-device-info:
  44
  45 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  46
  47 .. flat-table:: struct media_device_info
  48     :header-rows:  0
  49     :stub-columns: 0
  50     :widths:       1 1 2
  51
  52
  53     -  .. row 1
  54
  55        -  char
  56
  57        -  ``driver``\ [16]
  58
  59        -  Name of the driver implementing the media API as a NUL-terminated
  60           ASCII string. The driver version is stored in the
  61           ``driver_version`` field.
  62
  63           Driver specific applications can use this information to verify
  64           the driver identity. It is also useful to work around known bugs,
  65           or to identify drivers in error reports.
  66
  67     -  .. row 2
  68
  69        -  char
  70
  71        -  ``model``\ [32]
  72
  73        -  Device model name as a NUL-terminated UTF-8 string. The device
  74           version is stored in the ``device_version`` field and is not be
  75           appended to the model name.
  76
  77     -  .. row 3
  78
  79        -  char
  80
  81        -  ``serial``\ [40]
  82
  83        -  Serial number as a NUL-terminated ASCII string.
  84
  85     -  .. row 4
  86
  87        -  char
  88
  89        -  ``bus_info``\ [32]
  90
  91        -  Location of the device in the system as a NUL-terminated ASCII
  92           string. This includes the bus type name (PCI, USB, ...) and a
  93           bus-specific identifier.
  94
  95     -  .. row 5
  96
  97        -  __u32
  98
  99        -  ``media_version``
 100
 101        -  Media API version, formatted with the ``KERNEL_VERSION()`` macro.
 102
 103     -  .. row 6
 104
 105        -  __u32
 106
 107        -  ``hw_revision``
 108
 109        -  Hardware device revision in a driver-specific format.
 110
 111     -  .. row 7
 112
 113        -  __u32
 114
 115        -  ``driver_version``
 116
 117        -  Media device driver version, formatted with the
 118           ``KERNEL_VERSION()`` macro. Together with the ``driver`` field
 119           this identifies a particular driver.
 120
 121     -  .. row 8
 122
 123        -  __u32
 124
 125        -  ``reserved``\ [31]
 126
 127        -  Reserved for future extensions. Drivers and applications must set
 128           this array to zero.
 129
 130
 131 The ``serial`` and ``bus_info`` fields can be used to distinguish
 132 between multiple instances of otherwise identical hardware. The serial
 133 number takes precedence when provided and can be assumed to be unique.
 134 If the serial number is an empty string, the ``bus_info`` field can be
 135 used instead. The ``bus_info`` field is guaranteed to be unique, but can
 136 vary across reboots or device unplug/replug.
 137
 138
 139 Return Value
 140 ============
 141
 142 On success 0 is returned, on error -1 and the ``errno`` variable is set
 143 appropriately. The generic error codes are described at the
 144 :ref:`Generic Error Codes <gen-errors>` chapter.