From patchwork Thu May 19 10:41:25 2011 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sakari Ailus X-Patchwork-Id: 797012 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by demeter2.kernel.org (8.14.4/8.14.3) with ESMTP id p4JAfjFF018966 for ; Thu, 19 May 2011 10:41:45 GMT Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1753475Ab1ESKlm (ORCPT ); Thu, 19 May 2011 06:41:42 -0400 Received: from smtp.nokia.com ([147.243.128.24]:26079 "EHLO mgw-da01.nokia.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1753907Ab1ESKlk (ORCPT ); Thu, 19 May 2011 06:41:40 -0400 Received: from maxwell.research.nokia.com (maxwell.research.nokia.com [172.21.50.162]) by mgw-da01.nokia.com (Switch-3.4.4/Switch-3.4.3) with ESMTP id p4JAfRik008834 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Thu, 19 May 2011 13:41:28 +0300 Received: from kaali.localdomain (kaali.localdomain [192.168.239.7]) by maxwell.research.nokia.com (Postfix) with ESMTPS id E73FC3862ED; Thu, 19 May 2011 13:41:26 +0300 (EEST) Received: from sailus by kaali.localdomain with local (Exim 4.72) (envelope-from ) id 1QN0fW-0008Qp-QT; Thu, 19 May 2011 13:41:26 +0300 From: Sakari Ailus To: linux-media@vger.kernel.org Cc: laurent.pinchart@ideasonboard.com, nkanchev@mm-sol.com, g.liakhovetski@gmx.de, hverkuil@xs4all.nl, dacohen@gmail.com, riverful@gmail.com, andrew.b.adams@gmail.com, shpark7@stanford.edu Subject: [PATCH 2/3] v4l: Add flash control documentation Date: Thu, 19 May 2011 13:41:25 +0300 Message-Id: <1305801686-32360-2-git-send-email-sakari.ailus@maxwell.research.nokia.com> X-Mailer: git-send-email 1.7.2.5 In-Reply-To: <4DD4F3CA.3040300@maxwell.research.nokia.com> References: <4DD4F3CA.3040300@maxwell.research.nokia.com> X-Nokia-AV: Clean Sender: linux-media-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org X-Greylist: IP, sender and recipient auto-whitelisted, not delayed by milter-greylist-4.2.6 (demeter2.kernel.org [140.211.167.43]); Thu, 19 May 2011 10:41:46 +0000 (UTC) Add documentation for V4L2 flash controls. Signed-off-by: Sakari Ailus --- Documentation/DocBook/v4l/controls.xml | 275 ++++++++++++++++++++++ Documentation/DocBook/v4l/vidioc-g-ext-ctrls.xml | 7 + 2 files changed, 282 insertions(+), 0 deletions(-) diff --git a/Documentation/DocBook/v4l/controls.xml b/Documentation/DocBook/v4l/controls.xml index a920ee8..77913b7 100644 --- a/Documentation/DocBook/v4l/controls.xml +++ b/Documentation/DocBook/v4l/controls.xml @@ -2092,6 +2092,281 @@ manually or automatically if set to zero. Unit, range and step are driver-specif For more details about RDS specification, refer to document, from CENELEC. + +
+ Flash Control Reference + + + The V4L2 flash controls are intended to provide generic access + to flash controller devices. Flash controller devices are + typically used in digital cameras. + + + + The interface can support both LED and xenon flash devices. As + of writing this, there is no xenon flash driver using this + interface. + + +
+ Supported use cases + +
+ 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 + information typically must be made available to the + sensor. + + +
+ +
+ LED flash as torch + + + LED flash may be used as torch in conjunction with another + use case involving camera or individually. + + +
+ +
+ + + Flash Control IDs + + + + + + + + + + + ID + Type + Description + + + + + + V4L2_CID_FLASH_CLASS + class + + + The FLASH class descriptor. + + + V4L2_CID_FLASH_LED_MODE + menu + + + Defines the mode of the flash LED, + the high-power white LED attached to the flash controller. + Setting this control may not be possible in presence of + some faults. See V4L2_CID_FLASH_FAULT. + + + + + + V4L2_FLASH_LED_MODE_NONE + Off. + + + V4L2_FLASH_LED_MODE_FLASH + Flash mode. + + + V4L2_FLASH_LED_MODE_TORCH + Torch mode. See V4L2_CID_FLASH_TORCH_INTENSITY. + + + + + + V4L2_CID_FLASH_STROBE_SOURCE + menu + + Defines the mode of the + flash LED strobe. + + + + + + V4L2_FLASH_STROBE_SOURCE_SOFTWARE + The flash strobe is triggered by using + the V4L2_CID_FLASH_STROBE control. + + + V4L2_FLASH_STROBE_SOURCE_EXTERNAL + The flash strobe is triggered by an + external source. Typically this is a sensor, + which makes it possible to synchronises the + flash strobe start to exposure start. + + + + + + V4L2_CID_FLASH_STROBE + button + + + Strobe flash. Valid when + V4L2_CID_FLASH_LED_MODE is set to + V4L2_FLASH_LED_MODE_FLASH and V4L2_CID_FLASH_STROBE_SOURCE + is set to V4L2_FLASH_STROBE_SOURCE_SOFTWARE. Setting this + control may not be possible in presence of some faults. + See V4L2_CID_FLASH_FAULT. + + + V4L2_CID_FLASH_STROBE_STOP + button + + Stop flash strobe immediately. + + + V4L2_CID_FLASH_STROBE_STATUS + boolean + + + Strobe status: whether the flash + is strobing at the moment or not. This is a read-only + control. + + + V4L2_CID_FLASH_TIMEOUT + integer + + + Hardware timeout for flash. The + flash strobe is stopped after this period of time has + passed from the start of the strobe. + + + V4L2_CID_FLASH_INTENSITY + integer + + + Intensity of the flash strobe when + the flash LED is in flash mode + (V4L2_FLASH_LED_MODE_FLASH). The unit should be milliamps + (mA) if possible. + + + V4L2_CID_FLASH_TORCH_INTENSITY + integer + + + Intensity of the flash LED in + torch mode (V4L2_FLASH_LED_MODE_TORCH). The unit should be + milliamps (mA) if possible. Setting this control may not + be possible in presence of some faults. See + V4L2_CID_FLASH_FAULT. + + + V4L2_CID_FLASH_INDICATOR_INTENSITY + integer + + + Intensity of the indicator LED. + The indicator LED may be fully independent of the flash + LED. The unit should be microamps (uA) if possible. + + + V4L2_CID_FLASH_FAULT + bitmask + + + Faults related to the flash. The + faults tell about specific problems in the flash chip + itself or the LEDs attached to it. Faults may prevent + further use of some of the flash controls. In particular, + V4L2_CID_FLASH_LED_MODE is set to V4L2_FLASH_LED_MODE_NONE + if the fault affects the flash LED. Exactly which faults + have such an effect is chip dependent. Reading the faults + resets the control and returns the chip to a usable state + if possible. + + + + + + V4L2_FLASH_FAULT_OVER_VOLTAGE + Flash controller voltage to the flash LED + has exceeded the limit specific to the flash + controller. + + + V4L2_FLASH_FAULT_TIMEOUT + The flash strobe was still on when + the timeout set by the user --- + V4L2_CID_FLASH_TIMEOUT control --- has expired. + Not all flash controllers may set this in all + such conditions. + + + V4L2_FLASH_FAULT_OVER_TEMPERATURE + The flash controller has overheated. + + + V4L2_FLASH_FAULT_SHORT_CIRCUIT + The short circuit protection of the flash + controller has been triggered. + + + + + + V4L2_CID_FLASH_CHARGE + boolean + + Enable or disable charging of the xenon + flash capacitor. + + + V4L2_CID_FLASH_READY + boolean + + + Is the flash ready to strobe? + Xenon flashes require their capacitors charged before + strobing. LED flashes often require a cooldown period + after strobe during which another strobe will not be + possible. This is a read-only control. + + + + +
+ +