| 1 |
Media Subsystem Profile |
| 2 |
======================= |
| 3 |
|
| 4 |
Overview |
| 5 |
-------- |
| 6 |
|
| 7 |
The media subsystem covers support for a variety of devices: stream |
| 8 |
capture, analog and digital TV streams, cameras, remote controllers, HDMI CEC |
| 9 |
and media pipeline control. |
| 10 |
|
| 11 |
It covers, mainly, the contents of those directories: |
| 12 |
|
| 13 |
- drivers/media |
| 14 |
- drivers/staging/media |
| 15 |
- Documentation/admin-guide/media |
| 16 |
- Documentation/driver-api/media |
| 17 |
- Documentation/userspace-api/media |
| 18 |
- Documentation/devicetree/bindings/media/\ [1]_ |
| 19 |
- include/media |
| 20 |
|
| 21 |
.. [1] Device tree bindings are maintained by the |
| 22 |
OPEN FIRMWARE AND FLATTENED DEVICE TREE BINDINGS maintainers |
| 23 |
(see the MAINTAINERS file). So, changes there must be reviewed |
| 24 |
by them before being merged via the media subsystem's development |
| 25 |
tree. |
| 26 |
|
| 27 |
Both media userspace and Kernel APIs are documented and the documentation |
| 28 |
must be kept in sync with the API changes. It means that all patches that |
| 29 |
add new features to the subsystem must also bring changes to the |
| 30 |
corresponding API files. |
| 31 |
|
| 32 |
Due to the size and wide scope of the media subsystem, media's |
| 33 |
maintainership model is to have sub-maintainers that have a broad |
| 34 |
knowledge of a specific aspect of the subsystem. It is the sub-maintainers' |
| 35 |
task to review the patches, providing feedback to users if the patches are |
| 36 |
following the subsystem rules and are properly using the media kernel and |
| 37 |
userspace APIs. |
| 38 |
|
| 39 |
Patches for the media subsystem must be sent to the media mailing list |
| 40 |
at [email protected] as plain text only e-mail. Emails with |
| 41 |
HTML will be automatically rejected by the mail server. It could be wise |
| 42 |
to also copy the sub-maintainer(s). |
| 43 |
|
| 44 |
Media's workflow is heavily based on Patchwork, meaning that, once a patch |
| 45 |
is submitted, the e-mail will first be accepted by the mailing list |
| 46 |
server, and, after a while, it should appear at: |
| 47 |
|
| 48 |
- https://patchwork.linuxtv.org/project/linux-media/list/ |
| 49 |
|
| 50 |
If it doesn't automatically appear there after a few minutes, then |
| 51 |
probably something went wrong on your submission. Please check if the |
| 52 |
email is in plain text\ [2]_ only and if your emailer is not mangling |
| 53 |
whitespaces before complaining or submitting them again. |
| 54 |
|
| 55 |
You can check if the mailing list server accepted your patch, by looking at: |
| 56 |
|
| 57 |
- https://lore.kernel.org/linux-media/ |
| 58 |
|
| 59 |
.. [2] If your email contains HTML, the mailing list server will simply |
| 60 |
drop it, without any further notice. |
| 61 |
|
| 62 |
|
| 63 |
Media maintainers |
| 64 |
+++++++++++++++++ |
| 65 |
|
| 66 |
At the media subsystem, we have a group of senior developers that |
| 67 |
are responsible for doing the code reviews at the drivers (also known as |
| 68 |
sub-maintainers), and another senior developer responsible for the |
| 69 |
subsystem as a whole. For core changes, whenever possible, multiple |
| 70 |
media maintainers do the review. |
| 71 |
|
| 72 |
The media maintainers that work on specific areas of the subsystem are: |
| 73 |
|
| 74 |
- Remote Controllers (infrared): |
| 75 |
Sean Young <[email protected]> |
| 76 |
|
| 77 |
- HDMI CEC: |
| 78 |
Hans Verkuil <[email protected]> |
| 79 |
|
| 80 |
- Media controller drivers: |
| 81 |
Laurent Pinchart <[email protected]> |
| 82 |
|
| 83 |
- ISP, v4l2-async, v4l2-fwnode, v4l2-flash-led-class and Sensor drivers: |
| 84 |
Sakari Ailus <[email protected]> |
| 85 |
|
| 86 |
- V4L2 drivers and core V4L2 frameworks: |
| 87 |
Hans Verkuil <[email protected]> |
| 88 |
|
| 89 |
The subsystem maintainer is: |
| 90 |
Mauro Carvalho Chehab <[email protected]> |
| 91 |
|
| 92 |
Media maintainers may delegate a patch to other media maintainers as needed. |
| 93 |
On such case, checkpatch's ``delegate`` field indicates who's currently |
| 94 |
responsible for reviewing a patch. |
| 95 |
|
| 96 |
Submit Checklist Addendum |
| 97 |
------------------------- |
| 98 |
|
| 99 |
Patches that change the Open Firmware/Device Tree bindings must be |
| 100 |
reviewed by the Device Tree maintainers. So, DT maintainers should be |
| 101 |
Cc:ed when those are submitted via [email protected] mailing |
| 102 |
list. |
| 103 |
|
| 104 |
There is a set of compliance tools at https://git.linuxtv.org/v4l-utils.git/ |
| 105 |
that should be used in order to check if the drivers are properly |
| 106 |
implementing the media APIs: |
| 107 |
|
| 108 |
==================== ======================================================= |
| 109 |
Type Tool |
| 110 |
==================== ======================================================= |
| 111 |
V4L2 drivers\ [3]_ ``v4l2-compliance`` |
| 112 |
V4L2 virtual drivers ``contrib/test/test-media`` |
| 113 |
CEC drivers ``cec-compliance`` |
| 114 |
==================== ======================================================= |
| 115 |
|
| 116 |
.. [3] The ``v4l2-compliance`` also covers the media controller usage inside |
| 117 |
V4L2 drivers. |
| 118 |
|
| 119 |
Other compliance tools are under development to check other parts of the |
| 120 |
subsystem. |
| 121 |
|
| 122 |
Those tests need to pass before the patches go upstream. |
| 123 |
|
| 124 |
Also, please notice that we build the Kernel with:: |
| 125 |
|
| 126 |
make CF=-D__CHECK_ENDIAN__ CONFIG_DEBUG_SECTION_MISMATCH=y C=1 W=1 CHECK=check_script |
| 127 |
|
| 128 |
Where the check script is:: |
| 129 |
|
| 130 |
#!/bin/bash |
| 131 |
/devel/smatch/smatch -p=kernel $@ >&2 |
| 132 |
/devel/sparse/sparse $@ >&2 |
| 133 |
|
| 134 |
Be sure to not introduce new warnings on your patches without a |
| 135 |
very good reason. |
| 136 |
|
| 137 |
Style Cleanup Patches |
| 138 |
+++++++++++++++++++++ |
| 139 |
|
| 140 |
Style cleanups are welcome when they come together with other changes |
| 141 |
at the files where the style changes will affect. |
| 142 |
|
| 143 |
We may accept pure standalone style cleanups, but they should ideally |
| 144 |
be one patch for the whole subsystem (if the cleanup is low volume), |
| 145 |
or at least be grouped per directory. So, for example, if you're doing a |
| 146 |
big cleanup change set at drivers under drivers/media, please send a single |
| 147 |
patch for all drivers under drivers/media/pci, another one for |
| 148 |
drivers/media/usb and so on. |
| 149 |
|
| 150 |
Coding Style Addendum |
| 151 |
+++++++++++++++++++++ |
| 152 |
|
| 153 |
Media development uses ``checkpatch.pl`` on strict mode to verify the code |
| 154 |
style, e.g.:: |
| 155 |
|
| 156 |
$ ./scripts/checkpatch.pl --strict --max-line-length=80 |
| 157 |
|
| 158 |
In principle, patches should follow the coding style rules, but exceptions |
| 159 |
are allowed if there are good reasons. On such case, maintainers and reviewers |
| 160 |
may question about the rationale for not addressing the ``checkpatch.pl``. |
| 161 |
|
| 162 |
Please notice that the goal here is to improve code readability. On |
| 163 |
a few cases, ``checkpatch.pl`` may actually point to something that would |
| 164 |
look worse. So, you should use good sense. |
| 165 |
|
| 166 |
Note that addressing one ``checkpatch.pl`` issue (of any kind) alone may lead |
| 167 |
to having longer lines than 80 characters per line. While this is not |
| 168 |
strictly prohibited, efforts should be made towards staying within 80 |
| 169 |
characters per line. This could include using re-factoring code that leads |
| 170 |
to less indentation, shorter variable or function names and last but not |
| 171 |
least, simply wrapping the lines. |
| 172 |
|
| 173 |
In particular, we accept lines with more than 80 columns: |
| 174 |
|
| 175 |
- on strings, as they shouldn't be broken due to line length limits; |
| 176 |
- when a function or variable name need to have a big identifier name, |
| 177 |
which keeps hard to honor the 80 columns limit; |
| 178 |
- on arithmetic expressions, when breaking lines makes them harder to |
| 179 |
read; |
| 180 |
- when they avoid a line to end with an open parenthesis or an open |
| 181 |
bracket. |
| 182 |
|
| 183 |
Key Cycle Dates |
| 184 |
--------------- |
| 185 |
|
| 186 |
New submissions can be sent at any time, but if they intend to hit the |
| 187 |
next merge window they should be sent before -rc5, and ideally stabilized |
| 188 |
in the linux-media branch by -rc6. |
| 189 |
|
| 190 |
Review Cadence |
| 191 |
-------------- |
| 192 |
|
| 193 |
Provided that your patch is at https://patchwork.linuxtv.org, it should |
| 194 |
be sooner or later handled, so you don't need to re-submit a patch. |
| 195 |
|
| 196 |
Except for bug fixes, we don't usually add new patches to the development |
| 197 |
tree between -rc6 and the next -rc1. |
| 198 |
|
| 199 |
Please notice that the media subsystem is a high traffic one, so it |
| 200 |
could take a while for us to be able to review your patches. Feel free |
| 201 |
to ping if you don't get a feedback in a couple of weeks or to ask |
| 202 |
other developers to publicly add Reviewed-by and, more importantly, |
| 203 |
``Tested-by:`` tags. |
| 204 |
|
| 205 |
Please note that we expect a detailed description for ``Tested-by:``, |
| 206 |
identifying what boards were used at the test and what it was tested. |