OMAP 3 Image Signal Processor (ISP) driver

문서 정보와 연락처

이 문서는 GPL-2.0 라이선스를 따르며 OMAP 3 Image Signal Processor(ISP) 드라이버를 설명합니다.

저작권은 2010 Nokia Corporation과 2009 Texas Instruments, Inc.에 있습니다. 연락처는 Laurent Pinchart `<[email protected]>`, Sakari Ailus `<[email protected]>`, David Cohen `<[email protected]>`입니다.

.. SPDX-License-Identifier: GPL-2.0

.. include:: <isonum.txt>

OMAP 3 Image Signal Processor (ISP) driver
==========================================

Copyright |copy| 2010 Nokia Corporation

Copyright |copy| 2009 Texas Instruments, Inc.

Contacts: Laurent Pinchart <[email protected]>,
Sakari Ailus <[email protected]>, David Cohen <[email protected]>

CCDC와 통계 이벤트

OMAP 3 ISP 드라이버는 CCDC와 통계(AEWB, AF, histogram) 서브디바이스에서 V4L2 이벤트 인터페이스를 지원합니다.

CCDC 서브디바이스는 프레임 시작을 알리는 HS_VS 인터럽트에서 `V4L2_EVENT_FRAME_SYNC` 형식의 이벤트를 생성합니다. 이전 드라이버는 같은 용도로 `V4L2_EVENT_OMAP3ISP_HS_VS`를 사용했습니다. 이벤트는 CCDC 모듈이 프레임 첫 줄을 수신하기 시작하는 정확한 시점에 발생하며 CCDC 서브디바이스에서 구독할 수 있습니다.

병렬 인터페이스를 사용할 때는 VS 신호 극성을 올바르게 설정해야 합니다. 직렬 수신기를 사용하면 이 설정은 자동으로 올바르게 맞춰집니다.

각 통계 서브디바이스도 이벤트를 생성할 수 있습니다. 사용자 공간 애플리케이션이 `VIDIOC_OMAP3ISP_STAT_REQ` IOCTL로 dequeue할 수 있는 통계 버퍼가 생길 때마다 이벤트가 발생합니다.

이 IOCTL들의 이벤트 데이터 형식은 `struct omap3isp_stat_event_status`입니다. 통계 계산 중 오류가 나도 평소처럼 이벤트는 발생하지만 연결된 통계 버퍼는 없습니다. 이 경우 `omap3isp_stat_event_status.buf_err`가 0이 아닌 값으로 설정됩니다.

Events
------

The OMAP 3 ISP driver does support the V4L2 event interface on CCDC and
statistics (AEWB, AF and histogram) subdevs.

The CCDC subdev produces V4L2_EVENT_FRAME_SYNC type event on HS_VS
interrupt which is used to signal frame start. Earlier version of this
driver used V4L2_EVENT_OMAP3ISP_HS_VS for this purpose. The event is
triggered exactly when the reception of the first line of the frame starts
in the CCDC module. The event can be subscribed on the CCDC subdev.

(When using parallel interface one must pay account to correct configuration
of the VS signal polarity. This is automatically correct when using the serial
receivers.)

Each of the statistics subdevs is able to produce events. An event is
generated whenever a statistics buffer can be dequeued by a user space
application using the VIDIOC_OMAP3ISP_STAT_REQ IOCTL. The events available
are:

- V4L2_EVENT_OMAP3ISP_AEWB
- V4L2_EVENT_OMAP3ISP_AF
- V4L2_EVENT_OMAP3ISP_HIST

The type of the event data is struct omap3isp_stat_event_status for these
ioctls. If there is an error calculating the statistics, there will be an
event as usual, but no related statistics buffer. In this case
omap3isp_stat_event_status.buf_err is set to non-zero.

전용 IOCTL

OMAP 3 ISP 드라이버는 가능하고 실용적인 곳에서는 표준 V4L2 IOCTL과 컨트롤을 지원합니다. 그러나 감마 테이블이나 통계 수집 구성처럼 ISP가 제공하는 많은 기능은 표준 IOCTL 범위에 들어가지 않습니다.

일반적으로 하드웨어 의존 기능이 들어 있는 각 블록을 구성하기 위한 전용 IOCTL이 하나씩 제공됩니다.

