V4L2 File handles

v4l2_fh 생명주기

`struct v4l2_fh`는 V4L2 framework가 사용하는 file handle별 자료를 쉽게 보관하는 방법이며 모든 driver에서 반드시 사용해야 합니다.

Driver의 `open()` file operation에서 `v4l2_fh`를 할당합니다. 보통 더 큰 driver 전용 file handle 구조체 안에 포함합니다.

`v4l2_fh_init()`으로 초기화한 뒤 `v4l2_fh_add()`로 video device에 추가합니다. 이 과정에서 `file->private_data`가 `v4l2_fh`를 가리키도록 설정되어 file과 연결됩니다.

Driver의 `release()`에서는 먼저 `v4l2_fh_del()`로 video device에서 제거하고 `v4l2_fh_exit()`으로 정리한 뒤 메모리를 해제해야 합니다.

Driver는 `file->private_data`에 직접 접근해서는 안 됩니다. `file_to_v4l2_fh()`로 file에 연결된 `v4l2_fh`를 얻고, `container_of`로 driver 전용 file handle 구조체를 얻을 수 있습니다.

.. SPDX-License-Identifier: GPL-2.0

V4L2 File handles
-----------------

struct v4l2_fh provides a way to easily keep file handle specific data that is
used by the V4L2 framework. Its usage is mandatory in all drivers.

struct v4l2_fh is allocated in the driver's ``open()`` file operation handler.
It is typically embedded in a larger driver-specific structure. The
:c:type:`v4l2_fh` must be initialized with a call to :c:func:`v4l2_fh_init`,
and added to the video device with :c:func:`v4l2_fh_add`. This associates the
:c:type:`v4l2_fh` with the :c:type:`file` by setting ``file->private_data`` to
point to the :c:type:`v4l2_fh`.

Similarly, the struct v4l2_fh is freed in the driver's ``release()`` file
operation handler. It must be removed from the video device with
:c:func:`v4l2_fh_del` and cleaned up with :c:func:`v4l2_fh_exit` before being
freed.

Drivers must not access ``file->private_data`` directly. They can retrieve the
:c:type:`v4l2_fh` associated with a :c:type:`file` by calling
:c:func:`file_to_v4l2_fh`. Drivers can extract their own file handle structure
by using the container_of macro.

Driver 전용 file handle 예제

예제의 `struct my_fh`는 driver 전용 `blah` 자료와 `struct v4l2_fh fh`를 함께 포함합니다.

`my_open()`은 `my_fh`를 `kzalloc()`으로 할당하고 `v4l2_fh_init(&my_fh->fh, vfd)`으로 초기화한 뒤, 모든 file handle 초기화가 끝나면 `v4l2_fh_add(&my_fh->fh, file)`를 호출합니다.

`my_release()`는 `file_to_v4l2_fh(file)`로 framework file handle을 찾고 `container_of()`로 `my_fh`를 복원합니다. 이어서 `v4l2_fh_del()`, `v4l2_fh_exit()`, `kfree()` 순서로 제거·정리·해제합니다.

Example:

.. code-block:: c

        struct my_fh {
                int blah;
                struct v4l2_fh fh;
        };

        ...

        int my_open(struct file *file)
        {
                struct my_fh *my_fh;
                struct video_device *vfd;
                int ret;

                ...

                my_fh = kzalloc(sizeof(*my_fh), GFP_KERNEL);

                ...

                v4l2_fh_init(&my_fh->fh, vfd);

                ...

                v4l2_fh_add(&my_fh->fh, file);
                return 0;
        }

        int my_release(struct file *file)
        {
                struct v4l2_fh *fh = file_to_v4l2_fh(file);
                struct my_fh *my_fh = container_of(fh, struct my_fh, fh);

                ...
                v4l2_fh_del(&my_fh->fh, file);
                v4l2_fh_exit(&my_fh->fh);
                kfree(my_fh);
                return 0;
        }

기본 v4l2_fh 함수

`v4l2_fh_init(fh, vdev)`은 file handle을 초기화하며 driver의 `v4l2_file_operations->open()`에서 반드시 수행해야 합니다.

`v4l2_fh_add(fh, filp)`는 완전히 초기화된 `v4l2_fh`를 `video_device`의 file handle 목록에 추가합니다.

`v4l2_fh_del(fh, filp)`은 file handle과 `video_device`의 연결을 끊습니다. 이 호출 뒤에 file handle exit를 실행할 수 있습니다.

