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