[deliverable/linux.git] / Documentation / media / uapi / mediactl / media-ioc-device-info.rst

.. -*- coding: utf-8; mode: rst -*-

.. _media_ioc_device_info:

***************************
ioctl MEDIA_IOC_DEVICE_INFO
***************************

Name
====

MEDIA_IOC_DEVICE_INFO - Query device information


Synopsis
========

.. cpp:function:: int ioctl( int fd, int request, struct media_device_info *argp )


Arguments
=========

``fd``
    File descriptor returned by :ref:`open() <media-func-open>`.

``request``
    MEDIA_IOC_DEVICE_INFO

``argp``


Description
===========

All media devices must support the ``MEDIA_IOC_DEVICE_INFO`` ioctl. To
query device information, applications call the ioctl with a pointer to
a struct :ref:`media_device_info <media-device-info>`. The driver
fills the structure and returns the information to the application. The
ioctl never fails.


.. _media-device-info:

.. flat-table:: struct media_device_info
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2


    -  .. row 1

       -  char

       -  ``driver``\ [16]

       -  Name of the driver implementing the media API as a NUL-terminated
	  ASCII string. The driver version is stored in the
	  ``driver_version`` field.

	  Driver specific applications can use this information to verify
	  the driver identity. It is also useful to work around known bugs,
	  or to identify drivers in error reports.

    -  .. row 2

       -  char

       -  ``model``\ [32]

       -  Device model name as a NUL-terminated UTF-8 string. The device
	  version is stored in the ``device_version`` field and is not be
	  appended to the model name.

    -  .. row 3

       -  char

       -  ``serial``\ [40]

       -  Serial number as a NUL-terminated ASCII string.

    -  .. row 4

       -  char

       -  ``bus_info``\ [32]

       -  Location of the device in the system as a NUL-terminated ASCII
	  string. This includes the bus type name (PCI, USB, ...) and a
	  bus-specific identifier.

    -  .. row 5

       -  __u32

       -  ``media_version``

       -  Media API version, formatted with the ``KERNEL_VERSION()`` macro.

    -  .. row 6

       -  __u32

       -  ``hw_revision``

       -  Hardware device revision in a driver-specific format.

    -  .. row 7

       -  __u32

       -  ``driver_version``

       -  Media device driver version, formatted with the
	  ``KERNEL_VERSION()`` macro. Together with the ``driver`` field
	  this identifies a particular driver.

    -  .. row 8

       -  __u32

       -  ``reserved``\ [31]

       -  Reserved for future extensions. Drivers and applications must set
	  this array to zero.


The ``serial`` and ``bus_info`` fields can be used to distinguish
between multiple instances of otherwise identical hardware. The serial
number takes precedence when provided and can be assumed to be unique.
If the serial number is an empty string, the ``bus_info`` field can be
used instead. The ``bus_info`` field is guaranteed to be unique, but can
vary across reboots or device unplug/replug.


Return Value
============

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
Commit	Line	Data
5377d91f MH	1	.. -- coding: utf-8; mode: rst --
5377d91f MH	2
d2c68150	3	.. _media_ioc_device_info:
5377d91f MH	4
	5	***************************
	6	ioctl MEDIA_IOC_DEVICE_INFO
	7	***************************
	8
15e7d615	9	Name
586027ce	10	====
5377d91f	11
586027ce	12	MEDIA_IOC_DEVICE_INFO - Query device information
5377d91f	13
15e7d615 MCC	14
15e7d615 MCC	15	Synopsis
5377d91f MH	16	========
5377d91f MH	17
b7e67f6c	18	.. cpp:function:: int ioctl( int fd, int request, struct media_device_info *argp )
5377d91f	19
586027ce	20
15e7d615	21	Arguments
5377d91f MH	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
15e7d615	33	Description
5377d91f MH	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	.. 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
0579e6e3 MCC	58	ASCII string. The driver version is stored in the
0579e6e3 MCC	59	``driver_version`` field.
5377d91f	60
0579e6e3 MCC	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.
5377d91f MH	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
0579e6e3 MCC	72	version is stored in the ``device_version`` field and is not be
0579e6e3 MCC	73	appended to the model name.
5377d91f MH	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
0579e6e3 MCC	90	string. This includes the bus type name (PCI, USB, ...) and a
0579e6e3 MCC	91	bus-specific identifier.
5377d91f MH	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
0579e6e3 MCC	116	``KERNEL_VERSION()`` macro. Together with the ``driver`` field
0579e6e3 MCC	117	this identifies a particular driver.
5377d91f MH	118
	119	- .. row 8
	120
	121	- __u32
	122
	123	- ``reserved``\ [31]
	124
	125	- Reserved for future extensions. Drivers and applications must set
0579e6e3	126	this array to zero.
5377d91f MH	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
15e7d615	137	Return Value
5377d91f MH	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.