Documentation/driver-api/media/maintainer-entry-profile.rst

   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 linux-media@vger.kernel.org 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 - 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
  89 The subsystem maintainer is:
  90   Mauro Carvalho Chehab <mchehab@kernel.org>
  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 devicetree@vger.kernel.org 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 compilance 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.