diff options
Diffstat (limited to 'Documentation/driver-api')
| -rw-r--r-- | Documentation/driver-api/dpll.rst | 18 | ||||
| -rw-r--r-- | Documentation/driver-api/early-userspace/buffer-format.rst | 5 | ||||
| -rw-r--r-- | Documentation/driver-api/media/camera-sensor.rst | 24 | ||||
| -rw-r--r-- | Documentation/driver-api/media/maintainer-entry-profile.rst | 4 | ||||
| -rw-r--r-- | Documentation/driver-api/media/v4l2-fh.rst | 59 |
5 files changed, 68 insertions, 42 deletions
diff --git a/Documentation/driver-api/dpll.rst b/Documentation/driver-api/dpll.rst index eca72d9b9ed8..be1fc643b645 100644 --- a/Documentation/driver-api/dpll.rst +++ b/Documentation/driver-api/dpll.rst @@ -179,7 +179,23 @@ Phase offset measurement and adjustment Device may provide ability to measure a phase difference between signals on a pin and its parent dpll device. If pin-dpll phase offset measurement is supported, it shall be provided with ``DPLL_A_PIN_PHASE_OFFSET`` -attribute for each parent dpll device. +attribute for each parent dpll device. The reported phase offset may be +computed as the average of prior values and the current measurement, using +the following formula: + +.. math:: + curr\_avg = prev\_avg * \frac{2^N-1}{2^N} + new\_val * \frac{1}{2^N} + +where `curr_avg` is the current reported phase offset, `prev_avg` is the +previously reported value, `new_val` is the current measurement, and `N` is +the averaging factor. Configured averaging factor value is provided with +``DPLL_A_PHASE_OFFSET_AVG_FACTOR`` attribute of a device and value change can +be requested with the same attribute with ``DPLL_CMD_DEVICE_SET`` command. + + ================================== ====================================== + ``DPLL_A_PHASE_OFFSET_AVG_FACTOR`` attr configured value of phase offset + averaging factor + ================================== ====================================== Device may also provide ability to adjust a signal phase on a pin. If pin phase adjustment is supported, minimal and maximal values that pin diff --git a/Documentation/driver-api/early-userspace/buffer-format.rst b/Documentation/driver-api/early-userspace/buffer-format.rst index 726bfa2fe70d..4597a91100b7 100644 --- a/Documentation/driver-api/early-userspace/buffer-format.rst +++ b/Documentation/driver-api/early-userspace/buffer-format.rst @@ -86,6 +86,11 @@ c_mtime is ignored unless CONFIG_INITRAMFS_PRESERVE_MTIME=y is set. The c_filesize should be zero for any file which is not a regular file or symlink. +c_namesize may account for more than one trailing '\0', as long as the +value doesn't exceed PATH_MAX. This can be useful for ensuring that a +subsequent file data segment is aligned, e.g. to a filesystem block +boundary. + The c_chksum field contains a simple 32-bit unsigned sum of all the bytes in the data field. cpio(1) refers to this as "crc", which is clearly incorrect (a cyclic redundancy check is a different and diff --git a/Documentation/driver-api/media/camera-sensor.rst b/Documentation/driver-api/media/camera-sensor.rst index c290833165e6..94bd1dae82d5 100644 --- a/Documentation/driver-api/media/camera-sensor.rst +++ b/Documentation/driver-api/media/camera-sensor.rst @@ -29,21 +29,31 @@ used in the system. Using another frequency may cause harmful effects elsewhere. Therefore only the pre-determined frequencies are configurable by the user. +The external clock frequency shall be retrieved by obtaining the external clock +using the ``devm_v4l2_sensor_clk_get()`` helper function, and then getting its +frequency with ``clk_get_rate()``. Usage of the helper function guarantees +correct behaviour regardless of whether the sensor is integrated in a DT-based +or ACPI-based system. + ACPI ~~~~ -Read the ``clock-frequency`` _DSD property to denote the frequency. The driver -can rely on this frequency being used. +ACPI-based systems typically don't register the sensor external clock with the +kernel, but specify the external clock frequency in the ``clock-frequency`` +_DSD property. The ``devm_v4l2_sensor_clk_get()`` helper creates and returns a +fixed clock set at that rate. Devicetree ~~~~~~~~~~ -The preferred way to achieve this is using ``assigned-clocks``, -``assigned-clock-parents`` and ``assigned-clock-rates`` properties. See the -`clock device tree bindings +Devicetree-based systems declare the sensor external clock in the device tree +and reference it from the sensor node. The preferred way to select the external +clock frequency is to use the ``assigned-clocks``, ``assigned-clock-parents`` +and ``assigned-clock-rates`` properties in the sensor node to set the clock +rate. See the `clock device tree bindings <https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/clock/clock.yaml>`_ -for more information. The driver then gets the frequency using -``clk_get_rate()``. +for more information. The ``devm_v4l2_sensor_clk_get()`` helper retrieves and +returns that clock. This approach has the drawback that there's no guarantee that the frequency hasn't been modified directly or indirectly by another driver, or supported by diff --git a/Documentation/driver-api/media/maintainer-entry-profile.rst b/Documentation/driver-api/media/maintainer-entry-profile.rst index ad96a89ee916..2127e5b15e8f 100644 --- a/Documentation/driver-api/media/maintainer-entry-profile.rst +++ b/Documentation/driver-api/media/maintainer-entry-profile.rst @@ -75,7 +75,7 @@ The media maintainers that work on specific areas of the subsystem are: Sean Young <sean@mess.org> - HDMI CEC: - Hans Verkuil <hverkuil@xs4all.nl> + Hans Verkuil <hverkuil@kernel.org> - Media controller drivers: Laurent Pinchart <laurent.pinchart@ideasonboard.com> @@ -84,7 +84,7 @@ The media maintainers that work on specific areas of the subsystem are: Sakari Ailus <sakari.ailus@linux.intel.com> - V4L2 drivers and core V4L2 frameworks: - Hans Verkuil <hverkuil@xs4all.nl> + Hans Verkuil <hverkuil@kernel.org> The subsystem maintainer is: Mauro Carvalho Chehab <mchehab@kernel.org> diff --git a/Documentation/driver-api/media/v4l2-fh.rst b/Documentation/driver-api/media/v4l2-fh.rst index 3eeaa8da0c9e..a934caa483a4 100644 --- a/Documentation/driver-api/media/v4l2-fh.rst +++ b/Documentation/driver-api/media/v4l2-fh.rst @@ -1,33 +1,27 @@ .. SPDX-License-Identifier: GPL-2.0 -V4L2 File handlers ------------------- +V4L2 File handles +----------------- -struct v4l2_fh provides a way to easily keep file handle specific -data that is used by the V4L2 framework. +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. -.. attention:: - New drivers must use struct v4l2_fh - since it is also used to implement priority handling - (:ref:`VIDIOC_G_PRIORITY`). +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`. -The users of :c:type:`v4l2_fh` (in the V4L2 framework, not the driver) know -whether a driver uses :c:type:`v4l2_fh` as its ``file->private_data`` pointer -by testing the ``V4L2_FL_USES_V4L2_FH`` bit in :c:type:`video_device`->flags. -This bit is set whenever :c:func:`v4l2_fh_init` is called. +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. -struct v4l2_fh is allocated as a part of the driver's own file handle -structure and ``file->private_data`` is set to it in the driver's ``open()`` -function by the driver. - -In many cases the struct v4l2_fh will be embedded in a larger -structure. In that case you should call: - -#) :c:func:`v4l2_fh_init` and :c:func:`v4l2_fh_add` in ``open()`` -#) :c:func:`v4l2_fh_del` and :c:func:`v4l2_fh_exit` in ``release()`` - -Drivers can extract their own file handle structure by using the container_of -macro. +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. Example: @@ -56,18 +50,17 @@ Example: ... - file->private_data = &my_fh->fh; - v4l2_fh_add(&my_fh->fh); + v4l2_fh_add(&my_fh->fh, file); return 0; } int my_release(struct file *file) { - struct v4l2_fh *fh = file->private_data; + 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); + v4l2_fh_del(&my_fh->fh, file); v4l2_fh_exit(&my_fh->fh); kfree(my_fh); return 0; @@ -78,19 +71,17 @@ 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>`) +(: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>`) +(: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. @@ -101,6 +92,10 @@ Below is a short description of the :c:type:`v4l2_fh` functions used: - 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`. If struct v4l2_fh is not embedded, then you can use these helper functions: |