[RFC] V4L2 API for flash devices

[RFC] V4L2 API for flash devices

[Sakari Ailus]

Hi,

This is a proposal for an interface for controlling flash devices on the
V4L2/v4l2_subdev APIs. My plan is to use the interface in the ADP1653
driver, the flash controller used in the Nokia N900.

Comments and questions are very, very welcome!


Scope
=====

This RFC is focused mostly on the ADP1653 [1] and similar chips [2, 3]
which provides following functionality. [2, 3] mostly differ on the
available faults --- for example, there are faults also for the
indicator LED.

- High power LED output (flash or torch modes)
- Low power indicator LED output (a.k.a. privacy light)
- Programmable flash timeout
- Software and hardware strobe
- Fault detection
	- Overvoltage
	- Overtemperature
	- Short circuit
	- Timeout
- Programmable current (both high-power and indicator LEDs)

If anyone else is aware of hardware which significantly differs from
these and does not get served well under the proposed interface, please
tell about it.

This RFC does NOT address the synchronisation of the flash to a given
frame since this task is typically performed by the sensor through a
strobe signal. The host does not have enough information for this ---
exact timing information on the exposure of the sensor pixel array. In
this case the flash synchronisation is visible to the flash controller
as the hardware strobe originating from the sensor.

Flash synchronisation requires

1) flash control capability from the sensor including a strobe output,
2) strobe input in the flash controller,
3) (optionally) ability to program sensor parameters at given frame,
such as flash strobe, and
4) ability to read back metadata produced by the sensor related to a
given frame. This should include whether the frame is exposed with
flash, i.e. the sensor's flash strobe output.

Since we have little examples of both in terms of hardware support,
which is in practice required, it was decided to postpone the interface
specification for now. [6]

Xenon flash controllers exist but I don't have a specific example of
those. Typically the interface is quite simple. Gpio pins for charge and
strobe. The length of the strobe signal determines the strength of the
flash pulse. The strobe is controlled by the sensor as for LED flash if
it is hardware based.


Known use cases
===============

The use case listed below concentrate on using a flash in a mobile
device, for example in a mobile phone. The use cases could be somewhat
different in devices the primary use of which is camera.

Unsynchronised LED flash (software strobe)
------------------------------------------

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.

Example of such device: Nokia N900.


Synchronised LED flash (hardware strobe)
----------------------------------------

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.

The sensor controls the flash duration and timing. This control
typically must be programmed to the sensor, and specifying an interface
for this is out of scope of this RFC.

The LED flash controllers we know of can function in both synchronised
and unsynchronised modes.


LED flash as torch
------------------

LED flash may be used as torch in conjunction with another use case
involving camera or individually. [4]


Synchronised xenon flash
------------------------

The synchronised xenon flash is controlled more closely by the sensor
than the LED flash. There is no separate intensity control for the xenon
flash as its intensity is determined by the length of the strobe pulse.
Several consecutive strobe pluses are possible but this needs to be
still controlled by the sensor.


Proposed interface
==================

The flash, either LED or xenon, does not require large amounts of data
to control it. There are parameters to control it but they are
independent and assumably some hardware would only support some subsets
of the functionality available somewhere else. Thus V4L2 controls seem
an ideal way to support flash controllers.

A separate control class is reserved for the flash controls. It is
called V4L2_CTRL_CLASS_FLASH.

Type of the control; type of flash is in parentheses after the control.


	V4L2_CID_FLASH_STROBE (button; LED)

Strobe the flash using software strobe from the host, typically over I2C
or a GPIO. The flash is NOT synchronised to sensor pixel are exposure
since the command is given asynchronously. Alternatively, if the flash
controller is a master in the system, the sensor exposure may be
triggered based on software strobe.


	V4L2_CID_FLASH_STROBE_MODE (menu; LED)

Use hardware or software strobe. If hardware strobe is selected, the
flash controller is a slave in the system where the sensor produces the
strobe signal to the flash.

In this case the flash controller setup is limited to programming strobe
timeout and power (LED flash) and the sensor controls the timing and
length of the strobe.

enum v4l2_flash_strobe_mode {
	V4L2_FLASH_STROBE_MODE_SOFTWARE,
	V4L2_FLASH_STROBE_MODE_EXT_STROBE,
};


	V4L2_CID_FLASH_TIMEOUT (integer; LED)

The flash controller provides timeout functionality to shut down the led
in case the host fails to do that. For hardware strobe, this is the
maximum amount of time the flash should stay on, and the purpose of the
setting is to prevent the LED from catching fire.

For software strobe, the setting may be used to limit the length of the
strobe in case a driver does not implement it itself. The granularity of
the timeout in [1, 2, 3] is very coarse. However, the length of a
driver-implemented LED strobe shutoff is very dependent on host.
Possibly V4L2_CID_FLASH_DURATION should be added, and
V4L2_CID_FLASH_TIMEOUT would be read-only so that the user would be able
to obtain the actual hardware implemented safety timeout.

Likely a standard unit such as ms or µs should be used.


	V4L2_CID_FLASH_LED_MODE (menu; LED)

enum v4l2_flash_led_mode {
	V4L2_FLASH_LED_MODE_FLASH = 1,
	V4L2_FLASH_LED_MODE_TORCH,
};


	V4L2_CID_FLASH_INTENSITY (integer; LED)

Intensity of the flash in hardware specific units. The LED flash
controller provides current to the LED but the actual luminous power is
dictated by the LED connected to the controller.


	V4L2_CID_FLASH_TORCH_INTENSITY (integer; LED)

Intensity of the flash in hardware specific units.


	V4L2_CID_FLASH_INDICATOR_INTENSITY (integer; LED)

Intensity of the indicator light in hardware specific units.


	V4L2_CID_FLASH_FAULT (bit field; LED)

This is a bitmask containing the fault information for the flash. This
assumes the proposed V4L2 bit mask controls [5]; otherwise this would
likely need to be a set of controls.

#define V4L2_FLASH_FAULT_OVER_VOLTAGE		0x00000001
#define V4L2_FLASH_FAULT_TIMEOUT		0x00000002
#define V4L2_FLASH_FAULT_OVER_TEMPERATURE	0x00000004
#define V4L2_FLASH_FAULT_SHORT_CIRCUIT		0x00000008

Several faults may occur at single occasion. The ADP1653 is able to
inform the user a fault has occurred, so a V4L2 control event (proposed
earlier) could be used for that.

These faults are supported by the ADP1653. More faults may be added as
support for more chips require that. In some other hardware faults are
available for indicator led as well.

Question: should indicator faults be part of the same control, or a
different control, e.g. V4L2_CID_FLASH_INDICATOR_FAULT?


	V4L2_CID_FLASH_CHARGE (bool; xenon)

Charge control for the xenon flash. Enable or disable charging.


	V4L2_CID_FLASH_READY (bool; xenon, LED)

Flash is ready to strobe. On xenon flash this tells the capacitor has
been charged, on LED flash it's that the LED is no longer too hot.

The implementation on LED flash may be modelling the temperature
behaviour of the LED in the driver (or elsewhere, e.g. library or board
code) if the hardware does not provide direct temperature information
from the LED.

A V4L2 control event should be produced whenever the flash becomes ready.


References
==========

[1] http://www.analog.com/static/imported-files/data_sheets/ADP1653.pdf

[2] http://www.national.com/mpf/LM/LM3555.html#Overview

[3]
http://www.austriamicrosystems.com/eng/Products/Lighting-Management/Camera-Flash-LED-Drivers/AS3645

[4] http://maemo.org/downloads/product/Maemo5/flashlight-applet/

[5]
http://www.retiisi.org.uk/v4l2/v4l2-brainstorming-warsaw-2011-03/notes/day%202%20(SGz6LU2esk).html

[6]
http://www.retiisi.org.uk/v4l2/v4l2-brainstorming-warsaw-2011-03/notes/day%203%20(RhoYa0X9D7).html


Cheers,

-- 
Sakari Ailus
sakari.ailus@maxwell.research.nokia.com

Re: [RFC] V4L2 API for flash devices

[Hans Verkuil]

On Monday, March 28, 2011 14:55:40 Sakari Ailus wrote:
> Hi,
> 
> This is a proposal for an interface for controlling flash devices on the
> V4L2/v4l2_subdev APIs. My plan is to use the interface in the ADP1653
> driver, the flash controller used in the Nokia N900.
> 
> Comments and questions are very, very welcome!
> 
> 
> Scope
> =====
> 
> This RFC is focused mostly on the ADP1653 [1] and similar chips [2, 3]
> which provides following functionality. [2, 3] mostly differ on the
> available faults --- for example, there are faults also for the
> indicator LED.
> 
> - High power LED output (flash or torch modes)
> - Low power indicator LED output (a.k.a. privacy light)
> - Programmable flash timeout
> - Software and hardware strobe
> - Fault detection
> 	- Overvoltage
> 	- Overtemperature
> 	- Short circuit
> 	- Timeout
> - Programmable current (both high-power and indicator LEDs)
> 
> If anyone else is aware of hardware which significantly differs from
> these and does not get served well under the proposed interface, please
> tell about it.
> 
> This RFC does NOT address the synchronisation of the flash to a given
> frame since this task is typically performed by the sensor through a
> strobe signal. The host does not have enough information for this ---
> exact timing information on the exposure of the sensor pixel array. In
> this case the flash synchronisation is visible to the flash controller
> as the hardware strobe originating from the sensor.
> 
> Flash synchronisation requires
> 
> 1) flash control capability from the sensor including a strobe output,
> 2) strobe input in the flash controller,
> 3) (optionally) ability to program sensor parameters at given frame,
> such as flash strobe, and
> 4) ability to read back metadata produced by the sensor related to a
> given frame. This should include whether the frame is exposed with
> flash, i.e. the sensor's flash strobe output.
> 
> Since we have little examples of both in terms of hardware support,
> which is in practice required, it was decided to postpone the interface
> specification for now. [6]
> 
> Xenon flash controllers exist but I don't have a specific example of
> those. Typically the interface is quite simple. Gpio pins for charge and
> strobe. The length of the strobe signal determines the strength of the
> flash pulse. The strobe is controlled by the sensor as for LED flash if
> it is hardware based.
> 
> 
> Known use cases
> ===============
> 
> The use case listed below concentrate on using a flash in a mobile
> device, for example in a mobile phone. The use cases could be somewhat
> different in devices the primary use of which is camera.
> 
> Unsynchronised LED flash (software strobe)
> ------------------------------------------
> 
> 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.
> 
> Example of such device: Nokia N900.
> 
> 
> Synchronised LED flash (hardware strobe)
> ----------------------------------------
> 
> 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.
> 
> The sensor controls the flash duration and timing. This control
> typically must be programmed to the sensor, and specifying an interface
> for this is out of scope of this RFC.
> 
> The LED flash controllers we know of can function in both synchronised
> and unsynchronised modes.
> 
> 
> LED flash as torch
> ------------------
> 
> LED flash may be used as torch in conjunction with another use case
> involving camera or individually. [4]
> 
> 
> Synchronised xenon flash
> ------------------------
> 
> The synchronised xenon flash is controlled more closely by the sensor
> than the LED flash. There is no separate intensity control for the xenon
> flash as its intensity is determined by the length of the strobe pulse.
> Several consecutive strobe pluses are possible but this needs to be
> still controlled by the sensor.
> 
> 
> Proposed interface
> ==================
> 
> The flash, either LED or xenon, does not require large amounts of data
> to control it. There are parameters to control it but they are
> independent and assumably some hardware would only support some subsets
> of the functionality available somewhere else. Thus V4L2 controls seem
> an ideal way to support flash controllers.
> 
> A separate control class is reserved for the flash controls. It is
> called V4L2_CTRL_CLASS_FLASH.
> 
> Type of the control; type of flash is in parentheses after the control.
> 
> 
> 	V4L2_CID_FLASH_STROBE (button; LED)
> 
> Strobe the flash using software strobe from the host, typically over I2C
> or a GPIO. The flash is NOT synchronised to sensor pixel are exposure
> since the command is given asynchronously. Alternatively, if the flash
> controller is a master in the system, the sensor exposure may be
> triggered based on software strobe.
> 
> 
> 	V4L2_CID_FLASH_STROBE_MODE (menu; LED)
> 
> Use hardware or software strobe. If hardware strobe is selected, the
> flash controller is a slave in the system where the sensor produces the
> strobe signal to the flash.
> 
> In this case the flash controller setup is limited to programming strobe
> timeout and power (LED flash) and the sensor controls the timing and
> length of the strobe.
> 
> enum v4l2_flash_strobe_mode {
> 	V4L2_FLASH_STROBE_MODE_SOFTWARE,
> 	V4L2_FLASH_STROBE_MODE_EXT_STROBE,
> };

I'm not sure about the naming. Perhaps call the first MODE_SW_STROBE?
Or MODE_SW_TRIGGER and MODE_HW_TRIGGER? Or perhaps just MODE_SOFTWARE and
MODE_EXTERNAL or MODE_HARDWARE.

> 
> 
> 	V4L2_CID_FLASH_TIMEOUT (integer; LED)
> 
> The flash controller provides timeout functionality to shut down the led
> in case the host fails to do that. For hardware strobe, this is the
> maximum amount of time the flash should stay on, and the purpose of the
> setting is to prevent the LED from catching fire.
> 
> For software strobe, the setting may be used to limit the length of the
> strobe in case a driver does not implement it itself. The granularity of
> the timeout in [1, 2, 3] is very coarse. However, the length of a
> driver-implemented LED strobe shutoff is very dependent on host.
> Possibly V4L2_CID_FLASH_DURATION should be added, and
> V4L2_CID_FLASH_TIMEOUT would be read-only so that the user would be able
> to obtain the actual hardware implemented safety timeout.
> 
> Likely a standard unit such as ms or µs should be used.

It seems to me that this control should always be read-only. A setting like
this is very much hardware specific and you don't want an attacker changing
the timeout to the max value that might cause a LED catching fire.

> 
> 
> 	V4L2_CID_FLASH_LED_MODE (menu; LED)
> 
> enum v4l2_flash_led_mode {
> 	V4L2_FLASH_LED_MODE_FLASH = 1,
> 	V4L2_FLASH_LED_MODE_TORCH,
> };

Would a LED_MODE_NONE make sense as well to turn off the flash completely?

> 
> 
> 	V4L2_CID_FLASH_INTENSITY (integer; LED)
> 
> Intensity of the flash in hardware specific units. The LED flash
> controller provides current to the LED but the actual luminous power is
> dictated by the LED connected to the controller.
> 
> 
> 	V4L2_CID_FLASH_TORCH_INTENSITY (integer; LED)
> 
> Intensity of the flash in hardware specific units.
> 
> 
> 	V4L2_CID_FLASH_INDICATOR_INTENSITY (integer; LED)
> 
> Intensity of the indicator light in hardware specific units.
> 
> 
> 	V4L2_CID_FLASH_FAULT (bit field; LED)
> 
> This is a bitmask containing the fault information for the flash. This
> assumes the proposed V4L2 bit mask controls [5]; otherwise this would
> likely need to be a set of controls.

I intend to work on bitmask controls and control events tomorrow.

> 
> #define V4L2_FLASH_FAULT_OVER_VOLTAGE		0x00000001
> #define V4L2_FLASH_FAULT_TIMEOUT		0x00000002
> #define V4L2_FLASH_FAULT_OVER_TEMPERATURE	0x00000004
> #define V4L2_FLASH_FAULT_SHORT_CIRCUIT		0x00000008
> 
> Several faults may occur at single occasion. The ADP1653 is able to
> inform the user a fault has occurred, so a V4L2 control event (proposed
> earlier) could be used for that.
> 
> These faults are supported by the ADP1653. More faults may be added as
> support for more chips require that. In some other hardware faults are
> available for indicator led as well.
> 
> Question: should indicator faults be part of the same control, or a
> different control, e.g. V4L2_CID_FLASH_INDICATOR_FAULT?

If they are independently reported, then I would say so, yes.

> 
> 
> 	V4L2_CID_FLASH_CHARGE (bool; xenon)
> 
> Charge control for the xenon flash. Enable or disable charging.
> 
> 
> 	V4L2_CID_FLASH_READY (bool; xenon, LED)
> 
> Flash is ready to strobe. On xenon flash this tells the capacitor has
> been charged, on LED flash it's that the LED is no longer too hot.
> 
> The implementation on LED flash may be modelling the temperature
> behaviour of the LED in the driver (or elsewhere, e.g. library or board
> code) if the hardware does not provide direct temperature information
> from the LED.
> 
> A V4L2 control event should be produced whenever the flash becomes ready.

Looks good!

Regards,

	Hans

> 
> 
> References
> ==========
> 
> [1] http://www.analog.com/static/imported-files/data_sheets/ADP1653.pdf
> 
> [2] http://www.national.com/mpf/LM/LM3555.html#Overview
> 
> [3]
> http://www.austriamicrosystems.com/eng/Products/Lighting-Management/Camera-Flash-LED-Drivers/AS3645
> 
> [4] http://maemo.org/downloads/product/Maemo5/flashlight-applet/
> 
> [5]
> http://www.retiisi.org.uk/v4l2/v4l2-brainstorming-warsaw-2011-03/notes/day%202%20(SGz6LU2esk).html
> 
> [6]
> http://www.retiisi.org.uk/v4l2/v4l2-brainstorming-warsaw-2011-03/notes/day%203%20(RhoYa0X9D7).html
> 
> 
> Cheers,
> 
> 

Re: [RFC] V4L2 API for flash devices

[Sakari Ailus]

Hi Hans,

Many thanks for the comments!

Hans Verkuil wrote:
> On Monday, March 28, 2011 14:55:40 Sakari Ailus wrote:
>> Hi,
>>
>> This is a proposal for an interface for controlling flash devices on the
>> V4L2/v4l2_subdev APIs. My plan is to use the interface in the ADP1653
>> driver, the flash controller used in the Nokia N900.
>>
>> Comments and questions are very, very welcome!
>>
>>
>> Scope
>> =====
>>
>> This RFC is focused mostly on the ADP1653 [1] and similar chips [2, 3]
>> which provides following functionality. [2, 3] mostly differ on the
>> available faults --- for example, there are faults also for the
>> indicator LED.
>>
>> - High power LED output (flash or torch modes)
>> - Low power indicator LED output (a.k.a. privacy light)
>> - Programmable flash timeout
>> - Software and hardware strobe
>> - Fault detection
>> 	- Overvoltage
>> 	- Overtemperature
>> 	- Short circuit
>> 	- Timeout
>> - Programmable current (both high-power and indicator LEDs)
>>
>> If anyone else is aware of hardware which significantly differs from
>> these and does not get served well under the proposed interface, please
>> tell about it.
>>
>> This RFC does NOT address the synchronisation of the flash to a given
>> frame since this task is typically performed by the sensor through a
>> strobe signal. The host does not have enough information for this ---
>> exact timing information on the exposure of the sensor pixel array. In
>> this case the flash synchronisation is visible to the flash controller
>> as the hardware strobe originating from the sensor.
>>
>> Flash synchronisation requires
>>
>> 1) flash control capability from the sensor including a strobe output,
>> 2) strobe input in the flash controller,
>> 3) (optionally) ability to program sensor parameters at given frame,
>> such as flash strobe, and
>> 4) ability to read back metadata produced by the sensor related to a
>> given frame. This should include whether the frame is exposed with
>> flash, i.e. the sensor's flash strobe output.
>>
>> Since we have little examples of both in terms of hardware support,
>> which is in practice required, it was decided to postpone the interface
>> specification for now. [6]
>>
>> Xenon flash controllers exist but I don't have a specific example of
>> those. Typically the interface is quite simple. Gpio pins for charge and
>> strobe. The length of the strobe signal determines the strength of the
>> flash pulse. The strobe is controlled by the sensor as for LED flash if
>> it is hardware based.
>>
>>
>> Known use cases
>> ===============
>>
>> The use case listed below concentrate on using a flash in a mobile
>> device, for example in a mobile phone. The use cases could be somewhat
>> different in devices the primary use of which is camera.
>>
>> Unsynchronised LED flash (software strobe)
>> ------------------------------------------
>>
>> 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.
>>
>> Example of such device: Nokia N900.
>>
>>
>> Synchronised LED flash (hardware strobe)
>> ----------------------------------------
>>
>> 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.
>>
>> The sensor controls the flash duration and timing. This control
>> typically must be programmed to the sensor, and specifying an interface
>> for this is out of scope of this RFC.
>>
>> The LED flash controllers we know of can function in both synchronised
>> and unsynchronised modes.
>>
>>
>> LED flash as torch
>> ------------------
>>
>> LED flash may be used as torch in conjunction with another use case
>> involving camera or individually. [4]
>>
>>
>> Synchronised xenon flash
>> ------------------------
>>
>> The synchronised xenon flash is controlled more closely by the sensor
>> than the LED flash. There is no separate intensity control for the xenon
>> flash as its intensity is determined by the length of the strobe pulse.
>> Several consecutive strobe pluses are possible but this needs to be
>> still controlled by the sensor.
>>
>>
>> Proposed interface
>> ==================
>>
>> The flash, either LED or xenon, does not require large amounts of data
>> to control it. There are parameters to control it but they are
>> independent and assumably some hardware would only support some subsets
>> of the functionality available somewhere else. Thus V4L2 controls seem
>> an ideal way to support flash controllers.
>>
>> A separate control class is reserved for the flash controls. It is
>> called V4L2_CTRL_CLASS_FLASH.
>>
>> Type of the control; type of flash is in parentheses after the control.
>>
>>
>> 	V4L2_CID_FLASH_STROBE (button; LED)
>>
>> Strobe the flash using software strobe from the host, typically over I2C
>> or a GPIO. The flash is NOT synchronised to sensor pixel are exposure
>> since the command is given asynchronously. Alternatively, if the flash
>> controller is a master in the system, the sensor exposure may be
>> triggered based on software strobe.

It occurred to me that an application might want to turn off a flash
which has been strobed on software. That can't be done on a single
button control.

V4L2_CID_FLASH_SHUTDOWN?

The application would know the flash strobe is ongoing before it
receives a timeout fault. I somehow feel that there should be a control
telling that directly.

What about using a bool control for the strobe?

>> 	V4L2_CID_FLASH_STROBE_MODE (menu; LED)
>>
>> Use hardware or software strobe. If hardware strobe is selected, the
>> flash controller is a slave in the system where the sensor produces the
>> strobe signal to the flash.
>>
>> In this case the flash controller setup is limited to programming strobe
>> timeout and power (LED flash) and the sensor controls the timing and
>> length of the strobe.
>>
>> enum v4l2_flash_strobe_mode {
>> 	V4L2_FLASH_STROBE_MODE_SOFTWARE,
>> 	V4L2_FLASH_STROBE_MODE_EXT_STROBE,
>> };
> 
> I'm not sure about the naming. Perhaps call the first MODE_SW_STROBE?
> Or MODE_SW_TRIGGER and MODE_HW_TRIGGER? Or perhaps just MODE_SOFTWARE and
> MODE_EXTERNAL or MODE_HARDWARE.

MODE_SOFTWARE and MODE_EXTERNAL (or MODE_HARDWARE) are the best, I
think. Indeed there's no need to repeat strobe in the name of a strobe mode.

"External" is good since it directly indicates the strobe is external to
the flash controller.

