From: Mauro Carvalho Chehab Date: Mon, 4 Jul 2016 16:35:10 +0000 (-0300) Subject: doc-rst: linux_tv: move MC stuff to a separate dir X-Git-Url: https://git.stricted.de/?a=commitdiff_plain;h=7322c84c8aa391d42becd6f4d285c0f7a2bac2c3;p=GitHub%2FLineageOS%2Fandroid_kernel_motorola_exynos9610.git doc-rst: linux_tv: move MC stuff to a separate dir When we wrote the media controller's section, we re-used the V4L, just because we were lazy to create a brand new DocBook. Yet, it is a little ackward to have it mixed with V4L. So, move it to its own directory, in order to have it better organized. No functional changes. Signed-off-by: Mauro Carvalho Chehab --- diff --git a/Documentation/linux_tv/index.rst b/Documentation/linux_tv/index.rst index d3a243c86ba7..91c4ce570cb9 100644 --- a/Documentation/linux_tv/index.rst +++ b/Documentation/linux_tv/index.rst @@ -71,7 +71,7 @@ etc, please mail to: media/v4l/v4l2 media/dvb/dvbapi media/rc/remote_controllers - media/v4l/media-controller + media/mediactl/media-controller media/v4l/gen-errors media/v4l/fdl-appendix diff --git a/Documentation/linux_tv/media/mediactl/media-controller-intro.rst b/Documentation/linux_tv/media/mediactl/media-controller-intro.rst new file mode 100644 index 000000000000..3e776c0d8276 --- /dev/null +++ b/Documentation/linux_tv/media/mediactl/media-controller-intro.rst @@ -0,0 +1,33 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _media-controller-intro: + +Introduction +============ + +Media devices increasingly handle multiple related functions. Many USB +cameras include microphones, video capture hardware can also output +video, or SoC camera interfaces also perform memory-to-memory operations +similar to video codecs. + +Independent functions, even when implemented in the same hardware, can +be modelled as separate devices. A USB camera with a microphone will be +presented to userspace applications as V4L2 and ALSA capture devices. +The devices' relationships (when using a webcam, end-users shouldn't +have to manually select the associated USB microphone), while not made +available directly to applications by the drivers, can usually be +retrieved from sysfs. + +With more and more advanced SoC devices being introduced, the current +approach will not scale. Device topologies are getting increasingly +complex and can't always be represented by a tree structure. Hardware +blocks are shared between different functions, creating dependencies +between seemingly unrelated devices. + +Kernel abstraction APIs such as V4L2 and ALSA provide means for +applications to access hardware parameters. As newer hardware expose an +increasingly high number of those parameters, drivers need to guess what +applications really require based on limited information, thereby +implementing policies that belong to userspace. + +The media controller API aims at solving those problems. diff --git a/Documentation/linux_tv/media/mediactl/media-controller-model.rst b/Documentation/linux_tv/media/mediactl/media-controller-model.rst new file mode 100644 index 000000000000..7be58aecb882 --- /dev/null +++ b/Documentation/linux_tv/media/mediactl/media-controller-model.rst @@ -0,0 +1,35 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _media-controller-model: + +Media device model +================== + +Discovering a device internal topology, and configuring it at runtime, +is one of the goals of the media controller API. To achieve this, +hardware devices and Linux Kernel interfaces are modelled as graph +objects on an oriented graph. The object types that constitute the graph +are: + +- An **entity** is a basic media hardware or software building block. + It can correspond to a large variety of logical blocks such as + physical hardware devices (CMOS sensor for instance), logical + hardware devices (a building block in a System-on-Chip image + processing pipeline), DMA channels or physical connectors. + +- An **interface** is a graph representation of a Linux Kernel + userspace API interface, like a device node or a sysfs file that + controls one or more entities in the graph. + +- A **pad** is a data connection endpoint through which an entity can + interact with other entities. Data (not restricted to video) produced + by an entity flows from the entity's output to one or more entity + inputs. Pads should not be confused with physical pins at chip + boundaries. + +- A **data link** is a point-to-point oriented connection between two + pads, either on the same entity or on different entities. Data flows + from a source pad to a sink pad. + +- An **interface link** is a point-to-point bidirectional control + connection between a Linux Kernel interface and an entity.m diff --git a/Documentation/linux_tv/media/mediactl/media-controller.rst b/Documentation/linux_tv/media/mediactl/media-controller.rst new file mode 100644 index 000000000000..49fb76cafcab --- /dev/null +++ b/Documentation/linux_tv/media/mediactl/media-controller.rst @@ -0,0 +1,57 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _media_common: + +#################### +Media Controller API +#################### + +.. _media_controller: + +**************** +Media Controller +**************** + + +.. toctree:: + :maxdepth: 1 + + media-controller-intro + media-controller-model + media-types + + +.. _media-user-func: + +****************** +Function Reference +****************** + + +.. toctree:: + :maxdepth: 1 + + media-func-open + media-func-close + media-func-ioctl + media-ioc-device-info + media-ioc-g-topology + media-ioc-enum-entities + media-ioc-enum-links + media-ioc-setup-link + + +********************** +Revision and Copyright +********************** + + +:author: Pinchart Laurent +:address: laurent.pinchart@ideasonboard.com +:contrib: Initial version. + +**Copyright** 2010 : Laurent Pinchart + +:revision: 1.0.0 / 2010-11-10 (*lp*) + +Initial revision diff --git a/Documentation/linux_tv/media/mediactl/media-func-close.rst b/Documentation/linux_tv/media/mediactl/media-func-close.rst new file mode 100644 index 000000000000..109b831e4047 --- /dev/null +++ b/Documentation/linux_tv/media/mediactl/media-func-close.rst @@ -0,0 +1,45 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _media-func-close: + +************* +media close() +************* + +*man media-close(2)* + +Close a media device + + +Synopsis +======== + +.. code-block:: c + + #include + + +.. cpp:function:: int close( int fd ) + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() `. + + +Description +=========== + +Closes the media device. Resources associated with the file descriptor +are freed. The device configuration remain unchanged. + + +Return Value +============ + +:ref:`close() ` returns 0 on success. On error, -1 is returned, and +``errno`` is set appropriately. Possible error codes are: + +EBADF + ``fd`` is not a valid open file descriptor. diff --git a/Documentation/linux_tv/media/mediactl/media-func-ioctl.rst b/Documentation/linux_tv/media/mediactl/media-func-ioctl.rst new file mode 100644 index 000000000000..c56ccb9c9b39 --- /dev/null +++ b/Documentation/linux_tv/media/mediactl/media-func-ioctl.rst @@ -0,0 +1,65 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _media-func-ioctl: + +************* +media ioctl() +************* + +*man media-ioctl(2)* + +Control a media device + + +Synopsis +======== + +.. code-block:: c + + #include + + +.. cpp:function:: int ioctl( int fd, int request, void *argp ) + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() `. + +``request`` + Media ioctl request code as defined in the media.h header file, for + example MEDIA_IOC_SETUP_LINK. + +``argp`` + Pointer to a request-specific structure. + + +Description +=========== + +The :ref:`ioctl() ` function manipulates media device parameters. +The argument ``fd`` must be an open file descriptor. + +The ioctl ``request`` code specifies the media function to be called. It +has encoded in it whether the argument is an input, output or read/write +parameter, and the size of the argument ``argp`` in bytes. + +Macros and structures definitions specifying media ioctl requests and +their parameters are located in the media.h header file. All media ioctl +requests, their respective function and parameters are specified in +:ref:`media-user-func`. + + +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 ` chapter. + +Request-specific error codes are listed in the individual requests +descriptions. + +When an ioctl that takes an output or read/write parameter fails, the +parameter remains unmodified. diff --git a/Documentation/linux_tv/media/mediactl/media-func-open.rst b/Documentation/linux_tv/media/mediactl/media-func-open.rst new file mode 100644 index 000000000000..627860b33ae2 --- /dev/null +++ b/Documentation/linux_tv/media/mediactl/media-func-open.rst @@ -0,0 +1,67 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _media-func-open: + +************ +media open() +************ + +*man media-open(2)* + +Open a media device + + +Synopsis +======== + +.. code-block:: c + + #include + + +.. cpp:function:: int open( const char *device_name, int flags ) + +Arguments +========= + +``device_name`` + Device to be opened. + +``flags`` + Open flags. Access mode must be either ``O_RDONLY`` or ``O_RDWR``. + Other flags have no effect. + + +Description +=========== + +To open a media device applications call :ref:`open() ` with the +desired device name. The function has no side effects; the device +configuration remain unchanged. + +When the device is opened in read-only mode, attempts to modify its +configuration will result in an error, and ``errno`` will be set to +EBADF. + + +Return Value +============ + +:ref:`open() ` returns the new file descriptor on success. On error, +-1 is returned, and ``errno`` is set appropriately. Possible error codes +are: + +EACCES + The requested access to the file is not allowed. + +EMFILE + The process already has the maximum number of files open. + +ENFILE + The system limit on the total number of open files has been reached. + +ENOMEM + Insufficient kernel memory was available. + +ENXIO + No device corresponding to this device special file exists. diff --git a/Documentation/linux_tv/media/mediactl/media-ioc-device-info.rst b/Documentation/linux_tv/media/mediactl/media-ioc-device-info.rst new file mode 100644 index 000000000000..aca9c8aa736a --- /dev/null +++ b/Documentation/linux_tv/media/mediactl/media-ioc-device-info.rst @@ -0,0 +1,140 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _media-ioc-device-info: + +*************************** +ioctl MEDIA_IOC_DEVICE_INFO +*************************** + +*man MEDIA_IOC_DEVICE_INFO(2)* + +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() `. + +``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 `. 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 ` chapter. diff --git a/Documentation/linux_tv/media/mediactl/media-ioc-enum-entities.rst b/Documentation/linux_tv/media/mediactl/media-ioc-enum-entities.rst new file mode 100644 index 000000000000..8fe1f1966640 --- /dev/null +++ b/Documentation/linux_tv/media/mediactl/media-ioc-enum-entities.rst @@ -0,0 +1,195 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _media-ioc-enum-entities: + +***************************** +ioctl MEDIA_IOC_ENUM_ENTITIES +***************************** + +*man MEDIA_IOC_ENUM_ENTITIES(2)* + +Enumerate entities and their properties + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct media_entity_desc *argp ) + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() `. + +``request`` + MEDIA_IOC_ENUM_ENTITIES + +``argp`` + + +Description +=========== + +To query the attributes of an entity, applications set the id field of a +struct :ref:`media_entity_desc ` structure and +call the MEDIA_IOC_ENUM_ENTITIES ioctl with a pointer to this +structure. The driver fills the rest of the structure or returns an +EINVAL error code when the id is invalid. + +Entities can be enumerated by or'ing the id with the +``MEDIA_ENT_ID_FLAG_NEXT`` flag. The driver will return information +about the entity with the smallest id strictly larger than the requested +one ('next entity'), or the ``EINVAL`` error code if there is none. + +Entity IDs can be non-contiguous. Applications must *not* try to +enumerate entities by calling MEDIA_IOC_ENUM_ENTITIES with increasing +id's until they get an error. + + +.. _media-entity-desc: + +.. flat-table:: struct media_entity_desc + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - __u32 + + - ``id`` + + - + - + - Entity id, set by the application. When the id is or'ed with + ``MEDIA_ENT_ID_FLAG_NEXT``, the driver clears the flag and returns + the first entity with a larger id. + + - .. row 2 + + - char + + - ``name``\ [32] + + - + - + - Entity name as an UTF-8 NULL-terminated string. + + - .. row 3 + + - __u32 + + - ``type`` + + - + - + - Entity type, see :ref:`media-entity-type` for details. + + - .. row 4 + + - __u32 + + - ``revision`` + + - + - + - Entity revision. Always zero (obsolete) + + - .. row 5 + + - __u32 + + - ``flags`` + + - + - + - Entity flags, see :ref:`media-entity-flag` for details. + + - .. row 6 + + - __u32 + + - ``group_id`` + + - + - + - Entity group ID. Always zero (obsolete) + + - .. row 7 + + - __u16 + + - ``pads`` + + - + - + - Number of pads + + - .. row 8 + + - __u16 + + - ``links`` + + - + - + - Total number of outbound links. Inbound links are not counted in + this field. + + - .. row 9 + + - union + + - .. row 10 + + - + - struct + + - ``dev`` + + - + - Valid for (sub-)devices that create a single device node. + + - .. row 11 + + - + - + - __u32 + + - ``major`` + + - Device node major number. + + - .. row 12 + + - + - + - __u32 + + - ``minor`` + + - Device node minor number. + + - .. row 13 + + - + - __u8 + + - ``raw``\ [184] + + - + - + + + +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 ` chapter. + +EINVAL + The struct :ref:`media_entity_desc ` ``id`` + references a non-existing entity. diff --git a/Documentation/linux_tv/media/mediactl/media-ioc-enum-links.rst b/Documentation/linux_tv/media/mediactl/media-ioc-enum-links.rst new file mode 100644 index 000000000000..6989f4ae4748 --- /dev/null +++ b/Documentation/linux_tv/media/mediactl/media-ioc-enum-links.rst @@ -0,0 +1,171 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _media-ioc-enum-links: + +************************** +ioctl MEDIA_IOC_ENUM_LINKS +************************** + +*man MEDIA_IOC_ENUM_LINKS(2)* + +Enumerate all pads and links for a given entity + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct media_links_enum *argp ) + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() `. + +``request`` + MEDIA_IOC_ENUM_LINKS + +``argp`` + + +Description +=========== + +To enumerate pads and/or links for a given entity, applications set the +entity field of a struct :ref:`media_links_enum ` +structure and initialize the struct +:ref:`media_pad_desc ` and struct +:ref:`media_link_desc ` structure arrays pointed by +the ``pads`` and ``links`` fields. They then call the +MEDIA_IOC_ENUM_LINKS ioctl with a pointer to this structure. + +If the ``pads`` field is not NULL, the driver fills the ``pads`` array +with information about the entity's pads. The array must have enough +room to store all the entity's pads. The number of pads can be retrieved +with the :ref:`MEDIA_IOC_ENUM_ENTITIES ` +ioctl. + +If the ``links`` field is not NULL, the driver fills the ``links`` array +with information about the entity's outbound links. The array must have +enough room to store all the entity's outbound links. The number of +outbound links can be retrieved with the +:ref:`MEDIA_IOC_ENUM_ENTITIES ` ioctl. + +Only forward links that originate at one of the entity's source pads are +returned during the enumeration process. + + +.. _media-links-enum: + +.. flat-table:: struct media_links_enum + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``entity`` + + - Entity id, set by the application. + + - .. row 2 + + - struct :ref:`media_pad_desc ` + + - \*\ ``pads`` + + - Pointer to a pads array allocated by the application. Ignored if + NULL. + + - .. row 3 + + - struct :ref:`media_link_desc ` + + - \*\ ``links`` + + - Pointer to a links array allocated by the application. Ignored if + NULL. + + + +.. _media-pad-desc: + +.. flat-table:: struct media_pad_desc + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``entity`` + + - ID of the entity this pad belongs to. + + - .. row 2 + + - __u16 + + - ``index`` + + - 0-based pad index. + + - .. row 3 + + - __u32 + + - ``flags`` + + - Pad flags, see :ref:`media-pad-flag` for more details. + + + +.. _media-link-desc: + +.. flat-table:: struct media_link_desc + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - struct :ref:`media_pad_desc ` + + - ``source`` + + - Pad at the origin of this link. + + - .. row 2 + + - struct :ref:`media_pad_desc ` + + - ``sink`` + + - Pad at the target of this link. + + - .. row 3 + + - __u32 + + - ``flags`` + + - Link flags, see :ref:`media-link-flag` for more details. + + + +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 ` chapter. + +EINVAL + The struct :ref:`media_links_enum ` ``id`` + references a non-existing entity. diff --git a/Documentation/linux_tv/media/mediactl/media-ioc-g-topology.rst b/Documentation/linux_tv/media/mediactl/media-ioc-g-topology.rst new file mode 100644 index 000000000000..6d530dc2a92c --- /dev/null +++ b/Documentation/linux_tv/media/mediactl/media-ioc-g-topology.rst @@ -0,0 +1,427 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _media-g-topology: + +************************** +ioctl MEDIA_IOC_G_TOPOLOGY +************************** + +*man MEDIA_IOC_G_TOPOLOGY(2)* + +Enumerate the graph topology and graph element properties + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct media_v2_topology *argp ) + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() `. + +``request`` + MEDIA_IOC_G_TOPOLOGY + +``argp`` + + +Description +=========== + +The typical usage of this ioctl is to call it twice. On the first call, +the structure defined at struct +:ref:`media_v2_topology ` should be zeroed. At +return, if no errors happen, this ioctl will return the +``topology_version`` and the total number of entities, interfaces, pads +and links. + +Before the second call, the userspace should allocate arrays to store +the graph elements that are desired, putting the pointers to them at the +ptr_entities, ptr_interfaces, ptr_links and/or ptr_pads, keeping the +other values untouched. + +If the ``topology_version`` remains the same, the ioctl should fill the +desired arrays with the media graph elements. + + +.. _media-v2-topology: + +.. flat-table:: struct media_v2_topology + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - __u64 + + - ``topology_version`` + + - + - + - Version of the media graph topology. When the graph is created, + this field starts with zero. Every time a graph element is added + or removed, this field is incremented. + + - .. row 2 + + - __u64 + + - ``num_entities`` + + - + - + - Number of entities in the graph + + - .. row 3 + + - __u64 + + - ``ptr_entities`` + + - + - + - A pointer to a memory area where the entities array will be + stored, converted to a 64-bits integer. It can be zero. if zero, + the ioctl won't store the entities. It will just update + ``num_entities`` + + - .. row 4 + + - __u64 + + - ``num_interfaces`` + + - + - + - Number of interfaces in the graph + + - .. row 5 + + - __u64 + + - ``ptr_interfaces`` + + - + - + - A pointer to a memory area where the interfaces array will be + stored, converted to a 64-bits integer. It can be zero. if zero, + the ioctl won't store the interfaces. It will just update + ``num_interfaces`` + + - .. row 6 + + - __u64 + + - ``num_pads`` + + - + - + - Total number of pads in the graph + + - .. row 7 + + - __u64 + + - ``ptr_pads`` + + - + - + - A pointer to a memory area where the pads array will be stored, + converted to a 64-bits integer. It can be zero. if zero, the ioctl + won't store the pads. It will just update ``num_pads`` + + - .. row 8 + + - __u64 + + - ``num_links`` + + - + - + - Total number of data and interface links in the graph + + - .. row 9 + + - __u64 + + - ``ptr_links`` + + - + - + - A pointer to a memory area where the links array will be stored, + converted to a 64-bits integer. It can be zero. if zero, the ioctl + won't store the links. It will just update ``num_links`` + + + +.. _media-v2-entity: + +.. flat-table:: struct media_v2_entity + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - __u32 + + - ``id`` + + - + - + - Unique ID for the entity. + + - .. row 2 + + - char + + - ``name``\ [64] + + - + - + - Entity name as an UTF-8 NULL-terminated string. + + - .. row 3 + + - __u32 + + - ``function`` + + - + - + - Entity main function, see :ref:`media-entity-type` for details. + + - .. row 4 + + - __u32 + + - ``reserved``\ [12] + + - Reserved for future extensions. Drivers and applications must set + this array to zero. + + + +.. _media-v2-interface: + +.. flat-table:: struct media_v2_interface + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - __u32 + + - ``id`` + + - + - + - Unique ID for the interface. + + - .. row 2 + + - __u32 + + - ``intf_type`` + + - + - + - Interface type, see :ref:`media-intf-type` for details. + + - .. row 3 + + - __u32 + + - ``flags`` + + - + - + - Interface flags. Currently unused. + + - .. row 4 + + - __u32 + + - ``reserved``\ [9] + + - + - + - Reserved for future extensions. Drivers and applications must set + this array to zero. + + - .. row 5 + + - struct media_v2_intf_devnode + + - ``devnode`` + + - + - + - Used only for device node interfaces. See + :ref:`media-v2-intf-devnode` for details.. + + + +.. _media-v2-intf-devnode: + +.. flat-table:: struct media_v2_interface + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - __u32 + + - ``major`` + + - + - + - Device node major number. + + - .. row 2 + + - __u32 + + - ``minor`` + + - + - + - Device node minor number. + + + +.. _media-v2-pad: + +.. flat-table:: struct media_v2_pad + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - __u32 + + - ``id`` + + - + - + - Unique ID for the pad. + + - .. row 2 + + - __u32 + + - ``entity_id`` + + - + - + - Unique ID for the entity where this pad belongs. + + - .. row 3 + + - __u32 + + - ``flags`` + + - + - + - Pad flags, see :ref:`media-pad-flag` for more details. + + - .. row 4 + + - __u32 + + - ``reserved``\ [9] + + - + - + - Reserved for future extensions. Drivers and applications must set + this array to zero. + + + +.. _media-v2-link: + +.. flat-table:: struct media_v2_pad + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - __u32 + + - ``id`` + + - + - + - Unique ID for the pad. + + - .. row 2 + + - __u32 + + - ``source_id`` + + - + - + - On pad to pad links: unique ID for the source pad. + + On interface to entity links: unique ID for the interface. + + - .. row 3 + + - __u32 + + - ``sink_id`` + + - + - + - On pad to pad links: unique ID for the sink pad. + + On interface to entity links: unique ID for the entity. + + - .. row 4 + + - __u32 + + - ``flags`` + + - + - + - Link flags, see :ref:`media-link-flag` for more details. + + - .. row 5 + + - __u32 + + - ``reserved``\ [5] + + - + - + - Reserved for future extensions. Drivers and applications must set + this array to zero. + + + +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 ` chapter. + +ENOSPC + This is returned when either one or more of the num_entities, + num_interfaces, num_links or num_pads are non-zero and are + smaller than the actual number of elements inside the graph. This + may happen if the ``topology_version`` changed when compared to the + last time this ioctl was called. Userspace should usually free the + area for the pointers, zero the struct elements and call this ioctl + again. diff --git a/Documentation/linux_tv/media/mediactl/media-ioc-setup-link.rst b/Documentation/linux_tv/media/mediactl/media-ioc-setup-link.rst new file mode 100644 index 000000000000..135fa782dcd2 --- /dev/null +++ b/Documentation/linux_tv/media/mediactl/media-ioc-setup-link.rst @@ -0,0 +1,66 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _media-ioc-setup-link: + +************************** +ioctl MEDIA_IOC_SETUP_LINK +************************** + +*man MEDIA_IOC_SETUP_LINK(2)* + +Modify the properties of a link + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct media_link_desc *argp ) + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() `. + +``request`` + MEDIA_IOC_SETUP_LINK + +``argp`` + + +Description +=========== + +To change link properties applications fill a struct +:ref:`media_link_desc ` with link identification +information (source and sink pad) and the new requested link flags. They +then call the MEDIA_IOC_SETUP_LINK ioctl with a pointer to that +structure. + +The only configurable property is the ``ENABLED`` link flag to +enable/disable a link. Links marked with the ``IMMUTABLE`` link flag can +not be enabled or disabled. + +Link configuration has no side effect on other links. If an enabled link +at the sink pad prevents the link from being enabled, the driver returns +with an ``EBUSY`` error code. + +Only links marked with the ``DYNAMIC`` link flag can be enabled/disabled +while streaming media data. Attempting to enable or disable a streaming +non-dynamic link will return an ``EBUSY`` error code. + +If the specified link can't be found the driver returns with an ``EINVAL`` +error code. + + +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 ` chapter. + +EINVAL + The struct :ref:`media_link_desc ` references a + non-existing link, or the link is immutable and an attempt to modify + its configuration was made. diff --git a/Documentation/linux_tv/media/mediactl/media-types.rst b/Documentation/linux_tv/media/mediactl/media-types.rst new file mode 100644 index 000000000000..6a2d001babc2 --- /dev/null +++ b/Documentation/linux_tv/media/mediactl/media-types.rst @@ -0,0 +1,422 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _media-controller-types: + +Types and flags used to represent the media graph elements +========================================================== + + +.. _media-entity-type: + +.. flat-table:: Media entity types + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``MEDIA_ENT_F_UNKNOWN`` and ``MEDIA_ENT_F_V4L2_SUBDEV_UNKNOWN`` + + - Unknown entity. That generally indicates that a driver didn't + initialize properly the entity, with is a Kernel bug + + - .. row 2 + + - ``MEDIA_ENT_F_IO_V4L`` + + - Data streaming input and/or output entity. + + - .. row 3 + + - ``MEDIA_ENT_F_IO_VBI`` + + - V4L VBI streaming input or output entity + + - .. row 4 + + - ``MEDIA_ENT_F_IO_SWRADIO`` + + - V4L Software Digital Radio (SDR) streaming input or output entity + + - .. row 5 + + - ``MEDIA_ENT_F_IO_DTV`` + + - DVB Digital TV streaming input or output entity + + - .. row 6 + + - ``MEDIA_ENT_F_DTV_DEMOD`` + + - Digital TV demodulator entity. + + - .. row 7 + + - ``MEDIA_ENT_F_TS_DEMUX`` + + - MPEG Transport stream demux entity. Could be implemented on + hardware or in Kernelspace by the Linux DVB subsystem. + + - .. row 8 + + - ``MEDIA_ENT_F_DTV_CA`` + + - Digital TV Conditional Access module (CAM) entity + + - .. row 9 + + - ``MEDIA_ENT_F_DTV_NET_DECAP`` + + - Digital TV network ULE/MLE desencapsulation entity. Could be + implemented on hardware or in Kernelspace + + - .. row 10 + + - ``MEDIA_ENT_F_CONN_RF`` + + - Connector for a Radio Frequency (RF) signal. + + - .. row 11 + + - ``MEDIA_ENT_F_CONN_SVIDEO`` + + - Connector for a S-Video signal. + + - .. row 12 + + - ``MEDIA_ENT_F_CONN_COMPOSITE`` + + - Connector for a RGB composite signal. + + - .. row 13 + + - ``MEDIA_ENT_F_CAM_SENSOR`` + + - Camera video sensor entity. + + - .. row 14 + + - ``MEDIA_ENT_F_FLASH`` + + - Flash controller entity. + + - .. row 15 + + - ``MEDIA_ENT_F_LENS`` + + - Lens controller entity. + + - .. row 16 + + - ``MEDIA_ENT_F_ATV_DECODER`` + + - Analog video decoder, the basic function of the video decoder is + to accept analogue video from a wide variety of sources such as + broadcast, DVD players, cameras and video cassette recorders, in + either NTSC, PAL, SECAM or HD format, separating the stream into + its component parts, luminance and chrominance, and output it in + some digital video standard, with appropriate timing signals. + + - .. row 17 + + - ``MEDIA_ENT_F_TUNER`` + + - Digital TV, analog TV, radio and/or software radio tuner, with + consists on a PLL tuning stage that converts radio frequency (RF) + signal into an Intermediate Frequency (IF). Modern tuners have + internally IF-PLL decoders for audio and video, but older models + have those stages implemented on separate entities. + + - .. row 18 + + - ``MEDIA_ENT_F_IF_VID_DECODER`` + + - IF-PLL video decoder. It receives the IF from a PLL and decodes + the analog TV video signal. This is commonly found on some very + old analog tuners, like Philips MK3 designs. They all contain a + tda9887 (or some software compatible similar chip, like tda9885). + Those devices use a different I2C address than the tuner PLL. + + - .. row 19 + + - ``MEDIA_ENT_F_IF_AUD_DECODER`` + + - IF-PLL sound decoder. It receives the IF from a PLL and decodes + the analog TV audio signal. This is commonly found on some very + old analog hardware, like Micronas msp3400, Philips tda9840, + tda985x, etc. Those devices use a different I2C address than the + tuner PLL and should be controlled together with the IF-PLL video + decoder. + + - .. row 20 + + - ``MEDIA_ENT_F_AUDIO_CAPTURE`` + + - Audio Capture Function Entity. + + - .. row 21 + + - ``MEDIA_ENT_F_AUDIO_PLAYBACK`` + + - Audio Playback Function Entity. + + - .. row 22 + + - ``MEDIA_ENT_F_AUDIO_MIXER`` + + - Audio Mixer Function Entity. + + + +.. _media-entity-flag: + +.. flat-table:: Media entity flags + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``MEDIA_ENT_FL_DEFAULT`` + + - Default entity for its type. Used to discover the default audio, + VBI and video devices, the default camera sensor, ... + + - .. row 2 + + - ``MEDIA_ENT_FL_CONNECTOR`` + + - The entity represents a data conector + + + +.. _media-intf-type: + +.. flat-table:: Media interface types + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``MEDIA_INTF_T_DVB_FE`` + + - Device node interface for the Digital TV frontend + + - typically, /dev/dvb/adapter?/frontend? + + - .. row 2 + + - ``MEDIA_INTF_T_DVB_DEMUX`` + + - Device node interface for the Digital TV demux + + - typically, /dev/dvb/adapter?/demux? + + - .. row 3 + + - ``MEDIA_INTF_T_DVB_DVR`` + + - Device node interface for the Digital TV DVR + + - typically, /dev/dvb/adapter?/dvr? + + - .. row 4 + + - ``MEDIA_INTF_T_DVB_CA`` + + - Device node interface for the Digital TV Conditional Access + + - typically, /dev/dvb/adapter?/ca? + + - .. row 5 + + - ``MEDIA_INTF_T_DVB_FE`` + + - Device node interface for the Digital TV network control + + - typically, /dev/dvb/adapter?/net? + + - .. row 6 + + - ``MEDIA_INTF_T_V4L_VIDEO`` + + - Device node interface for video (V4L) + + - typically, /dev/video? + + - .. row 7 + + - ``MEDIA_INTF_T_V4L_VBI`` + + - Device node interface for VBI (V4L) + + - typically, /dev/vbi? + + - .. row 8 + + - ``MEDIA_INTF_T_V4L_RADIO`` + + - Device node interface for radio (V4L) + + - typically, /dev/vbi? + + - .. row 9 + + - ``MEDIA_INTF_T_V4L_SUBDEV`` + + - Device node interface for a V4L subdevice + + - typically, /dev/v4l-subdev? + + - .. row 10 + + - ``MEDIA_INTF_T_V4L_SWRADIO`` + + - Device node interface for Software Defined Radio (V4L) + + - typically, /dev/swradio? + + - .. row 11 + + - ``MEDIA_INTF_T_ALSA_PCM_CAPTURE`` + + - Device node interface for ALSA PCM Capture + + - typically, /dev/snd/pcmC?D?c + + - .. row 12 + + - ``MEDIA_INTF_T_ALSA_PCM_PLAYBACK`` + + - Device node interface for ALSA PCM Playback + + - typically, /dev/snd/pcmC?D?p + + - .. row 13 + + - ``MEDIA_INTF_T_ALSA_CONTROL`` + + - Device node interface for ALSA Control + + - typically, /dev/snd/controlC? + + - .. row 14 + + - ``MEDIA_INTF_T_ALSA_COMPRESS`` + + - Device node interface for ALSA Compress + + - typically, /dev/snd/compr? + + - .. row 15 + + - ``MEDIA_INTF_T_ALSA_RAWMIDI`` + + - Device node interface for ALSA Raw MIDI + + - typically, /dev/snd/midi? + + - .. row 16 + + - ``MEDIA_INTF_T_ALSA_HWDEP`` + + - Device node interface for ALSA Hardware Dependent + + - typically, /dev/snd/hwC?D? + + - .. row 17 + + - ``MEDIA_INTF_T_ALSA_SEQUENCER`` + + - Device node interface for ALSA Sequencer + + - typically, /dev/snd/seq + + - .. row 18 + + - ``MEDIA_INTF_T_ALSA_TIMER`` + + - Device node interface for ALSA Timer + + - typically, /dev/snd/timer + + + +.. _media-pad-flag: + +.. flat-table:: Media pad flags + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``MEDIA_PAD_FL_SINK`` + + - Input pad, relative to the entity. Input pads sink data and are + targets of links. + + - .. row 2 + + - ``MEDIA_PAD_FL_SOURCE`` + + - Output pad, relative to the entity. Output pads source data and + are origins of links. + + - .. row 3 + + - ``MEDIA_PAD_FL_MUST_CONNECT`` + + - If this flag is set and the pad is linked to any other pad, then + at least one of those links must be enabled for the entity to be + able to stream. There could be temporary reasons (e.g. device + configuration dependent) for the pad to need enabled links even + when this flag isn't set; the absence of the flag doesn't imply + there is none. + + +One and only one of ``MEDIA_PAD_FL_SINK`` and ``MEDIA_PAD_FL_SOURCE`` +must be set for every pad. + + +.. _media-link-flag: + +.. flat-table:: Media link flags + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``MEDIA_LNK_FL_ENABLED`` + + - The link is enabled and can be used to transfer media data. When + two or more links target a sink pad, only one of them can be + enabled at a time. + + - .. row 2 + + - ``MEDIA_LNK_FL_IMMUTABLE`` + + - The link enabled state can't be modified at runtime. An immutable + link is always enabled. + + - .. row 3 + + - ``MEDIA_LNK_FL_DYNAMIC`` + + - The link enabled state can be modified during streaming. This flag + is set by drivers and is read-only for applications. + + - .. row 4 + + - ``MEDIA_LNK_FL_LINK_TYPE`` + + - This is a bitmask that defines the type of the link. Currently, + two types of links are supported: + + ``MEDIA_LNK_FL_DATA_LINK`` if the link is between two pads + + ``MEDIA_LNK_FL_INTERFACE_LINK`` if the link is between an + interface and an entity diff --git a/Documentation/linux_tv/media/v4l/media-controller-intro.rst b/Documentation/linux_tv/media/v4l/media-controller-intro.rst deleted file mode 100644 index 3e776c0d8276..000000000000 --- a/Documentation/linux_tv/media/v4l/media-controller-intro.rst +++ /dev/null @@ -1,33 +0,0 @@ -.. -*- coding: utf-8; mode: rst -*- - -.. _media-controller-intro: - -Introduction -============ - -Media devices increasingly handle multiple related functions. Many USB -cameras include microphones, video capture hardware can also output -video, or SoC camera interfaces also perform memory-to-memory operations -similar to video codecs. - -Independent functions, even when implemented in the same hardware, can -be modelled as separate devices. A USB camera with a microphone will be -presented to userspace applications as V4L2 and ALSA capture devices. -The devices' relationships (when using a webcam, end-users shouldn't -have to manually select the associated USB microphone), while not made -available directly to applications by the drivers, can usually be -retrieved from sysfs. - -With more and more advanced SoC devices being introduced, the current -approach will not scale. Device topologies are getting increasingly -complex and can't always be represented by a tree structure. Hardware -blocks are shared between different functions, creating dependencies -between seemingly unrelated devices. - -Kernel abstraction APIs such as V4L2 and ALSA provide means for -applications to access hardware parameters. As newer hardware expose an -increasingly high number of those parameters, drivers need to guess what -applications really require based on limited information, thereby -implementing policies that belong to userspace. - -The media controller API aims at solving those problems. diff --git a/Documentation/linux_tv/media/v4l/media-controller-model.rst b/Documentation/linux_tv/media/v4l/media-controller-model.rst deleted file mode 100644 index 7be58aecb882..000000000000 --- a/Documentation/linux_tv/media/v4l/media-controller-model.rst +++ /dev/null @@ -1,35 +0,0 @@ -.. -*- coding: utf-8; mode: rst -*- - -.. _media-controller-model: - -Media device model -================== - -Discovering a device internal topology, and configuring it at runtime, -is one of the goals of the media controller API. To achieve this, -hardware devices and Linux Kernel interfaces are modelled as graph -objects on an oriented graph. The object types that constitute the graph -are: - -- An **entity** is a basic media hardware or software building block. - It can correspond to a large variety of logical blocks such as - physical hardware devices (CMOS sensor for instance), logical - hardware devices (a building block in a System-on-Chip image - processing pipeline), DMA channels or physical connectors. - -- An **interface** is a graph representation of a Linux Kernel - userspace API interface, like a device node or a sysfs file that - controls one or more entities in the graph. - -- A **pad** is a data connection endpoint through which an entity can - interact with other entities. Data (not restricted to video) produced - by an entity flows from the entity's output to one or more entity - inputs. Pads should not be confused with physical pins at chip - boundaries. - -- A **data link** is a point-to-point oriented connection between two - pads, either on the same entity or on different entities. Data flows - from a source pad to a sink pad. - -- An **interface link** is a point-to-point bidirectional control - connection between a Linux Kernel interface and an entity.m diff --git a/Documentation/linux_tv/media/v4l/media-controller.rst b/Documentation/linux_tv/media/v4l/media-controller.rst deleted file mode 100644 index 49fb76cafcab..000000000000 --- a/Documentation/linux_tv/media/v4l/media-controller.rst +++ /dev/null @@ -1,57 +0,0 @@ -.. -*- coding: utf-8; mode: rst -*- - -.. _media_common: - -#################### -Media Controller API -#################### - -.. _media_controller: - -**************** -Media Controller -**************** - - -.. toctree:: - :maxdepth: 1 - - media-controller-intro - media-controller-model - media-types - - -.. _media-user-func: - -****************** -Function Reference -****************** - - -.. toctree:: - :maxdepth: 1 - - media-func-open - media-func-close - media-func-ioctl - media-ioc-device-info - media-ioc-g-topology - media-ioc-enum-entities - media-ioc-enum-links - media-ioc-setup-link - - -********************** -Revision and Copyright -********************** - - -:author: Pinchart Laurent -:address: laurent.pinchart@ideasonboard.com -:contrib: Initial version. - -**Copyright** 2010 : Laurent Pinchart - -:revision: 1.0.0 / 2010-11-10 (*lp*) - -Initial revision diff --git a/Documentation/linux_tv/media/v4l/media-func-close.rst b/Documentation/linux_tv/media/v4l/media-func-close.rst deleted file mode 100644 index 109b831e4047..000000000000 --- a/Documentation/linux_tv/media/v4l/media-func-close.rst +++ /dev/null @@ -1,45 +0,0 @@ -.. -*- coding: utf-8; mode: rst -*- - -.. _media-func-close: - -************* -media close() -************* - -*man media-close(2)* - -Close a media device - - -Synopsis -======== - -.. code-block:: c - - #include - - -.. cpp:function:: int close( int fd ) - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - - -Description -=========== - -Closes the media device. Resources associated with the file descriptor -are freed. The device configuration remain unchanged. - - -Return Value -============ - -:ref:`close() ` returns 0 on success. On error, -1 is returned, and -``errno`` is set appropriately. Possible error codes are: - -EBADF - ``fd`` is not a valid open file descriptor. diff --git a/Documentation/linux_tv/media/v4l/media-func-ioctl.rst b/Documentation/linux_tv/media/v4l/media-func-ioctl.rst deleted file mode 100644 index c56ccb9c9b39..000000000000 --- a/Documentation/linux_tv/media/v4l/media-func-ioctl.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. -*- coding: utf-8; mode: rst -*- - -.. _media-func-ioctl: - -************* -media ioctl() -************* - -*man media-ioctl(2)* - -Control a media device - - -Synopsis -======== - -.. code-block:: c - - #include - - -.. cpp:function:: int ioctl( int fd, int request, void *argp ) - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``request`` - Media ioctl request code as defined in the media.h header file, for - example MEDIA_IOC_SETUP_LINK. - -``argp`` - Pointer to a request-specific structure. - - -Description -=========== - -The :ref:`ioctl() ` function manipulates media device parameters. -The argument ``fd`` must be an open file descriptor. - -The ioctl ``request`` code specifies the media function to be called. It -has encoded in it whether the argument is an input, output or read/write -parameter, and the size of the argument ``argp`` in bytes. - -Macros and structures definitions specifying media ioctl requests and -their parameters are located in the media.h header file. All media ioctl -requests, their respective function and parameters are specified in -:ref:`media-user-func`. - - -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 ` chapter. - -Request-specific error codes are listed in the individual requests -descriptions. - -When an ioctl that takes an output or read/write parameter fails, the -parameter remains unmodified. diff --git a/Documentation/linux_tv/media/v4l/media-func-open.rst b/Documentation/linux_tv/media/v4l/media-func-open.rst deleted file mode 100644 index 627860b33ae2..000000000000 --- a/Documentation/linux_tv/media/v4l/media-func-open.rst +++ /dev/null @@ -1,67 +0,0 @@ -.. -*- coding: utf-8; mode: rst -*- - -.. _media-func-open: - -************ -media open() -************ - -*man media-open(2)* - -Open a media device - - -Synopsis -======== - -.. code-block:: c - - #include - - -.. cpp:function:: int open( const char *device_name, int flags ) - -Arguments -========= - -``device_name`` - Device to be opened. - -``flags`` - Open flags. Access mode must be either ``O_RDONLY`` or ``O_RDWR``. - Other flags have no effect. - - -Description -=========== - -To open a media device applications call :ref:`open() ` with the -desired device name. The function has no side effects; the device -configuration remain unchanged. - -When the device is opened in read-only mode, attempts to modify its -configuration will result in an error, and ``errno`` will be set to -EBADF. - - -Return Value -============ - -:ref:`open() ` returns the new file descriptor on success. On error, --1 is returned, and ``errno`` is set appropriately. Possible error codes -are: - -EACCES - The requested access to the file is not allowed. - -EMFILE - The process already has the maximum number of files open. - -ENFILE - The system limit on the total number of open files has been reached. - -ENOMEM - Insufficient kernel memory was available. - -ENXIO - No device corresponding to this device special file exists. diff --git a/Documentation/linux_tv/media/v4l/media-ioc-device-info.rst b/Documentation/linux_tv/media/v4l/media-ioc-device-info.rst deleted file mode 100644 index aca9c8aa736a..000000000000 --- a/Documentation/linux_tv/media/v4l/media-ioc-device-info.rst +++ /dev/null @@ -1,140 +0,0 @@ -.. -*- coding: utf-8; mode: rst -*- - -.. _media-ioc-device-info: - -*************************** -ioctl MEDIA_IOC_DEVICE_INFO -*************************** - -*man MEDIA_IOC_DEVICE_INFO(2)* - -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() `. - -``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 `. 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 ` chapter. diff --git a/Documentation/linux_tv/media/v4l/media-ioc-enum-entities.rst b/Documentation/linux_tv/media/v4l/media-ioc-enum-entities.rst deleted file mode 100644 index 8fe1f1966640..000000000000 --- a/Documentation/linux_tv/media/v4l/media-ioc-enum-entities.rst +++ /dev/null @@ -1,195 +0,0 @@ -.. -*- coding: utf-8; mode: rst -*- - -.. _media-ioc-enum-entities: - -***************************** -ioctl MEDIA_IOC_ENUM_ENTITIES -***************************** - -*man MEDIA_IOC_ENUM_ENTITIES(2)* - -Enumerate entities and their properties - - -Synopsis -======== - -.. cpp:function:: int ioctl( int fd, int request, struct media_entity_desc *argp ) - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``request`` - MEDIA_IOC_ENUM_ENTITIES - -``argp`` - - -Description -=========== - -To query the attributes of an entity, applications set the id field of a -struct :ref:`media_entity_desc ` structure and -call the MEDIA_IOC_ENUM_ENTITIES ioctl with a pointer to this -structure. The driver fills the rest of the structure or returns an -EINVAL error code when the id is invalid. - -Entities can be enumerated by or'ing the id with the -``MEDIA_ENT_ID_FLAG_NEXT`` flag. The driver will return information -about the entity with the smallest id strictly larger than the requested -one ('next entity'), or the ``EINVAL`` error code if there is none. - -Entity IDs can be non-contiguous. Applications must *not* try to -enumerate entities by calling MEDIA_IOC_ENUM_ENTITIES with increasing -id's until they get an error. - - -.. _media-entity-desc: - -.. flat-table:: struct media_entity_desc - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - __u32 - - - ``id`` - - - - - - - Entity id, set by the application. When the id is or'ed with - ``MEDIA_ENT_ID_FLAG_NEXT``, the driver clears the flag and returns - the first entity with a larger id. - - - .. row 2 - - - char - - - ``name``\ [32] - - - - - - - Entity name as an UTF-8 NULL-terminated string. - - - .. row 3 - - - __u32 - - - ``type`` - - - - - - - Entity type, see :ref:`media-entity-type` for details. - - - .. row 4 - - - __u32 - - - ``revision`` - - - - - - - Entity revision. Always zero (obsolete) - - - .. row 5 - - - __u32 - - - ``flags`` - - - - - - - Entity flags, see :ref:`media-entity-flag` for details. - - - .. row 6 - - - __u32 - - - ``group_id`` - - - - - - - Entity group ID. Always zero (obsolete) - - - .. row 7 - - - __u16 - - - ``pads`` - - - - - - - Number of pads - - - .. row 8 - - - __u16 - - - ``links`` - - - - - - - Total number of outbound links. Inbound links are not counted in - this field. - - - .. row 9 - - - union - - - .. row 10 - - - - - struct - - - ``dev`` - - - - - Valid for (sub-)devices that create a single device node. - - - .. row 11 - - - - - - - __u32 - - - ``major`` - - - Device node major number. - - - .. row 12 - - - - - - - __u32 - - - ``minor`` - - - Device node minor number. - - - .. row 13 - - - - - __u8 - - - ``raw``\ [184] - - - - - - - - -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 ` chapter. - -EINVAL - The struct :ref:`media_entity_desc ` ``id`` - references a non-existing entity. diff --git a/Documentation/linux_tv/media/v4l/media-ioc-enum-links.rst b/Documentation/linux_tv/media/v4l/media-ioc-enum-links.rst deleted file mode 100644 index 6989f4ae4748..000000000000 --- a/Documentation/linux_tv/media/v4l/media-ioc-enum-links.rst +++ /dev/null @@ -1,171 +0,0 @@ -.. -*- coding: utf-8; mode: rst -*- - -.. _media-ioc-enum-links: - -************************** -ioctl MEDIA_IOC_ENUM_LINKS -************************** - -*man MEDIA_IOC_ENUM_LINKS(2)* - -Enumerate all pads and links for a given entity - - -Synopsis -======== - -.. cpp:function:: int ioctl( int fd, int request, struct media_links_enum *argp ) - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``request`` - MEDIA_IOC_ENUM_LINKS - -``argp`` - - -Description -=========== - -To enumerate pads and/or links for a given entity, applications set the -entity field of a struct :ref:`media_links_enum ` -structure and initialize the struct -:ref:`media_pad_desc ` and struct -:ref:`media_link_desc ` structure arrays pointed by -the ``pads`` and ``links`` fields. They then call the -MEDIA_IOC_ENUM_LINKS ioctl with a pointer to this structure. - -If the ``pads`` field is not NULL, the driver fills the ``pads`` array -with information about the entity's pads. The array must have enough -room to store all the entity's pads. The number of pads can be retrieved -with the :ref:`MEDIA_IOC_ENUM_ENTITIES ` -ioctl. - -If the ``links`` field is not NULL, the driver fills the ``links`` array -with information about the entity's outbound links. The array must have -enough room to store all the entity's outbound links. The number of -outbound links can be retrieved with the -:ref:`MEDIA_IOC_ENUM_ENTITIES ` ioctl. - -Only forward links that originate at one of the entity's source pads are -returned during the enumeration process. - - -.. _media-links-enum: - -.. flat-table:: struct media_links_enum - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - - - .. row 1 - - - __u32 - - - ``entity`` - - - Entity id, set by the application. - - - .. row 2 - - - struct :ref:`media_pad_desc ` - - - \*\ ``pads`` - - - Pointer to a pads array allocated by the application. Ignored if - NULL. - - - .. row 3 - - - struct :ref:`media_link_desc ` - - - \*\ ``links`` - - - Pointer to a links array allocated by the application. Ignored if - NULL. - - - -.. _media-pad-desc: - -.. flat-table:: struct media_pad_desc - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - - - .. row 1 - - - __u32 - - - ``entity`` - - - ID of the entity this pad belongs to. - - - .. row 2 - - - __u16 - - - ``index`` - - - 0-based pad index. - - - .. row 3 - - - __u32 - - - ``flags`` - - - Pad flags, see :ref:`media-pad-flag` for more details. - - - -.. _media-link-desc: - -.. flat-table:: struct media_link_desc - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - - - .. row 1 - - - struct :ref:`media_pad_desc ` - - - ``source`` - - - Pad at the origin of this link. - - - .. row 2 - - - struct :ref:`media_pad_desc ` - - - ``sink`` - - - Pad at the target of this link. - - - .. row 3 - - - __u32 - - - ``flags`` - - - Link flags, see :ref:`media-link-flag` for more details. - - - -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 ` chapter. - -EINVAL - The struct :ref:`media_links_enum ` ``id`` - references a non-existing entity. diff --git a/Documentation/linux_tv/media/v4l/media-ioc-g-topology.rst b/Documentation/linux_tv/media/v4l/media-ioc-g-topology.rst deleted file mode 100644 index 6d530dc2a92c..000000000000 --- a/Documentation/linux_tv/media/v4l/media-ioc-g-topology.rst +++ /dev/null @@ -1,427 +0,0 @@ -.. -*- coding: utf-8; mode: rst -*- - -.. _media-g-topology: - -************************** -ioctl MEDIA_IOC_G_TOPOLOGY -************************** - -*man MEDIA_IOC_G_TOPOLOGY(2)* - -Enumerate the graph topology and graph element properties - - -Synopsis -======== - -.. cpp:function:: int ioctl( int fd, int request, struct media_v2_topology *argp ) - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``request`` - MEDIA_IOC_G_TOPOLOGY - -``argp`` - - -Description -=========== - -The typical usage of this ioctl is to call it twice. On the first call, -the structure defined at struct -:ref:`media_v2_topology ` should be zeroed. At -return, if no errors happen, this ioctl will return the -``topology_version`` and the total number of entities, interfaces, pads -and links. - -Before the second call, the userspace should allocate arrays to store -the graph elements that are desired, putting the pointers to them at the -ptr_entities, ptr_interfaces, ptr_links and/or ptr_pads, keeping the -other values untouched. - -If the ``topology_version`` remains the same, the ioctl should fill the -desired arrays with the media graph elements. - - -.. _media-v2-topology: - -.. flat-table:: struct media_v2_topology - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - __u64 - - - ``topology_version`` - - - - - - - Version of the media graph topology. When the graph is created, - this field starts with zero. Every time a graph element is added - or removed, this field is incremented. - - - .. row 2 - - - __u64 - - - ``num_entities`` - - - - - - - Number of entities in the graph - - - .. row 3 - - - __u64 - - - ``ptr_entities`` - - - - - - - A pointer to a memory area where the entities array will be - stored, converted to a 64-bits integer. It can be zero. if zero, - the ioctl won't store the entities. It will just update - ``num_entities`` - - - .. row 4 - - - __u64 - - - ``num_interfaces`` - - - - - - - Number of interfaces in the graph - - - .. row 5 - - - __u64 - - - ``ptr_interfaces`` - - - - - - - A pointer to a memory area where the interfaces array will be - stored, converted to a 64-bits integer. It can be zero. if zero, - the ioctl won't store the interfaces. It will just update - ``num_interfaces`` - - - .. row 6 - - - __u64 - - - ``num_pads`` - - - - - - - Total number of pads in the graph - - - .. row 7 - - - __u64 - - - ``ptr_pads`` - - - - - - - A pointer to a memory area where the pads array will be stored, - converted to a 64-bits integer. It can be zero. if zero, the ioctl - won't store the pads. It will just update ``num_pads`` - - - .. row 8 - - - __u64 - - - ``num_links`` - - - - - - - Total number of data and interface links in the graph - - - .. row 9 - - - __u64 - - - ``ptr_links`` - - - - - - - A pointer to a memory area where the links array will be stored, - converted to a 64-bits integer. It can be zero. if zero, the ioctl - won't store the links. It will just update ``num_links`` - - - -.. _media-v2-entity: - -.. flat-table:: struct media_v2_entity - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - __u32 - - - ``id`` - - - - - - - Unique ID for the entity. - - - .. row 2 - - - char - - - ``name``\ [64] - - - - - - - Entity name as an UTF-8 NULL-terminated string. - - - .. row 3 - - - __u32 - - - ``function`` - - - - - - - Entity main function, see :ref:`media-entity-type` for details. - - - .. row 4 - - - __u32 - - - ``reserved``\ [12] - - - Reserved for future extensions. Drivers and applications must set - this array to zero. - - - -.. _media-v2-interface: - -.. flat-table:: struct media_v2_interface - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - __u32 - - - ``id`` - - - - - - - Unique ID for the interface. - - - .. row 2 - - - __u32 - - - ``intf_type`` - - - - - - - Interface type, see :ref:`media-intf-type` for details. - - - .. row 3 - - - __u32 - - - ``flags`` - - - - - - - Interface flags. Currently unused. - - - .. row 4 - - - __u32 - - - ``reserved``\ [9] - - - - - - - Reserved for future extensions. Drivers and applications must set - this array to zero. - - - .. row 5 - - - struct media_v2_intf_devnode - - - ``devnode`` - - - - - - - Used only for device node interfaces. See - :ref:`media-v2-intf-devnode` for details.. - - - -.. _media-v2-intf-devnode: - -.. flat-table:: struct media_v2_interface - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - __u32 - - - ``major`` - - - - - - - Device node major number. - - - .. row 2 - - - __u32 - - - ``minor`` - - - - - - - Device node minor number. - - - -.. _media-v2-pad: - -.. flat-table:: struct media_v2_pad - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - __u32 - - - ``id`` - - - - - - - Unique ID for the pad. - - - .. row 2 - - - __u32 - - - ``entity_id`` - - - - - - - Unique ID for the entity where this pad belongs. - - - .. row 3 - - - __u32 - - - ``flags`` - - - - - - - Pad flags, see :ref:`media-pad-flag` for more details. - - - .. row 4 - - - __u32 - - - ``reserved``\ [9] - - - - - - - Reserved for future extensions. Drivers and applications must set - this array to zero. - - - -.. _media-v2-link: - -.. flat-table:: struct media_v2_pad - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - __u32 - - - ``id`` - - - - - - - Unique ID for the pad. - - - .. row 2 - - - __u32 - - - ``source_id`` - - - - - - - On pad to pad links: unique ID for the source pad. - - On interface to entity links: unique ID for the interface. - - - .. row 3 - - - __u32 - - - ``sink_id`` - - - - - - - On pad to pad links: unique ID for the sink pad. - - On interface to entity links: unique ID for the entity. - - - .. row 4 - - - __u32 - - - ``flags`` - - - - - - - Link flags, see :ref:`media-link-flag` for more details. - - - .. row 5 - - - __u32 - - - ``reserved``\ [5] - - - - - - - Reserved for future extensions. Drivers and applications must set - this array to zero. - - - -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 ` chapter. - -ENOSPC - This is returned when either one or more of the num_entities, - num_interfaces, num_links or num_pads are non-zero and are - smaller than the actual number of elements inside the graph. This - may happen if the ``topology_version`` changed when compared to the - last time this ioctl was called. Userspace should usually free the - area for the pointers, zero the struct elements and call this ioctl - again. diff --git a/Documentation/linux_tv/media/v4l/media-ioc-setup-link.rst b/Documentation/linux_tv/media/v4l/media-ioc-setup-link.rst deleted file mode 100644 index 135fa782dcd2..000000000000 --- a/Documentation/linux_tv/media/v4l/media-ioc-setup-link.rst +++ /dev/null @@ -1,66 +0,0 @@ -.. -*- coding: utf-8; mode: rst -*- - -.. _media-ioc-setup-link: - -************************** -ioctl MEDIA_IOC_SETUP_LINK -************************** - -*man MEDIA_IOC_SETUP_LINK(2)* - -Modify the properties of a link - - -Synopsis -======== - -.. cpp:function:: int ioctl( int fd, int request, struct media_link_desc *argp ) - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``request`` - MEDIA_IOC_SETUP_LINK - -``argp`` - - -Description -=========== - -To change link properties applications fill a struct -:ref:`media_link_desc ` with link identification -information (source and sink pad) and the new requested link flags. They -then call the MEDIA_IOC_SETUP_LINK ioctl with a pointer to that -structure. - -The only configurable property is the ``ENABLED`` link flag to -enable/disable a link. Links marked with the ``IMMUTABLE`` link flag can -not be enabled or disabled. - -Link configuration has no side effect on other links. If an enabled link -at the sink pad prevents the link from being enabled, the driver returns -with an ``EBUSY`` error code. - -Only links marked with the ``DYNAMIC`` link flag can be enabled/disabled -while streaming media data. Attempting to enable or disable a streaming -non-dynamic link will return an ``EBUSY`` error code. - -If the specified link can't be found the driver returns with an ``EINVAL`` -error code. - - -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 ` chapter. - -EINVAL - The struct :ref:`media_link_desc ` references a - non-existing link, or the link is immutable and an attempt to modify - its configuration was made. diff --git a/Documentation/linux_tv/media/v4l/media-types.rst b/Documentation/linux_tv/media/v4l/media-types.rst deleted file mode 100644 index 6a2d001babc2..000000000000 --- a/Documentation/linux_tv/media/v4l/media-types.rst +++ /dev/null @@ -1,422 +0,0 @@ -.. -*- coding: utf-8; mode: rst -*- - -.. _media-controller-types: - -Types and flags used to represent the media graph elements -========================================================== - - -.. _media-entity-type: - -.. flat-table:: Media entity types - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``MEDIA_ENT_F_UNKNOWN`` and ``MEDIA_ENT_F_V4L2_SUBDEV_UNKNOWN`` - - - Unknown entity. That generally indicates that a driver didn't - initialize properly the entity, with is a Kernel bug - - - .. row 2 - - - ``MEDIA_ENT_F_IO_V4L`` - - - Data streaming input and/or output entity. - - - .. row 3 - - - ``MEDIA_ENT_F_IO_VBI`` - - - V4L VBI streaming input or output entity - - - .. row 4 - - - ``MEDIA_ENT_F_IO_SWRADIO`` - - - V4L Software Digital Radio (SDR) streaming input or output entity - - - .. row 5 - - - ``MEDIA_ENT_F_IO_DTV`` - - - DVB Digital TV streaming input or output entity - - - .. row 6 - - - ``MEDIA_ENT_F_DTV_DEMOD`` - - - Digital TV demodulator entity. - - - .. row 7 - - - ``MEDIA_ENT_F_TS_DEMUX`` - - - MPEG Transport stream demux entity. Could be implemented on - hardware or in Kernelspace by the Linux DVB subsystem. - - - .. row 8 - - - ``MEDIA_ENT_F_DTV_CA`` - - - Digital TV Conditional Access module (CAM) entity - - - .. row 9 - - - ``MEDIA_ENT_F_DTV_NET_DECAP`` - - - Digital TV network ULE/MLE desencapsulation entity. Could be - implemented on hardware or in Kernelspace - - - .. row 10 - - - ``MEDIA_ENT_F_CONN_RF`` - - - Connector for a Radio Frequency (RF) signal. - - - .. row 11 - - - ``MEDIA_ENT_F_CONN_SVIDEO`` - - - Connector for a S-Video signal. - - - .. row 12 - - - ``MEDIA_ENT_F_CONN_COMPOSITE`` - - - Connector for a RGB composite signal. - - - .. row 13 - - - ``MEDIA_ENT_F_CAM_SENSOR`` - - - Camera video sensor entity. - - - .. row 14 - - - ``MEDIA_ENT_F_FLASH`` - - - Flash controller entity. - - - .. row 15 - - - ``MEDIA_ENT_F_LENS`` - - - Lens controller entity. - - - .. row 16 - - - ``MEDIA_ENT_F_ATV_DECODER`` - - - Analog video decoder, the basic function of the video decoder is - to accept analogue video from a wide variety of sources such as - broadcast, DVD players, cameras and video cassette recorders, in - either NTSC, PAL, SECAM or HD format, separating the stream into - its component parts, luminance and chrominance, and output it in - some digital video standard, with appropriate timing signals. - - - .. row 17 - - - ``MEDIA_ENT_F_TUNER`` - - - Digital TV, analog TV, radio and/or software radio tuner, with - consists on a PLL tuning stage that converts radio frequency (RF) - signal into an Intermediate Frequency (IF). Modern tuners have - internally IF-PLL decoders for audio and video, but older models - have those stages implemented on separate entities. - - - .. row 18 - - - ``MEDIA_ENT_F_IF_VID_DECODER`` - - - IF-PLL video decoder. It receives the IF from a PLL and decodes - the analog TV video signal. This is commonly found on some very - old analog tuners, like Philips MK3 designs. They all contain a - tda9887 (or some software compatible similar chip, like tda9885). - Those devices use a different I2C address than the tuner PLL. - - - .. row 19 - - - ``MEDIA_ENT_F_IF_AUD_DECODER`` - - - IF-PLL sound decoder. It receives the IF from a PLL and decodes - the analog TV audio signal. This is commonly found on some very - old analog hardware, like Micronas msp3400, Philips tda9840, - tda985x, etc. Those devices use a different I2C address than the - tuner PLL and should be controlled together with the IF-PLL video - decoder. - - - .. row 20 - - - ``MEDIA_ENT_F_AUDIO_CAPTURE`` - - - Audio Capture Function Entity. - - - .. row 21 - - - ``MEDIA_ENT_F_AUDIO_PLAYBACK`` - - - Audio Playback Function Entity. - - - .. row 22 - - - ``MEDIA_ENT_F_AUDIO_MIXER`` - - - Audio Mixer Function Entity. - - - -.. _media-entity-flag: - -.. flat-table:: Media entity flags - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``MEDIA_ENT_FL_DEFAULT`` - - - Default entity for its type. Used to discover the default audio, - VBI and video devices, the default camera sensor, ... - - - .. row 2 - - - ``MEDIA_ENT_FL_CONNECTOR`` - - - The entity represents a data conector - - - -.. _media-intf-type: - -.. flat-table:: Media interface types - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``MEDIA_INTF_T_DVB_FE`` - - - Device node interface for the Digital TV frontend - - - typically, /dev/dvb/adapter?/frontend? - - - .. row 2 - - - ``MEDIA_INTF_T_DVB_DEMUX`` - - - Device node interface for the Digital TV demux - - - typically, /dev/dvb/adapter?/demux? - - - .. row 3 - - - ``MEDIA_INTF_T_DVB_DVR`` - - - Device node interface for the Digital TV DVR - - - typically, /dev/dvb/adapter?/dvr? - - - .. row 4 - - - ``MEDIA_INTF_T_DVB_CA`` - - - Device node interface for the Digital TV Conditional Access - - - typically, /dev/dvb/adapter?/ca? - - - .. row 5 - - - ``MEDIA_INTF_T_DVB_FE`` - - - Device node interface for the Digital TV network control - - - typically, /dev/dvb/adapter?/net? - - - .. row 6 - - - ``MEDIA_INTF_T_V4L_VIDEO`` - - - Device node interface for video (V4L) - - - typically, /dev/video? - - - .. row 7 - - - ``MEDIA_INTF_T_V4L_VBI`` - - - Device node interface for VBI (V4L) - - - typically, /dev/vbi? - - - .. row 8 - - - ``MEDIA_INTF_T_V4L_RADIO`` - - - Device node interface for radio (V4L) - - - typically, /dev/vbi? - - - .. row 9 - - - ``MEDIA_INTF_T_V4L_SUBDEV`` - - - Device node interface for a V4L subdevice - - - typically, /dev/v4l-subdev? - - - .. row 10 - - - ``MEDIA_INTF_T_V4L_SWRADIO`` - - - Device node interface for Software Defined Radio (V4L) - - - typically, /dev/swradio? - - - .. row 11 - - - ``MEDIA_INTF_T_ALSA_PCM_CAPTURE`` - - - Device node interface for ALSA PCM Capture - - - typically, /dev/snd/pcmC?D?c - - - .. row 12 - - - ``MEDIA_INTF_T_ALSA_PCM_PLAYBACK`` - - - Device node interface for ALSA PCM Playback - - - typically, /dev/snd/pcmC?D?p - - - .. row 13 - - - ``MEDIA_INTF_T_ALSA_CONTROL`` - - - Device node interface for ALSA Control - - - typically, /dev/snd/controlC? - - - .. row 14 - - - ``MEDIA_INTF_T_ALSA_COMPRESS`` - - - Device node interface for ALSA Compress - - - typically, /dev/snd/compr? - - - .. row 15 - - - ``MEDIA_INTF_T_ALSA_RAWMIDI`` - - - Device node interface for ALSA Raw MIDI - - - typically, /dev/snd/midi? - - - .. row 16 - - - ``MEDIA_INTF_T_ALSA_HWDEP`` - - - Device node interface for ALSA Hardware Dependent - - - typically, /dev/snd/hwC?D? - - - .. row 17 - - - ``MEDIA_INTF_T_ALSA_SEQUENCER`` - - - Device node interface for ALSA Sequencer - - - typically, /dev/snd/seq - - - .. row 18 - - - ``MEDIA_INTF_T_ALSA_TIMER`` - - - Device node interface for ALSA Timer - - - typically, /dev/snd/timer - - - -.. _media-pad-flag: - -.. flat-table:: Media pad flags - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``MEDIA_PAD_FL_SINK`` - - - Input pad, relative to the entity. Input pads sink data and are - targets of links. - - - .. row 2 - - - ``MEDIA_PAD_FL_SOURCE`` - - - Output pad, relative to the entity. Output pads source data and - are origins of links. - - - .. row 3 - - - ``MEDIA_PAD_FL_MUST_CONNECT`` - - - If this flag is set and the pad is linked to any other pad, then - at least one of those links must be enabled for the entity to be - able to stream. There could be temporary reasons (e.g. device - configuration dependent) for the pad to need enabled links even - when this flag isn't set; the absence of the flag doesn't imply - there is none. - - -One and only one of ``MEDIA_PAD_FL_SINK`` and ``MEDIA_PAD_FL_SOURCE`` -must be set for every pad. - - -.. _media-link-flag: - -.. flat-table:: Media link flags - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``MEDIA_LNK_FL_ENABLED`` - - - The link is enabled and can be used to transfer media data. When - two or more links target a sink pad, only one of them can be - enabled at a time. - - - .. row 2 - - - ``MEDIA_LNK_FL_IMMUTABLE`` - - - The link enabled state can't be modified at runtime. An immutable - link is always enabled. - - - .. row 3 - - - ``MEDIA_LNK_FL_DYNAMIC`` - - - The link enabled state can be modified during streaming. This flag - is set by drivers and is read-only for applications. - - - .. row 4 - - - ``MEDIA_LNK_FL_LINK_TYPE`` - - - This is a bitmask that defines the type of the link. Currently, - two types of links are supported: - - ``MEDIA_LNK_FL_DATA_LINK`` if the link is between two pads - - ``MEDIA_LNK_FL_INTERFACE_LINK`` if the link is between an - interface and an entity