이 IOCTL이 사용하는 매개변수 구조체는 `include/linux/omap3isp.h`에 설명되어 있습니다. ISP 블록별 세부 하드웨어 기능은 문서 끝에서 가리키는 Technical Reference Manual(TRM)을 참고해야 합니다.

전용 IOCTL을 전혀 쓰지 않고도 ISP 드라이버를 사용할 수는 있지만 최적의 이미지 품질을 얻을 수는 없습니다. AEWB, AF, histogram 모듈은 해당 전용 IOCTL로 구성하지 않으면 사용할 수 없습니다.

Private IOCTLs
--------------

The OMAP 3 ISP driver supports standard V4L2 IOCTLs and controls where
possible and practical. Much of the functions provided by the ISP, however,
does not fall under the standard IOCTLs --- gamma tables and configuration of
statistics collection are examples of such.

In general, there is a private ioctl for configuring each of the blocks
containing hardware-dependent functions.

The following private IOCTLs are supported:

- VIDIOC_OMAP3ISP_CCDC_CFG
- VIDIOC_OMAP3ISP_PRV_CFG
- VIDIOC_OMAP3ISP_AEWB_CFG
- VIDIOC_OMAP3ISP_HIST_CFG
- VIDIOC_OMAP3ISP_AF_CFG
- VIDIOC_OMAP3ISP_STAT_REQ
- VIDIOC_OMAP3ISP_STAT_EN

The parameter structures used by these ioctls are described in
include/linux/omap3isp.h. The detailed functions of the ISP itself related to
a given ISP block is described in the Technical Reference Manuals (TRMs) ---
see the end of the document for those.

While it is possible to use the ISP driver without any use of these private
IOCTLs it is not possible to obtain optimal image quality this way. The AEWB,
AF and histogram modules cannot be used without configuring them using the
appropriate private IOCTLs.

CCDC 블록 구성

`VIDIOC_OMAP3ISP_CCDC_CFG`와 `VIDIOC_OMAP3ISP_PRV_CFG` IOCTL은 각각 CCDC와 preview 블록의 기능을 구성하고 활성화하거나 비활성화합니다. 두 IOCTL 모두 담당 블록 안의 여러 기능을 한 번에 제어합니다.

`VIDIOC_OMAP3ISP_CCDC_CFG`는 `struct omap3isp_ccdc_update_config` 포인터를 인자로 받고, `VIDIOC_OMAP3ISP_PRV_CFG`는 `struct omap3isp_prev_update_config` 포인터를 받습니다. 두 구조체 정의는 `include/linux/omap3isp.h`에 있습니다.

구조체의 `update` 필드는 특정 기능의 구성을 갱신할지 나타내고, `flag` 필드는 그 기능을 활성화할지 비활성화할지 나타냅니다. 각 기능은 `flag` 필드의 활성화 또는 비활성화 비트와 기능별 구성 데이터 포인터에 연결됩니다.

`VIDIOC_OMAP3ISP_CCDC_CFG`의 `update`와 `flag`에 사용할 수 있는 값은 다음과 같습니다. 한 IOCTL 호출에서 여러 기능을 구성하려면 값을 비트 OR로 결합할 수 있습니다.

CCDC and preview block IOCTLs
-----------------------------

