summaryrefslogtreecommitdiff
path: root/Documentation/driver-api
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2021-04-28 09:24:36 -0700
committerLinus Torvalds <torvalds@linux-foundation.org>2021-04-28 09:24:36 -0700
commit3aa139aa9fdc138a84243dc49dc18d9b40e1c6e4 (patch)
tree5f533d8f1c48f0e8bc02b4f8079ed9ffdc14ebc1 /Documentation/driver-api
parentacd3d28594536e9096c1ea76c5867d8a68babef6 (diff)
parent0b276e470a4d43e1365d3eb53c608a3d208cabd4 (diff)
Merge tag 'media/v5.13-1' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media
Pull media updates from Mauro Carvalho Chehab: - addition of a maintainer's profile for the media subsystem - addition of i.MX8 IP support - qcom/camss gained support for hardware version Titan 170 - new RC keymaps - Lots of other improvements, cleanups and bug fixes * tag 'media/v5.13-1' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media: (488 commits) media: coda: fix macroblocks count control usage media: rkisp1: params: fix wrong bits settings media: cedrus: Fix H265 status definitions media: meson-ge2d: fix rotation parameters media: v4l2-ctrls: fix reference to freed memory media: venus : hfi: add venus image info into smem media: venus: Fix internal buffer size calculations for v6. media: venus: helpers: keep max bandwidth when mbps exceeds the supported range media: venus: fix hw overload error log condition media: venus: core: correct firmware name for sm8250 media: venus: core,pm: fix potential infinite loop media: venus: core: Fix kerneldoc warnings media: gscpa/stv06xx: fix memory leak media: cx25821: remove unused including <linux/version.h> media: staging: media/meson: remove redundant dev_err call media: adv7842: support 1 block EDIDs, fix clearing EDID media: adv7842: configure all pads media: allegro: change kernel-doc comment blocks to normal comments media: camss: ispif: Remove redundant dev_err call in msm_ispif_subdev_init() media: i2c: rdamc21: Fix warning on u8 cast ...
Diffstat (limited to 'Documentation/driver-api')
-rw-r--r--Documentation/driver-api/media/camera-sensor.rst3
-rw-r--r--Documentation/driver-api/media/index.rst2
-rw-r--r--Documentation/driver-api/media/maintainer-entry-profile.rst206
-rw-r--r--Documentation/driver-api/media/v4l2-subdev.rst4
4 files changed, 211 insertions, 4 deletions
diff --git a/Documentation/driver-api/media/camera-sensor.rst b/Documentation/driver-api/media/camera-sensor.rst
index 3fc378b3b269..7160336aa475 100644
--- a/Documentation/driver-api/media/camera-sensor.rst
+++ b/Documentation/driver-api/media/camera-sensor.rst
@@ -144,8 +144,7 @@ of the device. This is because the power state of the device is only changed
after the power state transition has taken place. The ``s_ctrl`` callback can be
used to obtain device's power state after the power state transition:
-.. c:function::
- int pm_runtime_get_if_in_use(struct device *dev);
+.. c:function:: int pm_runtime_get_if_in_use(struct device *dev);
The function returns a non-zero value if it succeeded getting the power count or
runtime PM was disabled, in either of which cases the driver may proceed to
diff --git a/Documentation/driver-api/media/index.rst b/Documentation/driver-api/media/index.rst
index c140692454b1..2ad71dfa8828 100644
--- a/Documentation/driver-api/media/index.rst
+++ b/Documentation/driver-api/media/index.rst
@@ -28,6 +28,8 @@ Please see:
:maxdepth: 5
:numbered:
+ maintainer-entry-profile
+
v4l2-core
dtv-core
rc-core
diff --git a/Documentation/driver-api/media/maintainer-entry-profile.rst b/Documentation/driver-api/media/maintainer-entry-profile.rst
new file mode 100644
index 000000000000..eb1cdfd280ba
--- /dev/null
+++ b/Documentation/driver-api/media/maintainer-entry-profile.rst
@@ -0,0 +1,206 @@
+Media Subsystem Profile
+=======================
+
+Overview
+--------
+
+The media subsystem covers support for a variety of devices: stream
+capture, analog and digital TV streams, cameras, remote controllers, HDMI CEC
+and media pipeline control.
+
+It covers, mainly, the contents of those directories:
+
+ - drivers/media
+ - drivers/staging/media
+ - Documentation/admin-guide/media
+ - Documentation/driver-api/media
+ - Documentation/userspace-api/media
+ - Documentation/devicetree/bindings/media/\ [1]_
+ - include/media
+
+.. [1] Device tree bindings are maintained by the
+ OPEN FIRMWARE AND FLATTENED DEVICE TREE BINDINGS maintainers
+ (see the MAINTAINERS file). So, changes there must be reviewed
+ by them before being merged via the media subsystem's development
+ tree.
+
+Both media userspace and Kernel APIs are documented and the documentation
+must be kept in sync with the API changes. It means that all patches that
+add new features to the subsystem must also bring changes to the
+corresponding API files.
+
+Due to the size and wide scope of the media subsystem, media's
+maintainership model is to have sub-maintainers that have a broad
+knowledge of a specific aspect of the subsystem. It is the sub-maintainers'
+task to review the patches, providing feedback to users if the patches are
+following the subsystem rules and are properly using the media kernel and
+userspace APIs.
+
+Patches for the media subsystem must be sent to the media mailing list
+at linux-media@vger.kernel.org as plain text only e-mail. Emails with
+HTML will be automatically rejected by the mail server. It could be wise
+to also copy the sub-maintainer(s).
+
+Media's workflow is heavily based on Patchwork, meaning that, once a patch
+is submitted, the e-mail will first be accepted by the mailing list
+server, and, after a while, it should appear at:
+
+ - https://patchwork.linuxtv.org/project/linux-media/list/
+
+If it doesn't automatically appear there after a few minutes, then
+probably something went wrong on your submission. Please check if the
+email is in plain text\ [2]_ only and if your emailer is not mangling
+whitespaces before complaining or submitting them again.
+
+You can check if the mailing list server accepted your patch, by looking at:
+
+ - https://lore.kernel.org/linux-media/
+
+.. [2] If your email contains HTML, the mailing list server will simply
+ drop it, without any further notice.
+
+
+Media maintainers
++++++++++++++++++
+
+At the media subsystem, we have a group of senior developers that
+are responsible for doing the code reviews at the drivers (also known as
+sub-maintainers), and another senior developer responsible for the
+subsystem as a whole. For core changes, whenever possible, multiple
+media maintainers do the review.
+
+The media maintainers that work on specific areas of the subsystem are:
+
+- Digital TV and remote controllers:
+ Sean Young <sean@mess.org>
+
+- HDMI CEC:
+ Hans Verkuil <hverkuil@xs4all.nl>
+
+- Media controller drivers:
+ Laurent Pinchart <laurent.pinchart@ideasonboard.com>
+
+- ISP, v4l2-async, v4l2-fwnode, v4l2-flash-led-class and Sensor drivers:
+ Sakari Ailus <sakari.ailus@linux.intel.com>
+
+- V4L2 drivers and core V4L2 frameworks:
+ Hans Verkuil <hverkuil@xs4all.nl>
+
+The subsystem maintainer is:
+ Mauro Carvalho Chehab <mchehab@kernel.org>
+
+Media maintainers may delegate a patch to other media maintainers as needed.
+On such case, checkpatch's ``delegate`` field indicates who's currently
+responsible for reviewing a patch.
+
+Submit Checklist Addendum
+-------------------------
+
+Patches that change the Open Firmware/Device Tree bindings must be
+reviewed by the Device Tree maintainers. So, DT maintainers should be
+Cc:ed when those are submitted via devicetree@vger.kernel.org mailing
+list.
+
+There is a set of compliance tools at https://git.linuxtv.org/v4l-utils.git/
+that should be used in order to check if the drivers are properly
+implementing the media APIs:
+
+==================== =======================================================
+Type Tool
+==================== =======================================================
+V4L2 drivers\ [3]_ ``v4l2-compliance``
+V4L2 virtual drivers ``contrib/test/test-media``
+CEC drivers ``cec-compliance``
+==================== =======================================================
+
+.. [3] The ``v4l2-compliance`` also covers the media controller usage inside
+ V4L2 drivers.
+
+Other compilance tools are under development to check other parts of the
+subsystem.
+
+Those tests need to pass before the patches go upstream.
+
+Also, please notice that we build the Kernel with::
+
+ make CF=-D__CHECK_ENDIAN__ CONFIG_DEBUG_SECTION_MISMATCH=y C=1 W=1 CHECK=check_script
+
+Where the check script is::
+
+ #!/bin/bash
+ /devel/smatch/smatch -p=kernel $@ >&2
+ /devel/sparse/sparse $@ >&2
+
+Be sure to not introduce new warnings on your patches without a
+very good reason.
+
+Style Cleanup Patches
++++++++++++++++++++++
+
+Style cleanups are welcome when they come together with other changes
+at the files where the style changes will affect.
+
+We may accept pure standalone style cleanups, but they should ideally
+be one patch for the whole subsystem (if the cleanup is low volume),
+or at least be grouped per directory. So, for example, if you're doing a
+big cleanup change set at drivers under drivers/media, please send a single
+patch for all drivers under drivers/media/pci, another one for
+drivers/media/usb and so on.
+
+Coding Style Addendum
++++++++++++++++++++++
+
+Media development uses ``checkpatch.pl`` on strict mode to verify the code
+style, e.g.::
+
+ $ ./scripts/checkpatch.pl --strict --max-line-length=80
+
+In principle, patches should follow the coding style rules, but exceptions
+are allowed if there are good reasons. On such case, maintainers and reviewers
+may question about the rationale for not addressing the ``checkpatch.pl``.
+
+Please notice that the goal here is to improve code readability. On
+a few cases, ``checkpatch.pl`` may actually point to something that would
+look worse. So, you should use good sense.
+
+Note that addressing one ``checkpatch.pl`` issue (of any kind) alone may lead
+to having longer lines than 80 characters per line. While this is not
+strictly prohibited, efforts should be made towards staying within 80
+characters per line. This could include using re-factoring code that leads
+to less indentation, shorter variable or function names and last but not
+least, simply wrapping the lines.
+
+In particular, we accept lines with more than 80 columns:
+
+ - on strings, as they shouldn't be broken due to line length limits;
+ - when a function or variable name need to have a big identifier name,
+ which keeps hard to honor the 80 columns limit;
+ - on arithmetic expressions, when breaking lines makes them harder to
+ read;
+ - when they avoid a line to end with an open parenthesis or an open
+ bracket.
+
+Key Cycle Dates
+---------------
+
+New submissions can be sent at any time, but if they intend to hit the
+next merge window they should be sent before -rc5, and ideally stabilized
+in the linux-media branch by -rc6.
+
+Review Cadence
+--------------
+
+Provided that your patch is at https://patchwork.linuxtv.org, it should
+be sooner or later handled, so you don't need to re-submit a patch.
+
+Except for bug fixes, we don't usually add new patches to the development
+tree between -rc6 and the next -rc1.
+
+Please notice that the media subsystem is a high traffic one, so it
+could take a while for us to be able to review your patches. Feel free
+to ping if you don't get a feedback in a couple of weeks or to ask
+other developers to publicly add Reviewed-by and, more importantly,
+``Tested-by:`` tags.
+
+Please note that we expect a detailed description for ``Tested-by:``,
+identifying what boards were used at the test and what it was tested.
diff --git a/Documentation/driver-api/media/v4l2-subdev.rst b/Documentation/driver-api/media/v4l2-subdev.rst
index 8b53da2f9c74..7736da077fb8 100644
--- a/Documentation/driver-api/media/v4l2-subdev.rst
+++ b/Documentation/driver-api/media/v4l2-subdev.rst
@@ -208,7 +208,7 @@ the needs of the driver.
:c:func:`v4l2_async_notifier_add_i2c_subdev` are for bridge and ISP drivers for
registering their async sub-devices with the notifier.
-:c:func:`v4l2_async_register_subdev_sensor_common` is a helper function for
+:c:func:`v4l2_async_register_subdev_sensor` is a helper function for
sensor drivers registering their own async sub-device, but it also registers a
notifier and further registers async sub-devices for lens and flash devices
found in firmware. The notifier for the sub-device is unregistered with the
@@ -252,7 +252,7 @@ contain several subdevs that use an I2C bus, but also a subdev that is
controlled through GPIO pins. This distinction is only relevant when setting
up the device, but once the subdev is registered it is completely transparent.
-Once te subdev has been registered you can call an ops function either
+Once the subdev has been registered you can call an ops function either
directly:
.. code-block:: c