>>
>>
>> 	V4L2_CID_FLASH_TIMEOUT (integer; LED)
>>
>> The flash controller provides timeout functionality to shut down the led
>> in case the host fails to do that. For hardware strobe, this is the
>> maximum amount of time the flash should stay on, and the purpose of the
>> setting is to prevent the LED from catching fire.
>>
>> For software strobe, the setting may be used to limit the length of the
>> strobe in case a driver does not implement it itself. The granularity of
>> the timeout in [1, 2, 3] is very coarse. However, the length of a
>> driver-implemented LED strobe shutoff is very dependent on host.
>> Possibly V4L2_CID_FLASH_DURATION should be added, and
>> V4L2_CID_FLASH_TIMEOUT would be read-only so that the user would be able
>> to obtain the actual hardware implemented safety timeout.
>>
>> Likely a standard unit such as ms or µs should be used.
> 
> It seems to me that this control should always be read-only. A setting like
> this is very much hardware specific and you don't want an attacker changing
> the timeout to the max value that might cause a LED catching fire.

I'm not sure about that.

The driver already must take care of protecting the hardware in my
opinion. Besides, at least one control is required to select the
duration for the flash if there's no hardware synchronisation.

What about this:

	V4L2_CID_FLASH_TIMEOUT

Hardware timeout, read-only. Programmed to the maximum value allowed by
the hardware for the external strobe, greater or equal to
V4L2_CID_FLASH_DURATION for software strobe.

	V4L2_CID_FLASH_DURATION

Software implemented timeout when V4L2_CID_FLASH_STROBE_MODE ==
V4L2_FLASH_STROBE_MODE_SOFTWARE.

I have to say I'm not entirely sure the duration control is required.
The timeout could be writable for software strobe in the case drivers do
not implement software timeout. The granularity isn't _that_ much
anyway. Also, a timeout fault should be produced whenever the duration
would expire.

Perhaps it would be best to just leave that out for now.

>>
>>
>> 	V4L2_CID_FLASH_LED_MODE (menu; LED)
>>
>> enum v4l2_flash_led_mode {
>> 	V4L2_FLASH_LED_MODE_FLASH = 1,
>> 	V4L2_FLASH_LED_MODE_TORCH,
>> };
> 
> Would a LED_MODE_NONE make sense as well to turn off the flash completely?

It would essentially be the same as choosing software strobe and
disabling strobe. A separate mode for this still could be good to make
it explicit.

>>
>>
>> 	V4L2_CID_FLASH_INTENSITY (integer; LED)
>>
>> Intensity of the flash in hardware specific units. The LED flash
>> controller provides current to the LED but the actual luminous power is
>> dictated by the LED connected to the controller.
>>
>>
>> 	V4L2_CID_FLASH_TORCH_INTENSITY (integer; LED)
>>
>> Intensity of the flash in hardware specific units.
>>
>>
>> 	V4L2_CID_FLASH_INDICATOR_INTENSITY (integer; LED)
>>
>> Intensity of the indicator light in hardware specific units.
>>
>>
>> 	V4L2_CID_FLASH_FAULT (bit field; LED)
>>
>> This is a bitmask containing the fault information for the flash. This
>> assumes the proposed V4L2 bit mask controls [5]; otherwise this would
>> likely need to be a set of controls.
> 
> I intend to work on bitmask controls and control events tomorrow.

Nice! I look forward to see them! :-)

>>
>> #define V4L2_FLASH_FAULT_OVER_VOLTAGE		0x00000001
>> #define V4L2_FLASH_FAULT_TIMEOUT		0x00000002
>> #define V4L2_FLASH_FAULT_OVER_TEMPERATURE	0x00000004
>> #define V4L2_FLASH_FAULT_SHORT_CIRCUIT		0x00000008
>>
>> Several faults may occur at single occasion. The ADP1653 is able to
>> inform the user a fault has occurred, so a V4L2 control event (proposed
>> earlier) could be used for that.

Btw. as this is an I2C device, there's an external interrupt pin which
tells this. Very likely the board code needs to tell this to the driver,
or the driver could depend on the GPIO framework while the configuration
would be in the board code.

>> These faults are supported by the ADP1653. More faults may be added as
>> support for more chips require that. In some other hardware faults are
>> available for indicator led as well.
>>
>> Question: should indicator faults be part of the same control, or a
>> different control, e.g. V4L2_CID_FLASH_INDICATOR_FAULT?
> 
> If they are independently reported, then I would say so, yes.

I believe it could be the same register, but this could be hardware
dependent.

Still, the faults essentially can be divided to separate LEDs. Perhaps
it'd be good to rethink this when someone writes a driver for such a
device. :-)

>>
>>
>> 	V4L2_CID_FLASH_CHARGE (bool; xenon)
>>
>> Charge control for the xenon flash. Enable or disable charging.
>>
>>
>> 	V4L2_CID_FLASH_READY (bool; xenon, LED)
>>
>> Flash is ready to strobe. On xenon flash this tells the capacitor has
>> been charged, on LED flash it's that the LED is no longer too hot.
>>
>> The implementation on LED flash may be modelling the temperature
>> behaviour of the LED in the driver (or elsewhere, e.g. library or board
>> code) if the hardware does not provide direct temperature information
>> from the LED.
>>
>> A V4L2 control event should be produced whenever the flash becomes ready.
> 
> Looks good!

Thanks! :-)

> 
> Regards,
> 
> 	Hans
> 
>>
>>
>> References
>> ==========
>>
>> [1] http://www.analog.com/static/imported-files/data_sheets/ADP1653.pdf
>>
>> [2] http://www.national.com/mpf/LM/LM3555.html#Overview
>>
>> [3]
>> http://www.austriamicrosystems.com/eng/Products/Lighting-Management/Camera-Flash-LED-Drivers/AS3645
>>
>> [4] http://maemo.org/downloads/product/Maemo5/flashlight-applet/
>>
>> [5]
>> http://www.retiisi.org.uk/v4l2/v4l2-brainstorming-warsaw-2011-03/notes/day%202%20(SGz6LU2esk).html
>>
>> [6]
>> http://www.retiisi.org.uk/v4l2/v4l2-brainstorming-warsaw-2011-03/notes/day%203%20(RhoYa0X9D7).html
>>
>>
>> Cheers,
>>
>>
> 


-- 
Sakari Ailus
sakari.ailus@maxwell.research.nokia.com

Re: [RFC] V4L2 API for flash devices

[Hans Verkuil]

On Tuesday, March 29, 2011 11:35:19 Sakari Ailus wrote:
> Hi Hans,
> 
> Many thanks for the comments!
> 
> Hans Verkuil wrote:
> > On Monday, March 28, 2011 14:55:40 Sakari Ailus wrote:
> >> Hi,
> >>
> >> This is a proposal for an interface for controlling flash devices on the
> >> V4L2/v4l2_subdev APIs. My plan is to use the interface in the ADP1653
> >> driver, the flash controller used in the Nokia N900.
> >>
> >> Comments and questions are very, very welcome!
> >>
> >>
> >> Scope
> >> =====
> >>
> >> This RFC is focused mostly on the ADP1653 [1] and similar chips [2, 3]
> >> which provides following functionality. [2, 3] mostly differ on the
> >> available faults --- for example, there are faults also for the
> >> indicator LED.
> >>
> >> - High power LED output (flash or torch modes)
> >> - Low power indicator LED output (a.k.a. privacy light)
> >> - Programmable flash timeout
> >> - Software and hardware strobe
> >> - Fault detection
> >> 	- Overvoltage
> >> 	- Overtemperature
> >> 	- Short circuit
> >> 	- Timeout
> >> - Programmable current (both high-power and indicator LEDs)
> >>
> >> If anyone else is aware of hardware which significantly differs from
> >> these and does not get served well under the proposed interface, please
> >> tell about it.
> >>
> >> This RFC does NOT address the synchronisation of the flash to a given
> >> frame since this task is typically performed by the sensor through a
> >> strobe signal. The host does not have enough information for this ---
> >> exact timing information on the exposure of the sensor pixel array. In
> >> this case the flash synchronisation is visible to the flash controller
> >> as the hardware strobe originating from the sensor.
> >>
> >> Flash synchronisation requires
> >>
> >> 1) flash control capability from the sensor including a strobe output,
> >> 2) strobe input in the flash controller,
> >> 3) (optionally) ability to program sensor parameters at given frame,
> >> such as flash strobe, and
> >> 4) ability to read back metadata produced by the sensor related to a
> >> given frame. This should include whether the frame is exposed with
> >> flash, i.e. the sensor's flash strobe output.
> >>
> >> Since we have little examples of both in terms of hardware support,
> >> which is in practice required, it was decided to postpone the interface
> >> specification for now. [6]
> >>
> >> Xenon flash controllers exist but I don't have a specific example of
> >> those. Typically the interface is quite simple. Gpio pins for charge and
> >> strobe. The length of the strobe signal determines the strength of the
> >> flash pulse. The strobe is controlled by the sensor as for LED flash if
> >> it is hardware based.
> >>
> >>
> >> Known use cases
> >> ===============
> >>
> >> The use case listed below concentrate on using a flash in a mobile
> >> device, for example in a mobile phone. The use cases could be somewhat
> >> different in devices the primary use of which is camera.
> >>
> >> Unsynchronised LED flash (software strobe)
> >> ------------------------------------------
> >>
> >> 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.
> >>
> >> Example of such device: Nokia N900.
> >>
> >>
> >> Synchronised LED flash (hardware strobe)
> >> ----------------------------------------
> >>
> >> 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.
> >>
> >> The sensor controls the flash duration and timing. This control
> >> typically must be programmed to the sensor, and specifying an interface
> >> for this is out of scope of this RFC.
> >>
> >> The LED flash controllers we know of can function in both synchronised
> >> and unsynchronised modes.
> >>
> >>
> >> LED flash as torch
> >> ------------------
> >>
> >> LED flash may be used as torch in conjunction with another use case
> >> involving camera or individually. [4]
> >>
> >>
> >> Synchronised xenon flash
> >> ------------------------
> >>
> >> The synchronised xenon flash is controlled more closely by the sensor
> >> than the LED flash. There is no separate intensity control for the xenon
> >> flash as its intensity is determined by the length of the strobe pulse.
> >> Several consecutive strobe pluses are possible but this needs to be
> >> still controlled by the sensor.
> >>
> >>
> >> Proposed interface
> >> ==================
> >>
> >> The flash, either LED or xenon, does not require large amounts of data
> >> to control it. There are parameters to control it but they are
> >> independent and assumably some hardware would only support some subsets
> >> of the functionality available somewhere else. Thus V4L2 controls seem
> >> an ideal way to support flash controllers.
> >>
> >> A separate control class is reserved for the flash controls. It is
> >> called V4L2_CTRL_CLASS_FLASH.
> >>
> >> Type of the control; type of flash is in parentheses after the control.
> >>
> >>
> >> 	V4L2_CID_FLASH_STROBE (button; LED)
> >>
> >> Strobe the flash using software strobe from the host, typically over I2C
> >> or a GPIO. The flash is NOT synchronised to sensor pixel are exposure
> >> since the command is given asynchronously. Alternatively, if the flash
> >> controller is a master in the system, the sensor exposure may be
> >> triggered based on software strobe.
> 
> It occurred to me that an application might want to turn off a flash
> which has been strobed on software. That can't be done on a single
> button control.
> 
> V4L2_CID_FLASH_SHUTDOWN?
> 
> The application would know the flash strobe is ongoing before it
> receives a timeout fault. I somehow feel that there should be a control
> telling that directly.
> 
> What about using a bool control for the strobe?

It depends: is the strobe signal just a pulse that kicks off the flash, or is 
it active throughout the flash duration? In the latter case a bool makes 
sense, in the first case an extra button control makes sense.

> 
> >> 	V4L2_CID_FLASH_STROBE_MODE (menu; LED)
> >>
> >> Use hardware or software strobe. If hardware strobe is selected, the
> >> flash controller is a slave in the system where the sensor produces the
> >> strobe signal to the flash.
> >>
> >> In this case the flash controller setup is limited to programming strobe
> >> timeout and power (LED flash) and the sensor controls the timing and
> >> length of the strobe.
> >>
> >> enum v4l2_flash_strobe_mode {
> >> 	V4L2_FLASH_STROBE_MODE_SOFTWARE,
> >> 	V4L2_FLASH_STROBE_MODE_EXT_STROBE,
> >> };
> > 
> > I'm not sure about the naming. Perhaps call the first MODE_SW_STROBE?
> > Or MODE_SW_TRIGGER and MODE_HW_TRIGGER? Or perhaps just MODE_SOFTWARE and
> > MODE_EXTERNAL or MODE_HARDWARE.
> 
> MODE_SOFTWARE and MODE_EXTERNAL (or MODE_HARDWARE) are the best, I
> think. Indeed there's no need to repeat strobe in the name of a strobe mode.
> 
> "External" is good since it directly indicates the strobe is external to
> the flash controller.
> 
> >>
> >>
> >> 	V4L2_CID_FLASH_TIMEOUT (integer; LED)
> >>
> >> The flash controller provides timeout functionality to shut down the led
> >> in case the host fails to do that. For hardware strobe, this is the
> >> maximum amount of time the flash should stay on, and the purpose of the
> >> setting is to prevent the LED from catching fire.
> >>
> >> For software strobe, the setting may be used to limit the length of the
> >> strobe in case a driver does not implement it itself. The granularity of
> >> the timeout in [1, 2, 3] is very coarse. However, the length of a
> >> driver-implemented LED strobe shutoff is very dependent on host.
> >> Possibly V4L2_CID_FLASH_DURATION should be added, and
> >> V4L2_CID_FLASH_TIMEOUT would be read-only so that the user would be able
> >> to obtain the actual hardware implemented safety timeout.
> >>
> >> Likely a standard unit such as ms or µs should be used.
> > 
> > It seems to me that this control should always be read-only. A setting 
like
> > this is very much hardware specific and you don't want an attacker 
changing
> > the timeout to the max value that might cause a LED catching fire.
> 
> I'm not sure about that.
> 
> The driver already must take care of protecting the hardware in my
> opinion. Besides, at least one control is required to select the
> duration for the flash if there's no hardware synchronisation.
> 
> What about this:
> 
> 	V4L2_CID_FLASH_TIMEOUT
> 
> Hardware timeout, read-only. Programmed to the maximum value allowed by
> the hardware for the external strobe, greater or equal to
> V4L2_CID_FLASH_DURATION for software strobe.
> 
> 	V4L2_CID_FLASH_DURATION
> 
> Software implemented timeout when V4L2_CID_FLASH_STROBE_MODE ==
> V4L2_FLASH_STROBE_MODE_SOFTWARE.
> 
> I have to say I'm not entirely sure the duration control is required.
> The timeout could be writable for software strobe in the case drivers do
> not implement software timeout. The granularity isn't _that_ much
> anyway. Also, a timeout fault should be produced whenever the duration
> would expire.
> 
> Perhaps it would be best to just leave that out for now.

Do you need something like this for the N900? If not, then leaving it out 
until we have a bit more experience is a good option.

Regards,

	Hans

> 
> >>
> >>
> >> 	V4L2_CID_FLASH_LED_MODE (menu; LED)
> >>
> >> enum v4l2_flash_led_mode {
> >> 	V4L2_FLASH_LED_MODE_FLASH = 1,
> >> 	V4L2_FLASH_LED_MODE_TORCH,
> >> };
> > 
> > Would a LED_MODE_NONE make sense as well to turn off the flash completely?
> 
> It would essentially be the same as choosing software strobe and
> disabling strobe. A separate mode for this still could be good to make
> it explicit.
> 
> >>
> >>
> >> 	V4L2_CID_FLASH_INTENSITY (integer; LED)
> >>
> >> Intensity of the flash in hardware specific units. The LED flash
> >> controller provides current to the LED but the actual luminous power is
> >> dictated by the LED connected to the controller.
> >>
> >>
> >> 	V4L2_CID_FLASH_TORCH_INTENSITY (integer; LED)
> >>
> >> Intensity of the flash in hardware specific units.
> >>
> >>
> >> 	V4L2_CID_FLASH_INDICATOR_INTENSITY (integer; LED)
> >>
> >> Intensity of the indicator light in hardware specific units.
> >>
> >>
> >> 	V4L2_CID_FLASH_FAULT (bit field; LED)
> >>
> >> This is a bitmask containing the fault information for the flash. This
> >> assumes the proposed V4L2 bit mask controls [5]; otherwise this would
> >> likely need to be a set of controls.
> > 
> > I intend to work on bitmask controls and control events tomorrow.
> 
> Nice! I look forward to see them! :-)
> 
> >>
> >> #define V4L2_FLASH_FAULT_OVER_VOLTAGE		0x00000001
> >> #define V4L2_FLASH_FAULT_TIMEOUT		0x00000002
> >> #define V4L2_FLASH_FAULT_OVER_TEMPERATURE	0x00000004
> >> #define V4L2_FLASH_FAULT_SHORT_CIRCUIT		0x00000008
> >>
> >> Several faults may occur at single occasion. The ADP1653 is able to
> >> inform the user a fault has occurred, so a V4L2 control event (proposed
> >> earlier) could be used for that.
> 
> Btw. as this is an I2C device, there's an external interrupt pin which
> tells this. Very likely the board code needs to tell this to the driver,
> or the driver could depend on the GPIO framework while the configuration
> would be in the board code.
> 
> >> These faults are supported by the ADP1653. More faults may be added as
> >> support for more chips require that. In some other hardware faults are
> >> available for indicator led as well.
> >>
> >> Question: should indicator faults be part of the same control, or a
> >> different control, e.g. V4L2_CID_FLASH_INDICATOR_FAULT?
> > 
> > If they are independently reported, then I would say so, yes.
> 
> I believe it could be the same register, but this could be hardware
> dependent.
> 
> Still, the faults essentially can be divided to separate LEDs. Perhaps
> it'd be good to rethink this when someone writes a driver for such a
> device. :-)
> 
> >>
> >>
> >> 	V4L2_CID_FLASH_CHARGE (bool; xenon)
> >>
> >> Charge control for the xenon flash. Enable or disable charging.
> >>
> >>
> >> 	V4L2_CID_FLASH_READY (bool; xenon, LED)
> >>
> >> Flash is ready to strobe. On xenon flash this tells the capacitor has
> >> been charged, on LED flash it's that the LED is no longer too hot.
> >>
> >> The implementation on LED flash may be modelling the temperature
> >> behaviour of the LED in the driver (or elsewhere, e.g. library or board
> >> code) if the hardware does not provide direct temperature information
> >> from the LED.
> >>
> >> A V4L2 control event should be produced whenever the flash becomes ready.
> > 
> > Looks good!
> 
> Thanks! :-)
> 
> > 
> > Regards,
> > 
> > 	Hans
> > 
> >>
> >>
> >> References
> >> ==========
> >>
> >> [1] http://www.analog.com/static/imported-files/data_sheets/ADP1653.pdf
> >>
> >> [2] http://www.national.com/mpf/LM/LM3555.html#Overview
> >>
> >> [3]
> >> http://www.austriamicrosystems.com/eng/Products/Lighting-
Management/Camera-Flash-LED-Drivers/AS3645
> >>
> >> [4] http://maemo.org/downloads/product/Maemo5/flashlight-applet/
> >>
> >> [5]
> >> http://www.retiisi.org.uk/v4l2/v4l2-brainstorming-
warsaw-2011-03/notes/day%202%20(SGz6LU2esk).html
> >>
> >> [6]
> >> http://www.retiisi.org.uk/v4l2/v4l2-brainstorming-
warsaw-2011-03/notes/day%203%20(RhoYa0X9D7).html
> >>
> >>
> >> Cheers,
> >>
> >>
> > 
> 
> 
> -- 
> Sakari Ailus
> sakari.ailus@maxwell.research.nokia.com
> --
> To unsubscribe from this list: send the line "unsubscribe linux-media" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> 

Re: [RFC] V4L2 API for flash devices

[Kim, HeungJun]

Hi Sakari,

Here's my humble opinions about this RFC.
Almost, this control may be also applied immediately in our case.
But, I have some opinions about that.
So, read comments plz and I wish this might be help to it.

2011-03-28 오후 9:55, Sakari Ailus 쓴 글:
> Hi,
> 
> This is a proposal for an interface for controlling flash devices on the
> V4L2/v4l2_subdev APIs. My plan is to use the interface in the ADP1653
> driver, the flash controller used in the Nokia N900.
> 
> Comments and questions are very, very welcome!
> 
> 
> Scope
> =====
> 
> This RFC is focused mostly on the ADP1653 [1] and similar chips [2, 3]
> which provides following functionality. [2, 3] mostly differ on the
> available faults --- for example, there are faults also for the
> indicator LED.
> 
> - High power LED output (flash or torch modes)
> - Low power indicator LED output (a.k.a. privacy light)
> - Programmable flash timeout
> - Software and hardware strobe
> - Fault detection
> 	- Overvoltage
> 	- Overtemperature
> 	- Short circuit
> 	- Timeout
> - Programmable current (both high-power and indicator LEDs)
> 
> If anyone else is aware of hardware which significantly differs from
> these and does not get served well under the proposed interface, please
> tell about it.
> 
> This RFC does NOT address the synchronisation of the flash to a given
> frame since this task is typically performed by the sensor through a
> strobe signal. The host does not have enough information for this ---
> exact timing information on the exposure of the sensor pixel array. In
> this case the flash synchronisation is visible to the flash controller
> as the hardware strobe originating from the sensor.
> 
> Flash synchronisation requires
> 
> 1) flash control capability from the sensor including a strobe output,
> 2) strobe input in the flash controller,
> 3) (optionally) ability to program sensor parameters at given frame,
> such as flash strobe, and
> 4) ability to read back metadata produced by the sensor related to a
> given frame. This should include whether the frame is exposed with
> flash, i.e. the sensor's flash strobe output.
> 
> Since we have little examples of both in terms of hardware support,
> which is in practice required, it was decided to postpone the interface
> specification for now. [6]
> 
> Xenon flash controllers exist but I don't have a specific example of
> those. Typically the interface is quite simple. Gpio pins for charge and
> strobe. The length of the strobe signal determines the strength of the
> flash pulse. The strobe is controlled by the sensor as for LED flash if
> it is hardware based.
> 
> 
> Known use cases
> ===============
> 
> The use case listed below concentrate on using a flash in a mobile
> device, for example in a mobile phone. The use cases could be somewhat
> different in devices the primary use of which is camera.
> 
> Unsynchronised LED flash (software strobe)
> ------------------------------------------
> 
> 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.
> 
> Example of such device: Nokia N900.
> 
> 
> Synchronised LED flash (hardware strobe)
> ----------------------------------------
> 
> 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.
> 
> The sensor controls the flash duration and timing. This control
> typically must be programmed to the sensor, and specifying an interface
> for this is out of scope of this RFC.
> 
> The LED flash controllers we know of can function in both synchronised
> and unsynchronised modes.
This case used in Galaxy S and the other these days smartphone in Samsung.
So, I checked possible APIs for our case, but it's not almost very different
with software strobe. It's safe to say, software strobe may be enough detailed
to express hardware strobe. So, software strobe APIs can cover the others.

This is just samsung case, but any case is possible.
Is there any other cases to be introduced, everybody?

