Commit 7ba85fa4 authored by Sakari Ailus's avatar Sakari Ailus Committed by Mauro Carvalho Chehab
Browse files

[media] v4l: Add flash control documentation 



Add documentation for V4L2 flash controls.

Signed-off-by: default avatarSakari Ailus <sakari.ailus@iki.fi>
Acked-by: default avatarLaurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@redhat.com>
parent 0b159acd

Documentation/DocBook/media/v4l/compat.xml

+3 −0
Original line number Diff line number Diff line
@@ -2475,6 +2475,9 @@ ioctls.</para> 
        <listitem>

	  <para>&VIDIOC-DBG-G-CHIP-IDENT; ioctl.</para>

        </listitem>

        <listitem>

	  <para>Flash API. <xref linkend="flash-controls" /></para>

        </listitem>

      </itemizedlist>

    </section>

Documentation/DocBook/media/v4l/controls.xml

+283 −0
Original line number Diff line number Diff line
@@ -2092,6 +2092,289 @@ manually or automatically if set to zero. Unit, range and step are driver-specif 
<para>For more details about RDS specification, refer to

<xref linkend="en50067" /> document, from CENELEC.</para>

    </section>



    <section id="flash-controls">

      <title>Flash Control Reference</title>



      <note>

	<title>Experimental</title>



	<para>This is an <link linkend="experimental">experimental</link>

