Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 140d8816 authored by Laurent Pinchart's avatar Laurent Pinchart Committed by Mauro Carvalho Chehab
Browse files

[media] media: Media device information query 



Create the following ioctl and implement it at the media device level to
query device information.

- MEDIA_IOC_DEVICE_INFO: Query media device information

The ioctl and its data structure are defined in the new kernel header
linux/media.h available to userspace applications.

Signed-off-by: default avatarLaurent Pinchart <laurent.pinchart@ideasonboard.com>
Acked-by: default avatarHans Verkuil <hverkuil@xs4all.nl>
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@redhat.com>
parent 503c3d82

Documentation/DocBook/media-entities.tmpl

+12 −0
Original line number Original line Diff line number Diff line
@@ -11,6 +11,10 @@ 
<!ENTITY func-select "<link linkend='func-select'><function>select()</function></link>">

<!ENTITY func-select "<link linkend='func-select'><function>select()</function></link>">

<!ENTITY func-write "<link linkend='func-write'><function>write()</function></link>">

<!ENTITY func-write "<link linkend='func-write'><function>write()</function></link>">





<!ENTITY media-func-close "<link linkend='media-func-close'><function>close()</function></link>">

<!ENTITY media-func-ioctl "<link linkend='media-func-ioctl'><function>ioctl()</function></link>">

<!ENTITY media-func-open "<link linkend='media-func-open'><function>open()</function></link>">



<!-- Ioctls -->

<!-- Ioctls -->

<!ENTITY VIDIOC-CROPCAP "<link linkend='vidioc-cropcap'><constant>VIDIOC_CROPCAP</constant></link>">

<!ENTITY VIDIOC-CROPCAP "<link linkend='vidioc-cropcap'><constant>VIDIOC_CROPCAP</constant></link>">

<!ENTITY VIDIOC-DBG-G-CHIP-IDENT "<link linkend='vidioc-dbg-g-chip-ident'><constant>VIDIOC_DBG_G_CHIP_IDENT</constant></link>">

<!ENTITY VIDIOC-DBG-G-CHIP-IDENT "<link linkend='vidioc-dbg-g-chip-ident'><constant>VIDIOC_DBG_G_CHIP_IDENT</constant></link>">
@@ -87,6 +91,8 @@ 
<!ENTITY VIDIOC-TRY-FMT "<link linkend='vidioc-g-fmt'><constant>VIDIOC_TRY_FMT</constant></link>">

<!ENTITY VIDIOC-TRY-FMT "<link linkend='vidioc-g-fmt'><constant>VIDIOC_TRY_FMT</constant></link>">

<!ENTITY VIDIOC-UNSUBSCRIBE-EVENT "<link linkend='vidioc-subscribe-event'><constant>VIDIOC_UNSUBSCRIBE_EVENT</constant></link>">

<!ENTITY VIDIOC-UNSUBSCRIBE-EVENT "<link linkend='vidioc-subscribe-event'><constant>VIDIOC_UNSUBSCRIBE_EVENT</constant></link>">





<!ENTITY MEDIA-IOC-DEVICE-INFO "<link linkend='media-ioc-device-info'><constant>MEDIA_IOC_DEVICE_INFO</constant></link>">



<!-- Types -->

<!-- Types -->

<!ENTITY v4l2-std-id "<link linkend='v4l2-std-id'>v4l2_std_id</link>">

<!ENTITY v4l2-std-id "<link linkend='v4l2-std-id'>v4l2_std_id</link>">
@@ -184,6 +190,8 @@ 
<!ENTITY v4l2-vbi-format "struct&nbsp;<link linkend='v4l2-vbi-format'>v4l2_vbi_format</link>">

<!ENTITY v4l2-vbi-format "struct&nbsp;<link linkend='v4l2-vbi-format'>v4l2_vbi_format</link>">

<!ENTITY v4l2-window "struct&nbsp;<link linkend='v4l2-window'>v4l2_window</link>">

<!ENTITY v4l2-window "struct&nbsp;<link linkend='v4l2-window'>v4l2_window</link>">





<!ENTITY media-device-info "struct&nbsp;<link linkend='media-device-info'>media_device_info</link>">



<!-- Error Codes -->

<!-- Error Codes -->

<!ENTITY EACCES "<errorcode>EACCES</errorcode> error code">

<!ENTITY EACCES "<errorcode>EACCES</errorcode> error code">

<!ENTITY EAGAIN "<errorcode>EAGAIN</errorcode> error code">

<!ENTITY EAGAIN "<errorcode>EAGAIN</errorcode> error code">
@@ -328,6 +336,10 @@ 
<!ENTITY sub-media-indices SYSTEM "media-indices.tmpl">

