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