V4L2 API for flash devices

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,

Quoted 125 lines · 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.

Quoted 7 lines

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.

Quoted 10 lines

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.

Quoted 4 lines

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.

Quoted 17 lines

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.

Quoted 1 line

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.

Quoted 8 lines

	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?

Quoted 19 lines

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.

Quoted 5 lines

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.

Quoted 9 lines

#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.

Quoted 6 lines

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.

Quoted 12 lines

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.

Quoted 6 lines

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

Quoted 24 lines

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,

Hi Hans,

Many thanks for the comments!

Quoted 126 lines · Hans Verkuil

Quoted 125 lines · 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.

Quoted 7 lines

Quoted 7 lines

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?

Quoted 11 lines

Quoted 11 lines

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.

Quoted 8 lines

Quoted 4 lines

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.

Quoted 20 lines

Quoted 17 lines

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.

Quoted 1 line

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

Quoted 1 line

this is very much hardware specific and you don't want an attacker

Quoted 1 line

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.

Quoted 11 lines

Quoted 9 lines

	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.

Quoted 19 lines

Quoted 19 lines

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.

Quoted 7 lines

Quoted 5 lines

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! :-)

Quoted 9 lines

Quoted 9 lines

#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.

Quoted 8 lines

Quoted 6 lines

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. :-)

Quoted 17 lines

Quoted 17 lines

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.

Quoted 3 lines

Quoted 1 line

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

Looks good!

Thanks! :-)

Quoted 16 lines

Regards,

Hans

Quoted 11 lines

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-

Quoted 5 lines

Quoted 5 lines

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

[5]
http://www.retiisi.org.uk/v4l2/v4l2-brainstorming-

Quoted 3 lines

Quoted 3 lines

[6]
http://www.retiisi.org.uk/v4l2/v4l2-brainstorming-

Quoted 6 lines

Quoted 5 lines

Cheers,

Signature · 6 lines

Sakari Ailus
[email protected]
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Quoted 4 lines · On Tuesday, March 29, 2011 11:35:19 Sakari Ailus wrote:

Hi Hans,

Many thanks for the comments!

Quoted 10 lines

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.

Quoted 1 line

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.

Quoted 25 lines

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.

Quoted 1 line

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.

Quoted 5 lines · Hans Verkuil

Quoted 4 lines · On Tuesday, March 29, 2011 11:35:19 Sakari Ailus wrote:

Hi Hans,

Many thanks for the comments!

...

Quoted 10 lines

Quoted 10 lines

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.

Quoted 5 lines

Quoted 1 line

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!).

Quoted 25 lines · Sakari Ailus

Quoted 4 lines · Hans Verkuil

Quoted 3 lines · On Tuesday, March 29, 2011 11:35:19 Sakari Ailus wrote:

Hi Hans,

Many thanks for the comments!

...

Quoted 10 lines

Quoted 10 lines

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.

Quoted 6 lines

Quoted 1 line

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.

Quoted 5 lines

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.

Hi Sakari,

Quoted 40 lines

Quoted 25 lines · Sakari Ailus

Quoted 4 lines · Hans Verkuil

Quoted 3 lines · On Tuesday, March 29, 2011 11:35:19 Sakari Ailus wrote:

Hi Hans,

Many thanks for the comments!

...

Quoted 10 lines

Quoted 10 lines

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.

Quoted 6 lines

Quoted 1 line

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.

Quoted 5 lines

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.

Quoted 4 lines

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.

Quoted 1 line · Laurent Pinchart

Hi Sakari,

Hi Laurent,

Quoted 41 lines · On Tuesday 29 March 2011 13:51:38 Sakari Ailus wrote:

Quoted 40 lines

Quoted 25 lines · Sakari Ailus

Quoted 4 lines · Hans Verkuil

Quoted 3 lines · On Tuesday, March 29, 2011 11:35:19 Sakari Ailus wrote:

Hi Hans,

Many thanks for the comments!

...

Quoted 10 lines

Quoted 10 lines

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.

Quoted 6 lines

Quoted 1 line

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.

Quoted 5 lines

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.

Quoted 7 lines

Quoted 4 lines

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.

Quoted 4 lines · Sakari Ailus

Quoted 1 line · Laurent Pinchart

Hi Sakari,

Hi Laurent,

Hi Hans and Laurent,

Quoted 55 lines

Quoted 41 lines · On Tuesday 29 March 2011 13:51:38 Sakari Ailus wrote:

Quoted 40 lines

