mirror of
https://github.com/edk2-porting/linux-next.git
synced 2024-12-22 20:23:57 +08:00
54f38fcae5
Since 2017, there is an space reserved for userspace API,
created by changeset 1d596dee38 ("docs: Create a user-space API guide").
As the media subsystem was one of the first subsystems to use
Sphinx, until this patch, we were keeping things on a separate
place.
Let's just use the new location, as having all uAPI altogether
will likely make things easier for developers.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
105 lines
3.9 KiB
ReStructuredText
105 lines
3.9 KiB
ReStructuredText
.. Permission is granted to copy, distribute and/or modify this
|
|
.. document under the terms of the GNU Free Documentation License,
|
|
.. Version 1.1 or any later version published by the Free Software
|
|
.. Foundation, with no Invariant Sections, no Front-Cover Texts
|
|
.. and no Back-Cover Texts. A copy of the license is included at
|
|
.. Documentation/userspace-api/media/fdl-appendix.rst.
|
|
..
|
|
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
|
|
|
|
.. _audio:
|
|
|
|
************************
|
|
Audio Inputs and Outputs
|
|
************************
|
|
|
|
Audio inputs and outputs are physical connectors of a device. Video
|
|
capture devices have inputs, output devices have outputs, zero or more
|
|
each. Radio devices have no audio inputs or outputs. They have exactly
|
|
one tuner which in fact *is* an audio source, but this API associates
|
|
tuners with video inputs or outputs only, and radio devices have none of
|
|
these. [#f1]_ A connector on a TV card to loop back the received audio
|
|
signal to a sound card is not considered an audio output.
|
|
|
|
Audio and video inputs and outputs are associated. Selecting a video
|
|
source also selects an audio source. This is most evident when the video
|
|
and audio source is a tuner. Further audio connectors can combine with
|
|
more than one video input or output. Assumed two composite video inputs
|
|
and two audio inputs exist, there may be up to four valid combinations.
|
|
The relation of video and audio connectors is defined in the
|
|
``audioset`` field of the respective struct
|
|
:c:type:`v4l2_input` or struct
|
|
:c:type:`v4l2_output`, where each bit represents the index
|
|
number, starting at zero, of one audio input or output.
|
|
|
|
To learn about the number and attributes of the available inputs and
|
|
outputs applications can enumerate them with the
|
|
:ref:`VIDIOC_ENUMAUDIO` and
|
|
:ref:`VIDIOC_ENUMAUDOUT <VIDIOC_ENUMAUDOUT>` ioctl, respectively.
|
|
The struct :c:type:`v4l2_audio` returned by the
|
|
:ref:`VIDIOC_ENUMAUDIO` ioctl also contains signal
|
|
status information applicable when the current audio input is queried.
|
|
|
|
The :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` and
|
|
:ref:`VIDIOC_G_AUDOUT <VIDIOC_G_AUDOUT>` ioctls report the current
|
|
audio input and output, respectively.
|
|
|
|
.. note::
|
|
|
|
Note that, unlike :ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` and
|
|
:ref:`VIDIOC_G_OUTPUT <VIDIOC_G_OUTPUT>` these ioctls return a
|
|
structure as :ref:`VIDIOC_ENUMAUDIO` and
|
|
:ref:`VIDIOC_ENUMAUDOUT <VIDIOC_ENUMAUDOUT>` do, not just an index.
|
|
|
|
To select an audio input and change its properties applications call the
|
|
:ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>` ioctl. To select an audio
|
|
output (which presently has no changeable properties) applications call
|
|
the :ref:`VIDIOC_S_AUDOUT <VIDIOC_G_AUDOUT>` ioctl.
|
|
|
|
Drivers must implement all audio input ioctls when the device has
|
|
multiple selectable audio inputs, all audio output ioctls when the
|
|
device has multiple selectable audio outputs. When the device has any
|
|
audio inputs or outputs the driver must set the ``V4L2_CAP_AUDIO`` flag
|
|
in the struct :c:type:`v4l2_capability` returned by
|
|
the :ref:`VIDIOC_QUERYCAP` ioctl.
|
|
|
|
|
|
Example: Information about the current audio input
|
|
==================================================
|
|
|
|
.. code-block:: c
|
|
|
|
struct v4l2_audio audio;
|
|
|
|
memset(&audio, 0, sizeof(audio));
|
|
|
|
if (-1 == ioctl(fd, VIDIOC_G_AUDIO, &audio)) {
|
|
perror("VIDIOC_G_AUDIO");
|
|
exit(EXIT_FAILURE);
|
|
}
|
|
|
|
printf("Current input: %s\\n", audio.name);
|
|
|
|
|
|
Example: Switching to the first audio input
|
|
===========================================
|
|
|
|
.. code-block:: c
|
|
|
|
struct v4l2_audio audio;
|
|
|
|
memset(&audio, 0, sizeof(audio)); /* clear audio.mode, audio.reserved */
|
|
|
|
audio.index = 0;
|
|
|
|
if (-1 == ioctl(fd, VIDIOC_S_AUDIO, &audio)) {
|
|
perror("VIDIOC_S_AUDIO");
|
|
exit(EXIT_FAILURE);
|
|
}
|
|
|
|
.. [#f1]
|
|
Actually struct :c:type:`v4l2_audio` ought to have a
|
|
``tuner`` field like struct :c:type:`v4l2_input`, not
|
|
only making the API more consistent but also permitting radio devices
|
|
with multiple tuners.
|