> 
> 
> LED flash as torch
> ------------------
> 
> LED flash may be used as torch in conjunction with another use case
> involving camera or individually. [4]
> 
> 
> Synchronised xenon flash
> ------------------------
> 
> The synchronised xenon flash is controlled more closely by the sensor
> than the LED flash. There is no separate intensity control for the xenon
> flash as its intensity is determined by the length of the strobe pulse.
> Several consecutive strobe pluses are possible but this needs to be
> still controlled by the sensor.
> 
> 
> Proposed interface
> ==================
> 
> The flash, either LED or xenon, does not require large amounts of data
> to control it. There are parameters to control it but they are
> independent and assumably some hardware would only support some subsets
> of the functionality available somewhere else. Thus V4L2 controls seem
> an ideal way to support flash controllers.
> 
> A separate control class is reserved for the flash controls. It is
> called V4L2_CTRL_CLASS_FLASH.
> 
> Type of the control; type of flash is in parentheses after the control.
> 
> 
> 	V4L2_CID_FLASH_STROBE (button; LED)
> 
> Strobe the flash using software strobe from the host, typically over I2C
> or a GPIO. The flash is NOT synchronised to sensor pixel are exposure
> since the command is given asynchronously. Alternatively, if the flash
> controller is a master in the system, the sensor exposure may be
> triggered based on software strobe.
> 
> 
> 	V4L2_CID_FLASH_STROBE_MODE (menu; LED)
> 
> Use hardware or software strobe. If hardware strobe is selected, the
> flash controller is a slave in the system where the sensor produces the
> strobe signal to the flash.
> 
> In this case the flash controller setup is limited to programming strobe
> timeout and power (LED flash) and the sensor controls the timing and
> length of the strobe.
> 
> enum v4l2_flash_strobe_mode {
> 	V4L2_FLASH_STROBE_MODE_SOFTWARE,
> 	V4L2_FLASH_STROBE_MODE_EXT_STROBE,
> };
> 
> 
> 	V4L2_CID_FLASH_TIMEOUT (integer; LED)
> 
> The flash controller provides timeout functionality to shut down the led
> in case the host fails to do that. For hardware strobe, this is the
> maximum amount of time the flash should stay on, and the purpose of the
> setting is to prevent the LED from catching fire.
> 
> For software strobe, the setting may be used to limit the length of the
> strobe in case a driver does not implement it itself. The granularity of
> the timeout in [1, 2, 3] is very coarse. However, the length of a
> driver-implemented LED strobe shutoff is very dependent on host.
> Possibly V4L2_CID_FLASH_DURATION should be added, and
> V4L2_CID_FLASH_TIMEOUT would be read-only so that the user would be able
> to obtain the actual hardware implemented safety timeout.
> 
> Likely a standard unit such as ms or µs should be used.
> 
> 
> 	V4L2_CID_FLASH_LED_MODE (menu; LED)
> 
> enum v4l2_flash_led_mode {
> 	V4L2_FLASH_LED_MODE_FLASH = 1,
> 	V4L2_FLASH_LED_MODE_TORCH,
> };
How about the name V4L2_FLAS_LED_MODE_DEDICATED than TORCH?

In the most case of the TORCH mode, the only led goes with powering up,
not the whole sensor. It's the same case that the flash-led integrated
in sensor module, and it will be turn on the only power pin of led.

I think it's not different method to turn on/off, whatever the mode name is.
But, the mode name DEDICATED is look more reasonable, because the reason 
which is devided FLASH and TORCH in the mode, is why only power up the led,
not sensor.

So, how about that?

Regards,
Heungjun Kim

> 
> 
> 	V4L2_CID_FLASH_INTENSITY (integer; LED)
> 
> Intensity of the flash in hardware specific units. The LED flash
> controller provides current to the LED but the actual luminous power is
> dictated by the LED connected to the controller.
> 
> 
> 	V4L2_CID_FLASH_TORCH_INTENSITY (integer; LED)
> 
> Intensity of the flash in hardware specific units.
> 
> 
> 	V4L2_CID_FLASH_INDICATOR_INTENSITY (integer; LED)
> 
> Intensity of the indicator light in hardware specific units.
> 
> 
> 	V4L2_CID_FLASH_FAULT (bit field; LED)
> 
> This is a bitmask containing the fault information for the flash. This
> assumes the proposed V4L2 bit mask controls [5]; otherwise this would
> likely need to be a set of controls.
> 
> #define V4L2_FLASH_FAULT_OVER_VOLTAGE		0x00000001
> #define V4L2_FLASH_FAULT_TIMEOUT		0x00000002
> #define V4L2_FLASH_FAULT_OVER_TEMPERATURE	0x00000004
> #define V4L2_FLASH_FAULT_SHORT_CIRCUIT		0x00000008
> 
> Several faults may occur at single occasion. The ADP1653 is able to
> inform the user a fault has occurred, so a V4L2 control event (proposed
> earlier) could be used for that.
> 
> These faults are supported by the ADP1653. More faults may be added as
> support for more chips require that. In some other hardware faults are
> available for indicator led as well.
> 
> Question: should indicator faults be part of the same control, or a
> different control, e.g. V4L2_CID_FLASH_INDICATOR_FAULT?
> 
> 
> 	V4L2_CID_FLASH_CHARGE (bool; xenon)
> 
> Charge control for the xenon flash. Enable or disable charging.
> 
> 
> 	V4L2_CID_FLASH_READY (bool; xenon, LED)
> 
> Flash is ready to strobe. On xenon flash this tells the capacitor has
> been charged, on LED flash it's that the LED is no longer too hot.
> 
> The implementation on LED flash may be modelling the temperature
> behaviour of the LED in the driver (or elsewhere, e.g. library or board
> code) if the hardware does not provide direct temperature information
> from the LED.
> 
> A V4L2 control event should be produced whenever the flash becomes ready.
> 
> 
> References
> ==========
> 
> [1] http://www.analog.com/static/imported-files/data_sheets/ADP1653.pdf
> 
> [2] http://www.national.com/mpf/LM/LM3555.html#Overview
> 
> [3]
> http://www.austriamicrosystems.com/eng/Products/Lighting-Management/Camera-Flash-LED-Drivers/AS3645
> 
> [4] http://maemo.org/downloads/product/Maemo5/flashlight-applet/
> 
> [5]
> http://www.retiisi.org.uk/v4l2/v4l2-brainstorming-warsaw-2011-03/notes/day%202%20(SGz6LU2esk).html
> 
> [6]
> http://www.retiisi.org.uk/v4l2/v4l2-brainstorming-warsaw-2011-03/notes/day%203%20(RhoYa0X9D7).html
> 
> 
> Cheers,
> 

Re: [RFC] V4L2 API for flash devices

[Sakari Ailus]

Hans Verkuil wrote:
> On Tuesday, March 29, 2011 11:35:19 Sakari Ailus wrote:
>> Hi Hans,
>>
>> Many thanks for the comments!
>>

...

>> It occurred to me that an application might want to turn off a flash
>> which has been strobed on software. That can't be done on a single
>> button control.
>>
>> V4L2_CID_FLASH_SHUTDOWN?
>>
>> The application would know the flash strobe is ongoing before it
>> receives a timeout fault. I somehow feel that there should be a control
>> telling that directly.
>>
>> What about using a bool control for the strobe?
> 
> It depends: is the strobe signal just a pulse that kicks off the flash, or is 
> it active throughout the flash duration? In the latter case a bool makes 
> sense, in the first case an extra button control makes sense.

I like buttons since I associate them with action (like strobing) but on
the other hand buttons don't allow querying the current state. On the
other hand, the current state isn't always determinable, e.g. in the
absence of the interrupt line from the flash controller interrupt pin
(e.g. N900!).

I don't think having a separate bool control for the state of the flash
is very neat either.

Well, a boolean control could be seen as a two-state button also. :-)

In a summary: sometimes the state can be determined, while sometimes it
can't. So I think we'd need both and some drivers could implement a
subset of them.

A single control could be used for both, but then the flash state would
be always off if the hardware doesn't support reading back the state. To
make this explicit for user space, likely three controls would be required:

V4L2_CID_FLASH_STROBE (button)
V4L2_CID_FLASH_SHUTDOWN (button)
V4L2_CID_FLASH_LIT (boolean)

...

>> I'm not sure about that.
>>
>> The driver already must take care of protecting the hardware in my
>> opinion. Besides, at least one control is required to select the
>> duration for the flash if there's no hardware synchronisation.
>>
>> What about this:
>>
>> 	V4L2_CID_FLASH_TIMEOUT
>>
>> Hardware timeout, read-only. Programmed to the maximum value allowed by
>> the hardware for the external strobe, greater or equal to
>> V4L2_CID_FLASH_DURATION for software strobe.
>>
>> 	V4L2_CID_FLASH_DURATION
>>
>> Software implemented timeout when V4L2_CID_FLASH_STROBE_MODE ==
>> V4L2_FLASH_STROBE_MODE_SOFTWARE.
>>
>> I have to say I'm not entirely sure the duration control is required.
>> The timeout could be writable for software strobe in the case drivers do
>> not implement software timeout. The granularity isn't _that_ much
>> anyway. Also, a timeout fault should be produced whenever the duration
>> would expire.
>>
>> Perhaps it would be best to just leave that out for now.
> 
> Do you need something like this for the N900? If not, then leaving it out 
> until we have a bit more experience is a good option.

We don't.

I think making V4L2_CID_FLASH_TIMEOUT writable would be useful since the
only other way to shut off the flash would be the shutdown control in
software strobe. On the other hand, this should bring no advantages to
flash synchronisation, but allows the application to get a strobe of
chosen length.

Also, the ADP1653 supports a mode of hardware strobe operation where the
strobe triggers the flash which stays on until the timeout independent
of the strobe signal.

There likely should be an additional control for this in the end,
although I don't know of any use for such mode.

Cheers,

-- 
Sakari Ailus
sakari.ailus@maxwell.research.nokia.com

Re: [RFC] V4L2 API for flash devices

[Sakari Ailus]

Sakari Ailus wrote:
> Hans Verkuil wrote:
>> On Tuesday, March 29, 2011 11:35:19 Sakari Ailus wrote:
>>> Hi Hans,
>>>
>>> Many thanks for the comments!
>>>
> 
> ...
> 
>>> It occurred to me that an application might want to turn off a flash
>>> which has been strobed on software. That can't be done on a single
>>> button control.
>>>
>>> V4L2_CID_FLASH_SHUTDOWN?
>>>
>>> The application would know the flash strobe is ongoing before it
>>> receives a timeout fault. I somehow feel that there should be a control
>>> telling that directly.
>>>
>>> What about using a bool control for the strobe?
>>
>> It depends: is the strobe signal just a pulse that kicks off the flash, or is 
>> it active throughout the flash duration? In the latter case a bool makes 
>> sense, in the first case an extra button control makes sense.
> 
> I like buttons since I associate them with action (like strobing) but on
> the other hand buttons don't allow querying the current state. On the
> other hand, the current state isn't always determinable, e.g. in the
> absence of the interrupt line from the flash controller interrupt pin
> (e.g. N900!).

Oh, I need to take my words back a bit.

There indeed is a way to get the on/off status for the flash, but that
involves I2C register access --- when you read the fault registers, you
do get the state, even if the interrupt linke is missing from the
device. At least I can't see why this wouldn't work, at least on this
particular chip.

What you can't have in this case is the event.

So, in my opinion this suggests that a single boolean control is the way
to go.

Regards,

-- 
Sakari Ailus
sakari.ailus@maxwell.research.nokia.com

Re: [RFC] V4L2 API for flash devices

[Sakari Ailus]

Kim, HeungJun wrote:
> Hi Sakari,

Hi HeungJun,

Thanks for the comments!

> Here's my humble opinions about this RFC.
> Almost, this control may be also applied immediately in our case.
> But, I have some opinions about that.
> So, read comments plz and I wish this might be help to it.
> 
> 2011-03-28 오후 9:55, Sakari Ailus 쓴 글:
>> Hi,
>>
>> This is a proposal for an interface for controlling flash devices on the
>> V4L2/v4l2_subdev APIs. My plan is to use the interface in the ADP1653
>> driver, the flash controller used in the Nokia N900.
>>
>> Comments and questions are very, very welcome!
>>
>>
>> Scope
>> =====
>>
>> This RFC is focused mostly on the ADP1653 [1] and similar chips [2, 3]
>> which provides following functionality. [2, 3] mostly differ on the
>> available faults --- for example, there are faults also for the
>> indicator LED.
>>
>> - High power LED output (flash or torch modes)
>> - Low power indicator LED output (a.k.a. privacy light)
>> - Programmable flash timeout
>> - Software and hardware strobe
>> - Fault detection
>> 	- Overvoltage
>> 	- Overtemperature
>> 	- Short circuit
>> 	- Timeout
>> - Programmable current (both high-power and indicator LEDs)
>>
>> If anyone else is aware of hardware which significantly differs from
>> these and does not get served well under the proposed interface, please
>> tell about it.
>>
>> This RFC does NOT address the synchronisation of the flash to a given
>> frame since this task is typically performed by the sensor through a
>> strobe signal. The host does not have enough information for this ---
>> exact timing information on the exposure of the sensor pixel array. In
>> this case the flash synchronisation is visible to the flash controller
>> as the hardware strobe originating from the sensor.
>>
>> Flash synchronisation requires
>>
>> 1) flash control capability from the sensor including a strobe output,
>> 2) strobe input in the flash controller,
>> 3) (optionally) ability to program sensor parameters at given frame,
>> such as flash strobe, and
>> 4) ability to read back metadata produced by the sensor related to a
>> given frame. This should include whether the frame is exposed with
>> flash, i.e. the sensor's flash strobe output.
>>
>> Since we have little examples of both in terms of hardware support,
>> which is in practice required, it was decided to postpone the interface
>> specification for now. [6]
>>
>> Xenon flash controllers exist but I don't have a specific example of
>> those. Typically the interface is quite simple. Gpio pins for charge and
>> strobe. The length of the strobe signal determines the strength of the
>> flash pulse. The strobe is controlled by the sensor as for LED flash if
>> it is hardware based.
>>
>>
>> Known use cases
>> ===============
>>
>> The use case listed below concentrate on using a flash in a mobile
>> device, for example in a mobile phone. The use cases could be somewhat
>> different in devices the primary use of which is camera.
>>
>> Unsynchronised LED flash (software strobe)
>> ------------------------------------------
>>
>> 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.
>>
>> Example of such device: Nokia N900.
>>
>>
>> Synchronised LED flash (hardware strobe)
>> ----------------------------------------
>>
>> 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.
>>
>> The sensor controls the flash duration and timing. This control
>> typically must be programmed to the sensor, and specifying an interface
>> for this is out of scope of this RFC.
>>
>> The LED flash controllers we know of can function in both synchronised
>> and unsynchronised modes.
> This case used in Galaxy S and the other these days smartphone in Samsung.
> So, I checked possible APIs for our case, but it's not almost very different
> with software strobe. It's safe to say, software strobe may be enough detailed
> to express hardware strobe. So, software strobe APIs can cover the others.

In case the user wants to use hardware strobe which is also supported by
the driver, the controls related to software strobe are not used at all.
The driver might choose not to implement them if they are not supported.

> This is just samsung case, but any case is possible.
> Is there any other cases to be introduced, everybody?
> 
>>
>>
>> LED flash as torch
>> ------------------
>>
>> LED flash may be used as torch in conjunction with another use case
>> involving camera or individually. [4]
>>
>>
>> Synchronised xenon flash
>> ------------------------
>>
>> The synchronised xenon flash is controlled more closely by the sensor
>> than the LED flash. There is no separate intensity control for the xenon
>> flash as its intensity is determined by the length of the strobe pulse.
>> Several consecutive strobe pluses are possible but this needs to be
>> still controlled by the sensor.
>>
>>
>> Proposed interface
>> ==================
>>
>> The flash, either LED or xenon, does not require large amounts of data
>> to control it. There are parameters to control it but they are
>> independent and assumably some hardware would only support some subsets
>> of the functionality available somewhere else. Thus V4L2 controls seem
>> an ideal way to support flash controllers.
>>
>> A separate control class is reserved for the flash controls. It is
>> called V4L2_CTRL_CLASS_FLASH.
>>
>> Type of the control; type of flash is in parentheses after the control.
>>
>>
>> 	V4L2_CID_FLASH_STROBE (button; LED)
>>
>> Strobe the flash using software strobe from the host, typically over I2C
>> or a GPIO. The flash is NOT synchronised to sensor pixel are exposure
>> since the command is given asynchronously. Alternatively, if the flash
>> controller is a master in the system, the sensor exposure may be
>> triggered based on software strobe.
>>
>>
>> 	V4L2_CID_FLASH_STROBE_MODE (menu; LED)
>>
>> Use hardware or software strobe. If hardware strobe is selected, the
>> flash controller is a slave in the system where the sensor produces the
>> strobe signal to the flash.
>>
>> In this case the flash controller setup is limited to programming strobe
>> timeout and power (LED flash) and the sensor controls the timing and
>> length of the strobe.
>>
>> enum v4l2_flash_strobe_mode {
>> 	V4L2_FLASH_STROBE_MODE_SOFTWARE,
>> 	V4L2_FLASH_STROBE_MODE_EXT_STROBE,
>> };
>>
>>
>> 	V4L2_CID_FLASH_TIMEOUT (integer; LED)
>>
>> The flash controller provides timeout functionality to shut down the led
>> in case the host fails to do that. For hardware strobe, this is the
>> maximum amount of time the flash should stay on, and the purpose of the
>> setting is to prevent the LED from catching fire.
>>
>> For software strobe, the setting may be used to limit the length of the
>> strobe in case a driver does not implement it itself. The granularity of
>> the timeout in [1, 2, 3] is very coarse. However, the length of a
>> driver-implemented LED strobe shutoff is very dependent on host.
>> Possibly V4L2_CID_FLASH_DURATION should be added, and
>> V4L2_CID_FLASH_TIMEOUT would be read-only so that the user would be able
>> to obtain the actual hardware implemented safety timeout.
>>
>> Likely a standard unit such as ms or µs should be used.
>>
>>
>> 	V4L2_CID_FLASH_LED_MODE (menu; LED)
>>
>> enum v4l2_flash_led_mode {
>> 	V4L2_FLASH_LED_MODE_FLASH = 1,
>> 	V4L2_FLASH_LED_MODE_TORCH,
>> };
> How about the name V4L2_FLAS_LED_MODE_DEDICATED than TORCH?
> 
> In the most case of the TORCH mode, the only led goes with powering up,
> not the whole sensor. It's the same case that the flash-led integrated
> in sensor module, and it will be turn on the only power pin of led.
>
> I think it's not different method to turn on/off, whatever the mode name is.
> But, the mode name DEDICATED is look more reasonable, because the reason 
> which is devided FLASH and TORCH in the mode, is why only power up the led,
> not sensor.

Sensor? Is the flash part of the sensor module for you?

I think it should be other factors than the flash mode that are used to
make the decision on whether to power on the sensor or not.

The factors based on which to power the subdevs probably will be
discussed in the future, and which entity is responsible for power
management. The power management code originally was part of the Media
controller framework but it was removed since it was not seen to be
generic enough.

Many subdev drivers (including the adp1653) basically get powered as
long as the subdev device node is open. Sensor can be powered based on
other factors as well, such as the streaming state and what are the
connections to the video nodes.

Flash in torch mode can also be used as video light.

Does this answer the questions you had?

Regards,

-- 
Sakari Ailus
sakari.ailus@maxwell.research.nokia.com

Re: [RFC] V4L2 API for flash devices

[Kim, HeungJun]

Hi Sakari,

2011-03-29 오후 11:41, Sakari Ailus 쓴 글:
> Kim, HeungJun wrote:
[snip]
>> I think it's not different method to turn on/off, whatever the mode name is.
>> But, the mode name DEDICATED is look more reasonable, because the reason 
>> which is devided FLASH and TORCH in the mode, is why only power up the led,
>> not sensor.
> 
> Sensor? Is the flash part of the sensor module for you?
Yes. The flash is a part of the sensor module(our case like M-5MOLS).
Precisely, the sensor internal core's gpio pin is connected with
external Flash LED, and the control master is the sensor internal core.
For turnning on the Flash LED, we should use I2C register access.
So, I think it's exactly matches with hardware strobe as you metioned.

> 
> I think it should be other factors than the flash mode that are used to
> make the decision on whether to power on the sensor or not.
> 
> The factors based on which to power the subdevs probably will be
> discussed in the future, and which entity is responsible for power
> management. The power management code originally was part of the Media
> controller framework but it was removed since it was not seen to be
> generic enough.
> 
> Many subdev drivers (including the adp1653) basically get powered as
> long as the subdev device node is open. Sensor can be powered based on
> other factors as well, such as the streaming state and what are the
> connections to the video nodes.
That's the start point I said. When the user use only the flash, it should be
accompanied(of course, I have same circumstance) by opening the videonode
and doing the media control operation, but we have no option to do because
it's depending on the hardware connection architecture.

So, I suggesst that, if we can not give to users(of course, this user
want to use only flash function, not the camera) proper method usage
(openning the videonode for using flash), let's express that the camera
flash is used in the DEDICATED MODE now, as the enumeration name DEDICATED.

But, I think it might be not a big issue. So, any others don't comment at this,
it's ok for me to pass this naming issue.

I can see this API is very cool for camera man just like me.

Cheers!

plus: actually I have the one of N-series, N810. So, the omap3isp is available to
activate this device, not even it's cpu is omap3? Just question.

Regards,
Heungjun Kim

Re: [RFC] V4L2 API for flash devices

[Laurent Pinchart]

Hi Sakari,

On Tuesday 29 March 2011 13:51:38 Sakari Ailus wrote:
> Sakari Ailus wrote:
> > Hans Verkuil wrote:
> >> On Tuesday, March 29, 2011 11:35:19 Sakari Ailus wrote:
> >>> Hi Hans,
> >>> 
> >>> Many thanks for the comments!
> > 
> > ...
> > 
> >>> It occurred to me that an application might want to turn off a flash
> >>> which has been strobed on software. That can't be done on a single
> >>> button control.
> >>> 
> >>> V4L2_CID_FLASH_SHUTDOWN?
> >>> 
> >>> The application would know the flash strobe is ongoing before it
> >>> receives a timeout fault. I somehow feel that there should be a control
> >>> telling that directly.
> >>> 
> >>> What about using a bool control for the strobe?
> >> 
> >> It depends: is the strobe signal just a pulse that kicks off the flash,
> >> or is it active throughout the flash duration? In the latter case a
> >> bool makes sense, in the first case an extra button control makes
> >> sense.
> > 
> > I like buttons since I associate them with action (like strobing) but on
> > the other hand buttons don't allow querying the current state. On the
> > other hand, the current state isn't always determinable, e.g. in the
> > absence of the interrupt line from the flash controller interrupt pin
> > (e.g. N900!).
> 
> Oh, I need to take my words back a bit.
> 
> There indeed is a way to get the on/off status for the flash, but that
> involves I2C register access --- when you read the fault registers, you
> do get the state, even if the interrupt linke is missing from the
> device. At least I can't see why this wouldn't work, at least on this
> particular chip.
> 
> What you can't have in this case is the event.
> 
> So, in my opinion this suggests that a single boolean control is the way
> to go.

Why would an application want to turn off a flash that has been strobbed in 
software ? Applications should set the flash duration and then strobe it.

-- 
Regards,

Laurent Pinchart

Re: [RFC] V4L2 API for flash devices

[Laurent Pinchart]

Hi Sakari,

On Tuesday 29 March 2011 11:35:19 Sakari Ailus wrote:
> Hans Verkuil wrote:
> > On Monday, March 28, 2011 14:55:40 Sakari Ailus wrote:

[snip]

