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

   1 .. Permission is granted to copy, distribute and/or modify this
   2 .. document under the terms of the GNU Free Documentation License,
   3 .. Version 1.1 or any later version published by the Free Software
   4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
   5 .. and no Back-Cover Texts. A copy of the license is included at
   6 .. Documentation/media/uapi/fdl-appendix.rst.
   7 ..
   8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
   9
  10 .. _media_ioc_device_info:
  11
  12 ***************************
  13 ioctl MEDIA_IOC_DEVICE_INFO
  14 ***************************
  15
  16 Name
  17 ====
  18
  19 MEDIA_IOC_DEVICE_INFO - Query device information
  20
  21
  22 Synopsis
  23 ========
  24
  25 .. c:function:: int ioctl( int fd, MEDIA_IOC_DEVICE_INFO, struct media_device_info *argp )
  26     :name: MEDIA_IOC_DEVICE_INFO
  27
  28
  29 Arguments
  30 =========
  31
  32 ``fd``
  33     File descriptor returned by :ref:`open() <media-func-open>`.
  34
  35 ``argp``
  36     Pointer to struct :c:type:`media_device_info`.
  37
  38
  39 Description
  40 ===========
  41
  42 All media devices must support the ``MEDIA_IOC_DEVICE_INFO`` ioctl. To
  43 query device information, applications call the ioctl with a pointer to
  44 a struct :c:type:`media_device_info`. The driver
  45 fills the structure and returns the information to the application. The
  46 ioctl never fails.
  47
  48
  49 .. c:type:: media_device_info
  50
  51 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  52
  53 .. flat-table:: struct media_device_info
  54     :header-rows:  0
  55     :stub-columns: 0
  56     :widths:       1 1 2
  57
  58
  59     *  -  char
  60        -  ``driver``\ [16]
  61        -  Name of the driver implementing the media API as a NUL-terminated
  62           ASCII string. The driver version is stored in the
  63           ``driver_version`` field.
  64
  65           Driver specific applications can use this information to verify
  66           the driver identity. It is also useful to work around known bugs,
  67           or to identify drivers in error reports.
  68
  69     *  -  char
  70        -  ``model``\ [32]
  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     *  -  char
  76        -  ``serial``\ [40]
  77        -  Serial number as a NUL-terminated ASCII string.
  78
  79     *  -  char
  80        -  ``bus_info``\ [32]
  81        -  Location of the device in the system as a NUL-terminated ASCII
  82           string. This includes the bus type name (PCI, USB, ...) and a
  83           bus-specific identifier.
  84
  85     *  -  __u32
  86        -  ``media_version``
  87        -  Media API version, formatted with the ``KERNEL_VERSION()`` macro.
  88
  89     *  -  __u32
  90        -  ``hw_revision``
  91        -  Hardware device revision in a driver-specific format.
  92
  93     *  -  __u32
  94        -  ``driver_version``
  95        -  Media device driver version, formatted with the
  96           ``KERNEL_VERSION()`` macro. Together with the ``driver`` field
  97           this identifies a particular driver.
  98
  99     *  -  __u32
 100        -  ``reserved``\ [31]
 101        -  Reserved for future extensions. Drivers and applications must set
 102           this array to zero.
 103
 104
 105 The ``serial`` and ``bus_info`` fields can be used to distinguish
 106 between multiple instances of otherwise identical hardware. The serial
 107 number takes precedence when provided and can be assumed to be unique.
 108 If the serial number is an empty string, the ``bus_info`` field can be
 109 used instead. The ``bus_info`` field is guaranteed to be unique, but can
 110 vary across reboots or device unplug/replug.
 111
 112
 113 Return Value
 114 ============
 115
 116 On success 0 is returned, on error -1 and the ``errno`` variable is set
 117 appropriately. The generic error codes are described at the
 118 :ref:`Generic Error Codes <gen-errors>` chapter.