1.. Permission is granted to copy, distribute and/or modify this
2.. document under the terms of the GNU Free Documentation License,
3.. Version 1.1 or any later version published by the Free Software
4.. Foundation, with no Invariant Sections, no Front-Cover Texts
5.. and no Back-Cover Texts. A copy of the license is included at
6.. Documentation/userspace-api/media/fdl-appendix.rst.
7..
8.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
9
10.. _flash-controls:
11
12***********************
13Flash Control Reference
14***********************
15
16The V4L2 flash controls are intended to provide generic access to flash
17controller devices. Flash controller devices are typically used in
18digital cameras.
19
20The interface can support both LED and xenon flash devices. As of
21writing this, there is no xenon flash driver using this interface.
22
23
24.. _flash-controls-use-cases:
25
26Supported use cases
27===================
28
29
30Unsynchronised LED flash (software strobe)
31------------------------------------------
32
33Unsynchronised LED flash is controlled directly by the host as the
34sensor. The flash must be enabled by the host before the exposure of the
35image starts and disabled once it ends. The host is fully responsible
36for the timing of the flash.
37
38Example of such device: Nokia N900.
39
40
41Synchronised LED flash (hardware strobe)
42----------------------------------------
43
44The synchronised LED flash is pre-programmed by the host (power and
45timeout) but controlled by the sensor through a strobe signal from the
46sensor to the flash.
47
48The sensor controls the flash duration and timing. This information
49typically must be made available to the sensor.
50
51
52LED flash as torch
53------------------
54
55LED flash may be used as torch in conjunction with another use case
56involving camera or individually.
57
58
59.. _flash-control-id:
60
61Flash Control IDs
62-----------------
63
64``V4L2_CID_FLASH_CLASS (class)``
65    The FLASH class descriptor.
66
67``V4L2_CID_FLASH_LED_MODE (menu)``
68    Defines the mode of the flash LED, the high-power white LED attached
69    to the flash controller. Setting this control may not be possible in
70    presence of some faults. See V4L2_CID_FLASH_FAULT.
71
72
73
74.. flat-table::
75    :header-rows:  0
76    :stub-columns: 0
77
78    * - ``V4L2_FLASH_LED_MODE_NONE``
79      - Off.
80    * - ``V4L2_FLASH_LED_MODE_FLASH``
81      - Flash mode.
82    * - ``V4L2_FLASH_LED_MODE_TORCH``
83      - Torch mode. See V4L2_CID_FLASH_TORCH_INTENSITY.
84
85
86
87``V4L2_CID_FLASH_STROBE_SOURCE (menu)``
88    Defines the source of the flash LED strobe.
89
90.. tabularcolumns:: |p{7.5cm}|p{10.0cm}|
91
92.. flat-table::
93    :header-rows:  0
94    :stub-columns: 0
95
96    * - ``V4L2_FLASH_STROBE_SOURCE_SOFTWARE``
97      - The flash strobe is triggered by using the
98	V4L2_CID_FLASH_STROBE control.
99    * - ``V4L2_FLASH_STROBE_SOURCE_EXTERNAL``
100      - The flash strobe is triggered by an external source. Typically
101	this is a sensor, which makes it possible to synchronise the
102	flash strobe start to exposure start.
103
104
105
106``V4L2_CID_FLASH_STROBE (button)``
107    Strobe flash. Valid when V4L2_CID_FLASH_LED_MODE is set to
108    V4L2_FLASH_LED_MODE_FLASH and V4L2_CID_FLASH_STROBE_SOURCE
109    is set to V4L2_FLASH_STROBE_SOURCE_SOFTWARE. Setting this
110    control may not be possible in presence of some faults. See
111    V4L2_CID_FLASH_FAULT.
112
113``V4L2_CID_FLASH_STROBE_STOP (button)``
114    Stop flash strobe immediately.
115
116``V4L2_CID_FLASH_STROBE_STATUS (boolean)``
117    Strobe status: whether the flash is strobing at the moment or not.
118    This is a read-only control.
119
120``V4L2_CID_FLASH_TIMEOUT (integer)``
121    Hardware timeout for flash. The flash strobe is stopped after this
122    period of time has passed from the start of the strobe.
123
124``V4L2_CID_FLASH_INTENSITY (integer)``
125    Intensity of the flash strobe when the flash LED is in flash mode
126    (V4L2_FLASH_LED_MODE_FLASH). The unit should be milliamps (mA)
127    if possible.
128
129``V4L2_CID_FLASH_TORCH_INTENSITY (integer)``
130    Intensity of the flash LED in torch mode
131    (V4L2_FLASH_LED_MODE_TORCH). The unit should be milliamps (mA)
132    if possible. Setting this control may not be possible in presence of
133    some faults. See V4L2_CID_FLASH_FAULT.
134
135``V4L2_CID_FLASH_INDICATOR_INTENSITY (integer)``
136    Intensity of the indicator LED. The indicator LED may be fully
137    independent of the flash LED. The unit should be microamps (uA) if
138    possible.
139
140``V4L2_CID_FLASH_FAULT (bitmask)``
141    Faults related to the flash. The faults tell about specific problems
142    in the flash chip itself or the LEDs attached to it. Faults may
143    prevent further use of some of the flash controls. In particular,
144    V4L2_CID_FLASH_LED_MODE is set to V4L2_FLASH_LED_MODE_NONE
145    if the fault affects the flash LED. Exactly which faults have such
146    an effect is chip dependent. Reading the faults resets the control
147    and returns the chip to a usable state if possible.
148
149.. tabularcolumns:: |p{8.4cm}|p{9.1cm}|
150
151.. flat-table::
152    :header-rows:  0
153    :stub-columns: 0
154
155    * - ``V4L2_FLASH_FAULT_OVER_VOLTAGE``
156      - Flash controller voltage to the flash LED has exceeded the limit
157	specific to the flash controller.
158    * - ``V4L2_FLASH_FAULT_TIMEOUT``
159      - The flash strobe was still on when the timeout set by the user ---
160	V4L2_CID_FLASH_TIMEOUT control --- has expired. Not all flash
161	controllers may set this in all such conditions.
162    * - ``V4L2_FLASH_FAULT_OVER_TEMPERATURE``
163      - The flash controller has overheated.
164    * - ``V4L2_FLASH_FAULT_SHORT_CIRCUIT``
165      - The short circuit protection of the flash controller has been
166	triggered.
167    * - ``V4L2_FLASH_FAULT_OVER_CURRENT``
168      - Current in the LED power supply has exceeded the limit specific to
169	the flash controller.
170    * - ``V4L2_FLASH_FAULT_INDICATOR``
171      - The flash controller has detected a short or open circuit
172	condition on the indicator LED.
173    * - ``V4L2_FLASH_FAULT_UNDER_VOLTAGE``
174      - Flash controller voltage to the flash LED has been below the
175	minimum limit specific to the flash controller.
176    * - ``V4L2_FLASH_FAULT_INPUT_VOLTAGE``
177      - The input voltage of the flash controller is below the limit under
178	which strobing the flash at full current will not be possible.The
179	condition persists until this flag is no longer set.
180    * - ``V4L2_FLASH_FAULT_LED_OVER_TEMPERATURE``
181      - The temperature of the LED has exceeded its allowed upper limit.
182
183
184
185``V4L2_CID_FLASH_CHARGE (boolean)``
186    Enable or disable charging of the xenon flash capacitor.
187
188``V4L2_CID_FLASH_READY (boolean)``
189    Is the flash ready to strobe? Xenon flashes require their capacitors
190    charged before strobing. LED flashes often require a cooldown period
191    after strobe during which another strobe will not be possible. This
192    is a read-only control.
193