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