> >> 	V4L2_CID_FLASH_TIMEOUT (integer; LED)
> >> 
> >> The flash controller provides timeout functionality to shut down the led
> >> in case the host fails to do that. For hardware strobe, this is the
> >> maximum amount of time the flash should stay on, and the purpose of the
> >> setting is to prevent the LED from catching fire.
> >> 
> >> For software strobe, the setting may be used to limit the length of the
> >> strobe in case a driver does not implement it itself. The granularity of
> >> the timeout in [1, 2, 3] is very coarse. However, the length of a
> >> driver-implemented LED strobe shutoff is very dependent on host.
> >> Possibly V4L2_CID_FLASH_DURATION should be added, and
> >> V4L2_CID_FLASH_TIMEOUT would be read-only so that the user would be able
> >> to obtain the actual hardware implemented safety timeout.
> >> 
> >> Likely a standard unit such as ms or µs should be used.
> > 
> > It seems to me that this control should always be read-only. A setting
> > like this is very much hardware specific and you don't want an attacker
> > changing the timeout to the max value that might cause a LED catching
> > fire.
> 
> I'm not sure about that.
> 
> The driver already must take care of protecting the hardware in my
> opinion. Besides, at least one control is required to select the
> duration for the flash if there's no hardware synchronisation.
> 
> What about this:
> 
> 	V4L2_CID_FLASH_TIMEOUT
> 
> Hardware timeout, read-only. Programmed to the maximum value allowed by
> the hardware for the external strobe, greater or equal to
> V4L2_CID_FLASH_DURATION for software strobe.
> 
> 	V4L2_CID_FLASH_DURATION
> 
> Software implemented timeout when V4L2_CID_FLASH_STROBE_MODE ==
> V4L2_FLASH_STROBE_MODE_SOFTWARE.

Why would we need two controls here ? My understanding is that the maximum 
strobe duration length can be limited by

- the flash controller itself
- platform-specific constraints to avoid over-heating the flash

The platform-specific constraints come from board code, and the flash driver 
needs to ensure that the flash is never strobed for a duration longer than the 
limit. This requires implementing a software timer if the hardware has no 
timeout control, and programming the hardware with the correct timeout value 
otherwise. The limit can be queried with QUERYCTRL on the duration control.

> I have to say I'm not entirely sure the duration control is required.
> The timeout could be writable for software strobe in the case drivers do
> not implement software timeout. The granularity isn't _that_ much
> anyway. Also, a timeout fault should be produced whenever the duration
> would expire.
> 
> Perhaps it would be best to just leave that out for now.
> 
> >> 	V4L2_CID_FLASH_LED_MODE (menu; LED)
> >> 
> >> enum v4l2_flash_led_mode {
> >> 
> >> 	V4L2_FLASH_LED_MODE_FLASH = 1,
> >> 	V4L2_FLASH_LED_MODE_TORCH,

"torch" mode can also be used for video, should we rename TORCH to something 
more generic ? Maybe a "manual" mode ?

> >> 
> >> };
> > 
> > Would a LED_MODE_NONE make sense as well to turn off the flash
> > completely?
> 
> It would essentially be the same as choosing software strobe and disabling
> strobe. A separate mode for this still could be good to make it explicit.

-- 
Regards,

Laurent Pinchart

Re: [RFC] V4L2 API for flash devices

[Laurent Pinchart]

Hi Sakari,

On Monday 28 March 2011 14:55:40 Sakari Ailus wrote:

[snip]

> 	V4L2_CID_FLASH_STROBE_MODE (menu; LED)
> 
> Use hardware or software strobe. If hardware strobe is selected, the
> flash controller is a slave in the system where the sensor produces the
> strobe signal to the flash.
> 
> In this case the flash controller setup is limited to programming strobe
> timeout and power (LED flash) and the sensor controls the timing and
> length of the strobe.
> 
> enum v4l2_flash_strobe_mode {
> 	V4L2_FLASH_STROBE_MODE_SOFTWARE,
> 	V4L2_FLASH_STROBE_MODE_EXT_STROBE,
> };

[snip]

> 	V4L2_CID_FLASH_LED_MODE (menu; LED)
> 
> enum v4l2_flash_led_mode {
> 	V4L2_FLASH_LED_MODE_FLASH = 1,
> 	V4L2_FLASH_LED_MODE_TORCH,
> };

Thinking about this some more, shouldn't we combine the two controls ? They 
are basically used to configure how the flash LED is controlled: manually 
(torch mode), automatically by the flash controller (software strobe mode) or 
automatically by an external component (external strobe mode).

-- 
Regards,

Laurent Pinchart

Re: [RFC] V4L2 API for flash devices

[Sakari Ailus]

Laurent Pinchart wrote:
> Hi Sakari,

Hi Laurent,

Thanks for the comments!

> On Monday 28 March 2011 14:55:40 Sakari Ailus wrote:
> 
> [snip]
> 
>> 	V4L2_CID_FLASH_STROBE_MODE (menu; LED)
>>
>> Use hardware or software strobe. If hardware strobe is selected, the
>> flash controller is a slave in the system where the sensor produces the
>> strobe signal to the flash.
>>
>> In this case the flash controller setup is limited to programming strobe
>> timeout and power (LED flash) and the sensor controls the timing and
>> length of the strobe.
>>
>> enum v4l2_flash_strobe_mode {
>> 	V4L2_FLASH_STROBE_MODE_SOFTWARE,
>> 	V4L2_FLASH_STROBE_MODE_EXT_STROBE,
>> };
> 
> [snip]
> 
>> 	V4L2_CID_FLASH_LED_MODE (menu; LED)
>>
>> enum v4l2_flash_led_mode {
>> 	V4L2_FLASH_LED_MODE_FLASH = 1,
>> 	V4L2_FLASH_LED_MODE_TORCH,
>> };
> 
> Thinking about this some more, shouldn't we combine the two controls ? They 
> are basically used to configure how the flash LED is controlled: manually 
> (torch mode), automatically by the flash controller (software strobe mode) or 
> automatically by an external component (external strobe mode).

That's a good question.

The adp1653 supports also additional control (not implemented in the
driver, though) that affect hardware strobe length. Based on register
setting, the led will be on after strobe either until the timeout
expires, or until the strobe signal is high.

Should this be also part of the same control, or a different one?

Even without this, we'd have:

V4L2_FLASH_MODE_OFF
V4L2_FLASH_MODE_TORCH
V4L2_FLASH_MODE_SOFTWARE_STROBE
V4L2_FLASH_MODE_EXTERNAL_STROBE

Additionally, this might be

V4L2_FLASH_MODE_EXTERNAL_STROBE_EDGE

It's true that these are mutually exclusive.

I think this is about whether we want to specify the operation of the
flash explicitly here or allow extending the interface later on when new
hardware is available by adding new controls. There are upsides and
downsides in each approach.

There could be additional differentiating factors to the functionalty
later on, like the torch/video light differentiation that some hardware
does --- who knows based on what?

I perhaps wouldn't combine the controls. What do you think?

-- 
Sakari Ailus
sakari.ailus@maxwell.research.nokia.com

Re: [RFC] V4L2 API for flash devices

[Sakari Ailus]

Kim, HeungJun wrote:
> Hi Sakari,

Hi HeungJun,

> 2011-03-29 오후 11:41, Sakari Ailus 쓴 글:
>> Kim, HeungJun wrote:
> [snip]
>>> I think it's not different method to turn on/off, whatever the mode name is.
>>> But, the mode name DEDICATED is look more reasonable, because the reason 
>>> which is devided FLASH and TORCH in the mode, is why only power up the led,
>>> not sensor.
>>
>> Sensor? Is the flash part of the sensor module for you?
> Yes. The flash is a part of the sensor module(our case like M-5MOLS).
> Precisely, the sensor internal core's gpio pin is connected with
> external Flash LED, and the control master is the sensor internal core.
> For turnning on the Flash LED, we should use I2C register access.
> So, I think it's exactly matches with hardware strobe as you metioned.

Ok, I think I'm lost now. :-)

What signals are sent from sensor to flash in both torch and flash cases?

>> I think it should be other factors than the flash mode that are used to
>> make the decision on whether to power on the sensor or not.
>>
>> The factors based on which to power the subdevs probably will be
>> discussed in the future, and which entity is responsible for power
>> management. The power management code originally was part of the Media
>> controller framework but it was removed since it was not seen to be
>> generic enough.
>>
>> Many subdev drivers (including the adp1653) basically get powered as
>> long as the subdev device node is open. Sensor can be powered based on
>> other factors as well, such as the streaming state and what are the
>> connections to the video nodes.
> That's the start point I said. When the user use only the flash, it should be
> accompanied(of course, I have same circumstance) by opening the videonode
> and doing the media control operation, but we have no option to do because
> it's depending on the hardware connection architecture.

When the user only needs to use the flash, in this case the user must
open the subdev node which is exported by the flash controller driver.
Not the video node, which is handled in the bridge (ISP) driver.

> So, I suggesst that, if we can not give to users(of course, this user
> want to use only flash function, not the camera) proper method usage
> (openning the videonode for using flash), let's express that the camera
> flash is used in the DEDICATED MODE now, as the enumeration name DEDICATED.

No. The video nodes should not be involved since they are related to the
bridge (ISP) which is not needed to use the flash. Assuming that this is
the situation.

This is how the use case should go:

1. open subdev node, e.g. /dev/v4l-subdev0, which is the flash
(flash controller powered on)
2. VIDIOC_S_CTRL: V4L2_CID_FLASH_LED_MODE, V4L2_FLASH_LED_MODE_TORCH
(flash is on now)
2. VIDIOC_S_CTRL: V4L2_CID_FLASH_LED_MODE, V4L2_FLASH_LED_MODE_NONE
(flash is off now)
3. close the file handle
(flash controller powered off)

> But, I think it might be not a big issue. So, any others don't comment at this,
> it's ok for me to pass this naming issue.
> 
> I can see this API is very cool for camera man just like me.

Thanks!

> plus: actually I have the one of N-series, N810. So, the omap3isp is available to
> activate this device, not even it's cpu is omap3? Just question.

The N810 has OMAP 2420 which has a completely different camera bridge,
and there's no flash. The drivers for the camera in N810 are omap24xxcam
and tcm825x. The drivers are functional in mainline but the platform
data is missing, as well as the CBUS driver. This work is queued but
unknown when there's time for this.

Regards,

-- 
Sakari Ailus
sakari.ailus@maxwell.research.nokia.com

Re: [RFC] V4L2 API for flash devices

[Sakari Ailus]

Laurent Pinchart wrote:
> Hi Sakari,

Hi Laurent,

> On Tuesday 29 March 2011 11:35:19 Sakari Ailus wrote:
>> Hans Verkuil wrote:
>>> On Monday, March 28, 2011 14:55:40 Sakari Ailus wrote:
> 
> [snip]
> 
>>>> 	V4L2_CID_FLASH_TIMEOUT (integer; LED)
>>>>
>>>> The flash controller provides timeout functionality to shut down the led
>>>> in case the host fails to do that. For hardware strobe, this is the
>>>> maximum amount of time the flash should stay on, and the purpose of the
>>>> setting is to prevent the LED from catching fire.
>>>>
>>>> For software strobe, the setting may be used to limit the length of the
>>>> strobe in case a driver does not implement it itself. The granularity of
>>>> the timeout in [1, 2, 3] is very coarse. However, the length of a
>>>> driver-implemented LED strobe shutoff is very dependent on host.
>>>> Possibly V4L2_CID_FLASH_DURATION should be added, and
>>>> V4L2_CID_FLASH_TIMEOUT would be read-only so that the user would be able
>>>> to obtain the actual hardware implemented safety timeout.
>>>>
>>>> Likely a standard unit such as ms or µs should be used.
>>>
>>> It seems to me that this control should always be read-only. A setting
>>> like this is very much hardware specific and you don't want an attacker
>>> changing the timeout to the max value that might cause a LED catching
>>> fire.
>>
>> I'm not sure about that.
>>
>> The driver already must take care of protecting the hardware in my
>> opinion. Besides, at least one control is required to select the
>> duration for the flash if there's no hardware synchronisation.
>>
>> What about this:
>>
>> 	V4L2_CID_FLASH_TIMEOUT
>>
>> Hardware timeout, read-only. Programmed to the maximum value allowed by
>> the hardware for the external strobe, greater or equal to
>> V4L2_CID_FLASH_DURATION for software strobe.
>>
>> 	V4L2_CID_FLASH_DURATION
>>
>> Software implemented timeout when V4L2_CID_FLASH_STROBE_MODE ==
>> V4L2_FLASH_STROBE_MODE_SOFTWARE.
> 
> Why would we need two controls here ? My understanding is that the maximum 
> strobe duration length can be limited by
> 
> - the flash controller itself
> - platform-specific constraints to avoid over-heating the flash
> 
> The platform-specific constraints come from board code, and the flash driver 
> needs to ensure that the flash is never strobed for a duration longer than the 
> limit. This requires implementing a software timer if the hardware has no 
> timeout control, and programming the hardware with the correct timeout value 
> otherwise. The limit can be queried with QUERYCTRL on the duration control.

That's true.

The alternative would be software timeout since the hardware timeout is
rather coarse. Its intention is to protect the hardware from catching
fire mostly.

But as I commented in the other e-mail, there likely isn't a need to be
able to control this very precisely. The user just shuts down the flash
whenever (s)he no longer needs it rather than knows beforehand how long
it needs to stay on.

