VIDIOC_S_HW_FREQ_SEEK ioctl

목적, 호출 형식과 인자

`VIDIOC_S_HW_FREQ_SEEK`는 현재 튜너 주파수에서 하드웨어 주파수 탐색을 시작합니다. `fd`는 `open()`이 반환한 파일 디스크립터이고, `argp`는 탐색 조건을 담은 `struct v4l2_hw_freq_seek`를 가리킵니다.

.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _VIDIOC_S_HW_FREQ_SEEK:

***************************
ioctl VIDIOC_S_HW_FREQ_SEEK
***************************

Name
====

VIDIOC_S_HW_FREQ_SEEK - Perform a hardware frequency seek

Synopsis
========

.. c:macro:: VIDIOC_S_HW_FREQ_SEEK

``int ioctl(int fd, VIDIOC_S_HW_FREQ_SEEK, struct v4l2_hw_freq_seek *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to struct :c:type:`v4l2_hw_freq_seek`.

탐색 범위와 실행 조건

응용 프로그램은 `tuner`, `type`, `seek_upward`, `wrap_around`, `spacing`, `rangelow`, `rangehigh`를 설정하고 `reserved` 배열을 0으로 만든 뒤 ioctl을 호출합니다.

`rangelow`와 `rangehigh`가 0이 아니면 검색할 주파수 대역을 제한합니다. `V4L2_TUNER_CAP_HWSEEK_PROG_LIM`이 있으면 두 값은 `VIDIOC_ENUM_FREQ_BANDS`가 반환한 어느 한 대역 안에 있으면 되지만, 이 기능이 없으면 대역의 하한과 상한에 정확히 일치해야 합니다.

현재 주파수가 선택한 대역 밖이면 드라이버는 탐색 전에 가장 가까운 대역 경계로 보정합니다. 탐색이 오류로 끝나면 원래 주파수를 복원하므로 실패한 호출이 튜너의 기존 조정을 남기지 않습니다.

장치가 이 ioctl을 제공하려면 `V4L2_CAP_HW_FREQ_SEEK` capability가 설정되어 있어야 합니다. 비차단 파일 핸들에서는 탐색을 시작하지 않고 `EAGAIN`을 반환합니다.

Description
===========

Start a hardware frequency seek from the current frequency. To do this
applications initialize the ``tuner``, ``type``, ``seek_upward``,
``wrap_around``, ``spacing``, ``rangelow`` and ``rangehigh`` fields, and
zero out the ``reserved`` array of a struct
:c:type:`v4l2_hw_freq_seek` and call the
``VIDIOC_S_HW_FREQ_SEEK`` ioctl with a pointer to this structure.

The ``rangelow`` and ``rangehigh`` fields can be set to a non-zero value
to tell the driver to search a specific band. If the struct
:c:type:`v4l2_tuner` ``capability`` field has the
``V4L2_TUNER_CAP_HWSEEK_PROG_LIM`` flag set, these values must fall
within one of the bands returned by
:ref:`VIDIOC_ENUM_FREQ_BANDS`. If the
``V4L2_TUNER_CAP_HWSEEK_PROG_LIM`` flag is not set, then these values
must exactly match those of one of the bands returned by
:ref:`VIDIOC_ENUM_FREQ_BANDS`. If the
current frequency of the tuner does not fall within the selected band it
will be clamped to fit in the band before the seek is started.

If an error is returned, then the original frequency will be restored.

This ioctl is supported if the ``V4L2_CAP_HW_FREQ_SEEK`` capability is
set.

If this ioctl is called from a non-blocking filehandle, then ``EAGAIN``
error code is returned and no seek takes place.

struct v4l2_hw_freq_seek

`rangelow`와 `rangehigh`의 단위는 기본적으로 62.5 kHz입니다. `V4L2_TUNER_CAP_LOW`가 설정되면 62.5 Hz, `V4L2_TUNER_CAP_1HZ`가 설정되면 1 Hz 단위를 사용합니다.

`wrap_around` 지원 여부는 `v4l2_tuner.capability`에서 확인해야 합니다. 장치가 지원하지 않는 값을 요청하면 탐색을 시작하지 않고 `EINVAL`을 반환합니다.

.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|

.. c:type:: v4l2_hw_freq_seek

.. flat-table:: struct v4l2_hw_freq_seek
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2

    * - __u32
      - ``tuner``
      - The tuner index number. This is the same value as in the struct
	:c:type:`v4l2_input` ``tuner`` field and the struct
	:c:type:`v4l2_tuner` ``index`` field.
    * - __u32
      - ``type``
      - The tuner type. This is the same value as in the struct
	:c:type:`v4l2_tuner` ``type`` field. See
	:c:type:`v4l2_tuner_type`
    * - __u32
      - ``seek_upward``
      - If non-zero, seek upward from the current frequency, else seek
	downward.
    * - __u32
      - ``wrap_around``
      - If non-zero, wrap around when at the end of the frequency range,
	else stop seeking. The struct :c:type:`v4l2_tuner`
	``capability`` field will tell you what the hardware supports.
    * - __u32
      - ``spacing``
      - If non-zero, defines the hardware seek resolution in Hz. The
	driver selects the nearest value that is supported by the device.
	If spacing is zero a reasonable default value is used.
    * - __u32
      - ``rangelow``
      - If non-zero, the lowest tunable frequency of the band to search in
	units of 62.5 kHz, or if the struct
	:c:type:`v4l2_tuner` ``capability`` field has the
	``V4L2_TUNER_CAP_LOW`` flag set, in units of 62.5 Hz or if the
	struct :c:type:`v4l2_tuner` ``capability`` field has
	the ``V4L2_TUNER_CAP_1HZ`` flag set, in units of 1 Hz. If
	``rangelow`` is zero a reasonable default value is used.
    * - __u32
      - ``rangehigh``
      - If non-zero, the highest tunable frequency of the band to search
	in units of 62.5 kHz, or if the struct
	:c:type:`v4l2_tuner` ``capability`` field has the
	``V4L2_TUNER_CAP_LOW`` flag set, in units of 62.5 Hz or if the
	struct :c:type:`v4l2_tuner` ``capability`` field has
	the ``V4L2_TUNER_CAP_1HZ`` flag set, in units of 1 Hz. If
	``rangehigh`` is zero a reasonable default value is used.
    * - __u32
      - ``reserved``\ [5]
      - Reserved for future extensions. Applications must set the array to
	zero.

반환값과 오류

성공하면 0, 오류이면 -1을 반환하고 `errno`를 설정합니다. 오류가 반환된 탐색은 원래 주파수를 복원합니다.

Return Value
============

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

EINVAL
    The ``tuner`` index is out of bounds, the ``wrap_around`` value is
    not supported or one of the values in the ``type``, ``rangelow`` or
    ``rangehigh`` fields is wrong.

EAGAIN
    Attempted to call ``VIDIOC_S_HW_FREQ_SEEK`` with the filehandle in
    non-blocking mode.

ENODATA
    The hardware seek found no channels.

EBUSY
    Another hardware seek is already in progress.