Quoted 25 lines · Sakari Ailus

Quoted 4 lines · Hans Verkuil

Quoted 3 lines · On Tuesday, March 29, 2011 11:35:19 Sakari Ailus wrote:

Hi Hans,

Many thanks for the comments!

...

Quoted 10 lines

Quoted 10 lines

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.

Quoted 6 lines

Quoted 1 line

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.

Quoted 5 lines

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.

Quoted 7 lines

Quoted 4 lines

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.

Quoted 3 lines

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?

Quoted 86 lines · On Monday, May 02, 2011 18:04:18 Sakari Ailus wrote:

Quoted 57 lines · Sakari Ailus

Quoted 41 lines · Laurent Pinchart

Quoted 40 lines · On Tuesday 29 March 2011 13:51:38 Sakari Ailus wrote:

Quoted 25 lines · Sakari Ailus

Quoted 4 lines · Hans Verkuil

Quoted 3 lines · On Tuesday, March 29, 2011 11:35:19 Sakari Ailus wrote:

Hi Hans,

Many thanks for the comments!

...

Quoted 10 lines

Quoted 10 lines

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.

Quoted 6 lines

Quoted 1 line

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.

Quoted 5 lines

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.

Quoted 8 lines

Quoted 4 lines

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.

Quoted 3 lines

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.

Quoted 1 line

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.

Hi Hans,

Quoted 87 lines · On Monday 02 May 2011 21:13:56 Hans Verkuil wrote:

Quoted 86 lines · On Monday, May 02, 2011 18:04:18 Sakari Ailus wrote:

Quoted 57 lines · Sakari Ailus

Quoted 41 lines · Laurent Pinchart

Quoted 40 lines · On Tuesday 29 March 2011 13:51:38 Sakari Ailus wrote:

Quoted 25 lines · Sakari Ailus

Quoted 4 lines · Hans Verkuil

Quoted 3 lines · On Tuesday, March 29, 2011 11:35:19 Sakari Ailus wrote:

Hi Hans,

Many thanks for the comments!

...

Quoted 10 lines

Quoted 10 lines

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.

Quoted 6 lines

Quoted 1 line

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.

Quoted 5 lines

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.

Quoted 8 lines

Quoted 4 lines

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.

Quoted 3 lines

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.

Quoted 7 lines

Quoted 1 line

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 ?

Quoted 1 line · Hans Verkuil

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

Quoted 15 lines

Quoted 15 lines

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.

Quoted 6 lines

Quoted 1 line

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.

Quoted 6 lines

Quoted 6 lines

	V4L2_CID_FLASH_LED_MODE (menu; LED)

enum v4l2_flash_led_mode {

	V4L2_FLASH_LED_MODE_FLASH = 1,
	V4L2_FLASH_LED_MODE_TORCH,

Quoted 5 lines

Quoted 2 lines

};

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.

Hi Sakari,

Quoted 2 lines

Quoted 1 line · Hans Verkuil

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

[snip]

Quoted 32 lines

Quoted 15 lines

Quoted 15 lines

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.

Quoted 6 lines

Quoted 1 line

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

Quoted 8 lines

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.

Quoted 10 lines

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.

Quoted 2 lines

Quoted 2 lines

	V4L2_CID_FLASH_LED_MODE (menu; LED)

Quoted 4 lines

Quoted 4 lines

Quoted 4 lines

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 ?

Quoted 51 lines · Laurent Pinchart

Quoted 2 lines · On Tuesday 29 March 2011 11:35:19 Sakari Ailus wrote:

Quoted 1 line · Hans Verkuil

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

[snip]

Quoted 31 lines

Quoted 15 lines

Quoted 15 lines

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.

Quoted 6 lines

Quoted 1 line

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

Quoted 8 lines

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

Quoted 6 lines

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.

Quoted 15 lines

Quoted 14 lines

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.

Quoted 6 lines

Quoted 6 lines

	V4L2_CID_FLASH_LED_MODE (menu; LED)

enum v4l2_flash_led_mode {