>> I have to say I'm not entirely sure the duration control is required.
>> The timeout could be writable for software strobe in the case drivers do
>> not implement software timeout. The granularity isn't _that_ much
>> anyway. Also, a timeout fault should be produced whenever the duration
>> would expire.
>>
>> Perhaps it would be best to just leave that out for now.
>>
>>>> 	V4L2_CID_FLASH_LED_MODE (menu; LED)
>>>>
>>>> enum v4l2_flash_led_mode {
>>>>
>>>> 	V4L2_FLASH_LED_MODE_FLASH = 1,
>>>> 	V4L2_FLASH_LED_MODE_TORCH,
> 
> "torch" mode can also be used for video, should we rename TORCH to something 
> more generic ? Maybe a "manual" mode ?

The controllers recognise a torch mode and I think it describes the
functionality quite well. Some appear to make a difference between torch
and video light --- but I can't imagine a purpose in which this could be
useful.

...

Regards,

-- 
Sakari Ailus
sakari.ailus@maxwell.research.nokia.com

Re: [RFC] V4L2 API for flash devices

[Laurent Pinchart]

Hi Sakari,

On Wednesday 30 March 2011 14:44:25 Sakari Ailus wrote:
> Laurent Pinchart wrote:
> > On Tuesday 29 March 2011 11:35:19 Sakari Ailus wrote:
> >> Hans Verkuil wrote:
> >>> On Monday, March 28, 2011 14:55:40 Sakari Ailus wrote:
> > [snip]
> > 
> >>>> 	V4L2_CID_FLASH_TIMEOUT (integer; LED)
> >>>> 
> >>>> The flash controller provides timeout functionality to shut down the
> >>>> led in case the host fails to do that. For hardware strobe, this is
> >>>> the maximum amount of time the flash should stay on, and the purpose
> >>>> of the setting is to prevent the LED from catching fire.
> >>>> 
> >>>> For software strobe, the setting may be used to limit the length of
> >>>> the strobe in case a driver does not implement it itself. The
> >>>> granularity of the timeout in [1, 2, 3] is very coarse. However, the
> >>>> length of a driver-implemented LED strobe shutoff is very dependent
> >>>> on host. Possibly V4L2_CID_FLASH_DURATION should be added, and
> >>>> V4L2_CID_FLASH_TIMEOUT would be read-only so that the user would be
> >>>> able to obtain the actual hardware implemented safety timeout.
> >>>> 
> >>>> Likely a standard unit such as ms or µs should be used.
> >>> 
> >>> It seems to me that this control should always be read-only. A setting
> >>> like this is very much hardware specific and you don't want an attacker
> >>> changing the timeout to the max value that might cause a LED catching
> >>> fire.
> >> 
> >> I'm not sure about that.
> >> 
> >> The driver already must take care of protecting the hardware in my
> >> opinion. Besides, at least one control is required to select the
> >> duration for the flash if there's no hardware synchronisation.
> >> 
> >> What about this:
> >> 	V4L2_CID_FLASH_TIMEOUT
> >> 
> >> Hardware timeout, read-only. Programmed to the maximum value allowed by
> >> the hardware for the external strobe, greater or equal to
> >> V4L2_CID_FLASH_DURATION for software strobe.
> >> 
> >> 	V4L2_CID_FLASH_DURATION
> >> 
> >> Software implemented timeout when V4L2_CID_FLASH_STROBE_MODE ==
> >> V4L2_FLASH_STROBE_MODE_SOFTWARE.
> > 
> > Why would we need two controls here ? My understanding is that the
> > maximum strobe duration length can be limited by
> > 
> > - the flash controller itself
> > - platform-specific constraints to avoid over-heating the flash
> > 
> > The platform-specific constraints come from board code, and the flash
> > driver needs to ensure that the flash is never strobed for a duration
> > longer than the limit. This requires implementing a software timer if
> > the hardware has no timeout control, and programming the hardware with
> > the correct timeout value otherwise. The limit can be queried with
> > QUERYCTRL on the duration control.
> 
> That's true.
> 
> The alternative would be software timeout since the hardware timeout is
> rather coarse. Its intention is to protect the hardware from catching
> fire mostly.

A software timeout can always be implemented in the driver in addition to the 
hardware timeout. I think this should be transparent for applications.
 
> But as I commented in the other e-mail, there likely isn't a need to be
> able to control this very precisely. The user just shuts down the flash
> whenever (s)he no longer needs it rather than knows beforehand how long
> it needs to stay on.

What about hardware that needs to be pre-programmed with a duration ?

> >> I have to say I'm not entirely sure the duration control is required.
> >> The timeout could be writable for software strobe in the case drivers do
> >> not implement software timeout. The granularity isn't _that_ much
> >> anyway. Also, a timeout fault should be produced whenever the duration
> >> would expire.
> >> 
> >> Perhaps it would be best to just leave that out for now.
> >> 
> >>>> 	V4L2_CID_FLASH_LED_MODE (menu; LED)
> >>>> 
> >>>> enum v4l2_flash_led_mode {
> >>>> 
> >>>> 	V4L2_FLASH_LED_MODE_FLASH = 1,
> >>>> 	V4L2_FLASH_LED_MODE_TORCH,
> > 
> > "torch" mode can also be used for video, should we rename TORCH to
> > something more generic ? Maybe a "manual" mode ?
> 
> The controllers recognise a torch mode and I think it describes the
> functionality quite well. Some appear to make a difference between torch
> and video light --- but I can't imagine a purpose in which this could be
> useful.

Torch mode is indeed a common name, but it sounds a bit specific to me.

-- 
Regards,

Laurent Pinchart

Re: [RFC] V4L2 API for flash devices

[Laurent Pinchart]

On Wednesday 30 March 2011 13:05:54 Sakari Ailus wrote:
> Laurent Pinchart wrote:
> > Hi Sakari,
> 
> Hi Laurent,
> 
> Thanks for the comments!
> 
> > On Monday 28 March 2011 14:55:40 Sakari Ailus wrote:
> > 
> > [snip]
> > 
> >> 	V4L2_CID_FLASH_STROBE_MODE (menu; LED)
> >> 
> >> Use hardware or software strobe. If hardware strobe is selected, the
> >> flash controller is a slave in the system where the sensor produces the
> >> strobe signal to the flash.
> >> 
> >> In this case the flash controller setup is limited to programming strobe
> >> timeout and power (LED flash) and the sensor controls the timing and
> >> length of the strobe.
> >> 
> >> enum v4l2_flash_strobe_mode {
> >> 
> >> 	V4L2_FLASH_STROBE_MODE_SOFTWARE,
> >> 	V4L2_FLASH_STROBE_MODE_EXT_STROBE,
> >> 
> >> };
> > 
> > [snip]
> > 
> >> 	V4L2_CID_FLASH_LED_MODE (menu; LED)
> >> 
> >> enum v4l2_flash_led_mode {
> >> 
> >> 	V4L2_FLASH_LED_MODE_FLASH = 1,
> >> 	V4L2_FLASH_LED_MODE_TORCH,
> >> 
> >> };
> > 
> > Thinking about this some more, shouldn't we combine the two controls ?
> > They are basically used to configure how the flash LED is controlled:
> > manually (torch mode), automatically by the flash controller (software
> > strobe mode) or automatically by an external component (external strobe
> > mode).
> 
> That's a good question.
> 
> The adp1653 supports also additional control (not implemented in the
> driver, though) that affect hardware strobe length. Based on register
> setting, the led will be on after strobe either until the timeout
> expires, or until the strobe signal is high.
>
> Should this be also part of the same control, or a different one?

That can be controlled by a duration control. If the duration is 0, the flash 
is lit for the duration of the external strobe, otherwise it's lit for the 
programmed duration.

> 
> Even without this, we'd have:
> 
> V4L2_FLASH_MODE_OFF
> V4L2_FLASH_MODE_TORCH
> V4L2_FLASH_MODE_SOFTWARE_STROBE
> V4L2_FLASH_MODE_EXTERNAL_STROBE
> 
> Additionally, this might be
> 
> V4L2_FLASH_MODE_EXTERNAL_STROBE_EDGE
> 
> It's true that these are mutually exclusive.
> 
> I think this is about whether we want to specify the operation of the
> flash explicitly here or allow extending the interface later on when new
> hardware is available by adding new controls. There are upsides and
> downsides in each approach.
> 
> There could be additional differentiating factors to the functionalty
> later on, like the torch/video light differentiation that some hardware
> does --- who knows based on what?
> 
> I perhaps wouldn't combine the controls. What do you think?

I'm not sure yet :-)

-- 
Regards,

Laurent Pinchart

Re: [RFC] V4L2 API for flash devices

[Sakari Ailus]

Laurent Pinchart wrote:
> Hi Sakari,

Heippa,

> On Wednesday 30 March 2011 14:44:25 Sakari Ailus wrote:
>> Laurent Pinchart wrote:
>>> On Tuesday 29 March 2011 11:35:19 Sakari Ailus wrote:
>>>> Hans Verkuil wrote:
>>>>> On Monday, March 28, 2011 14:55:40 Sakari Ailus wrote:
>>> [snip]
>>>
>>>>>> 	V4L2_CID_FLASH_TIMEOUT (integer; LED)
>>>>>>
>>>>>> The flash controller provides timeout functionality to shut down the
>>>>>> led in case the host fails to do that. For hardware strobe, this is
>>>>>> the maximum amount of time the flash should stay on, and the purpose
>>>>>> of the setting is to prevent the LED from catching fire.
>>>>>>
>>>>>> For software strobe, the setting may be used to limit the length of
>>>>>> the strobe in case a driver does not implement it itself. The
>>>>>> granularity of the timeout in [1, 2, 3] is very coarse. However, the
>>>>>> length of a driver-implemented LED strobe shutoff is very dependent
>>>>>> on host. Possibly V4L2_CID_FLASH_DURATION should be added, and
>>>>>> V4L2_CID_FLASH_TIMEOUT would be read-only so that the user would be
>>>>>> able to obtain the actual hardware implemented safety timeout.
>>>>>>
>>>>>> Likely a standard unit such as ms or µs should be used.
>>>>>
>>>>> It seems to me that this control should always be read-only. A setting
>>>>> like this is very much hardware specific and you don't want an attacker
>>>>> changing the timeout to the max value that might cause a LED catching
>>>>> fire.
>>>>
>>>> I'm not sure about that.
>>>>
>>>> The driver already must take care of protecting the hardware in my
>>>> opinion. Besides, at least one control is required to select the
>>>> duration for the flash if there's no hardware synchronisation.
>>>>
>>>> What about this:
>>>> 	V4L2_CID_FLASH_TIMEOUT
>>>>
>>>> Hardware timeout, read-only. Programmed to the maximum value allowed by
>>>> the hardware for the external strobe, greater or equal to
>>>> V4L2_CID_FLASH_DURATION for software strobe.
>>>>
>>>> 	V4L2_CID_FLASH_DURATION
>>>>
>>>> Software implemented timeout when V4L2_CID_FLASH_STROBE_MODE ==
>>>> V4L2_FLASH_STROBE_MODE_SOFTWARE.
>>>
>>> Why would we need two controls here ? My understanding is that the
>>> maximum strobe duration length can be limited by
>>>
>>> - the flash controller itself
>>> - platform-specific constraints to avoid over-heating the flash
>>>
>>> The platform-specific constraints come from board code, and the flash
>>> driver needs to ensure that the flash is never strobed for a duration
>>> longer than the limit. This requires implementing a software timer if
>>> the hardware has no timeout control, and programming the hardware with
>>> the correct timeout value otherwise. The limit can be queried with
>>> QUERYCTRL on the duration control.
>>
>> That's true.
>>
>> The alternative would be software timeout since the hardware timeout is
>> rather coarse. Its intention is to protect the hardware from catching
>> fire mostly.
> 
> A software timeout can always be implemented in the driver in addition to the 
> hardware timeout. I think this should be transparent for applications.
>  
>> But as I commented in the other e-mail, there likely isn't a need to be
>> able to control this very precisely. The user just shuts down the flash
>> whenever (s)he no longer needs it rather than knows beforehand how long
>> it needs to stay on.
> 
> What about hardware that needs to be pre-programmed with a duration ?

Same control?

I wonder if I could say we agree to have one timeout control which is
used to control the hardware timeout directly, or to implement a timeout
in software? :-)

>>>> I have to say I'm not entirely sure the duration control is required.
>>>> The timeout could be writable for software strobe in the case drivers do
>>>> not implement software timeout. The granularity isn't _that_ much
>>>> anyway. Also, a timeout fault should be produced whenever the duration
>>>> would expire.
>>>>
>>>> Perhaps it would be best to just leave that out for now.
>>>>
>>>>>> 	V4L2_CID_FLASH_LED_MODE (menu; LED)
>>>>>>
>>>>>> enum v4l2_flash_led_mode {
>>>>>>
>>>>>> 	V4L2_FLASH_LED_MODE_FLASH = 1,
>>>>>> 	V4L2_FLASH_LED_MODE_TORCH,
>>>
>>> "torch" mode can also be used for video, should we rename TORCH to
>>> something more generic ? Maybe a "manual" mode ?
>>
>> The controllers recognise a torch mode and I think it describes the
>> functionality quite well. Some appear to make a difference between torch
>> and video light --- but I can't imagine a purpose in which this could be
>> useful.
> 
> Torch mode is indeed a common name, but it sounds a bit specific to me.

Torch suggests it can be used over extended periods of time, unlike
manual which doesn't really say much. I'd keep it torch since what it
suggests is that it can stay on for long. No references outside the
flash controller itself.

-- 
Sakari Ailus
sakari.ailus@maxwell.research.nokia.com

Re: [RFC] V4L2 API for flash devices

[David Cohen]

On Wed, Mar 30, 2011 at 5:18 PM, Sakari Ailus
<sakari.ailus@maxwell.research.nokia.com> wrote:
> Laurent Pinchart wrote:
>> Hi Sakari,
>
> Heippa,

Hello,

My 2 cents below.

>
>> On Wednesday 30 March 2011 14:44:25 Sakari Ailus wrote:
>>> Laurent Pinchart wrote:
>>>> On Tuesday 29 March 2011 11:35:19 Sakari Ailus wrote:
>>>>> Hans Verkuil wrote:
>>>>>> On Monday, March 28, 2011 14:55:40 Sakari Ailus wrote:
>>>> [snip]
>>>>
>>>>>>>  V4L2_CID_FLASH_TIMEOUT (integer; LED)
>>>>>>>
>>>>>>> The flash controller provides timeout functionality to shut down the
>>>>>>> led in case the host fails to do that. For hardware strobe, this is
>>>>>>> the maximum amount of time the flash should stay on, and the purpose
>>>>>>> of the setting is to prevent the LED from catching fire.
>>>>>>>
>>>>>>> For software strobe, the setting may be used to limit the length of
>>>>>>> the strobe in case a driver does not implement it itself. The
>>>>>>> granularity of the timeout in [1, 2, 3] is very coarse. However, the
>>>>>>> length of a driver-implemented LED strobe shutoff is very dependent
>>>>>>> on host. Possibly V4L2_CID_FLASH_DURATION should be added, and
>>>>>>> V4L2_CID_FLASH_TIMEOUT would be read-only so that the user would be
>>>>>>> able to obtain the actual hardware implemented safety timeout.
>>>>>>>
>>>>>>> Likely a standard unit such as ms or 盜 should be used.
>>>>>>
>>>>>> It seems to me that this control should always be read-only. A setting
>>>>>> like this is very much hardware specific and you don't want an attacker
>>>>>> changing the timeout to the max value that might cause a LED catching
>>>>>> fire.
>>>>>
>>>>> I'm not sure about that.
>>>>>
>>>>> The driver already must take care of protecting the hardware in my
>>>>> opinion. Besides, at least one control is required to select the
>>>>> duration for the flash if there's no hardware synchronisation.
>>>>>
>>>>> What about this:
>>>>>    V4L2_CID_FLASH_TIMEOUT
>>>>>
>>>>> Hardware timeout, read-only. Programmed to the maximum value allowed by
>>>>> the hardware for the external strobe, greater or equal to
>>>>> V4L2_CID_FLASH_DURATION for software strobe.
>>>>>
>>>>>    V4L2_CID_FLASH_DURATION
>>>>>
>>>>> Software implemented timeout when V4L2_CID_FLASH_STROBE_MODE ==
>>>>> V4L2_FLASH_STROBE_MODE_SOFTWARE.
>>>>
>>>> Why would we need two controls here ? My understanding is that the
>>>> maximum strobe duration length can be limited by
>>>>
>>>> - the flash controller itself
>>>> - platform-specific constraints to avoid over-heating the flash
>>>>
>>>> The platform-specific constraints come from board code, and the flash
>>>> driver needs to ensure that the flash is never strobed for a duration
>>>> longer than the limit. This requires implementing a software timer if
>>>> the hardware has no timeout control, and programming the hardware with
>>>> the correct timeout value otherwise. The limit can be queried with
>>>> QUERYCTRL on the duration control.
>>>
>>> That's true.
>>>
>>> The alternative would be software timeout since the hardware timeout is
>>> rather coarse. Its intention is to protect the hardware from catching
>>> fire mostly.
>>
>> A software timeout can always be implemented in the driver in addition to the
>> hardware timeout. I think this should be transparent for applications.
>>
>>> But as I commented in the other e-mail, there likely isn't a need to be
>>> able to control this very precisely. The user just shuts down the flash
>>> whenever (s)he no longer needs it rather than knows beforehand how long
>>> it needs to stay on.
>>
>> What about hardware that needs to be pre-programmed with a duration ?
>
> Same control?
>
> I wonder if I could say we agree to have one timeout control which is
> used to control the hardware timeout directly, or to implement a timeout
> in software? :-)

Correct if I'm wrong, but I guess we might be talking about 2 kind of timeouts:
 - One for the duration itself
 - Another one to act like watchdog in addition to the hw timeout

IMO they should be different controls. We could even specify on the
control name when it's a watchdog case to make it more clear.

>
>>>>> I have to say I'm not entirely sure the duration control is required.
>>>>> The timeout could be writable for software strobe in the case drivers do
>>>>> not implement software timeout. The granularity isn't _that_ much
>>>>> anyway. Also, a timeout fault should be produced whenever the duration
>>>>> would expire.
>>>>>
>>>>> Perhaps it would be best to just leave that out for now.
>>>>>
>>>>>>>  V4L2_CID_FLASH_LED_MODE (menu; LED)
>>>>>>>
>>>>>>> enum v4l2_flash_led_mode {
>>>>>>>
>>>>>>>  V4L2_FLASH_LED_MODE_FLASH = 1,
>>>>>>>  V4L2_FLASH_LED_MODE_TORCH,
>>>>
>>>> "torch" mode can also be used for video, should we rename TORCH to
>>>> something more generic ? Maybe a "manual" mode ?
>>>
>>> The controllers recognise a torch mode and I think it describes the
>>> functionality quite well. Some appear to make a difference between torch
>>> and video light --- but I can't imagine a purpose in which this could be
>>> useful.
>>
>> Torch mode is indeed a common name, but it sounds a bit specific to me.
>
> Torch suggests it can be used over extended periods of time, unlike
> manual which doesn't really say much. I'd keep it torch since what it
> suggests is that it can stay on for long. No references outside the
> flash controller itself.

I'd keep with torch also as it seems to be more clear.

Regards,

David

>
> --
> Sakari Ailus
> sakari.ailus@maxwell.research.nokia.com
> --
> To unsubscribe from this list: send the line "unsubscribe linux-media" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>

Re: [RFC] V4L2 API for flash devices

[Laurent Pinchart]

Hi David,

On Wednesday 30 March 2011 16:57:30 David Cohen wrote:
> On Wed, Mar 30, 2011 at 5:18 PM, Sakari Ailus wrote:
> >> On Wednesday 30 March 2011 14:44:25 Sakari Ailus wrote:
> >>> Laurent Pinchart wrote:
> >>>> On Tuesday 29 March 2011 11:35:19 Sakari Ailus wrote:
> >>>>> Hans Verkuil wrote:
> >>>>>> On Monday, March 28, 2011 14:55:40 Sakari Ailus wrote:
> >>>> [snip]
> >>>> 
> >>>>>>>  V4L2_CID_FLASH_TIMEOUT (integer; LED)
> >>>>>>> 
> >>>>>>> The flash controller provides timeout functionality to shut down
> >>>>>>> the led in case the host fails to do that. For hardware strobe,
> >>>>>>> this is the maximum amount of time the flash should stay on, and
> >>>>>>> the purpose of the setting is to prevent the LED from catching
> >>>>>>> fire.
> >>>>>>> 
> >>>>>>> For software strobe, the setting may be used to limit the length of
> >>>>>>> the strobe in case a driver does not implement it itself. The
> >>>>>>> granularity of the timeout in [1, 2, 3] is very coarse. However,
> >>>>>>> the length of a driver-implemented LED strobe shutoff is very
> >>>>>>> dependent on host. Possibly V4L2_CID_FLASH_DURATION should be
> >>>>>>> added, and V4L2_CID_FLASH_TIMEOUT would be read-only so that the
> >>>>>>> user would be able to obtain the actual hardware implemented
> >>>>>>> safety timeout.
> >>>>>>> 
> >>>>>>> Likely a standard unit such as ms or 盜 should be used.
> >>>>>> 
> >>>>>> It seems to me that this control should always be read-only. A
> >>>>>> setting like this is very much hardware specific and you don't want
> >>>>>> an attacker changing the timeout to the max value that might cause
> >>>>>> a LED catching fire.
> >>>>> 
> >>>>> I'm not sure about that.
> >>>>> 
> >>>>> The driver already must take care of protecting the hardware in my
> >>>>> opinion. Besides, at least one control is required to select the
> >>>>> duration for the flash if there's no hardware synchronisation.
> >>>>> 
> >>>>> What about this:
> >>>>>    V4L2_CID_FLASH_TIMEOUT
> >>>>> 
> >>>>> Hardware timeout, read-only. Programmed to the maximum value allowed
> >>>>> by the hardware for the external strobe, greater or equal to
> >>>>> V4L2_CID_FLASH_DURATION for software strobe.
> >>>>> 
> >>>>>    V4L2_CID_FLASH_DURATION
> >>>>> 
> >>>>> Software implemented timeout when V4L2_CID_FLASH_STROBE_MODE ==
> >>>>> V4L2_FLASH_STROBE_MODE_SOFTWARE.
> >>>> 
> >>>> Why would we need two controls here ? My understanding is that the
> >>>> maximum strobe duration length can be limited by
> >>>> 
> >>>> - the flash controller itself
> >>>> - platform-specific constraints to avoid over-heating the flash
> >>>> 
> >>>> The platform-specific constraints come from board code, and the flash
> >>>> driver needs to ensure that the flash is never strobed for a duration
> >>>> longer than the limit. This requires implementing a software timer if
> >>>> the hardware has no timeout control, and programming the hardware with
> >>>> the correct timeout value otherwise. The limit can be queried with
> >>>> QUERYCTRL on the duration control.
> >>> 
> >>> That's true.
> >>> 
> >>> The alternative would be software timeout since the hardware timeout is
> >>> rather coarse. Its intention is to protect the hardware from catching
> >>> fire mostly.
> >> 
> >> A software timeout can always be implemented in the driver in addition
> >> to the hardware timeout. I think this should be transparent for
> >> applications.
> >> 
> >>> But as I commented in the other e-mail, there likely isn't a need to be
> >>> able to control this very precisely. The user just shuts down the flash
> >>> whenever (s)he no longer needs it rather than knows beforehand how long
> >>> it needs to stay on.
> >> 
> >> What about hardware that needs to be pre-programmed with a duration ?
> > 
> > Same control?
> > 
> > I wonder if I could say we agree to have one timeout control which is
> > used to control the hardware timeout directly, or to implement a timeout
> > in software? :-)
> 
> Correct if I'm wrong, but I guess we might be talking about 2 kind of
> timeouts:
> - One for the duration itself
> - Another one to act like watchdog in addition to the hw timeout

Do we need a control for that, or should it just be a fixed value that comes 
from platform data ?

> IMO they should be different controls. We could even specify on the
> control name when it's a watchdog case to make it more clear.
> 
> >>>>> I have to say I'm not entirely sure the duration control is required.
> >>>>> The timeout could be writable for software strobe in the case drivers
> >>>>> do not implement software timeout. The granularity isn't _that_ much
> >>>>> anyway. Also, a timeout fault should be produced whenever the
> >>>>> duration would expire.
> >>>>> 
> >>>>> Perhaps it would be best to just leave that out for now.
> >>>>> 
> >>>>>>>  V4L2_CID_FLASH_LED_MODE (menu; LED)
> >>>>>>> 
> >>>>>>> enum v4l2_flash_led_mode {
> >>>>>>> 
> >>>>>>>  V4L2_FLASH_LED_MODE_FLASH = 1,
> >>>>>>>  V4L2_FLASH_LED_MODE_TORCH,
> >>>> 
> >>>> "torch" mode can also be used for video, should we rename TORCH to
> >>>> something more generic ? Maybe a "manual" mode ?
> >>> 
> >>> The controllers recognise a torch mode and I think it describes the
> >>> functionality quite well. Some appear to make a difference between
> >>> torch and video light --- but I can't imagine a purpose in which this
> >>> could be useful.
> >> 
> >> Torch mode is indeed a common name, but it sounds a bit specific to me.
> > 
> > Torch suggests it can be used over extended periods of time, unlike
> > manual which doesn't really say much. I'd keep it torch since what it
> > suggests is that it can stay on for long. No references outside the
> > flash controller itself.
> 
> I'd keep with torch also as it seems to be more clear.

OK, I'll give up then :-)

-- 
Regards,

Laurent Pinchart

Re: [RFC] V4L2 API for flash devices

[Kim HeungJun]

Hi Sakari,

2011. 3. 30., 오후 8:37, Sakari Ailus 작성:

> Kim, HeungJun wrote:
>> Hi Sakari,
> 
> Hi HeungJun,
> 
>> 2011-03-29 오후 11:41, Sakari Ailus 쓴 글:
>>> Kim, HeungJun wrote:
>> [snip]
>>>> I think it's not different method to turn on/off, whatever the mode name is.
>>>> But, the mode name DEDICATED is look more reasonable, because the reason 
>>>> which is devided FLASH and TORCH in the mode, is why only power up the led,
>>>> not sensor.
>>> 
>>> Sensor? Is the flash part of the sensor module for you?
>> Yes. The flash is a part of the sensor module(our case like M-5MOLS).
>> Precisely, the sensor internal core's gpio pin is connected with
>> external Flash LED, and the control master is the sensor internal core.
>> For turnning on the Flash LED, we should use I2C register access.
>> So, I think it's exactly matches with hardware strobe as you metioned.
> 
> Ok, I think I'm lost now. :-)
> 
> What signals are sent from sensor to flash in both torch and flash cases?
I guess the signal probably is just continuous repetition High/Low like PWM signal,
which is generated by the core of sensor module.  Although I don't check what signal
it is, it's very possible. Because it's the only way to be able to control intensity of  Flash.

So, I think the torch and flash case is the same way or signal in this case.

> 
>>> I think it should be other factors than the flash mode that are used to
>>> make the decision on whether to power on the sensor or not.
>>> 
>>> The factors based on which to power the subdevs probably will be
>>> discussed in the future, and which entity is responsible for power
>>> management. The power management code originally was part of the Media
>>> controller framework but it was removed since it was not seen to be
>>> generic enough.
>>> 
>>> Many subdev drivers (including the adp1653) basically get powered as
>>> long as the subdev device node is open. Sensor can be powered based on
>>> other factors as well, such as the streaming state and what are the
>>> connections to the video nodes.
>> That's the start point I said. When the user use only the flash, it should be
>> accompanied(of course, I have same circumstance) by opening the videonode
>> and doing the media control operation, but we have no option to do because
>> it's depending on the hardware connection architecture.
> 
> When the user only needs to use the flash, in this case the user must
> open the subdev node which is exported by the flash controller driver.
> Not the video node, which is handled in the bridge (ISP) driver.

> 
>> So, I suggesst that, if we can not give to users(of course, this user
>> want to use only flash function, not the camera) proper method usage
>> (openning the videonode for using flash), let's express that the camera
>> flash is used in the DEDICATED MODE now, as the enumeration name DEDICATED.
> 
> No. The video nodes should not be involved since they are related to the
> bridge (ISP) which is not needed to use the flash. Assuming that this is
> the situation.
> 
> This is how the use case should go:
> 
> 1. open subdev node, e.g. /dev/v4l-subdev0, which is the flash
> (flash controller powered on)
> 2. VIDIOC_S_CTRL: V4L2_CID_FLASH_LED_MODE, V4L2_FLASH_LED_MODE_TORCH
> (flash is on now)
> 2. VIDIOC_S_CTRL: V4L2_CID_FLASH_LED_MODE, V4L2_FLASH_LED_MODE_NONE
> (flash is off now)
> 3. close the file handle
> (flash controller powered off)
Probably you mean media controller framework is based on. I get it. :)

> 
>> But, I think it might be not a big issue. So, any others don't comment at this,
>> it's ok for me to pass this naming issue.
>> 
>> I can see this API is very cool for camera man just like me.
> 
> Thanks!
> 
>> plus: actually I have the one of N-series, N810. So, the omap3isp is available to
>> activate this device, not even it's cpu is omap3? Just question.
> 
> The N810 has OMAP 2420 which has a completely different camera bridge,
> and there's no flash. The drivers for the camera in N810 are omap24xxcam
> and tcm825x. The drivers are functional in mainline but the platform
> data is missing, as well as the CBUS driver. This work is queued but
> unknown when there's time for this.
Thanks for plus reply. I've tested tony's patch for booting the ubuntu long time ago,
but I'm sure this gadget is good device. 

> 
> Regards,
> 
> -- 
> Sakari Ailus
> sakari.ailus@maxwell.research.nokia.com
> --
> To unsubscribe from this list: send the line "unsubscribe linux-media" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC] V4L2 API for flash devices

[Sakari Ailus]

Laurent Pinchart wrote:
> Hi David,

Salut,

> On Wednesday 30 March 2011 16:57:30 David Cohen wrote:
>> On Wed, Mar 30, 2011 at 5:18 PM, Sakari Ailus wrote:
>>>> On Wednesday 30 March 2011 14:44:25 Sakari Ailus wrote:
...
>>>>> But as I commented in the other e-mail, there likely isn't a need to be
>>>>> able to control this very precisely. The user just shuts down the flash
>>>>> whenever (s)he no longer needs it rather than knows beforehand how long
>>>>> it needs to stay on.
>>>>
>>>> What about hardware that needs to be pre-programmed with a duration ?
>>>
>>> Same control?
>>>
>>> I wonder if I could say we agree to have one timeout control which is
>>> used to control the hardware timeout directly, or to implement a timeout
>>> in software? :-)
>>
>> Correct if I'm wrong, but I guess we might be talking about 2 kind of
>> timeouts:
>> - One for the duration itself
>> - Another one to act like watchdog in addition to the hw timeout
> 
> Do we need a control for that, or should it just be a fixed value that comes 
> from platform data ?

I think it's good to set the hardware timeout as small as possible. This
makes the timeout behaviour more deterministic. I'm not sure if the
information _needs_ to be delivered to user space though.

On the other hand, if we now use the same control for both software and
hardware timeout we can't add a new one without changing the meaning for
the old one.

My proposal: let's postpone this and decide when we need to. Only
hardware timeouts are implemented for now. When someone wants a software
timeout then figure out what to do. We'd have exactly the same options
then: the same control or a new control.

>> IMO they should be different controls. We could even specify on the
>> control name when it's a watchdog case to make it more clear.
>>
>>>>>>> I have to say I'm not entirely sure the duration control is required.
>>>>>>> The timeout could be writable for software strobe in the case drivers
>>>>>>> do not implement software timeout. The granularity isn't _that_ much
>>>>>>> anyway. Also, a timeout fault should be produced whenever the
>>>>>>> duration would expire.
>>>>>>>
>>>>>>> Perhaps it would be best to just leave that out for now.
>>>>>>>
>>>>>>>>>  V4L2_CID_FLASH_LED_MODE (menu; LED)
>>>>>>>>>
>>>>>>>>> enum v4l2_flash_led_mode {
>>>>>>>>>
>>>>>>>>>  V4L2_FLASH_LED_MODE_FLASH = 1,
>>>>>>>>>  V4L2_FLASH_LED_MODE_TORCH,
>>>>>>
>>>>>> "torch" mode can also be used for video, should we rename TORCH to
>>>>>> something more generic ? Maybe a "manual" mode ?
>>>>>
>>>>> The controllers recognise a torch mode and I think it describes the
>>>>> functionality quite well. Some appear to make a difference between
>>>>> torch and video light --- but I can't imagine a purpose in which this
>>>>> could be useful.
>>>>
>>>> Torch mode is indeed a common name, but it sounds a bit specific to me.
>>>
>>> Torch suggests it can be used over extended periods of time, unlike
>>> manual which doesn't really say much. I'd keep it torch since what it
>>> suggests is that it can stay on for long. No references outside the
>>> flash controller itself.
>>
>> I'd keep with torch also as it seems to be more clear.
> 
> OK, I'll give up then :-)

Torch, then. :-)

-- 
Sakari Ailus
sakari.ailus@maxwell.research.nokia.com

Re: [RFC] V4L2 API for flash devices

[Sakari Ailus]

Laurent Pinchart wrote:
> On Wednesday 30 March 2011 13:05:54 Sakari Ailus wrote:
>> Laurent Pinchart wrote:
>>> Hi Sakari,
>>
>> Hi Laurent,
>>
>> Thanks for the comments!
>>
>>> On Monday 28 March 2011 14:55:40 Sakari Ailus wrote:
>>>
>>> [snip]
>>>
>>>> 	V4L2_CID_FLASH_STROBE_MODE (menu; LED)
>>>>
>>>> Use hardware or software strobe. If hardware strobe is selected, the
>>>> flash controller is a slave in the system where the sensor produces the
>>>> strobe signal to the flash.
>>>>
>>>> In this case the flash controller setup is limited to programming strobe
>>>> timeout and power (LED flash) and the sensor controls the timing and
>>>> length of the strobe.
>>>>
>>>> enum v4l2_flash_strobe_mode {
>>>>
>>>> 	V4L2_FLASH_STROBE_MODE_SOFTWARE,
>>>> 	V4L2_FLASH_STROBE_MODE_EXT_STROBE,
>>>>
>>>> };
>>>
>>> [snip]
>>>
>>>> 	V4L2_CID_FLASH_LED_MODE (menu; LED)
>>>>
>>>> enum v4l2_flash_led_mode {
>>>>
>>>> 	V4L2_FLASH_LED_MODE_FLASH = 1,
>>>> 	V4L2_FLASH_LED_MODE_TORCH,
>>>>
>>>> };
>>>
>>> Thinking about this some more, shouldn't we combine the two controls ?
>>> They are basically used to configure how the flash LED is controlled:
>>> manually (torch mode), automatically by the flash controller (software
>>> strobe mode) or automatically by an external component (external strobe
>>> mode).
>>
>> That's a good question.
>>
>> The adp1653 supports also additional control (not implemented in the
>> driver, though) that affect hardware strobe length. Based on register
>> setting, the led will be on after strobe either until the timeout
>> expires, or until the strobe signal is high.
>>
>> Should this be also part of the same control, or a different one?
> 
> That can be controlled by a duration control. If the duration is 0, the flash 
> is lit for the duration of the external strobe, otherwise it's lit for the 
> programmed duration.