<!ENTITY sub-media-indices SYSTEM "media-indices.tmpl">





<!ENTITY sub-media-controller SYSTEM "v4l/media-controller.xml">

<!ENTITY sub-media-controller SYSTEM "v4l/media-controller.xml">

<!ENTITY sub-media-open SYSTEM "v4l/media-func-open.xml">

<!ENTITY sub-media-close SYSTEM "v4l/media-func-close.xml">

<!ENTITY sub-media-ioctl SYSTEM "v4l/media-func-ioctl.xml">

<!ENTITY sub-media-ioc-device-info SYSTEM "v4l/media-ioc-device-info.xml">





<!-- Function Reference -->

<!-- Function Reference -->

<!ENTITY close SYSTEM "v4l/func-close.xml">

<!ENTITY close SYSTEM "v4l/func-close.xml">

Documentation/DocBook/v4l/media-controller.xml

+10 −0
Original line number Original line Diff line number Diff line
@@ -74,3 +74,13 @@ 
    pad to a sink pad.</para>

    pad to a sink pad.</para>

  </section>

  </section>

</chapter>

</chapter>



<appendix id="media-user-func">

  <title>Function Reference</title>

  <!-- Keep this alphabetically sorted. -->

  &sub-media-open;

  &sub-media-close;

  &sub-media-ioctl;

  <!-- All ioctls go here. -->

  &sub-media-ioc-device-info;

</appendix>

Documentation/DocBook/v4l/media-func-close.xml

0 → 100644
+59 −0
Original line number Original line Diff line number Diff line 
<refentry id="media-func-close">

  <refmeta>

    <refentrytitle>media close()</refentrytitle>

    &manvol;

  </refmeta>



  <refnamediv>

    <refname>media-close</refname>

    <refpurpose>Close a media device</refpurpose>

  </refnamediv>



  <refsynopsisdiv>

    <funcsynopsis>

      <funcsynopsisinfo>#include &lt;unistd.h&gt;</funcsynopsisinfo>

      <funcprototype>

	<funcdef>int <function>close</function></funcdef>

	<paramdef>int <parameter>fd</parameter></paramdef>

      </funcprototype>

    </funcsynopsis>

  </refsynopsisdiv>



  <refsect1>

    <title>Arguments</title>



    <variablelist>

      <varlistentry>

	<term><parameter>fd</parameter></term>

	<listitem>

	  <para>&fd;</para>

	</listitem>

      </varlistentry>

    </variablelist>

  </refsect1>



  <refsect1>

    <title>Description</title>



    <para>Closes the media device. Resources associated with the file descriptor

    are freed. The device configuration remain unchanged.</para>

  </refsect1>



  <refsect1>

    <title>Return Value</title>



    <para><function>close</function> returns 0 on success. On error, -1 is

    returned, and <varname>errno</varname> is set appropriately. Possible error

    codes are:</para>



    <variablelist>

      <varlistentry>

	<term><errorcode>EBADF</errorcode></term>

	<listitem>

	  <para><parameter>fd</parameter> is not a valid open file descriptor.

	  </para>

	</listitem>

      </varlistentry>

    </variablelist>

  </refsect1>

</refentry>

Documentation/DocBook/v4l/media-func-ioctl.xml

