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