Sounds good to me.

>> Even without this, we'd have:
>>
>> V4L2_FLASH_MODE_OFF
>> V4L2_FLASH_MODE_TORCH
>> V4L2_FLASH_MODE_SOFTWARE_STROBE
>> V4L2_FLASH_MODE_EXTERNAL_STROBE
>>
>> Additionally, this might be
>>
>> V4L2_FLASH_MODE_EXTERNAL_STROBE_EDGE
>>
>> It's true that these are mutually exclusive.
>>
>> I think this is about whether we want to specify the operation of the
>> flash explicitly here or allow extending the interface later on when new
>> hardware is available by adding new controls. There are upsides and
>> downsides in each approach.
>>
>> There could be additional differentiating factors to the functionalty
>> later on, like the torch/video light differentiation that some hardware
>> does --- who knows based on what?
>>
>> I perhaps wouldn't combine the controls. What do you think?
> 
> I'm not sure yet :-)

I have a vague feeling that as we don't know about the future hardware
I'd prefer to keep this as extensible as possible, meaning that I'd
rather add new controls than define menu controls with use case specific
items in them. This would translate to two controls: flash mode (none,
torch, flash) and strobe mode (software, external).

What do the others think on this?

-- 
Sakari Ailus
sakari.ailus@maxwell.research.nokia.com

Re: [RFC] V4L2 API for flash devices

[Sakari Ailus]

Kim HeungJun wrote:
> Hi Sakari,

Hi,

> 2011. 3. 30., 오후 8:37, Sakari Ailus 작성:
> 
>> Kim, HeungJun wrote:
>>> Hi Sakari,
>>
>> Hi HeungJun,
>>
>>> 2011-03-29 오후 11:41, Sakari Ailus 쓴 글:
>>>> Kim, HeungJun wrote:
>>> [snip]
>>>>> I think it's not different method to turn on/off, whatever the mode name is.
>>>>> But, the mode name DEDICATED is look more reasonable, because the reason 
>>>>> which is devided FLASH and TORCH in the mode, is why only power up the led,
>>>>> not sensor.
>>>>
>>>> Sensor? Is the flash part of the sensor module for you?
>>> Yes. The flash is a part of the sensor module(our case like M-5MOLS).
>>> Precisely, the sensor internal core's gpio pin is connected with
>>> external Flash LED, and the control master is the sensor internal core.
>>> For turnning on the Flash LED, we should use I2C register access.
>>> So, I think it's exactly matches with hardware strobe as you metioned.
>>
>> Ok, I think I'm lost now. :-)
>>
>> What signals are sent from sensor to flash in both torch and flash cases?
> I guess the signal probably is just continuous repetition High/Low like PWM signal,
> which is generated by the core of sensor module.  Although I don't check what signal
> it is, it's very possible. Because it's the only way to be able to control intensity of  Flash.
> 
> So, I think the torch and flash case is the same way or signal in this case.

So... to summarise, the sensor determines the flash power by providing
the flash controller a pwm signal both in flash and torch modes, if I
understand correctly?

This sounds like a quite low level control. Is the flash controller
still an I2C device?

...

>>> So, I suggesst that, if we can not give to users(of course, this user
>>> want to use only flash function, not the camera) proper method usage
>>> (openning the videonode for using flash), let's express that the camera
>>> flash is used in the DEDICATED MODE now, as the enumeration name DEDICATED.
>>
>> No. The video nodes should not be involved since they are related to the
>> bridge (ISP) which is not needed to use the flash. Assuming that this is
>> the situation.
>>
>> This is how the use case should go:
>>
>> 1. open subdev node, e.g. /dev/v4l-subdev0, which is the flash
>> (flash controller powered on)
>> 2. VIDIOC_S_CTRL: V4L2_CID_FLASH_LED_MODE, V4L2_FLASH_LED_MODE_TORCH
>> (flash is on now)
>> 2. VIDIOC_S_CTRL: V4L2_CID_FLASH_LED_MODE, V4L2_FLASH_LED_MODE_NONE
>> (flash is off now)
>> 3. close the file handle
>> (flash controller powered off)
> Probably you mean media controller framework is based on. I get it. :)
> 
>>
>>> But, I think it might be not a big issue. So, any others don't comment at this,
>>> it's ok for me to pass this naming issue.
>>>
>>> I can see this API is very cool for camera man just like me.
>>
>> Thanks!
>>
>>> plus: actually I have the one of N-series, N810. So, the omap3isp is available to
>>> activate this device, not even it's cpu is omap3? Just question.
>>
>> The N810 has OMAP 2420 which has a completely different camera bridge,
>> and there's no flash. The drivers for the camera in N810 are omap24xxcam
>> and tcm825x. The drivers are functional in mainline but the platform
>> data is missing, as well as the CBUS driver. This work is queued but
>> unknown when there's time for this.
> Thanks for plus reply. I've tested tony's patch for booting the ubuntu long time ago,
> but I'm sure this gadget is good device. 

I've never tried it out with Ubuntu. Probably that 128 MiB of RAM is
slightly small for Ubuntu. ;-)

-- 
Sakari Ailus
sakari.ailus@maxwell.research.nokia.com

Re: [RFC] V4L2 API for flash devices

[Sakari Ailus]

Laurent Pinchart wrote:
> Hi Sakari,

Hi Laurent,

> On Tuesday 29 March 2011 13:51:38 Sakari Ailus wrote:
>> Sakari Ailus wrote:
>>> Hans Verkuil wrote:
>>>> On Tuesday, March 29, 2011 11:35:19 Sakari Ailus wrote:
>>>>> Hi Hans,
>>>>>
>>>>> Many thanks for the comments!
>>>
>>> ...
>>>
>>>>> It occurred to me that an application might want to turn off a flash
>>>>> which has been strobed on software. That can't be done on a single
>>>>> button control.
>>>>>
>>>>> V4L2_CID_FLASH_SHUTDOWN?
>>>>>
>>>>> The application would know the flash strobe is ongoing before it
>>>>> receives a timeout fault. I somehow feel that there should be a control
>>>>> telling that directly.
>>>>>
>>>>> What about using a bool control for the strobe?
>>>>
>>>> It depends: is the strobe signal just a pulse that kicks off the flash,
>>>> or is it active throughout the flash duration? In the latter case a
>>>> bool makes sense, in the first case an extra button control makes
>>>> sense.
>>>
>>> I like buttons since I associate them with action (like strobing) but on
>>> the other hand buttons don't allow querying the current state. On the
>>> other hand, the current state isn't always determinable, e.g. in the
>>> absence of the interrupt line from the flash controller interrupt pin
>>> (e.g. N900!).
>>
>> Oh, I need to take my words back a bit.
>>
>> There indeed is a way to get the on/off status for the flash, but that
>> involves I2C register access --- when you read the fault registers, you
>> do get the state, even if the interrupt linke is missing from the
>> device. At least I can't see why this wouldn't work, at least on this
>> particular chip.
>>
>> What you can't have in this case is the event.
>>
>> So, in my opinion this suggests that a single boolean control is the way
>> to go.
> 
> Why would an application want to turn off a flash that has been strobbed in 
> software ? Applications should set the flash duration and then strobe it.

The applications won't know beforehand the exact timing of the exposure
of the frames on the sensor and the latencies of the operating system
possibly affected by other processes running on the system. Thus it's
impossible to know exactly how long flash strobe (on software, that is!)
is required.

So, as far as I see there should be a way to turn the flash off and the
timeout would mostly function as a safeguard. This is likely dependent
on the flash controller as well.

-- 
Sakari Ailus
sakari.ailus@maxwell.research.nokia.com

Re: [RFC] V4L2 API for flash devices

[Sakari Ailus]

Hi Laurent,

Sakari Ailus wrote:
> Laurent Pinchart wrote:
>> On Wednesday 30 March 2011 13:05:54 Sakari Ailus wrote:
>>> Laurent Pinchart wrote:
>>>> Hi Sakari,
>>>
>>> Hi Laurent,
>>>
>>> Thanks for the comments!
>>>
>>>> On Monday 28 March 2011 14:55:40 Sakari Ailus wrote:
>>>>
>>>> [snip]
>>>>
>>>>> 	V4L2_CID_FLASH_STROBE_MODE (menu; LED)
>>>>>
>>>>> Use hardware or software strobe. If hardware strobe is selected, the
>>>>> flash controller is a slave in the system where the sensor produces the
>>>>> strobe signal to the flash.
>>>>>
>>>>> In this case the flash controller setup is limited to programming strobe
>>>>> timeout and power (LED flash) and the sensor controls the timing and
>>>>> length of the strobe.
>>>>>
>>>>> enum v4l2_flash_strobe_mode {
>>>>>
>>>>> 	V4L2_FLASH_STROBE_MODE_SOFTWARE,
>>>>> 	V4L2_FLASH_STROBE_MODE_EXT_STROBE,
>>>>>
>>>>> };
>>>>
>>>> [snip]
>>>>
>>>>> 	V4L2_CID_FLASH_LED_MODE (menu; LED)
>>>>>
>>>>> enum v4l2_flash_led_mode {
>>>>>
>>>>> 	V4L2_FLASH_LED_MODE_FLASH = 1,
>>>>> 	V4L2_FLASH_LED_MODE_TORCH,
>>>>>
>>>>> };
>>>>
>>>> Thinking about this some more, shouldn't we combine the two controls ?
>>>> They are basically used to configure how the flash LED is controlled:
>>>> manually (torch mode), automatically by the flash controller (software
>>>> strobe mode) or automatically by an external component (external strobe
>>>> mode).
>>>
>>> That's a good question.
>>>
>>> The adp1653 supports also additional control (not implemented in the
>>> driver, though) that affect hardware strobe length. Based on register
>>> setting, the led will be on after strobe either until the timeout
>>> expires, or until the strobe signal is high.
>>>
>>> Should this be also part of the same control, or a different one?
>>
>> That can be controlled by a duration control. If the duration is 0, the flash 
>> is lit for the duration of the external strobe, otherwise it's lit for the 
>> programmed duration.
> 
> Sounds good to me.

Thinking about this again; there won't be a separate duration control
and the hardware timeout can't be zero in a general case.

So this is not an option, and I don't think we'd want to add duration
control for this purpose.

What about V4L2_CID_FLASH_EXTERNAL_STROBE_EDGE?

-- 
Sakari Ailus
sakari.ailus@maxwell.research.nokia.com

Re: [RFC] V4L2 API for flash devices

[Laurent Pinchart]

Hi Sakari,

On Tuesday 05 April 2011 12:23:51 Sakari Ailus wrote:
> Sakari Ailus wrote:
> > Laurent Pinchart wrote:
> >> On Wednesday 30 March 2011 13:05:54 Sakari Ailus wrote:
> >>> Laurent Pinchart wrote:
> >>>> On Monday 28 March 2011 14:55:40 Sakari Ailus wrote:
> >>>> 
> >>>> [snip]
> >>>> 
> >>>>> 	V4L2_CID_FLASH_STROBE_MODE (menu; LED)
> >>>>> 
> >>>>> Use hardware or software strobe. If hardware strobe is selected, the
> >>>>> flash controller is a slave in the system where the sensor produces
> >>>>> the strobe signal to the flash.
> >>>>> 
> >>>>> In this case the flash controller setup is limited to programming
> >>>>> strobe timeout and power (LED flash) and the sensor controls the
> >>>>> timing and length of the strobe.
> >>>>> 
> >>>>> enum v4l2_flash_strobe_mode {
> >>>>> 
> >>>>> 	V4L2_FLASH_STROBE_MODE_SOFTWARE,
> >>>>> 	V4L2_FLASH_STROBE_MODE_EXT_STROBE,
> >>>>> 
> >>>>> };
> >>>> 
> >>>> [snip]
> >>>> 
> >>>>> 	V4L2_CID_FLASH_LED_MODE (menu; LED)
> >>>>> 
> >>>>> enum v4l2_flash_led_mode {
> >>>>> 
> >>>>> 	V4L2_FLASH_LED_MODE_FLASH = 1,
> >>>>> 	V4L2_FLASH_LED_MODE_TORCH,
> >>>>> 
> >>>>> };
> >>>> 
> >>>> Thinking about this some more, shouldn't we combine the two controls ?
> >>>> They are basically used to configure how the flash LED is controlled:
> >>>> manually (torch mode), automatically by the flash controller (software
> >>>> strobe mode) or automatically by an external component (external
> >>>> strobe mode).
> >>> 
> >>> That's a good question.
> >>> 
> >>> The adp1653 supports also additional control (not implemented in the
> >>> driver, though) that affect hardware strobe length. Based on register
> >>> setting, the led will be on after strobe either until the timeout
> >>> expires, or until the strobe signal is high.
> >>> 
> >>> Should this be also part of the same control, or a different one?
> >> 
> >> That can be controlled by a duration control. If the duration is 0, the
> >> flash is lit for the duration of the external strobe, otherwise it's
> >> lit for the programmed duration.
> > 
> > Sounds good to me.
> 
> Thinking about this again; there won't be a separate duration control

Why not ? I think we need two timeouts, a watchdog timeout to prevent flash 
fire or meltdown, and a normal timeout to lit the flash for a user-selected 
duration.

> and the hardware timeout can't be zero in a general case.
> 
> So this is not an option, and I don't think we'd want to add duration
> control for this purpose.
> 
> What about V4L2_CID_FLASH_EXTERNAL_STROBE_EDGE?

-- 
Regards,

Laurent Pinchart

Re: [RFC] V4L2 API for flash devices

[Sakari Ailus]

Laurent Pinchart wrote:
> Hi Sakari,
> 
> On Tuesday 05 April 2011 12:23:51 Sakari Ailus wrote:
>> Sakari Ailus wrote:
>>> Laurent Pinchart wrote:
>>>> On Wednesday 30 March 2011 13:05:54 Sakari Ailus wrote:
>>>>> Laurent Pinchart wrote:
>>>>>> On Monday 28 March 2011 14:55:40 Sakari Ailus wrote:
>>>>>>
>>>>>> [snip]
>>>>>>
>>>>>>> 	V4L2_CID_FLASH_STROBE_MODE (menu; LED)
>>>>>>>
>>>>>>> Use hardware or software strobe. If hardware strobe is selected, the
>>>>>>> flash controller is a slave in the system where the sensor produces
>>>>>>> the strobe signal to the flash.
>>>>>>>
>>>>>>> In this case the flash controller setup is limited to programming
>>>>>>> strobe timeout and power (LED flash) and the sensor controls the
>>>>>>> timing and length of the strobe.
>>>>>>>
>>>>>>> enum v4l2_flash_strobe_mode {
>>>>>>>
>>>>>>> 	V4L2_FLASH_STROBE_MODE_SOFTWARE,
>>>>>>> 	V4L2_FLASH_STROBE_MODE_EXT_STROBE,
>>>>>>>
>>>>>>> };
>>>>>>
>>>>>> [snip]
>>>>>>
>>>>>>> 	V4L2_CID_FLASH_LED_MODE (menu; LED)
>>>>>>>
>>>>>>> enum v4l2_flash_led_mode {
>>>>>>>
>>>>>>> 	V4L2_FLASH_LED_MODE_FLASH = 1,
>>>>>>> 	V4L2_FLASH_LED_MODE_TORCH,
>>>>>>>
>>>>>>> };
>>>>>>
>>>>>> Thinking about this some more, shouldn't we combine the two controls ?
>>>>>> They are basically used to configure how the flash LED is controlled:
>>>>>> manually (torch mode), automatically by the flash controller (software
>>>>>> strobe mode) or automatically by an external component (external
>>>>>> strobe mode).
>>>>>
>>>>> That's a good question.
>>>>>
>>>>> The adp1653 supports also additional control (not implemented in the
>>>>> driver, though) that affect hardware strobe length. Based on register
>>>>> setting, the led will be on after strobe either until the timeout
>>>>> expires, or until the strobe signal is high.
>>>>>
>>>>> Should this be also part of the same control, or a different one?
>>>>
>>>> That can be controlled by a duration control. If the duration is 0, the
>>>> flash is lit for the duration of the external strobe, otherwise it's
>>>> lit for the programmed duration.
>>>
>>> Sounds good to me.
>>
>> Thinking about this again; there won't be a separate duration control
> 
> Why not ? I think we need two timeouts, a watchdog timeout to prevent flash 
> fire or meltdown, and a normal timeout to lit the flash for a user-selected 
> duration.

Let's assume that an application wants to expose a frame using flash
with software strobe.

1. strobe flash
2. qbuf
3. streamon
4. dqbuf
5. streamoff
6. ...

How does an application know how long is the time between 1 -- 4? I'd
guess that in 6 the application would like to switch off the flash
instead of specifying a timeout for it.

-- 
Sakari Ailus
sakari.ailus@maxwell.research.nokia.com

Re: [RFC] V4L2 API for flash devices

[Laurent Pinchart]

Hi Sakari,

On Tuesday 05 April 2011 13:21:03 Sakari Ailus wrote:
> Laurent Pinchart wrote:
> > On Tuesday 05 April 2011 12:23:51 Sakari Ailus wrote:
> >> Sakari Ailus wrote:
> >>> Laurent Pinchart wrote:
> >>>> On Wednesday 30 March 2011 13:05:54 Sakari Ailus wrote:
> >>>>> Laurent Pinchart wrote:
> >>>>>> On Monday 28 March 2011 14:55:40 Sakari Ailus wrote:
> >>>>>> 
> >>>>>> [snip]
> >>>>>> 
> >>>>>>> 	V4L2_CID_FLASH_STROBE_MODE (menu; LED)
> >>>>>>> 
> >>>>>>> Use hardware or software strobe. If hardware strobe is selected,
> >>>>>>> the flash controller is a slave in the system where the sensor
> >>>>>>> produces the strobe signal to the flash.
> >>>>>>> 
> >>>>>>> In this case the flash controller setup is limited to programming
> >>>>>>> strobe timeout and power (LED flash) and the sensor controls the
> >>>>>>> timing and length of the strobe.
> >>>>>>> 
> >>>>>>> enum v4l2_flash_strobe_mode {
> >>>>>>> 
> >>>>>>> 	V4L2_FLASH_STROBE_MODE_SOFTWARE,
> >>>>>>> 	V4L2_FLASH_STROBE_MODE_EXT_STROBE,
> >>>>>>> 
> >>>>>>> };
> >>>>>> 
> >>>>>> [snip]
> >>>>>> 
> >>>>>>> 	V4L2_CID_FLASH_LED_MODE (menu; LED)
> >>>>>>> 
> >>>>>>> enum v4l2_flash_led_mode {
> >>>>>>> 
> >>>>>>> 	V4L2_FLASH_LED_MODE_FLASH = 1,
> >>>>>>> 	V4L2_FLASH_LED_MODE_TORCH,
> >>>>>>> 
> >>>>>>> };
> >>>>>> 
> >>>>>> Thinking about this some more, shouldn't we combine the two controls
> >>>>>> ? They are basically used to configure how the flash LED is
> >>>>>> controlled: manually (torch mode), automatically by the flash
> >>>>>> controller (software strobe mode) or automatically by an external
> >>>>>> component (external strobe mode).
> >>>>> 
> >>>>> That's a good question.
> >>>>> 
> >>>>> The adp1653 supports also additional control (not implemented in the
> >>>>> driver, though) that affect hardware strobe length. Based on register
> >>>>> setting, the led will be on after strobe either until the timeout
> >>>>> expires, or until the strobe signal is high.
> >>>>> 
> >>>>> Should this be also part of the same control, or a different one?
> >>>> 
> >>>> That can be controlled by a duration control. If the duration is 0,
> >>>> the flash is lit for the duration of the external strobe, otherwise
> >>>> it's lit for the programmed duration.
> >>> 
> >>> Sounds good to me.
> >> 
> >> Thinking about this again; there won't be a separate duration control
> > 
> > Why not ? I think we need two timeouts, a watchdog timeout to prevent
> > flash fire or meltdown, and a normal timeout to lit the flash for a
> > user-selected duration.
> 
> Let's assume that an application wants to expose a frame using flash
> with software strobe.
> 
> 1. strobe flash
> 2. qbuf
> 3. streamon
> 4. dqbuf
> 5. streamoff
> 6. ...
> 
> How does an application know how long is the time between 1 -- 4? I'd
> guess that in 6 the application would like to switch off the flash
> instead of specifying a timeout for it.

That's a valid use case, and we need to support it. It requires a way to lit 
the flash with no timeout other than the watchdog timeout, and a way to turn 
it off.

However, I'm not sure we should rule out the usefulness of a duration-based 
software flash strobe. Can't the two APIs coexist ? Or do you think a 
duration-based API is useless ?

-- 
Regards,

Laurent Pinchart

Re: [RFC] V4L2 API for flash devices

[David Cohen]

On Mon, Mar 28, 2011 at 3:55 PM, Sakari Ailus
<sakari.ailus@maxwell.research.nokia.com> wrote:
> Hi,

Hi Sakari,

[snip]

> This is a bitmask containing the fault information for the flash. This
> assumes the proposed V4L2 bit mask controls [5]; otherwise this would
> likely need to be a set of controls.
>
> #define V4L2_FLASH_FAULT_OVER_VOLTAGE           0x00000001
> #define V4L2_FLASH_FAULT_TIMEOUT                0x00000002
> #define V4L2_FLASH_FAULT_OVER_TEMPERATURE       0x00000004
> #define V4L2_FLASH_FAULT_SHORT_CIRCUIT          0x00000008

Sorry for bringing this a bit late.  As we already talked directly,
IMO (1 << 0), (1 << 1), ... could have a better readability to expose
how you want to define an expand these macros.

Br,

David Cohen

Re: [RFC] V4L2 API for flash devices

[Sakari Ailus]

Laurent Pinchart wrote:
> Hi Sakari,

Hi,