0 → 100644
+116 −0
Original line number Original line Diff line number Diff line 
<refentry id="media-func-ioctl">

  <refmeta>

    <refentrytitle>media ioctl()</refentrytitle>

    &manvol;

  </refmeta>



  <refnamediv>

    <refname>media-ioctl</refname>

    <refpurpose>Control a media device</refpurpose>

  </refnamediv>



  <refsynopsisdiv>

    <funcsynopsis>

      <funcsynopsisinfo>#include &lt;sys/ioctl.h&gt;</funcsynopsisinfo>

      <funcprototype>

	<funcdef>int <function>ioctl</function></funcdef>

	<paramdef>int <parameter>fd</parameter></paramdef>

	<paramdef>int <parameter>request</parameter></paramdef>

	<paramdef>void *<parameter>argp</parameter></paramdef>

      </funcprototype>

    </funcsynopsis>

  </refsynopsisdiv>



  <refsect1>

    <title>Arguments</title>



    <variablelist>

      <varlistentry>

	<term><parameter>fd</parameter></term>

	<listitem>

	  <para>&fd;</para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><parameter>request</parameter></term>

	<listitem>

	  <para>Media ioctl request code as defined in the media.h header file,

	  for example MEDIA_IOC_SETUP_LINK.</para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><parameter>argp</parameter></term>

	<listitem>

	  <para>Pointer to a request-specific structure.</para>

	</listitem>

      </varlistentry>

    </variablelist>

  </refsect1>



  <refsect1>

    <title>Description</title>

    <para>The <function>ioctl()</function> function manipulates media device

    parameters. The argument <parameter>fd</parameter> must be an open file

    descriptor.</para>

    <para>The ioctl <parameter>request</parameter> 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

    <parameter>argp</parameter> in bytes.</para>

    <para>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

    <xref linkend="media-user-func" />.</para>

  </refsect1>



  <refsect1>

    <title>Return Value</title>



    <para><function>ioctl()</function> returns <returnvalue>0</returnvalue> on

    success. On failure, <returnvalue>-1</returnvalue> is returned, and the

    <varname>errno</varname> variable is set appropriately. Generic error codes

    are listed below, and request-specific error codes are listed in the

    individual requests descriptions.</para>

    <para>When an ioctl that takes an output or read/write parameter fails,

    the parameter remains unmodified.</para>



    <variablelist>

      <varlistentry>

	<term><errorcode>EBADF</errorcode></term>

	<listitem>

	  <para><parameter>fd</parameter> is not a valid open file descriptor.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><errorcode>EFAULT</errorcode></term>

	<listitem>

	  <para><parameter>argp</parameter> references an inaccessible memory

	  area.</para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><errorcode>EINVAL</errorcode></term>

	<listitem>

	  <para>The <parameter>request</parameter> or the data pointed to by

	  <parameter>argp</parameter> is not valid. This is a very common error

	  code, see the individual ioctl requests listed in

	  <xref linkend="media-user-func" /> for actual causes.</para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><errorcode>ENOMEM</errorcode></term>

	<listitem>

	  <para>Insufficient kernel memory was available to complete the

	  request.</para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><errorcode>ENOTTY</errorcode></term>

	<listitem>

	  <para><parameter>fd</parameter> is  not  associated  with  a character

	  special device.</para>

	</listitem>

      </varlistentry>

    </variablelist>

  </refsect1>

</refentry>

Documentation/DocBook/v4l/media-func-open.xml

0 → 100644
+94 −0
Original line number Original line Diff line number Diff line 
<refentry id="media-func-open">

  <refmeta>

    <refentrytitle>media open()</refentrytitle>

    &manvol;

  </refmeta>



  <refnamediv>

    <refname>media-open</refname>

    <refpurpose>Open a media device</refpurpose>

  </refnamediv>



  <refsynopsisdiv>

    <funcsynopsis>

      <funcsynopsisinfo>#include &lt;fcntl.h&gt;</funcsynopsisinfo>

      <funcprototype>

	<funcdef>int <function>open</function></funcdef>

	<paramdef>const char *<parameter>device_name</parameter></paramdef>

	<paramdef>int <parameter>flags</parameter></paramdef>

      </funcprototype>

    </funcsynopsis>

  </refsynopsisdiv>



  <refsect1>

    <title>Arguments</title>



    <variablelist>

      <varlistentry>

	<term><parameter>device_name</parameter></term>

	<listitem>

	  <para>Device to be opened.</para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><parameter>flags</parameter></term>

	<listitem>

	  <para>Open flags. Access mode must be either <constant>O_RDONLY</constant>

	  or <constant>O_RDWR</constant>. Other flags have no effect.</para>

	</listitem>

      </varlistentry>

    </variablelist>

  </refsect1>

  <refsect1>

    <title>Description</title>

    <para>To open a media device applications call <function>open()</function>

    with the desired device name. The function has no side effects; the device

    configuration remain unchanged.</para>

    <para>When the device is opened in read-only mode, attemps to modify its

    configuration will result in an error, and <varname>errno</varname> will be

    set to <errorcode>EBADF</errorcode>.</para>

  </refsect1>

  <refsect1>

    <title>Return Value</title>



    <para><function>open</function> returns the new file descriptor on success.

    On error, -1 is returned, and <varname>errno</varname> is set appropriately.

    Possible error codes are:</para>



    <variablelist>

      <varlistentry>

	<term><errorcode>EACCES</errorcode></term>

	<listitem>

	  <para>The requested access to the file is not allowed.</para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><errorcode>EMFILE</errorcode></term>

	<listitem>

	  <para>The  process  already  has  the  maximum number of files open.

	  </para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><errorcode>ENFILE</errorcode></term>

	<listitem>

	  <para>The system limit on the total number of open files has been

	  reached.</para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><errorcode>ENOMEM</errorcode></term>

	<listitem>

	  <para>Insufficient kernel memory was available.</para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><errorcode>ENXIO</errorcode></term>

	<listitem>

	  <para>No device corresponding to this device special file exists.

	  </para>

	</listitem>

      </varlistentry>

    </variablelist>

  </refsect1>

</refentry>