1.. SPDX-License-Identifier: GPL-2.0 2 3Media Subsystem Profile 4======================= 5 6Overview 7-------- 8 9The Linux Media Community (aka: the LinuxTV Community) is formed by 10developers working on Linux Kernel Media Subsystem, together with users 11who also play an important role in testing the code. 12 13The Media Subsystem has code to support a wide variety of media-related 14devices: stream capture, analog and digital TV streams, cameras, 15video codecs, video processing (resizers, etc.), radio, remote controllers, 16HDMI CEC and media pipeline control. 17 18The Media Subsystem consists of the following directories in the kernel 19tree: 20 21 - drivers/media 22 - drivers/staging/media 23 - include/media 24 - Documentation/devicetree/bindings/media/\ [1]_ 25 - Documentation/admin-guide/media 26 - Documentation/driver-api/media 27 - Documentation/userspace-api/media 28 29.. [1] Device tree bindings are maintained by the 30 OPEN FIRMWARE AND FLATTENED DEVICE TREE BINDINGS maintainers 31 (see the MAINTAINERS file). So, changes there must be reviewed 32 by them before being merged into the media subsystem's development 33 tree. 34 35Both media userspace and Kernel APIs are documented and the documentation 36must be kept in sync with the API changes. It means that all patches that 37add new features to the subsystem must also bring changes to the 38corresponding API documentation. 39 40Media Maintainers 41----------------- 42 43Media Maintainers are not just people capable of writing code, but they 44are developers who have demonstrated their ability to collaborate with 45the team, get the most knowledgeable people to review code, contribute 46high-quality code, and follow through to fix issues (in code or tests). 47 48Due to the size and wide scope of the media subsystem, multiple layers of 49maintainers are required, each with their own areas of expertise: 50 51- **Media Driver Maintainer**: 52 Responsible for one or more drivers within the Media Subsystem. They 53 are listed in the MAINTAINERS file as maintainer for those drivers. Media 54 Driver Maintainers review patches for those drivers, provide feedback if 55 patches do not follow the subsystem rules, or are not using the 56 media kernel or userspace APIs correctly, or if they have poor code 57 quality. 58 59 If you are the patch author, you work with other Media 60 Maintainers to ensure your patches are reviewed. 61 62 Some Media Driver Maintainers have additional responsibilities. They have 63 been granted Patchwork access and keep 64 `Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_ 65 up to date, decide when patches are ready for merging, and create Pull 66 Requests for the Media Subsystem Maintainers to merge. 67 68- **Media Core Maintainer**: 69 Media Driver Maintainers with Patchwork access who are also responsible for 70 one or more media core frameworks. 71 72 Core framework changes are done via consensus between the relevant Media 73 Core Maintainers. Media Maintainers may include core framework changes in 74 their Pull Requests if they are signed off by the relevant Media Core 75 Maintainers. 76 77- **Media Subsystem Maintainers**: 78 Media Core Maintainers who are also responsible for the subsystem as a 79 whole, with access to the entire subsystem. Responsible for merging Pull 80 Requests from other Media Maintainers. 81 82 Userspace API/ABI changes are made via consensus among Media Subsystem 83 Maintainers\ [2]_. Media Maintainers may include API/ABI changes in 84 their Pull Requests if they are signed off by all Media Subsystem 85 Maintainers. 86 87All Media Maintainers shall agree with the Kernel development process as 88described in Documentation/process/index.rst and with the Kernel development 89rules in the Kernel documentation, including its code of conduct. 90 91Media Maintainers are often reachable via the #linux-media IRC channel at OFTC. 92 93.. [2] Everything that would break backward compatibility with existing 94 non-kernel code are API/ABI changes. This includes ioctl and sysfs 95 interfaces, v4l2 controls, and their behaviors. 96 97Patchwork Access 98---------------- 99 100All Media Maintainers who have been granted Patchwork access shall ensure that 101`Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_ 102will reflect the current status, e.g. patches shall be delegated to the Media 103Maintainer who is handling them and the patch status shall be updated according 104to these rules: 105 106- ``Under Review``: Used if the patch requires a second opinion 107 or when it is part of a Pull Request; 108- ``Superseded``: There is a newer version of the patch posted to the 109 mailing list. 110- ``Duplicated``: There was another patch doing the same thing from someone 111 else that was accepted. 112- ``Not Applicable``: Use for patch series that are not merged at media.git 113 tree (e.g. drm, dmabuf, upstream merge, etc.) but were cross-posted to the 114 linux-media mailing list. 115- ``Accepted``: Once a patch is merged in the multi-committer tree. Only Media 116 Maintainers with commit rights are allowed to set this state. 117 118If Media Maintainers decide not to accept a patch, they should reply to the 119patch authors by e‑mail, explaining why it is not accepted, and 120update `Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_ 121accordingly with one of the following statuses: 122 123- ``Changes Requested``: if a new revision was requested; 124- ``Rejected``: if the proposed change is not acceptable at all. 125 126.. Note:: 127 128 Patchwork supports a couple of clients to help semi-automate 129 status updates via its REST interface: 130 131 https://patchwork.readthedocs.io/en/latest/usage/clients/ 132 133For patches that fall within their area of responsibility a Media Maintainer 134also decides when those patches are ready for merging, and create Pull Requests 135for the Media Subsystem Maintainers to merge. 136 137The most important aspect of becoming a Media Maintainer with Patchwork access 138is that you have demonstrated an ability to give good code reviews. We value 139your ability to deliver thorough, constructive code reviews. 140 141As such, potential maintainers must earn enough credibility and trust from the 142Linux Media Community. To do that, developers shall be familiar with the open 143source model and have been active in the Linux Kernel community for some time, 144and, in particular, in the media subsystem. 145 146In addition to actually making the code changes, you are basically 147demonstrating your: 148 149- commitment to the project; 150- ability to collaborate with the team and communicate well; 151- understanding of how upstream and the Linux Media Community work 152 (policies, processes for testing, code review, ...) 153- reasonable knowledge about: 154 155 - the Kernel development process: 156 Documentation/process/index.rst 157 158 - the Media development profile: 159 Documentation/driver-api/media/maintainer-entry-profile.rst 160 161- understanding of the projects' code base and coding style; 162- ability to provide feedback to the patch authors; 163- ability to judge when a patch might be ready for review and to submit; 164- ability to write good code (last but certainly not least). 165 166Media Driver Maintainers that desire to get Patchwork access are encouraged 167to participate at the yearly Linux Media Summit, typically co-located with 168a Linux-related conference. These summits are announced on the linux-media 169mailing list. 170 171If you are doing such tasks and have become a valued developer, an 172existing Media Maintainer can nominate you to the Media Subsystem Maintainers. 173 174The ultimate responsibility for accepting a nominated maintainer is up to 175the subsystem's maintainers. The nominated maintainer must have earned a trust 176relationship with all Media Subsystem Maintainers, as, by being granted 177Patchwork access, you will take over part of their maintenance tasks. 178 179Media Committers 180---------------- 181 182Experienced and trusted Media Maintainers may be granted commit rights 183which allow them to directly push patches to the media development tree instead 184of posting a Pull Request for the Media Subsystem Maintainers. This helps 185offloading some of the work of the Media Subsystem Maintainers. 186 187More details about Media Committers' roles and responsibilities can be 188found here: :ref:`Media Committers`. 189 190Media development sites 191----------------------- 192 193The `LinuxTV <https://linuxtv.org/>`_ web site hosts news about the subsystem, 194together with: 195 196- `Wiki pages <https://www.linuxtv.org/wiki/index.php/Main_Page>`_; 197- `Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_; 198- `Linux Media documentation <https://linuxtv.org/docs.php>`_; 199- and more. 200 201The main development trees used by the media subsystem are at: 202 203- Stable tree: 204 - https://git.linuxtv.org/media.git/ 205 206- Media committers tree: 207 - https://gitlab.freedesktop.org/linux-media/media-committers.git 208 209 Please note that it can be rebased, although only as a last resort. 210 211- Media development trees, including apps and CI: 212 213 - https://git.linuxtv.org/ 214 - https://gitlab.freedesktop.org/linux-media/ 215 216 217.. _Media development workflow: 218 219Media development workflow 220++++++++++++++++++++++++++ 221 222All changes for the media subsystem shall be sent first as e-mails to the 223media mailing list, following the process documented at 224Documentation/process/index.rst. 225 226It means that patches shall be submitted as plain text only via e-mail to 227linux-media@vger.kernel.org (aka: LMML). While subscription is not mandatory, 228you can find details about how to subscribe to it and to see its archives at: 229 230 https://subspace.kernel.org/vger.kernel.org.html 231 232Emails with HTML will be automatically rejected by the mail server. 233 234It could be wise to also copy the relevant Media Maintainer(s). You should use 235``scripts/get_maintainers.pl`` to identify whom else needs to be copied. 236Please always copy driver's authors and maintainers. 237 238To minimize the chance of merge conflicts for your patch series, and make it 239easier to backport patches to stable Kernels, we recommend that you use the 240following baseline for your patch series: 241 2421. Features for the next mainline release: 243 244 - baseline shall be the ``media-committers.git next`` branch; 245 2462. Bug fixes for the next mainline release: 247 248 - baseline shall be the ``media-committers.git next`` branch. If the 249 changes depend on a fix from the ``media-committers.git fixes`` 250 branch, then you can use that as baseline. 251 2523. Bug fixes for the current mainline release (-rcX): 253 254 - baseline shall be the latest mainline -rcX release or the 255 ``media-committers.git fixes`` branch if changes depend on a mainline 256 fix that is not yet merged; 257 258.. Note:: 259 260 See https://www.kernel.org/category/releases.html for an overview 261 about Kernel release types. 262 263Patches with fixes shall have: 264 265- a ``Fixes:`` tag pointing to the first commit that introduced the bug; 266- when applicable, a ``Cc: stable@vger.kernel.org``. 267 268Patches that were fixing bugs publicly reported by someone at the 269linux-media@vger.kernel.org mailing list shall have: 270 271- a ``Reported-by:`` tag immediately followed by a ``Closes:`` tag. 272 273Patches that change API shall update documentation accordingly at the 274same patch series. 275 276See Documentation/process/index.rst for more details about e-mail submission. 277 278Once a patch is submitted, it may follow either one of the following 279workflows: 280 281a. Media Maintainers' workflow: Media Maintainers post the Pull Requests, 282 which are handled by the Media Subsystem Maintainers:: 283 284 +-------+ +------------+ +------+ +-------+ +---------------------+ 285 |e-mail |-->|picked up by|-->|code |-->|pull |-->|Subsystem Maintainers| 286 |to LMML| |Patchwork | |review| |request| |merge in | 287 | | | | | | | | |media-committers.git | 288 +-------+ +------------+ +------+ +-------+ +---------------------+ 289 290 For this workflow, Pull Requests are generated by Media Maintainers with 291 Patchwork access. If you do not have Patchwork access, then please don't 292 submit Pull Requests, as they will not be processed. 293 294b. Media Committers' workflow: patches are handled by Media Maintainers with 295 commit rights:: 296 297 +-------+ +------------+ +------+ +--------------------------+ 298 |e-mail |-->|picked up by|-->|code |-->|Media Committers merge in | 299 |to LMML| |Patchwork | |review| |media-committers.git | 300 +-------+ +------------+ +------+ +--------------------------+ 301 302When patches are picked up by 303`Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_ 304and when merged at media-committers, Media CI bots will check for errors and 305may provide e-mail feedback about patch problems. When this happens, the patch 306submitter must fix them or explain why the errors are false positives. 307 308Patches will only be moved to the next stage in these two workflows if they 309pass on Media CI or if there are false-positives in the Media CI reports. 310 311For both workflows, all patches shall be properly reviewed at 312linux-media@vger.kernel.org (LMML) before being merged in 313``media-committers.git``. Media patches will be reviewed in a timely manner 314by the maintainers and reviewers as listed in the MAINTAINERS file. 315 316Media Maintainers shall request reviews from other Media Maintainers and 317developers where applicable, i.e. because those developers have more 318knowledge about some areas that are changed by a patch. 319 320There shall be no open issues or unresolved or conflicting feedback 321from anyone. Clear them up first. Defer to the Media Subsystem 322Maintainers if needed. 323 324Failures during e-mail submission 325+++++++++++++++++++++++++++++++++ 326 327Media's workflow is heavily based on Patchwork, meaning that, once a patch 328is submitted, the e-mail will first be accepted by the mailing list 329server, and, after a while, it should appear at: 330 331 - https://patchwork.linuxtv.org/project/linux-media/list/ 332 333If it doesn't automatically appear there after some time [3]_, then 334probably something went wrong on your submission. Please check if the 335email is in plain text\ [4]_ only and if your emailer is not mangling 336whitespaces before complaining or submitting them again. 337 338To troubleshoot problems, you should first check if the mailing list 339server has accepted your patch, by looking at: 340 341 - https://lore.kernel.org/linux-media/ 342 343If the patch is there and not at 344`Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_, 345it is likely that your e-mailer mangled the patch. Patchwork internally 346has logic that checks if the received e-mail contains a valid patch. 347Any whitespace and new line breakages mangling the patch won't be recognized by 348`Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_, 349and such a patch will be rejected. 350 351.. [3] It usually takes a few minutes for the patch to arrive, but 352 the e-mail server may be busy, so it may take a longer time 353 for a patch to be picked by 354 `Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_. 355 356.. [4] If your email contains HTML, the mailing list server will simply 357 drop it, without any further notice. 358 359.. _media-developers-gpg: 360 361Authentication for pull and merge requests 362++++++++++++++++++++++++++++++++++++++++++ 363 364The authenticity of developers submitting Pull Requests and merge requests 365shall be validated by using the Linux Kernel Web of Trust, with PGP signing 366at some moment. See: :ref:`kernel_org_trust_repository`. 367 368With the Pull Request workflow, Pull Requests shall use PGP-signed tags. 369 370With the committers' workflow, this is ensured at the time merge request 371rights will be granted to the gitlab instance used by the media-committers.git 372tree, after receiving the e-mail documented in 373:ref:`media-committer-agreement`. 374 375For more details about PGP signing, please read 376Documentation/process/maintainer-pgp-guide.rst. 377 378Maintaining media maintainer status 379----------------------------------- 380 381See :ref:`Maintain Media Status`. 382 383List of Media Maintainers 384------------------------- 385 386The Media Maintainers listed here all have patchwork access and can 387make Pull Requests or have commit rights. 388 389The Media Subsystem Maintainers are: 390 - Mauro Carvalho Chehab <mchehab@kernel.org> 391 - Hans Verkuil <hverkuil@kernel.org> 392 393The Media Core Maintainers are: 394 - Sakari Ailus <sakari.ailus@linux.intel.com> 395 396 - Media controller drivers 397 - Core media controller framework 398 - ISP 399 - sensor drivers 400 - v4l2-async and v4l2-fwnode core frameworks 401 - v4l2-flash-led-class core framework 402 403 - Mauro Carvalho Chehab <mchehab@kernel.org> 404 405 - DVB 406 407 - Laurent Pinchart <laurent.pinchart@ideasonboard.com> 408 409 - Media controller drivers 410 - Core media controller framework 411 - ISP 412 413 - Hans Verkuil <hverkuil@kernel.org> 414 415 - V4L2 drivers 416 - V4L2 and videobuf2 core frameworks 417 - HDMI CEC drivers 418 - HDMI CEC core framework 419 420 - Sean Young <sean@mess.org> 421 422 - Remote Controller (infrared) drivers 423 - Remote Controller (infrared) core framework 424 425The Media Driver Maintainers responsible for specific areas are: 426 - Nicolas Dufresne <nicolas.dufresne@collabora.com> 427 428 - Codec drivers 429 - M2M driver not otherwise delegated 430 431 - Bryan O'Donoghue <bryan.odonoghue@linaro.org> 432 433 - Qualcomm drivers 434 435Submit Checklist Addendum 436------------------------- 437 438Patches that change the Open Firmware/Device Tree bindings must be 439reviewed by the Device Tree maintainers. So, DT maintainers should be 440Cc:ed when those are submitted via devicetree@vger.kernel.org mailing 441list. 442 443There is a set of compliance tools at https://git.linuxtv.org/v4l-utils.git/ 444that should be used in order to check if the drivers are properly 445implementing the media APIs: 446 447==================== ======================================================= 448Type Utility 449==================== ======================================================= 450V4L2 drivers\ [5]_ ``v4l2-compliance`` 451V4L2 virtual drivers ``contrib/test/test-media`` 452CEC drivers ``cec-compliance`` 453==================== ======================================================= 454 455.. [5] The ``v4l2-compliance`` utility also covers the media controller usage 456 inside V4L2 drivers. 457 458Those tests need to pass before the patches go upstream. 459 460Also, please notice that we build the Kernel with:: 461 462 make CF=-D__CHECK_ENDIAN__ CONFIG_DEBUG_SECTION_MISMATCH=y C=1 W=1 CHECK=check_script 463 464Where the check script is:: 465 466 #!/bin/bash 467 /devel/smatch/smatch -p=kernel $@ >&2 468 /devel/sparse/sparse $@ >&2 469 470Be sure to not introduce new warnings on your patches without a 471very good reason. 472 473Please see `Media development workflow`_ for e-mail submission rules. 474 475Style Cleanup Patches 476+++++++++++++++++++++ 477 478Style cleanups are welcome when they come together with other changes 479at the files where the style changes will affect. 480 481We may accept pure standalone style cleanups, but they should ideally 482be one patch for the whole subsystem (if the cleanup is low volume), 483or at least be grouped per directory. So, for example, if you're doing a 484big cleanup change set at drivers under drivers/media, please send a single 485patch for all drivers under drivers/media/pci, another one for 486drivers/media/usb and so on. 487 488Coding Style Addendum 489+++++++++++++++++++++ 490 491Media development uses ``checkpatch.pl`` on strict mode to verify the code 492style, e.g.:: 493 494 $ ./scripts/checkpatch.pl --strict --max-line-length=80 495 496In principle, patches should follow the coding style rules, but exceptions 497are allowed if there are good reasons. On such case, maintainers and reviewers 498may question about the rationale for not addressing the ``checkpatch.pl``. 499 500Please notice that the goal here is to improve code readability. On 501a few cases, ``checkpatch.pl`` may actually point to something that would 502look worse. So, you should use good sense. 503 504Note that addressing one ``checkpatch.pl`` issue (of any kind) alone may lead 505to having longer lines than 80 characters per line. While this is not 506strictly prohibited, efforts should be made towards staying within 80 507characters per line. This could include using re-factoring code that leads 508to less indentation, shorter variable or function names and last but not 509least, simply wrapping the lines. 510 511In particular, we accept lines with more than 80 columns: 512 513 - on strings, as they shouldn't be broken due to line length limits; 514 - when a function or variable name needs to have a long identifier name, 515 which makes hard to honor the 80 columns limit; 516 - on arithmetic expressions, when breaking lines makes them harder to 517 read; 518 - when they avoid a line ending with an open parenthesis or an open 519 bracket. 520 521Key Cycle Dates 522--------------- 523 524New submissions can be sent at any time, but if they are intended to hit the 525next merge window they should be sent before -rc5, and ideally stabilized 526in the linux-media branch by -rc6. 527 528Review Cadence 529-------------- 530 531Provided that your patch has landed in 532`Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_, it 533should be sooner or later handled, so you don't need to re-submit a patch. 534 535Except for important bug fixes, we don't usually add new patches to the 536development tree between -rc6 and the next -rc1. 537 538Please notice that the media subsystem is a high traffic one, so it 539could take a while for us to be able to review your patches. Feel free 540to ping if you don't get a feedback in a couple of weeks or to ask 541other developers to publicly add ``Reviewed-by:`` and, more importantly, 542``Tested-by:`` tags. 543 544Please note that we expect a detailed description for ``Tested-by:``, 545identifying what boards were used during the test and what it was tested. 546