> On Tuesday 05 April 2011 13:21:03 Sakari Ailus wrote:
>> Laurent Pinchart wrote:
>>> On Tuesday 05 April 2011 12:23:51 Sakari Ailus wrote:
>>>> Sakari Ailus wrote:
>>>>> Laurent Pinchart wrote:
>>>>>> On Wednesday 30 March 2011 13:05:54 Sakari Ailus wrote:
>>>>>>> Laurent Pinchart wrote:
>>>>>>>> On Monday 28 March 2011 14:55:40 Sakari Ailus wrote:
>>>>>>>>
>>>>>>>> [snip]
>>>>>>>>
>>>>>>>>> 	V4L2_CID_FLASH_STROBE_MODE (menu; LED)
>>>>>>>>>
>>>>>>>>> Use hardware or software strobe. If hardware strobe is selected,
>>>>>>>>> the flash controller is a slave in the system where the sensor
>>>>>>>>> produces the strobe signal to the flash.
>>>>>>>>>
>>>>>>>>> In this case the flash controller setup is limited to programming
>>>>>>>>> strobe timeout and power (LED flash) and the sensor controls the
>>>>>>>>> timing and length of the strobe.
>>>>>>>>>
>>>>>>>>> enum v4l2_flash_strobe_mode {
>>>>>>>>>
>>>>>>>>> 	V4L2_FLASH_STROBE_MODE_SOFTWARE,
>>>>>>>>> 	V4L2_FLASH_STROBE_MODE_EXT_STROBE,
>>>>>>>>>
>>>>>>>>> };
>>>>>>>>
>>>>>>>> [snip]
>>>>>>>>
>>>>>>>>> 	V4L2_CID_FLASH_LED_MODE (menu; LED)
>>>>>>>>>
>>>>>>>>> enum v4l2_flash_led_mode {
>>>>>>>>>
>>>>>>>>> 	V4L2_FLASH_LED_MODE_FLASH = 1,
>>>>>>>>> 	V4L2_FLASH_LED_MODE_TORCH,
>>>>>>>>>
>>>>>>>>> };
>>>>>>>>
>>>>>>>> Thinking about this some more, shouldn't we combine the two controls
>>>>>>>> ? They are basically used to configure how the flash LED is
>>>>>>>> controlled: manually (torch mode), automatically by the flash
>>>>>>>> controller (software strobe mode) or automatically by an external
>>>>>>>> component (external strobe mode).
>>>>>>>
>>>>>>> That's a good question.
>>>>>>>
>>>>>>> The adp1653 supports also additional control (not implemented in the
>>>>>>> driver, though) that affect hardware strobe length. Based on register
>>>>>>> setting, the led will be on after strobe either until the timeout
>>>>>>> expires, or until the strobe signal is high.
>>>>>>>
>>>>>>> Should this be also part of the same control, or a different one?
>>>>>>
>>>>>> That can be controlled by a duration control. If the duration is 0,
>>>>>> the flash is lit for the duration of the external strobe, otherwise
>>>>>> it's lit for the programmed duration.
>>>>>
>>>>> Sounds good to me.
>>>>
>>>> Thinking about this again; there won't be a separate duration control
>>>
>>> Why not ? I think we need two timeouts, a watchdog timeout to prevent
>>> flash fire or meltdown, and a normal timeout to lit the flash for a
>>> user-selected duration.
>>
>> Let's assume that an application wants to expose a frame using flash
>> with software strobe.
>>
>> 1. strobe flash
>> 2. qbuf
>> 3. streamon
>> 4. dqbuf
>> 5. streamoff
>> 6. ...
>>
>> How does an application know how long is the time between 1 -- 4? I'd
>> guess that in 6 the application would like to switch off the flash
>> instead of specifying a timeout for it.
> 
> That's a valid use case, and we need to support it. It requires a way to lit 
> the flash with no timeout other than the watchdog timeout, and a way to turn 
> it off.
> 
> However, I'm not sure we should rule out the usefulness of a duration-based 
> software flash strobe. Can't the two APIs coexist ? Or do you think a 
> duration-based API is useless ?

I don't want to rule it out, but I don't see use for it either for the
time being and thus don't see a reason to specify an API for it. The
adp1653 driver does not implement a software based shutdown timeout and
I'm not aware of others implementing it either. It was just an idea to
overcome the coarse hardware watchdog timeout.

If there is use for it then I think we could bring up the question
again: use V4L2_CID_FLASH_TIMEOUT or create V4L2_CID_FLASH_DURATION for it.

What do you think?

-- 
Sakari Ailus
sakari.ailus@maxwell.research.nokia.com

Re: [RFC] V4L2 API for flash devices

[Laurent Pinchart]

Hi Nayden,

On Tuesday 05 April 2011 17:07:41 Nayden Kanchev wrote:
> On 04/05/2011 04:35 PM, Sakari Ailus wrote:
> > Laurent Pinchart wrote:
> >> On Tuesday 05 April 2011 13:21:03 Sakari Ailus wrote:
> >>> Laurent Pinchart wrote:
> >>>> On Tuesday 05 April 2011 12:23:51 Sakari Ailus wrote:
> >>>>> Sakari Ailus wrote:
> >>>>>> Laurent Pinchart wrote:
> >>>>>>> On Wednesday 30 March 2011 13:05:54 Sakari Ailus wrote:
> >>>>>>>> Laurent Pinchart wrote:
> >>>>>>>>> On Monday 28 March 2011 14:55:40 Sakari Ailus wrote:
> >>>>>>>>> 
> >>>>>>>>> [snip]
> >>>>>>>>> 
> >>>>>>>>>> 	V4L2_CID_FLASH_STROBE_MODE (menu; LED)
> >>>>>>>>>> 
> >>>>>>>>>> Use hardware or software strobe. If hardware strobe is selected,
> >>>>>>>>>> the flash controller is a slave in the system where the sensor
> >>>>>>>>>> produces the strobe signal to the flash.
> >>>>>>>>>> 
> >>>>>>>>>> In this case the flash controller setup is limited to
> >>>>>>>>>> programming strobe timeout and power (LED flash) and the sensor
> >>>>>>>>>> controls the timing and length of the strobe.
> >>>>>>>>>> 
> >>>>>>>>>> enum v4l2_flash_strobe_mode {
> >>>>>>>>>> 
> >>>>>>>>>> 	V4L2_FLASH_STROBE_MODE_SOFTWARE,
> >>>>>>>>>> 	V4L2_FLASH_STROBE_MODE_EXT_STROBE,
> >>>>>>>>>> 
> >>>>>>>>>> };
> >>>>>>>>> 
> >>>>>>>>> [snip]
> >>>>>>>>> 
> >>>>>>>>>> 	V4L2_CID_FLASH_LED_MODE (menu; LED)
> >>>>>>>>>> 
> >>>>>>>>>> enum v4l2_flash_led_mode {
> >>>>>>>>>> 
> >>>>>>>>>> 	V4L2_FLASH_LED_MODE_FLASH = 1,
> >>>>>>>>>> 	V4L2_FLASH_LED_MODE_TORCH,
> >>>>>>>>>> 
> >>>>>>>>>> };
> >>>>>>>>> 
> >>>>>>>>> Thinking about this some more, shouldn't we combine the two
> >>>>>>>>> controls ? They are basically used to configure how the flash
> >>>>>>>>> LED is controlled: manually (torch mode), automatically by the
> >>>>>>>>> flash controller (software strobe mode) or automatically by an
> >>>>>>>>> external component (external strobe mode).
> >>>>>>>> 
> >>>>>>>> That's a good question.
> >>>>>>>> 
> >>>>>>>> The adp1653 supports also additional control (not implemented in
> >>>>>>>> the driver, though) that affect hardware strobe length. Based on
> >>>>>>>> register setting, the led will be on after strobe either until
> >>>>>>>> the timeout expires, or until the strobe signal is high.
> >>>>>>>> 
> >>>>>>>> Should this be also part of the same control, or a different one?
> >>>>>>> 
> >>>>>>> That can be controlled by a duration control. If the duration is 0,
> >>>>>>> the flash is lit for the duration of the external strobe, otherwise
> >>>>>>> it's lit for the programmed duration.
> >>>>>> 
> >>>>>> Sounds good to me.
> >>>>> 
> >>>>> Thinking about this again; there won't be a separate duration control
> >>>> 
> >>>> Why not ? I think we need two timeouts, a watchdog timeout to prevent
> >>>> flash fire or meltdown, and a normal timeout to lit the flash for a
> >>>> user-selected duration.
> >>> 
> >>> Let's assume that an application wants to expose a frame using flash
> >>> with software strobe.
> >>> 
> >>> 1. strobe flash
> >>> 2. qbuf
> >>> 3. streamon
> >>> 4. dqbuf
> >>> 5. streamoff
> >>> 6. ...
> >>> 
> >>> How does an application know how long is the time between 1 -- 4? I'd
> >>> guess that in 6 the application would like to switch off the flash
> >>> instead of specifying a timeout for it.
> >> 
> >> That's a valid use case, and we need to support it. It requires a way to
> >> lit the flash with no timeout other than the watchdog timeout, and a
> >> way to turn it off.
> >> 
> >> However, I'm not sure we should rule out the usefulness of a
> >> duration-based software flash strobe. Can't the two APIs coexist ? Or
> >> do you think a duration-based API is useless ?
> > 
> > I don't want to rule it out, but I don't see use for it either for the
> > time being and thus don't see a reason to specify an API for it. The
> > adp1653 driver does not implement a software based shutdown timeout and
> > I'm not aware of others implementing it either. It was just an idea to
> > overcome the coarse hardware watchdog timeout.
> > 
> > If there is use for it then I think we could bring up the question
> > again: use V4L2_CID_FLASH_TIMEOUT or create V4L2_CID_FLASH_DURATION for
> > it.
> > 
> > What do you think?
> 
> According to me it is a matter of choice whether flash will be started
> and stopped explicitly or timer will be used.
> 
> My personal opinion is that both APIs could coexist although I wouldn't
> use timebased approach. The problem is that timeout should be always a
> little bit higher than actual required time (Sensor frame rate + sensor
> exposure time) because some delays are expected from starting the flash
> till starting the camera. Those delay could vary depending on the
> implementation and could be several ms. In that case flash will stop
> before sensor is ready. So as result half bright half dark images will
> be captured.
> 
> On the other hand if timer is used for stopping it that would optimize
> the flash usage and lower flash duty cycle. That on the other hand will
> lead to smaller cooldown time required between two consecutive captures.
> 
> So I would go with the explicit control over the flash, since timebased
> approach has several variable in the calculations.

OK, I surrender :-)

I'm then fine with an explicit on/off API for software strobe. If we need a 
duration-based API later we will just introduce a new control.

-- 
Regards,

Laurent Pinchart

Re: [RFC] V4L2 API for flash devices

[Sakari Ailus]

David Cohen wrote:
> On Mon, Mar 28, 2011 at 3:55 PM, Sakari Ailus
> <sakari.ailus@maxwell.research.nokia.com> wrote:
>> Hi,
> 
> Hi Sakari,

Thanks for the comments, David!

> [snip]
> 
>> This is a bitmask containing the fault information for the flash. This
>> assumes the proposed V4L2 bit mask controls [5]; otherwise this would
>> likely need to be a set of controls.
>>
>> #define V4L2_FLASH_FAULT_OVER_VOLTAGE           0x00000001
>> #define V4L2_FLASH_FAULT_TIMEOUT                0x00000002
>> #define V4L2_FLASH_FAULT_OVER_TEMPERATURE       0x00000004
>> #define V4L2_FLASH_FAULT_SHORT_CIRCUIT          0x00000008
> 
> Sorry for bringing this a bit late.  As we already talked directly,
> IMO (1 << 0), (1 << 1), ... could have a better readability to expose
> how you want to define an expand these macros.

I'll change this to the next version of the RFC.

Regards,

-- 
Sakari Ailus
sakari.ailus@maxwell.research.nokia.com

Re: [RFC] V4L2 API for flash devices

[Sung Hee Park]

Here are two more use-cases for flash that might help inform the API
design. Sakari encouraged me to post these. The person writing this is
Andrew Adams, but I'm sending this from Sung Hee's account, because I
only just subscribed to linux-media and can't immediately figure out
how to reply to messages from before I subscribed. Sung Hee and I are
both grad students at Stanford who work on FCam
(http://fcam.garage.maemo.org/)

Second-curtain-sync:

Sometimes you want to fire the flash at the end of a long exposure
time. It's usually a way to depict motion. Here's an example:
http://www.flickr.com/photos/latitudes/133206615/.

This only really applies to xenon flashes because you can't get a
crisp image out of a longer duration LED flash. Even then it's
somewhat problematic on rolling-shutter sensors but still possible
provided you don't mind a slight shear to the crisp part of the image.
>From an API perspective, it requires you to be able to specify a
trigger time at some number of microseconds into the exposure. On the
N900 we did this with a real-time thread.

Triggering external hardware:

This use-case is a little weirder, but it has the same API
requirement. Some photographic setups require you to synchronize some
piece of hardware with the exposure (e.g. an oscilloscope, or an
external slave flash). On embedded devices this is generally
difficult. If you can at least fire the flash at a precise delay into
the exposure, you can attach a photodiode to it, and use the
flash+photodiode as an opto-isolator to trigger your external
hardware.

So we're in favor of having user-settable flash duration, and also
user-settable trigger times (with reference to the start of the
exposure time). I'm guessing that in a SMIA++ driver the trigger time
would actually be a control on the sensor device, but it seemed
relevant to bring up while you guys were talking about the flash API.

- Andrew

On Mon, Mar 28, 2011 at 5:55 AM, Sakari Ailus
<sakari.ailus@maxwell.research.nokia.com> wrote:
>
> Hi,
>
> This is a proposal for an interface for controlling flash devices on the
> V4L2/v4l2_subdev APIs. My plan is to use the interface in the ADP1653
> driver, the flash controller used in the Nokia N900.
>
> Comments and questions are very, very welcome!
>
>
> Scope
> =====
>
> This RFC is focused mostly on the ADP1653 [1] and similar chips [2, 3]
> which provides following functionality. [2, 3] mostly differ on the
> available faults --- for example, there are faults also for the
> indicator LED.
>
> - High power LED output (flash or torch modes)
> - Low power indicator LED output (a.k.a. privacy light)
> - Programmable flash timeout
> - Software and hardware strobe
> - Fault detection
>        - Overvoltage
>        - Overtemperature
>        - Short circuit
>        - Timeout
> - Programmable current (both high-power and indicator LEDs)
>
> If anyone else is aware of hardware which significantly differs from
> these and does not get served well under the proposed interface, please
> tell about it.
>
> This RFC does NOT address the synchronisation of the flash to a given
> frame since this task is typically performed by the sensor through a
> strobe signal. The host does not have enough information for this ---
> exact timing information on the exposure of the sensor pixel array. In
> this case the flash synchronisation is visible to the flash controller
> as the hardware strobe originating from the sensor.
>
> Flash synchronisation requires
>
> 1) flash control capability from the sensor including a strobe output,
> 2) strobe input in the flash controller,
> 3) (optionally) ability to program sensor parameters at given frame,
> such as flash strobe, and
> 4) ability to read back metadata produced by the sensor related to a
> given frame. This should include whether the frame is exposed with
> flash, i.e. the sensor's flash strobe output.
>
> Since we have little examples of both in terms of hardware support,
> which is in practice required, it was decided to postpone the interface
> specification for now. [6]
>
> Xenon flash controllers exist but I don't have a specific example of
> those. Typically the interface is quite simple. Gpio pins for charge and
> strobe. The length of the strobe signal determines the strength of the
> flash pulse. The strobe is controlled by the sensor as for LED flash if
> it is hardware based.
>
>
> Known use cases
> ===============
>
> The use case listed below concentrate on using a flash in a mobile
> device, for example in a mobile phone. The use cases could be somewhat
> different in devices the primary use of which is camera.
>
> Unsynchronised LED flash (software strobe)
> ------------------------------------------
>
> 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.
>
> Example of such device: Nokia N900.
>
>
> Synchronised LED flash (hardware strobe)
> ----------------------------------------
>
> 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.
>
> The sensor controls the flash duration and timing. This control
> typically must be programmed to the sensor, and specifying an interface
> for this is out of scope of this RFC.
>
> The LED flash controllers we know of can function in both synchronised
> and unsynchronised modes.
>
>
> LED flash as torch
> ------------------
>
> LED flash may be used as torch in conjunction with another use case
> involving camera or individually. [4]
>
>
> Synchronised xenon flash
> ------------------------
>
> The synchronised xenon flash is controlled more closely by the sensor
> than the LED flash. There is no separate intensity control for the xenon
> flash as its intensity is determined by the length of the strobe pulse.
> Several consecutive strobe pluses are possible but this needs to be
> still controlled by the sensor.
>
>
> Proposed interface
> ==================
>
> The flash, either LED or xenon, does not require large amounts of data
> to control it. There are parameters to control it but they are
> independent and assumably some hardware would only support some subsets
> of the functionality available somewhere else. Thus V4L2 controls seem
> an ideal way to support flash controllers.
>
> A separate control class is reserved for the flash controls. It is
> called V4L2_CTRL_CLASS_FLASH.
>
> Type of the control; type of flash is in parentheses after the control.
>
>
>        V4L2_CID_FLASH_STROBE (button; LED)
>
> Strobe the flash using software strobe from the host, typically over I2C
> or a GPIO. The flash is NOT synchronised to sensor pixel are exposure
> since the command is given asynchronously. Alternatively, if the flash
> controller is a master in the system, the sensor exposure may be
> triggered based on software strobe.
>
>
>        V4L2_CID_FLASH_STROBE_MODE (menu; LED)
>
> Use hardware or software strobe. If hardware strobe is selected, the
> flash controller is a slave in the system where the sensor produces the
> strobe signal to the flash.
>
> In this case the flash controller setup is limited to programming strobe
> timeout and power (LED flash) and the sensor controls the timing and
> length of the strobe.
>
> enum v4l2_flash_strobe_mode {
>        V4L2_FLASH_STROBE_MODE_SOFTWARE,
>        V4L2_FLASH_STROBE_MODE_EXT_STROBE,
> };
>
>
>        V4L2_CID_FLASH_TIMEOUT (integer; LED)
>
> The flash controller provides timeout functionality to shut down the led
> in case the host fails to do that. For hardware strobe, this is the
> maximum amount of time the flash should stay on, and the purpose of the
> setting is to prevent the LED from catching fire.
>
> For software strobe, the setting may be used to limit the length of the
> strobe in case a driver does not implement it itself. The granularity of
> the timeout in [1, 2, 3] is very coarse. However, the length of a
> driver-implemented LED strobe shutoff is very dependent on host.
> Possibly V4L2_CID_FLASH_DURATION should be added, and
> V4L2_CID_FLASH_TIMEOUT would be read-only so that the user would be able
> to obtain the actual hardware implemented safety timeout.
>
> Likely a standard unit such as ms or 盜 should be used.
>
>
>        V4L2_CID_FLASH_LED_MODE (menu; LED)
>
> enum v4l2_flash_led_mode {
>        V4L2_FLASH_LED_MODE_FLASH = 1,
>        V4L2_FLASH_LED_MODE_TORCH,
> };
>
>
>        V4L2_CID_FLASH_INTENSITY (integer; LED)
>
> Intensity of the flash in hardware specific units. The LED flash
> controller provides current to the LED but the actual luminous power is
> dictated by the LED connected to the controller.
>
>
>        V4L2_CID_FLASH_TORCH_INTENSITY (integer; LED)
>
> Intensity of the flash in hardware specific units.
>
>
>        V4L2_CID_FLASH_INDICATOR_INTENSITY (integer; LED)
>
> Intensity of the indicator light in hardware specific units.
>
>
>        V4L2_CID_FLASH_FAULT (bit field; LED)
>
> This is a bitmask containing the fault information for the flash. This
> assumes the proposed V4L2 bit mask controls [5]; otherwise this would
> likely need to be a set of controls.
>
> #define V4L2_FLASH_FAULT_OVER_VOLTAGE           0x00000001
> #define V4L2_FLASH_FAULT_TIMEOUT                0x00000002
> #define V4L2_FLASH_FAULT_OVER_TEMPERATURE       0x00000004
> #define V4L2_FLASH_FAULT_SHORT_CIRCUIT          0x00000008
>
> Several faults may occur at single occasion. The ADP1653 is able to
> inform the user a fault has occurred, so a V4L2 control event (proposed
> earlier) could be used for that.
>
> These faults are supported by the ADP1653. More faults may be added as
> support for more chips require that. In some other hardware faults are
> available for indicator led as well.
>
> Question: should indicator faults be part of the same control, or a
> different control, e.g. V4L2_CID_FLASH_INDICATOR_FAULT?
>
>
>        V4L2_CID_FLASH_CHARGE (bool; xenon)
>
> Charge control for the xenon flash. Enable or disable charging.
>
>
>        V4L2_CID_FLASH_READY (bool; xenon, LED)
>
> Flash is ready to strobe. On xenon flash this tells the capacitor has
> been charged, on LED flash it's that the LED is no longer too hot.
>
> The implementation on LED flash may be modelling the temperature
> behaviour of the LED in the driver (or elsewhere, e.g. library or board
> code) if the hardware does not provide direct temperature information
> from the LED.
>
> A V4L2 control event should be produced whenever the flash becomes ready.
>
>
> References
> ==========
>
> [1] http://www.analog.com/static/imported-files/data_sheets/ADP1653.pdf
>
> [2] http://www.national.com/mpf/LM/LM3555.html#Overview
>
> [3]
> http://www.austriamicrosystems.com/eng/Products/Lighting-Management/Camera-Flash-LED-Drivers/AS3645
>
> [4] http://maemo.org/downloads/product/Maemo5/flashlight-applet/
>
> [5]
> http://www.retiisi.org.uk/v4l2/v4l2-brainstorming-warsaw-2011-03/notes/day%202%20(SGz6LU2esk).html
>
> [6]
> http://www.retiisi.org.uk/v4l2/v4l2-brainstorming-warsaw-2011-03/notes/day%203%20(RhoYa0X9D7).html
>
>
> Cheers,
>
> --
> Sakari Ailus
> sakari.ailus@maxwell.research.nokia.com
> --
> To unsubscribe from this list: send the line "unsubscribe linux-media" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC] V4L2 API for flash devices

[Sakari Ailus]