	V4L2_FLASH_LED_MODE_FLASH = 1,
	V4L2_FLASH_LED_MODE_TORCH,

Quoted 2 lines

"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.

Hi Sakari,

Quoted 59 lines

Quoted 51 lines · Laurent Pinchart

Quoted 2 lines · On Tuesday 29 March 2011 11:35:19 Sakari Ailus wrote:

Quoted 1 line · Hans Verkuil

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

[snip]

Quoted 31 lines

Quoted 15 lines

Quoted 15 lines

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.

Quoted 6 lines

Quoted 1 line

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

Quoted 8 lines

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

Quoted 6 lines

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.

Quoted 5 lines

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.

Quoted 4 lines

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 ?

Quoted 18 lines

Quoted 17 lines

Quoted 6 lines

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.

Quoted 8 lines

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

Quoted 6 lines

Quoted 6 lines

	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 ?

Quoted 4 lines

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.

Quoted 1 line · Laurent Pinchart

Hi Sakari,

Heippa,

Quoted 75 lines · On Wednesday 30 March 2011 14:44:25 Sakari Ailus wrote:

Quoted 59 lines

Quoted 51 lines · Laurent Pinchart

Quoted 2 lines · On Tuesday 29 March 2011 11:35:19 Sakari Ailus wrote:

Quoted 1 line · Hans Verkuil

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

[snip]

Quoted 31 lines

Quoted 15 lines

Quoted 15 lines

 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.

Quoted 6 lines

Quoted 1 line

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

Quoted 8 lines

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

Quoted 6 lines

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.

Quoted 5 lines

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.

Quoted 4 lines

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.

Quoted 1 line

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? :-)

Quoted 24 lines

Quoted 23 lines

Quoted 11 lines

Quoted 11 lines

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.

Quoted 2 lines

Quoted 2 lines

 V4L2_CID_FLASH_LED_MODE (menu; LED)

Quoted 7 lines

Quoted 4 lines

Quoted 4 lines

Quoted 4 lines

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.

Quoted 1 line

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
[email protected]
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Quoted 81 lines · Sakari Ailus

Quoted 72 lines · On Wednesday 30 March 2011 14:44:25 Sakari Ailus wrote:

Quoted 61 lines

Quoted 53 lines · Laurent Pinchart

Quoted 2 lines · On Tuesday 29 March 2011 11:35:19 Sakari Ailus wrote:

Quoted 1 line · Hans Verkuil

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

[snip]

Quoted 33 lines

Quoted 17 lines

Quoted 17 lines

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.

Quoted 6 lines

Quoted 1 line

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

Quoted 8 lines

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

Quoted 6 lines

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.

Quoted 5 lines

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.

Quoted 6 lines

Quoted 4 lines

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?

Quoted 3 lines

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.

Quoted 23 lines

Quoted 23 lines

Quoted 22 lines

Quoted 10 lines

Quoted 10 lines

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.

Quoted 2 lines

Quoted 2 lines

V4L2_CID_FLASH_LED_MODE (menu; LED)

Quoted 7 lines

Quoted 4 lines

Quoted 4 lines

Quoted 4 lines

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.

Quoted 6 lines

Quoted 1 line

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.

Hi David,

Quoted 2 lines · Sakari Ailus

Quoted 1 line

Quoted 1 line · On Wednesday 30 March 2011 14:44:25 Sakari Ailus wrote:

Quoted 13 lines

Quoted 12 lines

Quoted 6 lines

Quoted 4 lines

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? :-)

Quoted 4 lines

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 ?

Quoted 28 lines

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.

Quoted 25 lines

Quoted 24 lines

Quoted 15 lines

Quoted 15 lines

Quoted 14 lines

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.

Quoted 6 lines

Quoted 6 lines

V4L2_CID_FLASH_LED_MODE (menu; LED)

enum v4l2_flash_led_mode {

V4L2_FLASH_LED_MODE_FLASH = 1,
V4L2_FLASH_LED_MODE_TORCH,

Quoted 7 lines

Quoted 2 lines

"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.

Quoted 6 lines

Quoted 4 lines

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 :-)

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,

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 쓴 글:

Quoted 89 lines

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.

Quoted 2 lines

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?

Quoted 77 lines

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.

Quoted 6 lines

	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.

Kim, HeungJun wrote:

Quoted 4 lines

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.

Hi Sakari,

2011-03-29 오후 11:41, Sakari Ailus 쓴 글:

Quoted 1 line

Kim, HeungJun wrote:

[snip]

Quoted 5 lines

Quoted 4 lines

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.

Quoted 1 line

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.

Quoted 9 lines

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.

Quoted 4 lines

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.

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.

Quoted 1 line · HeungJun

Hi Sakari,

Hi HeungJun,

Quoted 8 lines

2011-03-29 오후 11:41, Sakari Ailus 쓴 글:

Quoted 1 line

Kim, HeungJun wrote:

