1059b1c5bSMauro Carvalho Chehab.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2407e84cdSMauro Carvalho Chehab.. c:namespace:: V4L 354f38fcaSMauro Carvalho Chehab 454f38fcaSMauro Carvalho Chehab.. _VIDIOC_S_HW_FREQ_SEEK: 554f38fcaSMauro Carvalho Chehab 654f38fcaSMauro Carvalho Chehab*************************** 754f38fcaSMauro Carvalho Chehabioctl VIDIOC_S_HW_FREQ_SEEK 854f38fcaSMauro Carvalho Chehab*************************** 954f38fcaSMauro Carvalho Chehab 1054f38fcaSMauro Carvalho ChehabName 1154f38fcaSMauro Carvalho Chehab==== 1254f38fcaSMauro Carvalho Chehab 1354f38fcaSMauro Carvalho ChehabVIDIOC_S_HW_FREQ_SEEK - Perform a hardware frequency seek 1454f38fcaSMauro Carvalho Chehab 1554f38fcaSMauro Carvalho ChehabSynopsis 1654f38fcaSMauro Carvalho Chehab======== 1754f38fcaSMauro Carvalho Chehab 18407e84cdSMauro Carvalho Chehab.. c:macro:: VIDIOC_S_HW_FREQ_SEEK 1954f38fcaSMauro Carvalho Chehab 20407e84cdSMauro Carvalho Chehab``int ioctl(int fd, VIDIOC_S_HW_FREQ_SEEK, struct v4l2_hw_freq_seek *argp)`` 2154f38fcaSMauro Carvalho Chehab 2254f38fcaSMauro Carvalho ChehabArguments 2354f38fcaSMauro Carvalho Chehab========= 2454f38fcaSMauro Carvalho Chehab 2554f38fcaSMauro Carvalho Chehab``fd`` 26407e84cdSMauro Carvalho Chehab File descriptor returned by :c:func:`open()`. 2754f38fcaSMauro Carvalho Chehab 2854f38fcaSMauro Carvalho Chehab``argp`` 2954f38fcaSMauro Carvalho Chehab Pointer to struct :c:type:`v4l2_hw_freq_seek`. 3054f38fcaSMauro Carvalho Chehab 3154f38fcaSMauro Carvalho ChehabDescription 3254f38fcaSMauro Carvalho Chehab=========== 3354f38fcaSMauro Carvalho Chehab 3454f38fcaSMauro Carvalho ChehabStart a hardware frequency seek from the current frequency. To do this 3554f38fcaSMauro Carvalho Chehabapplications initialize the ``tuner``, ``type``, ``seek_upward``, 3654f38fcaSMauro Carvalho Chehab``wrap_around``, ``spacing``, ``rangelow`` and ``rangehigh`` fields, and 3754f38fcaSMauro Carvalho Chehabzero out the ``reserved`` array of a struct 3854f38fcaSMauro Carvalho Chehab:c:type:`v4l2_hw_freq_seek` and call the 3954f38fcaSMauro Carvalho Chehab``VIDIOC_S_HW_FREQ_SEEK`` ioctl with a pointer to this structure. 4054f38fcaSMauro Carvalho Chehab 4154f38fcaSMauro Carvalho ChehabThe ``rangelow`` and ``rangehigh`` fields can be set to a non-zero value 4254f38fcaSMauro Carvalho Chehabto tell the driver to search a specific band. If the struct 4354f38fcaSMauro Carvalho Chehab:c:type:`v4l2_tuner` ``capability`` field has the 4454f38fcaSMauro Carvalho Chehab``V4L2_TUNER_CAP_HWSEEK_PROG_LIM`` flag set, these values must fall 4554f38fcaSMauro Carvalho Chehabwithin one of the bands returned by 4654f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_ENUM_FREQ_BANDS`. If the 4754f38fcaSMauro Carvalho Chehab``V4L2_TUNER_CAP_HWSEEK_PROG_LIM`` flag is not set, then these values 4854f38fcaSMauro Carvalho Chehabmust exactly match those of one of the bands returned by 4954f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_ENUM_FREQ_BANDS`. If the 5054f38fcaSMauro Carvalho Chehabcurrent frequency of the tuner does not fall within the selected band it 5154f38fcaSMauro Carvalho Chehabwill be clamped to fit in the band before the seek is started. 5254f38fcaSMauro Carvalho Chehab 5354f38fcaSMauro Carvalho ChehabIf an error is returned, then the original frequency will be restored. 5454f38fcaSMauro Carvalho Chehab 5554f38fcaSMauro Carvalho ChehabThis ioctl is supported if the ``V4L2_CAP_HW_FREQ_SEEK`` capability is 5654f38fcaSMauro Carvalho Chehabset. 5754f38fcaSMauro Carvalho Chehab 5854f38fcaSMauro Carvalho ChehabIf this ioctl is called from a non-blocking filehandle, then ``EAGAIN`` 5954f38fcaSMauro Carvalho Chehaberror code is returned and no seek takes place. 6054f38fcaSMauro Carvalho Chehab 61*fea13a69SMauro Carvalho Chehab.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| 6254f38fcaSMauro Carvalho Chehab 6354f38fcaSMauro Carvalho Chehab.. c:type:: v4l2_hw_freq_seek 6454f38fcaSMauro Carvalho Chehab 6554f38fcaSMauro Carvalho Chehab.. flat-table:: struct v4l2_hw_freq_seek 6654f38fcaSMauro Carvalho Chehab :header-rows: 0 6754f38fcaSMauro Carvalho Chehab :stub-columns: 0 6854f38fcaSMauro Carvalho Chehab :widths: 1 1 2 6954f38fcaSMauro Carvalho Chehab 7054f38fcaSMauro Carvalho Chehab * - __u32 7154f38fcaSMauro Carvalho Chehab - ``tuner`` 7254f38fcaSMauro Carvalho Chehab - The tuner index number. This is the same value as in the struct 7354f38fcaSMauro Carvalho Chehab :c:type:`v4l2_input` ``tuner`` field and the struct 7454f38fcaSMauro Carvalho Chehab :c:type:`v4l2_tuner` ``index`` field. 7554f38fcaSMauro Carvalho Chehab * - __u32 7654f38fcaSMauro Carvalho Chehab - ``type`` 7754f38fcaSMauro Carvalho Chehab - The tuner type. This is the same value as in the struct 7854f38fcaSMauro Carvalho Chehab :c:type:`v4l2_tuner` ``type`` field. See 7954f38fcaSMauro Carvalho Chehab :c:type:`v4l2_tuner_type` 8054f38fcaSMauro Carvalho Chehab * - __u32 8154f38fcaSMauro Carvalho Chehab - ``seek_upward`` 8254f38fcaSMauro Carvalho Chehab - If non-zero, seek upward from the current frequency, else seek 8354f38fcaSMauro Carvalho Chehab downward. 8454f38fcaSMauro Carvalho Chehab * - __u32 8554f38fcaSMauro Carvalho Chehab - ``wrap_around`` 8654f38fcaSMauro Carvalho Chehab - If non-zero, wrap around when at the end of the frequency range, 8754f38fcaSMauro Carvalho Chehab else stop seeking. The struct :c:type:`v4l2_tuner` 8854f38fcaSMauro Carvalho Chehab ``capability`` field will tell you what the hardware supports. 8954f38fcaSMauro Carvalho Chehab * - __u32 9054f38fcaSMauro Carvalho Chehab - ``spacing`` 9154f38fcaSMauro Carvalho Chehab - If non-zero, defines the hardware seek resolution in Hz. The 9254f38fcaSMauro Carvalho Chehab driver selects the nearest value that is supported by the device. 9354f38fcaSMauro Carvalho Chehab If spacing is zero a reasonable default value is used. 9454f38fcaSMauro Carvalho Chehab * - __u32 9554f38fcaSMauro Carvalho Chehab - ``rangelow`` 9654f38fcaSMauro Carvalho Chehab - If non-zero, the lowest tunable frequency of the band to search in 9754f38fcaSMauro Carvalho Chehab units of 62.5 kHz, or if the struct 9854f38fcaSMauro Carvalho Chehab :c:type:`v4l2_tuner` ``capability`` field has the 9954f38fcaSMauro Carvalho Chehab ``V4L2_TUNER_CAP_LOW`` flag set, in units of 62.5 Hz or if the 10054f38fcaSMauro Carvalho Chehab struct :c:type:`v4l2_tuner` ``capability`` field has 10154f38fcaSMauro Carvalho Chehab the ``V4L2_TUNER_CAP_1HZ`` flag set, in units of 1 Hz. If 10254f38fcaSMauro Carvalho Chehab ``rangelow`` is zero a reasonable default value is used. 10354f38fcaSMauro Carvalho Chehab * - __u32 10454f38fcaSMauro Carvalho Chehab - ``rangehigh`` 10554f38fcaSMauro Carvalho Chehab - If non-zero, the highest tunable frequency of the band to search 10654f38fcaSMauro Carvalho Chehab in units of 62.5 kHz, or if the struct 10754f38fcaSMauro Carvalho Chehab :c:type:`v4l2_tuner` ``capability`` field has the 10854f38fcaSMauro Carvalho Chehab ``V4L2_TUNER_CAP_LOW`` flag set, in units of 62.5 Hz or if the 10954f38fcaSMauro Carvalho Chehab struct :c:type:`v4l2_tuner` ``capability`` field has 11054f38fcaSMauro Carvalho Chehab the ``V4L2_TUNER_CAP_1HZ`` flag set, in units of 1 Hz. If 11154f38fcaSMauro Carvalho Chehab ``rangehigh`` is zero a reasonable default value is used. 11254f38fcaSMauro Carvalho Chehab * - __u32 11354f38fcaSMauro Carvalho Chehab - ``reserved``\ [5] 11454f38fcaSMauro Carvalho Chehab - Reserved for future extensions. Applications must set the array to 11554f38fcaSMauro Carvalho Chehab zero. 11654f38fcaSMauro Carvalho Chehab 11754f38fcaSMauro Carvalho ChehabReturn Value 11854f38fcaSMauro Carvalho Chehab============ 11954f38fcaSMauro Carvalho Chehab 12054f38fcaSMauro Carvalho ChehabOn success 0 is returned, on error -1 and the ``errno`` variable is set 12154f38fcaSMauro Carvalho Chehabappropriately. The generic error codes are described at the 12254f38fcaSMauro Carvalho Chehab:ref:`Generic Error Codes <gen-errors>` chapter. 12354f38fcaSMauro Carvalho Chehab 12454f38fcaSMauro Carvalho ChehabEINVAL 12554f38fcaSMauro Carvalho Chehab The ``tuner`` index is out of bounds, the ``wrap_around`` value is 12654f38fcaSMauro Carvalho Chehab not supported or one of the values in the ``type``, ``rangelow`` or 12754f38fcaSMauro Carvalho Chehab ``rangehigh`` fields is wrong. 12854f38fcaSMauro Carvalho Chehab 12954f38fcaSMauro Carvalho ChehabEAGAIN 13054f38fcaSMauro Carvalho Chehab Attempted to call ``VIDIOC_S_HW_FREQ_SEEK`` with the filehandle in 13154f38fcaSMauro Carvalho Chehab non-blocking mode. 13254f38fcaSMauro Carvalho Chehab 13354f38fcaSMauro Carvalho ChehabENODATA 13454f38fcaSMauro Carvalho Chehab The hardware seek found no channels. 13554f38fcaSMauro Carvalho Chehab 13654f38fcaSMauro Carvalho ChehabEBUSY 13754f38fcaSMauro Carvalho Chehab Another hardware seek is already in progress. 138