interface and may change in the future.</para>

      </note>



      <para>

	The V4L2 flash controls are intended to provide generic access

	to flash controller devices. Flash controller devices are

	typically used in digital cameras.

      </para>



      <para>

	The interface can support both LED and xenon flash devices. As

	of writing this, there is no xenon flash driver using this

	interface.

      </para>



      <section id="flash-controls-use-cases">

	<title>Supported use cases</title>



	<section>

	  <title>Unsynchronised LED flash (software strobe)</title>



	  <para>

	    Unsynchronised LED flash is controlled directly by the

	    host as the sensor. The flash must be enabled by the host

	    before the exposure of the image starts and disabled once

	    it ends. The host is fully responsible for the timing of

	    the flash.

	  </para>



	  <para>Example of such device: Nokia N900.</para>

	</section>



	<section>

	  <title>Synchronised LED flash (hardware strobe)</title>



	  <para>

	    The synchronised LED flash is pre-programmed by the host

	    (power and timeout) but controlled by the sensor through a

	    strobe signal from the sensor to the flash.

	  </para>



	  <para>

	    The sensor controls the flash duration and timing. This

	    information typically must be made available to the

	    sensor.

	  </para>



	</section>



	<section>

	  <title>LED flash as torch</title>



	  <para>

	    LED flash may be used as torch in conjunction with another

	    use case involving camera or individually.

	  </para>



	</section>



      </section>



      <table pgwide="1" frame="none" id="flash-control-id">

      <title>Flash Control IDs</title>



      <tgroup cols="4">

	<colspec colname="c1" colwidth="1*" />

	<colspec colname="c2" colwidth="6*" />

	<colspec colname="c3" colwidth="2*" />

	<colspec colname="c4" colwidth="6*" />

	<spanspec namest="c1" nameend="c2" spanname="id" />

	<spanspec namest="c2" nameend="c4" spanname="descr" />

	<thead>

	  <row>

	    <entry spanname="id" align="left">ID</entry>

	    <entry align="left">Type</entry>

	  </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry>

	  </row>

	</thead>

	<tbody valign="top">

	  <row><entry></entry></row>

	  <row>

	    <entry spanname="id"><constant>V4L2_CID_FLASH_CLASS</constant></entry>

	    <entry>class</entry>

	  </row>

	  <row>

	    <entry spanname="descr">The FLASH class descriptor.</entry>

	  </row>

	  <row>

	    <entry spanname="id"><constant>V4L2_CID_FLASH_LED_MODE</constant></entry>

	    <entry>menu</entry>

	  </row>

	  <row id="v4l2-flash-led-mode">

	    <entry spanname="descr">Defines the mode of the flash LED,

	    the high-power white LED attached to the flash controller.

	    Setting this control may not be possible in presence of

	    some faults. See V4L2_CID_FLASH_FAULT.</entry>

	  </row>

	  <row>

	    <entrytbl spanname="descr" cols="2">

	      <tbody valign="top">

		<row>

		  <entry><constant>V4L2_FLASH_LED_MODE_NONE</constant></entry>

		  <entry>Off.</entry>

		</row>

		<row>

		  <entry><constant>V4L2_FLASH_LED_MODE_FLASH</constant></entry>

		  <entry>Flash mode.</entry>

		</row>

		<row>

		  <entry><constant>V4L2_FLASH_LED_MODE_TORCH</constant></entry>

		  <entry>Torch mode. See V4L2_CID_FLASH_TORCH_INTENSITY.</entry>

		</row>

	      </tbody>

	    </entrytbl>

	  </row>

	  <row>

	    <entry spanname="id"><constant>V4L2_CID_FLASH_STROBE_SOURCE</constant></entry>

	    <entry>menu</entry>

	  </row>

	  <row id="v4l2-flash-strobe-source"><entry

	  spanname="descr">Defines the source of the flash LED

	  strobe.</entry>

	  </row>

	  <row>

	    <entrytbl spanname="descr" cols="2">

	      <tbody valign="top">

		<row>

		  <entry><constant>V4L2_FLASH_STROBE_SOURCE_SOFTWARE</constant></entry>

		  <entry>The flash strobe is triggered by using

		  the V4L2_CID_FLASH_STROBE control.</entry>

		</row>

		<row>

		  <entry><constant>V4L2_FLASH_STROBE_SOURCE_EXTERNAL</constant></entry>

		  <entry>The flash strobe is triggered by an

		  external source. Typically this is a sensor,

		  which makes it possible to synchronises the

		  flash strobe start to exposure start.</entry>

		</row>

	      </tbody>

	    </entrytbl>

	  </row>

	  <row>

	    <entry spanname="id"><constant>V4L2_CID_FLASH_STROBE</constant></entry>

	    <entry>button</entry>

	  </row>

	  <row>

	    <entry spanname="descr">Strobe flash. Valid when

	    V4L2_CID_FLASH_LED_MODE is set to

	    V4L2_FLASH_LED_MODE_FLASH and V4L2_CID_FLASH_STROBE_SOURCE

	    is set to V4L2_FLASH_STROBE_SOURCE_SOFTWARE. Setting this

	    control may not be possible in presence of some faults.

	    See V4L2_CID_FLASH_FAULT.</entry>

	  </row>

	  <row>

	    <entry spanname="id"><constant>V4L2_CID_FLASH_STROBE_STOP</constant></entry>

	    <entry>button</entry>

	  </row>

	  <row><entry spanname="descr">Stop flash strobe immediately.</entry>

	  </row>

	  <row>

	    <entry spanname="id"><constant>V4L2_CID_FLASH_STROBE_STATUS</constant></entry>

	    <entry>boolean</entry>

	  </row>

	  <row>

	    <entry spanname="descr">Strobe status: whether the flash

	    is strobing at the moment or not. This is a read-only

	    control.</entry>

	  </row>

	  <row>

	    <entry spanname="id"><constant>V4L2_CID_FLASH_TIMEOUT</constant></entry>

	    <entry>integer</entry>

	  </row>

	  <row>

	    <entry spanname="descr">Hardware timeout for flash. The

	    flash strobe is stopped after this period of time has

	    passed from the start of the strobe.</entry>

	  </row>

	  <row>

	    <entry spanname="id"><constant>V4L2_CID_FLASH_INTENSITY</constant></entry>

	    <entry>integer</entry>

	  </row>

	  <row>

	    <entry spanname="descr">Intensity of the flash strobe when

	    the flash LED is in flash mode

	    (V4L2_FLASH_LED_MODE_FLASH). The unit should be milliamps

	    (mA) if possible.</entry>

	  </row>

	  <row>

	    <entry spanname="id"><constant>V4L2_CID_FLASH_TORCH_INTENSITY</constant></entry>

	    <entry>integer</entry>

	  </row>

	  <row>

	    <entry spanname="descr">Intensity of the flash LED in

	    torch mode (V4L2_FLASH_LED_MODE_TORCH). The unit should be

	    milliamps (mA) if possible. Setting this control may not

	    be possible in presence of some faults. See

	    V4L2_CID_FLASH_FAULT.</entry>

	  </row>

	  <row>

	    <entry spanname="id"><constant>V4L2_CID_FLASH_INDICATOR_INTENSITY</constant></entry>

	    <entry>integer</entry>

	  </row>

	  <row>

	    <entry spanname="descr">Intensity of the indicator LED.

	    The indicator LED may be fully independent of the flash

	    LED. The unit should be microamps (uA) if possible.</entry>

	  </row>

	  <row>

	    <entry spanname="id"><constant>V4L2_CID_FLASH_FAULT</constant></entry>

	    <entry>bitmask</entry>

	  </row>

	  <row>

	    <entry spanname="descr">Faults related to the flash. The

	    faults tell about specific problems in the flash chip

	    itself or the LEDs attached to it. Faults may prevent

	    further use of some of the flash controls. In particular,

	    V4L2_CID_FLASH_LED_MODE is set to V4L2_FLASH_LED_MODE_NONE

	    if the fault affects the flash LED. Exactly which faults

	    have such an effect is chip dependent. Reading the faults

	    resets the control and returns the chip to a usable state

	    if possible.</entry>

	  </row>

	  <row>

	    <entrytbl spanname="descr" cols="2">

	      <tbody valign="top">

		<row>

		  <entry><constant>V4L2_FLASH_FAULT_OVER_VOLTAGE</constant></entry>

		  <entry>Flash controller voltage to the flash LED

		  has exceeded the limit specific to the flash

		  controller.</entry>

		</row>

		<row>

		  <entry><constant>V4L2_FLASH_FAULT_TIMEOUT</constant></entry>

		  <entry>The flash strobe was still on when

		  the timeout set by the user ---

		  V4L2_CID_FLASH_TIMEOUT control --- has expired.

		  Not all flash controllers may set this in all

		  such conditions.</entry>

		</row>

		<row>

		  <entry><constant>V4L2_FLASH_FAULT_OVER_TEMPERATURE</constant></entry>

		  <entry>The flash controller has overheated.</entry>

		</row>

		<row>

		  <entry><constant>V4L2_FLASH_FAULT_SHORT_CIRCUIT</constant></entry>

		  <entry>The short circuit protection of the flash

		  controller has been triggered.</entry>

		</row>

	      </tbody>

	    </entrytbl>

	  </row>

	  <row>

	    <entry spanname="id"><constant>V4L2_CID_FLASH_CHARGE</constant></entry>

	    <entry>boolean</entry>

	  </row>

	  <row><entry spanname="descr">Enable or disable charging of the xenon

	  flash capacitor.</entry>

	  </row>

	  <row>

	    <entry spanname="id"><constant>V4L2_CID_FLASH_READY</constant></entry>

	    <entry>boolean</entry>

	  </row>

	  <row>

	    <entry spanname="descr">Is the flash ready to strobe?

	    Xenon flashes require their capacitors charged before

	    strobing. LED flashes often require a cooldown period

	    after strobe during which another strobe will not be

	    possible. This is a read-only control.</entry>

	  </row>

	  <row><entry></entry></row>

	</tbody>

      </tgroup>

      </table>



    </section>

</section>



  <!--

Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml

+7 −0
Original line number Diff line number Diff line
@@ -250,6 +250,13 @@ These controls are described in <xref 
These controls are described in <xref

		linkend="fm-tx-controls" />.</entry>

	  </row>

	  <row>

	    <entry><constant>V4L2_CTRL_CLASS_FLASH</constant></entry>

	    <entry>0x9c0000</entry>

	    <entry>The class containing flash device controls.

These controls are described in <xref

		linkend="flash-controls" />.</entry>

	  </row>

	</tbody>

      </tgroup>

    </table>