[snip]

Quoted 5 lines

Quoted 4 lines

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.

Quoted 6 lines

Quoted 1 line

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?

Quoted 10 lines

Quoted 10 lines

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.

Quoted 8 lines

Quoted 4 lines

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.

Quoted 4 lines

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)

Quoted 5 lines

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!

Quoted 2 lines

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,

Signature · 6 lines

Sakari Ailus
[email protected]
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Hi Sakari,

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

Quoted 20 lines

Quoted 1 line · HeungJun

Hi Sakari,

Hi HeungJun,

Quoted 14 lines

2011-03-29 오후 11:41, Sakari Ailus 쓴 글:

Quoted 1 line

Kim, HeungJun wrote:

[snip]

Quoted 6 lines

Quoted 4 lines

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.

Quoted 3 lines

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.

Quoted 11 lines

Quoted 4 lines

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:

Quoted 8 lines

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. :)

Quoted 11 lines

Quoted 5 lines

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!

Quoted 2 lines

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.

Quoted 5 lines

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.

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_LED_MODE (menu; LED)

enum v4l2_flash_led_mode {
	V4L2_FLASH_LED_MODE_FLASH = 1,
	V4L2_FLASH_LED_MODE_TORCH,
};

Hi Sakari,

[snip]

Quoted 14 lines

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]

Quoted 6 lines

	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).

Quoted 1 line · Laurent Pinchart

Hi Sakari,

Hi Laurent,

Thanks for the comments!

Quoted 30 lines · On Monday 28 March 2011 14:55:40 Sakari Ailus wrote:

[snip]

Quoted 16 lines

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]

Quoted 7 lines

	V4L2_CID_FLASH_LED_MODE (menu; LED)

enum v4l2_flash_led_mode {

	V4L2_FLASH_LED_MODE_FLASH = 1,
	V4L2_FLASH_LED_MODE_TORCH,

Quoted 7 lines

Quoted 1 line

};

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?

Quoted 52 lines · On Wednesday 30 March 2011 13:05:54 Sakari Ailus wrote:

Quoted 1 line · Laurent Pinchart

Hi Sakari,

Hi Laurent,

Thanks for the comments!

Quoted 30 lines · On Monday 28 March 2011 14:55:40 Sakari Ailus wrote:

[snip]

Quoted 16 lines

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]

Quoted 7 lines

	V4L2_CID_FLASH_LED_MODE (menu; LED)

enum v4l2_flash_led_mode {

	V4L2_FLASH_LED_MODE_FLASH = 1,
	V4L2_FLASH_LED_MODE_TORCH,

Quoted 7 lines

Quoted 1 line

};

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.

Quoted 1 line

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.

Quoted 18 lines

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.

Quoted 5 lines

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 :-)

Quoted 53 lines · Laurent Pinchart

Quoted 52 lines · On Wednesday 30 March 2011 13:05:54 Sakari Ailus wrote:

Quoted 1 line · Laurent Pinchart

Hi Sakari,

Hi Laurent,

Thanks for the comments!

Quoted 30 lines · On Monday 28 March 2011 14:55:40 Sakari Ailus wrote:

[snip]

Quoted 16 lines

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]

Quoted 7 lines

	V4L2_CID_FLASH_LED_MODE (menu; LED)

enum v4l2_flash_led_mode {

	V4L2_FLASH_LED_MODE_FLASH = 1,
	V4L2_FLASH_LED_MODE_TORCH,

Quoted 7 lines

Quoted 1 line

};

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.

Quoted 5 lines

Quoted 1 line

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.

Quoted 50 lines · Sakari Ailus

Quoted 49 lines · Laurent Pinchart

Quoted 47 lines · On Wednesday 30 March 2011 13:05:54 Sakari Ailus wrote:

Quoted 30 lines · Laurent Pinchart

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

[snip]

Quoted 16 lines

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]

Quoted 7 lines

	V4L2_CID_FLASH_LED_MODE (menu; LED)

enum v4l2_flash_led_mode {

	V4L2_FLASH_LED_MODE_FLASH = 1,
	V4L2_FLASH_LED_MODE_TORCH,

Quoted 7 lines

Quoted 1 line

};

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?

Quoted 5 lines

Quoted 3 lines

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?

Hi Sakari,

Quoted 55 lines · On Tuesday 05 April 2011 12:23:51 Sakari Ailus wrote:

Quoted 54 lines · Sakari Ailus

Quoted 52 lines · Laurent Pinchart

