[media] v4l: Add flash control documentation
Add documentation for V4L2 flash controls. Signed-off-by: Sakari Ailus <sakari.ailus@iki.fi> Acked-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
This commit is contained in:
Sakari Ailus
committed by
Mauro Carvalho Chehab
Mauro Carvalho Chehab
parent
0b159acdd5
commit
7ba85fa4fd
@@ -2475,6 +2475,9 @@ ioctls.</para>
|
|||||||
<listitem>
|
<listitem>
|
||||||
<para>&VIDIOC-DBG-G-CHIP-IDENT; ioctl.</para>
|
<para>&VIDIOC-DBG-G-CHIP-IDENT; ioctl.</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>Flash API. <xref linkend="flash-controls" /></para>
|
||||||
|
</listitem>
|
||||||
</itemizedlist>
|
</itemizedlist>
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
|
|||||||
@@ -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
|
<para>For more details about RDS specification, refer to
|
||||||
<xref linkend="en50067" /> document, from CENELEC.</para>
|
<xref linkend="en50067" /> document, from CENELEC.</para>
|
||||||
</section>
|
</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>
|
</section>
|
||||||
|
|
||||||
<!--
|
<!--
|
||||||
|
|||||||
@@ -250,6 +250,13 @@ These controls are described in <xref
|
|||||||
These controls are described in <xref
|
These controls are described in <xref
|
||||||
linkend="fm-tx-controls" />.</entry>
|
linkend="fm-tx-controls" />.</entry>
|
||||||
</row>
|
</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>
|
</tbody>
|
||||||
</tgroup>
|
</tgroup>
|
||||||
</table>
|
</table>
|
||||||
|
|||||||
Reference in New Issue
Block a user