`v4l2_fh_exit(fh)`은 file handle 초기화를 해제합니다. 이후 `v4l2_fh` 메모리를 해제할 수 있습니다.

`file_to_v4l2_fh(filp)`는 `file`에 연결된 `v4l2_fh` instance를 반환합니다.

Below is a short description of the :c:type:`v4l2_fh` functions used:

:c:func:`v4l2_fh_init <v4l2_fh_init>`
(:c:type:`fh <v4l2_fh>`, :c:type:`vdev <video_device>`)

- Initialise the file handle. This **MUST** be performed in the driver's
  :c:type:`v4l2_file_operations`->open() handler.

:c:func:`v4l2_fh_add <v4l2_fh_add>`
(:c:type:`fh <v4l2_fh>`, struct file \*filp)

- Add a :c:type:`v4l2_fh` to :c:type:`video_device` file handle list.
  Must be called once the file handle is completely initialized.

:c:func:`v4l2_fh_del <v4l2_fh_del>`
(:c:type:`fh <v4l2_fh>`, struct file \*filp)

- Unassociate the file handle from :c:type:`video_device`. The file handle
  exit function may now be called.

:c:func:`v4l2_fh_exit <v4l2_fh_exit>`
(:c:type:`fh <v4l2_fh>`)

- Uninitialise the file handle. After uninitialisation the :c:type:`v4l2_fh`
  memory can be freed.

:c:func:`file_to_v4l2_fh <file_to_v4l2_fh>`
(struct file \*filp)

- Retrieve the :c:type:`v4l2_fh` instance associated with a :c:type:`file`.

독립 v4l2_fh helper

`v4l2_fh`를 driver 전용 구조체에 포함하지 않는 경우 `v4l2_fh_open()`과 `v4l2_fh_release()` helper를 사용할 수 있습니다.

`v4l2_fh_open(filp)`은 `v4l2_fh`를 할당·초기화하고 file에 연결된 `video_device`에 추가합니다.

`v4l2_fh_release(filp)`는 해당 `video_device`에서 file handle을 제거하고 초기화를 해제한 뒤 메모리도 해제합니다.

두 함수는 `v4l2_file_operations`의 `open()`과 `release()` operation에 직접 연결할 수 있습니다.

If struct v4l2_fh is not embedded, then you can use these helper functions:

:c:func:`v4l2_fh_open <v4l2_fh_open>`
(struct file \*filp)

- This allocates a struct v4l2_fh, initializes it and adds it to
  the struct video_device associated with the file struct.

:c:func:`v4l2_fh_release <v4l2_fh_release>`
(struct file \*filp)

- This deletes it from the struct video_device associated with the
  file struct, uninitialised the :c:type:`v4l2_fh` and frees it.

These two functions can be plugged into the v4l2_file_operation's ``open()``
and ``release()`` ops.

첫 open과 마지막 close 판별

여러 driver는 첫 file handle이 열릴 때와 마지막 file handle이 닫힐 때 별도 작업이 필요합니다. 이를 위해 해당 `v4l2_fh`가 연관 device node의 유일한 open file handle인지 검사하는 helper가 제공됩니다.

`v4l2_fh_is_singular(fh)`은 유일한 open file handle이면 1, 아니면 0을 반환합니다.

`v4l2_fh_is_singular_file(filp)`은 같은 검사이지만 `filp->private_data`를 사용해 `v4l2_fh_is_singular()`을 호출합니다.

Several drivers need to do something when the first file handle is opened and
when the last file handle closes. Two helper functions were added to check
whether the :c:type:`v4l2_fh` struct is the only open filehandle of the
associated device node:

:c:func:`v4l2_fh_is_singular <v4l2_fh_is_singular>`
(:c:type:`fh <v4l2_fh>`)

-  Returns 1 if the file handle is the only open file handle, else 0.

:c:func:`v4l2_fh_is_singular_file <v4l2_fh_is_singular_file>`
(struct file \*filp)

- Same, but it calls v4l2_fh_is_singular with filp->private_data.

V4L2 fh 함수와 자료구조

`include/media/v4l2-fh.h`의 kernel-doc에서 V4L2 file handle 함수와 자료구조의 상세 API를 제공합니다.

V4L2 fh functions and data structures
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. kernel-doc:: include/media/v4l2-fh.h