Quoted 39 lines · On Wednesday 30 March 2011 13:05:54 Sakari Ailus wrote:

Quoted 30 lines · Laurent Pinchart

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

[snip]

Quoted 16 lines

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]

Quoted 7 lines

	V4L2_CID_FLASH_LED_MODE (menu; LED)

enum v4l2_flash_led_mode {

	V4L2_FLASH_LED_MODE_FLASH = 1,
	V4L2_FLASH_LED_MODE_TORCH,

Quoted 7 lines

Quoted 1 line

};

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).

Quoted 8 lines

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.

Quoted 3 lines

Quoted 1 line

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.

Quoted 56 lines · Laurent Pinchart

Quoted 55 lines · On Tuesday 05 April 2011 12:23:51 Sakari Ailus wrote:

Quoted 54 lines · Sakari Ailus

Quoted 52 lines · Laurent Pinchart

Quoted 39 lines · On Wednesday 30 March 2011 13:05:54 Sakari Ailus wrote:

Quoted 30 lines · Laurent Pinchart

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

[snip]

Quoted 16 lines

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]

Quoted 7 lines

	V4L2_CID_FLASH_LED_MODE (menu; LED)

enum v4l2_flash_led_mode {

	V4L2_FLASH_LED_MODE_FLASH = 1,
	V4L2_FLASH_LED_MODE_TORCH,

Quoted 7 lines

Quoted 1 line

};

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).

Quoted 8 lines

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.

Quoted 7 lines

Quoted 3 lines

Quoted 1 line

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.

Hi Sakari,

Quoted 75 lines

Quoted 56 lines · Laurent Pinchart

Quoted 55 lines · On Tuesday 05 April 2011 12:23:51 Sakari Ailus wrote:

Quoted 54 lines · Sakari Ailus

Quoted 52 lines · Laurent Pinchart

Quoted 39 lines · On Wednesday 30 March 2011 13:05:54 Sakari Ailus wrote:

Quoted 30 lines · Laurent Pinchart

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

[snip]

Quoted 16 lines

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]

Quoted 7 lines

	V4L2_CID_FLASH_LED_MODE (menu; LED)

enum v4l2_flash_led_mode {

	V4L2_FLASH_LED_MODE_FLASH = 1,
	V4L2_FLASH_LED_MODE_TORCH,

Quoted 7 lines

Quoted 1 line

};

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).

Quoted 8 lines

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.

Quoted 7 lines

Quoted 3 lines

Quoted 1 line

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. ...

Quoted 3 lines

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 ?

Quoted 95 lines · Sakari Ailus

Quoted 80 lines · Laurent Pinchart

Quoted 75 lines · On Tuesday 05 April 2011 13:21:03 Sakari Ailus wrote:

Quoted 56 lines · Laurent Pinchart

Quoted 55 lines · On Tuesday 05 April 2011 12:23:51 Sakari Ailus wrote:

Quoted 54 lines · Sakari Ailus

Quoted 52 lines · Laurent Pinchart

Quoted 39 lines · On Wednesday 30 March 2011 13:05:54 Sakari Ailus wrote:

Quoted 30 lines · Laurent Pinchart

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

[snip]

Quoted 16 lines

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]

Quoted 7 lines

	V4L2_CID_FLASH_LED_MODE (menu; LED)

enum v4l2_flash_led_mode {

	V4L2_FLASH_LED_MODE_FLASH = 1,
	V4L2_FLASH_LED_MODE_TORCH,

Quoted 7 lines

Quoted 1 line

};

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).

Quoted 8 lines

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.

Quoted 7 lines

Quoted 3 lines

Quoted 1 line

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. ...

Quoted 3 lines

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.

Quoted 7 lines

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.

Quoted 5 lines

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.

Hi,

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

Quoted 1 line · Sakari Ailus

Hi,

Hi Sakari,

[snip]

Quoted 4 lines

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.

Quoted 4 lines

#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.

From an API perspective, it requires you to be able to specify a

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
[email protected]
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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.

From this I reckon that in a general case the handling of the flash

Quoted 7 lines · 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/)

Hi Andrew,

Many thanks for the comments.

Quoted 24 lines

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.

Quoted 5 lines

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?

Hi Sakari,

Quoted 47 lines

Quoted 7 lines · 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/)

Hi Andrew,

Many thanks for the comments.

Quoted 24 lines

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.

Quoted 5 lines

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.

Quoted 4 lines

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.

Quoted 4 lines

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.