The VIDIOC_OMAP3ISP_CCDC_CFG and VIDIOC_OMAP3ISP_PRV_CFG IOCTLs are used to
configure, enable and disable functions in the CCDC and preview blocks,
respectively. Both IOCTLs control several functions in the blocks they
control. VIDIOC_OMAP3ISP_CCDC_CFG IOCTL accepts a pointer to struct
omap3isp_ccdc_update_config as its argument. Similarly VIDIOC_OMAP3ISP_PRV_CFG
accepts a pointer to struct omap3isp_prev_update_config. The definition of
both structures is available in [#]_.

The update field in the structures tells whether to update the configuration
for the specific function and the flag tells whether to enable or disable the
function.

The update and flag bit masks accept the following values. Each separate
functions in the CCDC and preview blocks is associated with a flag (either
disable or enable; part of the flag field in the structure) and a pointer to
configuration data for the function.

Valid values for the update and flag fields are listed here for
VIDIOC_OMAP3ISP_CCDC_CFG. Values may be or'ed to configure more than one
function in the same IOCTL call.

- OMAP3ISP_CCDC_ALAW
- OMAP3ISP_CCDC_LPF
- OMAP3ISP_CCDC_BLCLAMP
- OMAP3ISP_CCDC_BCOMP
- OMAP3ISP_CCDC_FPC
- OMAP3ISP_CCDC_CULL
- OMAP3ISP_CCDC_CONFIG_LSC
- OMAP3ISP_CCDC_TBL_LSC

Preview 블록 구성

`VIDIOC_OMAP3ISP_PRV_CFG`에 대응하는 `update`와 `flag` 값은 다음과 같습니다.

기능을 활성화할 때는 그 기능에 연결된 구성 포인터가 `NULL`이어서는 안 됩니다. 기능을 비활성화할 때는 구성 포인터가 무시됩니다.

The corresponding values for the VIDIOC_OMAP3ISP_PRV_CFG are here:

- OMAP3ISP_PREV_LUMAENH
- OMAP3ISP_PREV_INVALAW
- OMAP3ISP_PREV_HRZ_MED
- OMAP3ISP_PREV_CFA
- OMAP3ISP_PREV_CHROMA_SUPP
- OMAP3ISP_PREV_WB
- OMAP3ISP_PREV_BLKADJ
- OMAP3ISP_PREV_RGB2RGB
- OMAP3ISP_PREV_COLOR_CONV
- OMAP3ISP_PREV_YC_LIMIT
- OMAP3ISP_PREV_DEFECT_COR
- OMAP3ISP_PREV_GAMMABYPASS
- OMAP3ISP_PREV_DRK_FRM_CAPTURE
- OMAP3ISP_PREV_DRK_FRM_SUBTRACT
- OMAP3ISP_PREV_LENS_SHADING
- OMAP3ISP_PREV_NF
- OMAP3ISP_PREV_GAMMA

The associated configuration pointer for the function may not be NULL when
enabling the function. When disabling a function the configuration pointer is
ignored.

통계 블록 IOCTL

통계 서브디바이스는 다른 서브디바이스보다 동적인 구성 옵션을 제공합니다. 파이프라인이 스트리밍 중일 때도 활성화, 비활성화, 재구성이 가능합니다.

Histogram의 메모리 읽기는 구현되지 않았으므로 통계 블록은 항상 CCDC에서 입력 이미지 데이터를 받습니다. 사용자는 전용 IOCTL을 이용해 통계 서브디바이스 노드에서 통계를 dequeue할 수 있습니다.

AEWB, AF, histogram 서브디바이스의 전용 IOCTL은 ISP 하드웨어가 제공하는 레지스터 수준 인터페이스를 강하게 반영합니다. 이어지는 내용은 TRM의 하드웨어 설명과 별개로 드라이버 구현에만 관계된 부분을 다룹니다.

Statistic blocks IOCTLs
-----------------------

The statistics subdevs do offer more dynamic configuration options than the
other subdevs. They can be enabled, disable and reconfigured when the pipeline
is in streaming state.

The statistics blocks always get the input image data from the CCDC (as the
histogram memory read isn't implemented). The statistics are dequeueable by
the user from the statistics subdev nodes using private IOCTLs.

The private IOCTLs offered by the AEWB, AF and histogram subdevs are heavily
reflected by the register level interface offered by the ISP hardware. There
are aspects that are purely related to the driver implementation and these are
discussed next.

VIDIOC_OMAP3ISP_STAT_EN

`VIDIOC_OMAP3ISP_STAT_EN` 전용 IOCTL은 통계 모듈을 활성화하거나 비활성화합니다. 스트리밍 전에 요청하면 파이프라인이 스트리밍을 시작하는 즉시 적용됩니다. 이미 스트리밍 중이면 CCDC가 idle 상태가 되는 즉시 적용됩니다.

VIDIOC_OMAP3ISP_STAT_EN
-----------------------

This private IOCTL enables/disables a statistic module. If this request is
done before streaming, it will take effect as soon as the pipeline starts to
stream.  If the pipeline is already streaming, it will take effect as soon as
the CCDC becomes idle.

통계 구성과 buf_size

`VIDIOC_OMAP3ISP_AEWB_CFG`, `VIDIOC_OMAP3ISP_HIST_CFG`, `VIDIOC_OMAP3ISP_AF_CFG`는 각 통계 모듈을 구성합니다. 사용자 애플리케이션은 하드웨어를 깊이 이해해야 하며, 대부분의 필드 설명은 OMAP TRM에서 찾을 수 있습니다. 다만 다음 공통 필드는 TRM에 없는 드라이버 인터페이스이므로 별도 설명이 필요합니다.

`omap3isp_[h3a_af/h3a_aewb/hist]_config.buf_size`는 모듈의 내부 버퍼 크기에 영향을 줍니다. 필요한 출력 버퍼 크기는 요청한 구성에 따라 달라집니다.

드라이버는 스트리밍 중 재구성을 지원하지만, 모듈이 활성화된 상태에서 이미 내부 할당된 것보다 큰 버퍼가 필요한 구성으로 바꾸는 것은 지원하지 않습니다. 이 경우 `-EBUSY`를 반환합니다.

이 상황을 피하려면 모듈을 비활성화하고 재구성한 뒤 다시 활성화하거나, 모듈이 비활성화된 첫 구성 시점에 필요한 버퍼 크기를 요청해야 합니다.

내부 버퍼 할당은 요청한 구성의 최소 버퍼 크기와 `buf_size` 필드 값을 함께 고려합니다. `buf_size`가 [minimum, maximum] 범위를 벗어나면 범위 안으로 clamp하고, 드라이버는 최소 크기와 보정된 요청값 중 더 큰 값을 선택합니다. 보정된 `buf_size` 값은 사용자 애플리케이션에 다시 기록됩니다.

VIDIOC_OMAP3ISP_AEWB_CFG, VIDIOC_OMAP3ISP_HIST_CFG and VIDIOC_OMAP3ISP_AF_CFG
-----------------------------------------------------------------------------

Those IOCTLs are used to configure the modules. They require user applications
to have an in-depth knowledge of the hardware. Most of the fields explanation
can be found on OMAP's TRMs. The two following fields common to all the above
configure private IOCTLs require explanation for better understanding as they
are not part of the TRM.

omap3isp_[h3a_af/h3a_aewb/hist]\_config.buf_size:

The modules handle their buffers internally. The necessary buffer size for the
module's data output depends on the requested configuration. Although the
driver supports reconfiguration while streaming, it does not support a
reconfiguration which requires bigger buffer size than what is already
internally allocated if the module is enabled. It will return -EBUSY on this
case. In order to avoid such condition, either disable/reconfigure/enable the
module or request the necessary buffer size during the first configuration
while the module is disabled.

The internal buffer size allocation considers the requested configuration's
minimum buffer size and the value set on buf_size field. If buf_size field is
out of [minimum, maximum] buffer size range, it's clamped to fit in there.
The driver then selects the biggest value. The corrected buf_size value is
written back to user application.

config_counter로 구성 추적

`omap3isp_[h3a_af/h3a_aewb/hist]_config.config_counter`는 비동기로 적용되는 구성과 통계 데이터를 연결합니다.

구성 요청 뒤 사용자 공간에 반환되는 `config_counter`는 그 요청에 연결된 고유 값입니다. 애플리케이션이 버퍼 가용 이벤트를 받거나 새 버퍼를 요청할 때 이 값을 사용해 버퍼 데이터가 어느 구성으로 생성되었는지 맞춥니다.

omap3isp_[h3a_af/h3a_aewb/hist]\_config.config_counter:

As the configuration doesn't take effect synchronously to the request, the
driver must provide a way to track this information to provide more accurate
data. After a configuration is requested, the config_counter returned to user
space application will be an unique value associated to that request. When
user application receives an event for buffer availability or when a new
buffer is requested, this config_counter is used to match a buffer data and a
configuration.

VIDIOC_OMAP3ISP_STAT_REQ와 참고 자료

`VIDIOC_OMAP3ISP_STAT_REQ`는 내부 버퍼 큐에서 가장 오래된 가용 데이터를 사용자 공간으로 보내고, 전송한 버퍼를 큐에서 폐기합니다.

`omap3isp_stat_data.frame_number` 필드는 비디오 버퍼의 `field_count`와 일치합니다.

구조체와 인터페이스 정의의 참고 경로는 `include/linux/omap3isp.h`입니다.

VIDIOC_OMAP3ISP_STAT_REQ
------------------------

Send to user space the oldest data available in the internal buffer queue and
discards such buffer afterwards. The field omap3isp_stat_data.frame_number
matches with the video buffer's field_count.


References
----------

.. [#] include/linux/omap3isp.h