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     Pointer to struct :c:type:`media_device_info`.
  30
  31
  32 Description
  33 ===========
  34
  35 All media devices must support the ``MEDIA_IOC_DEVICE_INFO`` ioctl. To
  36 query device information, applications call the ioctl with a pointer to
  37 a struct :c:type:`media_device_info`. The driver
  38 fills the structure and returns the information to the application. The
  39 ioctl never fails.
  40
  41
  42 .. c:type:: media_device_info
  43
  44 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  45
  46 .. flat-table:: struct media_device_info
  47     :header-rows:  0
  48     :stub-columns: 0
  49     :widths:       1 1 2
  50
  51
  52     *  -  char
  53        -  ``driver``\ [16]
  54        -  Name of the driver implementing the media API as a NUL-terminated
  55           ASCII string. The driver version is stored in the
  56           ``driver_version`` field.
  57
  58           Driver specific applications can use this information to verify
  59           the driver identity. It is also useful to work around known bugs,
  60           or to identify drivers in error reports.
  61
  62     *  -  char
  63        -  ``model``\ [32]
  64        -  Device model name as a NUL-terminated UTF-8 string. The device
  65           version is stored in the ``device_version`` field and is not be
  66           appended to the model name.
  67
  68     *  -  char
  69        -  ``serial``\ [40]
  70        -  Serial number as a NUL-terminated ASCII string.
  71
  72     *  -  char
  73        -  ``bus_info``\ [32]
  74        -  Location of the device in the system as a NUL-terminated ASCII
  75           string. This includes the bus type name (PCI, USB, ...) and a
  76           bus-specific identifier.
  77
  78     *  -  __u32
  79        -  ``media_version``
  80        -  Media API version, formatted with the ``KERNEL_VERSION()`` macro.
  81
  82     *  -  __u32
  83        -  ``hw_revision``
  84        -  Hardware device revision in a driver-specific format.
  85
  86     *  -  __u32
  87        -  ``driver_version``
  88        -  Media device driver version, formatted with the
  89           ``KERNEL_VERSION()`` macro. Together with the ``driver`` field
  90           this identifies a particular driver.
  91
  92     *  -  __u32
  93        -  ``reserved``\ [31]
  94        -  Reserved for future extensions. Drivers and applications must set
  95           this array to zero.
  96
  97
  98 The ``serial`` and ``bus_info`` fields can be used to distinguish
  99 between multiple instances of otherwise identical hardware. The serial
 100 number takes precedence when provided and can be assumed to be unique.
 101 If the serial number is an empty string, the ``bus_info`` field can be
 102 used instead. The ``bus_info`` field is guaranteed to be unique, but can
 103 vary across reboots or device unplug/replug.
 104
 105
 106 Return Value
 107 ============
 108
 109 On success 0 is returned, on error -1 and the ``errno`` variable is set
 110 appropriately. The generic error codes are described at the
 111 :ref:`Generic Error Codes <gen-errors>` chapter.