Sung Hee Park wrote:
> Here are two more use-cases for flash that might help inform the API design.
> Sakari encouraged me to post these. The person writing this is Andrew Adams,
> but I'm sending this from Sung Hee's account, because I only just subscribed
> to linux-media and can't immediately figure out how to reply to messages
> from before I subscribed. Sung Hee and I are both grad students at Stanford
> who work on FCam (http://fcam.garage.maemo.org/)

Hi Andrew,

Many thanks for the comments.

> Second-curtain-sync:
> 
> Sometimes you want to fire the flash at the end of a long exposure time.
> It's usually a way to depict motion. Here's an example:
> http://www.flickr.com/photos/latitudes/133206615/.
> 
> This only really applies to xenon flashes because you can't get a crisp
> image out of a longer duration LED flash. Even then it's somewhat
> problematic on rolling-shutter sensors but still possible provided you don't
> mind a slight shear to the crisp part of the image. From an API perspective,
> it requires you to be able to specify a trigger time at some number of
> microseconds into the exposure. On the N900 we did this with a real-time
> thread.
>
> Triggering external hardware:
> 
> This use-case is a little weirder, but it has the same API requirement. Some
> photographic setups require you to synchronize some piece of hardware with
> the exposure (e.g. an oscilloscope, or an external slave flash). On embedded
> devices this is generally difficult. If you can at least fire the flash at a
> precise delay into the exposure, you can attach a photodiode to it, and use
> the flash+photodiode as an opto-isolator to trigger your external hardware.
> 
> So we're in favor of having user-settable flash duration, and also
> user-settable trigger times (with reference to the start of the exposure
> time). I'm guessing that in a SMIA++ driver the trigger time would actually
> be a control on the sensor device, but it seemed relevant to bring up while
> you guys were talking about the flash API.

>From this I reckon that in a general case the handling of the flash
timing cannot be left for the drivers only. There must be a way to
control it.

So I'd think that also the level/edge trigger for the flash should be
visible. On edge trigger, the only limiting factor for the flash
duration on hardware would be the relatively coarse watchdog timer, and
I'd think the user should be able to know that.

The flash timing controls should be exposed by the sensor driver since
the sensor is what actually performs the timing.

Laurent; what do you think?

Cheers,

-- 
Sakari Ailus
sakari.ailus@maxwell.research.nokia.com

Re: [RFC] V4L2 API for flash devices

[Laurent Pinchart]

Hi Sakari,

On Wednesday 13 April 2011 14:16:38 Sakari Ailus wrote:
> Sung Hee Park wrote:
> > Here are two more use-cases for flash that might help inform the API
> > design. Sakari encouraged me to post these. The person writing this is
> > Andrew Adams, but I'm sending this from Sung Hee's account, because I
> > only just subscribed to linux-media and can't immediately figure out how
> > to reply to messages from before I subscribed. Sung Hee and I are both
> > grad students at Stanford who work on FCam
> > (http://fcam.garage.maemo.org/)
> 
> Hi Andrew,
> 
> Many thanks for the comments.
> 
> > Second-curtain-sync:
> > 
> > Sometimes you want to fire the flash at the end of a long exposure time.
> > It's usually a way to depict motion. Here's an example:
> > http://www.flickr.com/photos/latitudes/133206615/.
> > 
> > This only really applies to xenon flashes because you can't get a crisp
> > image out of a longer duration LED flash. Even then it's somewhat
> > problematic on rolling-shutter sensors but still possible provided you
> > don't mind a slight shear to the crisp part of the image. From an API
> > perspective, it requires you to be able to specify a trigger time at
> > some number of microseconds into the exposure. On the N900 we did this
> > with a real-time thread.
> > 
> > Triggering external hardware:
> > 
> > This use-case is a little weirder, but it has the same API requirement.
> > Some photographic setups require you to synchronize some piece of
> > hardware with the exposure (e.g. an oscilloscope, or an external slave
> > flash). On embedded devices this is generally difficult. If you can at
> > least fire the flash at a precise delay into the exposure, you can
> > attach a photodiode to it, and use the flash+photodiode as an
> > opto-isolator to trigger your external hardware.
> > 
> > So we're in favor of having user-settable flash duration, and also
> > user-settable trigger times (with reference to the start of the exposure
> > time). I'm guessing that in a SMIA++ driver the trigger time would
> > actually be a control on the sensor device, but it seemed relevant to
> > bring up while you guys were talking about the flash API.
> 
> From this I reckon that in a general case the handling of the flash
> timing cannot be left for the drivers only. There must be a way to
> control it.
> 
> So I'd think that also the level/edge trigger for the flash should be
> visible. On edge trigger, the only limiting factor for the flash
> duration on hardware would be the relatively coarse watchdog timer, and
> I'd think the user should be able to know that.

I agree that the user should be able to query the limit. The limit value 
should come from platform data.

> The flash timing controls should be exposed by the sensor driver since
> the sensor is what actually performs the timing.
> 
> Laurent; what do you think?

As already discussed with you offline, I think we will need flash timing 
controls on the sensor when the flash controller is configured with external 
strobe in level triggered mode. I'm still not sure if the edge/level-triggered 
names are the best option. They confused me in the beginning, so I find them 
confusing :-) If we keep them, they will need to be very precisely documented.

-- 
Regards,

Laurent Pinchart

Re: [RFC] V4L2 API for flash devices

[Sakari Ailus]

Laurent Pinchart wrote:
> Hi Sakari,

Heippa,

> On Wednesday 13 April 2011 14:16:38 Sakari Ailus wrote:
>> Sung Hee Park wrote:
>>> Here are two more use-cases for flash that might help inform the API
>>> design. Sakari encouraged me to post these. The person writing this is
>>> Andrew Adams, but I'm sending this from Sung Hee's account, because I
>>> only just subscribed to linux-media and can't immediately figure out how
>>> to reply to messages from before I subscribed. Sung Hee and I are both
>>> grad students at Stanford who work on FCam
>>> (http://fcam.garage.maemo.org/)
>>
>> Hi Andrew,
>>
>> Many thanks for the comments.
>>
>>> Second-curtain-sync:
>>>
>>> Sometimes you want to fire the flash at the end of a long exposure time.
>>> It's usually a way to depict motion. Here's an example:
>>> http://www.flickr.com/photos/latitudes/133206615/.
>>>
>>> This only really applies to xenon flashes because you can't get a crisp
>>> image out of a longer duration LED flash. Even then it's somewhat
>>> problematic on rolling-shutter sensors but still possible provided you
>>> don't mind a slight shear to the crisp part of the image. From an API
>>> perspective, it requires you to be able to specify a trigger time at
>>> some number of microseconds into the exposure. On the N900 we did this
>>> with a real-time thread.
>>>
>>> Triggering external hardware:
>>>
>>> This use-case is a little weirder, but it has the same API requirement.
>>> Some photographic setups require you to synchronize some piece of
>>> hardware with the exposure (e.g. an oscilloscope, or an external slave
>>> flash). On embedded devices this is generally difficult. If you can at
>>> least fire the flash at a precise delay into the exposure, you can
>>> attach a photodiode to it, and use the flash+photodiode as an
>>> opto-isolator to trigger your external hardware.
>>>
>>> So we're in favor of having user-settable flash duration, and also
>>> user-settable trigger times (with reference to the start of the exposure
>>> time). I'm guessing that in a SMIA++ driver the trigger time would
>>> actually be a control on the sensor device, but it seemed relevant to
>>> bring up while you guys were talking about the flash API.
>>
>> From this I reckon that in a general case the handling of the flash
>> timing cannot be left for the drivers only. There must be a way to
>> control it.
>>
>> So I'd think that also the level/edge trigger for the flash should be
>> visible. On edge trigger, the only limiting factor for the flash
>> duration on hardware would be the relatively coarse watchdog timer, and
>> I'd think the user should be able to know that.
> 
> I agree that the user should be able to query the limit. The limit value 
> should come from platform data.

Agreed.

>> The flash timing controls should be exposed by the sensor driver since
>> the sensor is what actually performs the timing.
>>
>> Laurent; what do you think?
> 
> As already discussed with you offline, I think we will need flash timing 
> controls on the sensor when the flash controller is configured with external 
> strobe in level triggered mode. I'm still not sure if the edge/level-triggered 
> names are the best option. They confused me in the beginning, so I find them 
> confusing :-) If we keep them, they will need to be very precisely documented.

I'm fine with other naming --- edge/level is from the AS3645
documentation. ADP1653 does not call it with a name as far as I
remember. Other similar chips can be found here:

<URL:http://www.austriamicrosystems.com/eng/Products/Lighting-Management/>

I tried to download the datasheets but couldn't. The AS3645 datasheet,
however, is also available here:

<URL:http://www.cdiweb.com/datasheets/austriamicro/AS3645_Datasheet_v1-6.pdf>

Regards,

-- 
Sakari Ailus
sakari.ailus@maxwell.research.nokia.com

Re: [RFC] V4L2 API for flash devices

[Sakari Ailus]

Sakari Ailus wrote:
> Laurent Pinchart wrote:
>> Hi Sakari,
> 
> Hi Laurent,

Hi Hans and Laurent,

>> On Tuesday 29 March 2011 13:51:38 Sakari Ailus wrote:
>>> Sakari Ailus wrote:
>>>> Hans Verkuil wrote:
>>>>> On Tuesday, March 29, 2011 11:35:19 Sakari Ailus wrote:
>>>>>> Hi Hans,
>>>>>>
>>>>>> Many thanks for the comments!
>>>>
>>>> ...
>>>>
>>>>>> It occurred to me that an application might want to turn off a flash
>>>>>> which has been strobed on software. That can't be done on a single
>>>>>> button control.
>>>>>>
>>>>>> V4L2_CID_FLASH_SHUTDOWN?
>>>>>>
>>>>>> The application would know the flash strobe is ongoing before it
>>>>>> receives a timeout fault. I somehow feel that there should be a control
>>>>>> telling that directly.
>>>>>>
>>>>>> What about using a bool control for the strobe?
>>>>>
>>>>> It depends: is the strobe signal just a pulse that kicks off the flash,
>>>>> or is it active throughout the flash duration? In the latter case a
>>>>> bool makes sense, in the first case an extra button control makes
>>>>> sense.
>>>>
>>>> I like buttons since I associate them with action (like strobing) but on
>>>> the other hand buttons don't allow querying the current state. On the
>>>> other hand, the current state isn't always determinable, e.g. in the
>>>> absence of the interrupt line from the flash controller interrupt pin
>>>> (e.g. N900!).
>>>
>>> Oh, I need to take my words back a bit.
>>>
>>> There indeed is a way to get the on/off status for the flash, but that
>>> involves I2C register access --- when you read the fault registers, you
>>> do get the state, even if the interrupt linke is missing from the
>>> device. At least I can't see why this wouldn't work, at least on this
>>> particular chip.
>>>
>>> What you can't have in this case is the event.
>>>
>>> So, in my opinion this suggests that a single boolean control is the way
>>> to go.
>>
>> Why would an application want to turn off a flash that has been strobbed in 
>> software ? Applications should set the flash duration and then strobe it.
> 
> The applications won't know beforehand the exact timing of the exposure
> of the frames on the sensor and the latencies of the operating system
> possibly affected by other processes running on the system. Thus it's
> impossible to know exactly how long flash strobe (on software, that is!)
> is required.
> 
> So, as far as I see there should be a way to turn the flash off and the
> timeout would mostly function as a safeguard. This is likely dependent
> on the flash controller as well.

Today I was working on the ADP1653 driver and realised that this chip
doesn't actually provide a way to stop the strobe by the user at all.
There's just the timeout. The user may not turn off the strobe, as it
first seemed to me in the spec. If I look at the AS3654A spec, it's
almost equally vague on this topic.

This means that there are chips that do not allow explicitly stopping
the strobe and probably those that do (I assume that hardware people
will learn some day that a hard timeout isn't the best you can provide
to software!).

There was a discussion on the type of the V4L2_CID_FLASH_STROBE control;
whether that should be a button or boolean control. Buttons cannot be
unpressed, so a button control would work for adp1653 but possibly not
for other similar chips in the future.

Even if we have a standard control, can the type of the control change,
depending on the properties of the hardware? This would also allow
providing to user the knowledge on whether the flash may be explicitly
turned off. On the other hand, I don't like the idea of having a
standard control with several possible types (there are none at the
moment, AFAIK). I would side with keeping the type of the control
boolean all the time but I'm not fully certain.

Hans, do you have an opinion on this?

-- 
Sakari Ailus
sakari.ailus@maxwell.research.nokia.com

Re: [RFC] V4L2 API for flash devices

[Hans Verkuil]

On Monday, May 02, 2011 18:04:18 Sakari Ailus wrote:
> Sakari Ailus wrote:
> > Laurent Pinchart wrote:
> >> Hi Sakari,
> > 
> > Hi Laurent,
> 
> Hi Hans and Laurent,
> 
> >> On Tuesday 29 March 2011 13:51:38 Sakari Ailus wrote:
> >>> Sakari Ailus wrote:
> >>>> Hans Verkuil wrote:
> >>>>> On Tuesday, March 29, 2011 11:35:19 Sakari Ailus wrote:
> >>>>>> Hi Hans,
> >>>>>>
> >>>>>> Many thanks for the comments!
> >>>>
> >>>> ...
> >>>>
> >>>>>> It occurred to me that an application might want to turn off a flash
> >>>>>> which has been strobed on software. That can't be done on a single
> >>>>>> button control.
> >>>>>>
> >>>>>> V4L2_CID_FLASH_SHUTDOWN?
> >>>>>>
> >>>>>> The application would know the flash strobe is ongoing before it
> >>>>>> receives a timeout fault. I somehow feel that there should be a control
> >>>>>> telling that directly.
> >>>>>>
> >>>>>> What about using a bool control for the strobe?
> >>>>>
> >>>>> It depends: is the strobe signal just a pulse that kicks off the flash,
> >>>>> or is it active throughout the flash duration? In the latter case a
> >>>>> bool makes sense, in the first case an extra button control makes
> >>>>> sense.
> >>>>
> >>>> I like buttons since I associate them with action (like strobing) but on
> >>>> the other hand buttons don't allow querying the current state. On the
> >>>> other hand, the current state isn't always determinable, e.g. in the
> >>>> absence of the interrupt line from the flash controller interrupt pin
> >>>> (e.g. N900!).
> >>>
> >>> Oh, I need to take my words back a bit.
> >>>
> >>> There indeed is a way to get the on/off status for the flash, but that
> >>> involves I2C register access --- when you read the fault registers, you
> >>> do get the state, even if the interrupt linke is missing from the
> >>> device. At least I can't see why this wouldn't work, at least on this
> >>> particular chip.
> >>>
> >>> What you can't have in this case is the event.
> >>>
> >>> So, in my opinion this suggests that a single boolean control is the way
> >>> to go.
> >>
> >> Why would an application want to turn off a flash that has been strobbed in 
> >> software ? Applications should set the flash duration and then strobe it.
> > 
> > The applications won't know beforehand the exact timing of the exposure
> > of the frames on the sensor and the latencies of the operating system
> > possibly affected by other processes running on the system. Thus it's
> > impossible to know exactly how long flash strobe (on software, that is!)
> > is required.
> > 
> > So, as far as I see there should be a way to turn the flash off and the
> > timeout would mostly function as a safeguard. This is likely dependent
> > on the flash controller as well.
> 
> Today I was working on the ADP1653 driver and realised that this chip
> doesn't actually provide a way to stop the strobe by the user at all.
> There's just the timeout. The user may not turn off the strobe, as it
> first seemed to me in the spec. If I look at the AS3654A spec, it's
> almost equally vague on this topic.
> 
> This means that there are chips that do not allow explicitly stopping
> the strobe and probably those that do (I assume that hardware people
> will learn some day that a hard timeout isn't the best you can provide
> to software!).
> 
> There was a discussion on the type of the V4L2_CID_FLASH_STROBE control;
> whether that should be a button or boolean control. Buttons cannot be
> unpressed, so a button control would work for adp1653 but possibly not
> for other similar chips in the future.
> 
> Even if we have a standard control, can the type of the control change,
> depending on the properties of the hardware? This would also allow
> providing to user the knowledge on whether the flash may be explicitly
> turned off. On the other hand, I don't like the idea of having a
> standard control with several possible types (there are none at the
> moment, AFAIK). I would side with keeping the type of the control
> boolean all the time but I'm not fully certain.
> 
> Hans, do you have an opinion on this?

Theoretically the type may change depending on the hardware, but I don't
think that is something we should support. In particularly, that will make
it very hard to programmatically use such controls. There are all sorts of
subtle problems you run into when you allow for different types for the same
standard control.

Regards,

	Hans

Re: [RFC] V4L2 API for flash devices

[Laurent Pinchart]

Hi Hans,

On Monday 02 May 2011 21:13:56 Hans Verkuil wrote:
> On Monday, May 02, 2011 18:04:18 Sakari Ailus wrote:
> > Sakari Ailus wrote:
> > > Laurent Pinchart wrote:
> > >> On Tuesday 29 March 2011 13:51:38 Sakari Ailus wrote:
> > >>> Sakari Ailus wrote:
> > >>>> Hans Verkuil wrote:
> > >>>>> On Tuesday, March 29, 2011 11:35:19 Sakari Ailus wrote:
> > >>>>>> Hi Hans,
> > >>>>>> 
> > >>>>>> Many thanks for the comments!
> > >>>> 
> > >>>> ...
> > >>>> 
> > >>>>>> It occurred to me that an application might want to turn off a
> > >>>>>> flash which has been strobed on software. That can't be done on a
> > >>>>>> single button control.
> > >>>>>> 
> > >>>>>> V4L2_CID_FLASH_SHUTDOWN?
> > >>>>>> 
> > >>>>>> The application would know the flash strobe is ongoing before it
> > >>>>>> receives a timeout fault. I somehow feel that there should be a
> > >>>>>> control telling that directly.
> > >>>>>> 
> > >>>>>> What about using a bool control for the strobe?
> > >>>>> 
> > >>>>> It depends: is the strobe signal just a pulse that kicks off the
> > >>>>> flash, or is it active throughout the flash duration? In the
> > >>>>> latter case a bool makes sense, in the first case an extra button
> > >>>>> control makes sense.
> > >>>> 
> > >>>> I like buttons since I associate them with action (like strobing)
> > >>>> but on the other hand buttons don't allow querying the current
> > >>>> state. On the other hand, the current state isn't always
> > >>>> determinable, e.g. in the absence of the interrupt line from the
> > >>>> flash controller interrupt pin (e.g. N900!).
> > >>> 
> > >>> Oh, I need to take my words back a bit.
> > >>> 
> > >>> There indeed is a way to get the on/off status for the flash, but
> > >>> that involves I2C register access --- when you read the fault
> > >>> registers, you do get the state, even if the interrupt linke is
> > >>> missing from the device. At least I can't see why this wouldn't
> > >>> work, at least on this particular chip.
> > >>> 
> > >>> What you can't have in this case is the event.
> > >>> 
> > >>> So, in my opinion this suggests that a single boolean control is the
> > >>> way to go.
> > >> 
> > >> Why would an application want to turn off a flash that has been
> > >> strobbed in software ? Applications should set the flash duration and
> > >> then strobe it.
> > > 
> > > The applications won't know beforehand the exact timing of the exposure
> > > of the frames on the sensor and the latencies of the operating system
> > > possibly affected by other processes running on the system. Thus it's
> > > impossible to know exactly how long flash strobe (on software, that
> > > is!) is required.
> > > 
> > > So, as far as I see there should be a way to turn the flash off and the
> > > timeout would mostly function as a safeguard. This is likely dependent
> > > on the flash controller as well.
> > 
> > Today I was working on the ADP1653 driver and realised that this chip
> > doesn't actually provide a way to stop the strobe by the user at all.
> > There's just the timeout. The user may not turn off the strobe, as it
> > first seemed to me in the spec. If I look at the AS3654A spec, it's
> > almost equally vague on this topic.
> > 
> > This means that there are chips that do not allow explicitly stopping
> > the strobe and probably those that do (I assume that hardware people
> > will learn some day that a hard timeout isn't the best you can provide
> > to software!).
> > 
> > There was a discussion on the type of the V4L2_CID_FLASH_STROBE control;
> > whether that should be a button or boolean control. Buttons cannot be
> > unpressed, so a button control would work for adp1653 but possibly not
> > for other similar chips in the future.
> > 
> > Even if we have a standard control, can the type of the control change,
> > depending on the properties of the hardware? This would also allow
> > providing to user the knowledge on whether the flash may be explicitly
> > turned off. On the other hand, I don't like the idea of having a
> > standard control with several possible types (there are none at the
> > moment, AFAIK). I would side with keeping the type of the control
> > boolean all the time but I'm not fully certain.
> > 
> > Hans, do you have an opinion on this?
> 
> Theoretically the type may change depending on the hardware, but I don't
> think that is something we should support. In particularly, that will make
> it very hard to programmatically use such controls. There are all sorts of
> subtle problems you run into when you allow for different types for the
> same standard control.

I'm still undecided. If we standardize a boolean control, how will userspace 
know that, for the adp1653, the control can be written to 1 but can't be 
written to 0 ?

-- 
Regards,

Laurent Pinchart

Re: [RFC] V4L2 API for flash devices

[Hans Verkuil]

On Monday, May 02, 2011 21:32:46 Laurent Pinchart wrote:
> Hi Hans,
> 
> On Monday 02 May 2011 21:13:56 Hans Verkuil wrote:
> > On Monday, May 02, 2011 18:04:18 Sakari Ailus wrote:
> > > Sakari Ailus wrote:
> > > > Laurent Pinchart wrote:
> > > >> On Tuesday 29 March 2011 13:51:38 Sakari Ailus wrote:
> > > >>> Sakari Ailus wrote:
> > > >>>> Hans Verkuil wrote:
> > > >>>>> On Tuesday, March 29, 2011 11:35:19 Sakari Ailus wrote:
> > > >>>>>> Hi Hans,
> > > >>>>>> 
> > > >>>>>> Many thanks for the comments!
> > > >>>> 
> > > >>>> ...
> > > >>>> 
> > > >>>>>> It occurred to me that an application might want to turn off a
> > > >>>>>> flash which has been strobed on software. That can't be done on a
> > > >>>>>> single button control.
> > > >>>>>> 
> > > >>>>>> V4L2_CID_FLASH_SHUTDOWN?
> > > >>>>>> 
> > > >>>>>> The application would know the flash strobe is ongoing before it
> > > >>>>>> receives a timeout fault. I somehow feel that there should be a
> > > >>>>>> control telling that directly.
> > > >>>>>> 
> > > >>>>>> What about using a bool control for the strobe?
> > > >>>>> 
> > > >>>>> It depends: is the strobe signal just a pulse that kicks off the
> > > >>>>> flash, or is it active throughout the flash duration? In the
> > > >>>>> latter case a bool makes sense, in the first case an extra button
> > > >>>>> control makes sense.
> > > >>>> 
> > > >>>> I like buttons since I associate them with action (like strobing)
> > > >>>> but on the other hand buttons don't allow querying the current
> > > >>>> state. On the other hand, the current state isn't always
> > > >>>> determinable, e.g. in the absence of the interrupt line from the
> > > >>>> flash controller interrupt pin (e.g. N900!).
> > > >>> 
> > > >>> Oh, I need to take my words back a bit.
> > > >>> 
> > > >>> There indeed is a way to get the on/off status for the flash, but
> > > >>> that involves I2C register access --- when you read the fault
> > > >>> registers, you do get the state, even if the interrupt linke is
> > > >>> missing from the device. At least I can't see why this wouldn't
> > > >>> work, at least on this particular chip.
> > > >>> 
> > > >>> What you can't have in this case is the event.
> > > >>> 
> > > >>> So, in my opinion this suggests that a single boolean control is the
> > > >>> way to go.
> > > >> 
> > > >> Why would an application want to turn off a flash that has been
> > > >> strobbed in software ? Applications should set the flash duration and
> > > >> then strobe it.
> > > > 
> > > > The applications won't know beforehand the exact timing of the exposure
> > > > of the frames on the sensor and the latencies of the operating system
> > > > possibly affected by other processes running on the system. Thus it's
> > > > impossible to know exactly how long flash strobe (on software, that
> > > > is!) is required.
> > > > 
> > > > So, as far as I see there should be a way to turn the flash off and the
> > > > timeout would mostly function as a safeguard. This is likely dependent
> > > > on the flash controller as well.
> > > 
> > > Today I was working on the ADP1653 driver and realised that this chip
> > > doesn't actually provide a way to stop the strobe by the user at all.
> > > There's just the timeout. The user may not turn off the strobe, as it
> > > first seemed to me in the spec. If I look at the AS3654A spec, it's
> > > almost equally vague on this topic.
> > > 
> > > This means that there are chips that do not allow explicitly stopping
> > > the strobe and probably those that do (I assume that hardware people
> > > will learn some day that a hard timeout isn't the best you can provide
> > > to software!).
> > > 
> > > There was a discussion on the type of the V4L2_CID_FLASH_STROBE control;
> > > whether that should be a button or boolean control. Buttons cannot be
> > > unpressed, so a button control would work for adp1653 but possibly not
> > > for other similar chips in the future.
> > > 
> > > Even if we have a standard control, can the type of the control change,
> > > depending on the properties of the hardware? This would also allow
> > > providing to user the knowledge on whether the flash may be explicitly
> > > turned off. On the other hand, I don't like the idea of having a
> > > standard control with several possible types (there are none at the
> > > moment, AFAIK). I would side with keeping the type of the control
> > > boolean all the time but I'm not fully certain.
> > > 
> > > Hans, do you have an opinion on this?
> > 
> > Theoretically the type may change depending on the hardware, but I don't
> > think that is something we should support. In particularly, that will make
> > it very hard to programmatically use such controls. There are all sorts of
> > subtle problems you run into when you allow for different types for the
> > same standard control.
> 
> I'm still undecided. If we standardize a boolean control, how will userspace 
> know that, for the adp1653, the control can be written to 1 but can't be 
> written to 0 ?

We need two controls: one button control, one boolean control. The first can
be called FLASH_STROBE, the second FLASH_STROBE_ON. Depending on the hardware,
only one of these is implemented. These two strobe implementations behave
differently in important ways, so I believe it makes sense to have two controls
as well.

Regards,

	Hans