Media Subsystem Profile

Media subsystem 범위와 문서 동기화

Media subsystem은 stream capture, analog·digital TV stream, camera, remote controller, HDMI CEC 및 media pipeline 제어를 포함한 여러 장치를 지원합니다.

주요 관리 범위는 `drivers/media`, `drivers/staging/media`, media 관련 admin guide·driver API·userspace API, `Documentation/devicetree/bindings/media/`, `include/media`입니다.

Device Tree binding은 `MAINTAINERS` 파일에 기재된 OPEN FIRMWARE AND FLATTENED DEVICE TREE BINDINGS maintainer가 관리합니다. 따라서 해당 영역의 변경은 media subsystem 개발 tree를 통해 merge하기 전에 이들의 review를 받아야 합니다.

Media userspace API와 kernel API는 모두 문서화되어 있으며 API 변경과 문서를 동기화해야 합니다. Subsystem에 새 기능을 추가하는 모든 patch는 해당 API 문서의 변경도 함께 포함해야 합니다.

Media Subsystem Profile
=======================

Overview
--------

The media subsystem covers support for a variety of devices: stream
capture, analog and digital TV streams, cameras, remote controllers, HDMI CEC
and media pipeline control.

It covers, mainly, the contents of those directories:

  - drivers/media
  - drivers/staging/media
  - Documentation/admin-guide/media
  - Documentation/driver-api/media
  - Documentation/userspace-api/media
  - Documentation/devicetree/bindings/media/\ [1]_
  - include/media

.. [1] Device tree bindings are maintained by the
       OPEN FIRMWARE AND FLATTENED DEVICE TREE BINDINGS maintainers
       (see the MAINTAINERS file). So, changes there must be reviewed
       by them before being merged via the media subsystem's development
       tree.

Both media userspace and Kernel APIs are documented and the documentation
must be kept in sync with the API changes. It means that all patches that
add new features to the subsystem must also bring changes to the
corresponding API files.

Sub-maintainer 모델과 patch 제출 흐름

Media subsystem은 크고 범위가 넓기 때문에 특정 영역을 폭넓게 이해하는 sub-maintainer를 둡니다. Sub-maintainer는 patch를 review하고 subsystem 규칙을 따르는지, media kernel·userspace API를 올바르게 사용하는지 제출자에게 feedback을 제공합니다.

Media patch는 `[email protected]` mailing list에 plain text email로 보내야 합니다. HTML email은 mail server가 자동 거부하므로 관련 sub-maintainer도 Cc하는 것이 좋습니다.

Workflow는 Patchwork에 크게 의존합니다. 제출 email이 mailing list server에서 수락된 뒤 잠시 후 `https://patchwork.linuxtv.org/project/linux-media/list/`에 나타나야 합니다. 몇 분이 지나도 보이지 않으면 다시 제출하거나 항의하기 전에 email이 plain text인지, mailer가 whitespace를 손상시키지 않았는지 확인해야 합니다.

Mailing list server의 수락 여부는 `https://lore.kernel.org/linux-media/`에서 확인할 수 있습니다. HTML이 들어간 email은 별도 통지 없이 삭제됩니다.

Due to the size and wide scope of the media subsystem, media's
maintainership model is to have sub-maintainers that have a broad
knowledge of a specific aspect of the subsystem. It is the sub-maintainers'
task to review the patches, providing feedback to users if the patches are
following the subsystem rules and are properly using the media kernel and
userspace APIs.

Patches for the media subsystem must be sent to the media mailing list
at [email protected] as plain text only e-mail. Emails with
HTML will be automatically rejected by the mail server. It could be wise
to also copy the sub-maintainer(s).

Media's workflow is heavily based on Patchwork, meaning that, once a patch
is submitted, the e-mail will first be accepted by the mailing list
server, and, after a while, it should appear at:

   - https://patchwork.linuxtv.org/project/linux-media/list/

If it doesn't automatically appear there after a few minutes, then
probably something went wrong on your submission. Please check if the
email is in plain text\ [2]_ only and if your emailer is not mangling
whitespaces before complaining or submitting them again.

You can check if the mailing list server accepted your patch, by looking at:

   - https://lore.kernel.org/linux-media/

.. [2] If your email contains HTML, the mailing list server will simply
       drop it, without any further notice.

Media maintainer와 review 위임

Media subsystem에는 driver code review를 담당하는 senior developer인 sub-maintainer 그룹과 subsystem 전체를 담당하는 senior developer가 있습니다. Core 변경은 가능한 경우 여러 media maintainer가 review합니다.

영역별 maintainer는 remote controller(적외선)의 Sean Young, HDMI CEC의 Hans Verkuil, media controller driver의 Laurent Pinchart, ISP·`v4l2-async`·`v4l2-fwnode`·`v4l2-flash-led-class`·sensor driver의 Sakari Ailus, V4L2 driver와 core framework의 Hans Verkuil입니다. Subsystem maintainer는 Mauro Carvalho Chehab입니다.

필요하면 media maintainer가 patch를 다른 media maintainer에게 위임할 수 있습니다. 이때 Patchwork의 `delegate` 필드는 현재 review 책임자를 나타냅니다.

Media maintainers
+++++++++++++++++

At the media subsystem, we have a group of senior developers that
are responsible for doing the code reviews at the drivers (also known as
sub-maintainers), and another senior developer responsible for the
subsystem as a whole. For core changes, whenever possible, multiple
media maintainers do the review.

The media maintainers that work on specific areas of the subsystem are:

- Remote Controllers (infrared):
    Sean Young <[email protected]>

- HDMI CEC:
    Hans Verkuil <[email protected]>

- Media controller drivers:
    Laurent Pinchart <[email protected]>

- ISP, v4l2-async, v4l2-fwnode, v4l2-flash-led-class and Sensor drivers:
    Sakari Ailus <[email protected]>

- V4L2 drivers and core V4L2 frameworks:
    Hans Verkuil <[email protected]>

The subsystem maintainer is:
  Mauro Carvalho Chehab <[email protected]>

Media maintainers may delegate a patch to other media maintainers as needed.
On such case, checkpatch's ``delegate`` field indicates who's currently
responsible for reviewing a patch.

제출 checklist와 compliance 도구

Open Firmware 또는 Device Tree binding을 바꾸는 patch는 Device Tree maintainer의 review를 받아야 합니다. 제출할 때 `[email protected]` mailing list를 통해 DT maintainer를 Cc해야 합니다.

`https://git.linuxtv.org/v4l-utils.git/`에는 driver가 media API를 제대로 구현했는지 확인하는 compliance 도구가 있습니다. V4L2 driver는 `v4l2-compliance`, V4L2 virtual driver는 `contrib/test/test-media`, CEC driver는 `cec-compliance`를 사용합니다.

`v4l2-compliance`는 V4L2 driver 안의 media controller 사용도 검사합니다. Subsystem의 다른 부분을 검사하는 추가 도구는 개발 중이며, 관련 test는 patch가 upstream으로 가기 전에 통과해야 합니다.

Submit Checklist Addendum
-------------------------

Patches that change the Open Firmware/Device Tree bindings must be
reviewed by the Device Tree maintainers. So, DT maintainers should be
Cc:ed when those are submitted via [email protected] mailing
list.

There is a set of compliance tools at https://git.linuxtv.org/v4l-utils.git/
that should be used in order to check if the drivers are properly
implementing the media APIs:

====================        =======================================================
Type                        Tool
====================        =======================================================
V4L2 drivers\ [3]_        ``v4l2-compliance``
V4L2 virtual drivers        ``contrib/test/test-media``
CEC drivers                ``cec-compliance``
====================        =======================================================

.. [3] The ``v4l2-compliance`` also covers the media controller usage inside
       V4L2 drivers.

Other compliance tools are under development to check other parts of the
subsystem.

Those tests need to pass before the patches go upstream.

Kernel build와 static analysis

Media patch는 endian 검사, section mismatch debug, Sparse의 `C=1`, warning level `W=1`, 사용자 지정 `CHECK=check_script`를 켠 Kernel build로 검사합니다.

예제 `check_script`는 `smatch -p=kernel`과 `sparse`를 차례로 실행하고 진단을 standard error로 보냅니다. 충분히 타당한 이유가 없다면 patch가 새 warning을 만들지 않도록 해야 합니다.

Also, please notice that we build the Kernel with::

        make CF=-D__CHECK_ENDIAN__ CONFIG_DEBUG_SECTION_MISMATCH=y C=1 W=1 CHECK=check_script

Where the check script is::

        #!/bin/bash
        /devel/smatch/smatch -p=kernel $@ >&2
        /devel/sparse/sparse $@ >&2

Be sure to not introduce new warnings on your patches without a
very good reason.

Style cleanup patch 범위

Style cleanup은 해당 파일의 다른 변경과 함께 제출할 때 환영합니다. 순수한 standalone style cleanup도 받아들일 수 있지만, 변경량이 적다면 subsystem 전체를 하나의 patch로 처리하고 그렇지 않다면 최소한 directory별로 묶는 것이 바람직합니다.

예를 들어 `drivers/media` 아래의 대규모 cleanup이라면 `drivers/media/pci` 아래 모든 driver를 위한 patch 하나, `drivers/media/usb`를 위한 patch 하나처럼 나누어 제출합니다.

Style Cleanup Patches
+++++++++++++++++++++

Style cleanups are welcome when they come together with other changes
at the files where the style changes will affect.

We may accept pure standalone style cleanups, but they should ideally
be one patch for the whole subsystem (if the cleanup is low volume),
or at least be grouped per directory. So, for example, if you're doing a
big cleanup change set at drivers under drivers/media, please send a single
patch for all drivers under drivers/media/pci, another one for
drivers/media/usb and so on.

Strict checkpatch와 80-column 예외

Media 개발은 strict mode의 `checkpatch.pl`로 coding style을 검사하며 예제 명령은 `./scripts/checkpatch.pl --strict --max-line-length=80`입니다.

원칙적으로 patch는 coding style 규칙을 따라야 하지만 타당한 이유가 있으면 예외를 허용합니다. 이 경우 maintainer와 reviewer가 `checkpatch.pl` 지적을 해결하지 않은 이유를 물을 수 있습니다. 목표는 code 가독성 향상이므로 도구의 제안이 오히려 읽기 나쁘게 만드는 경우에는 합리적인 판단을 사용해야 합니다.

한 종류의 `checkpatch.pl` 문제를 해결하다가 한 줄이 80자를 넘을 수 있습니다. 엄격히 금지되지는 않지만 indentation을 줄이는 refactoring, 더 짧은 변수·함수 이름, line wrapping을 통해 80자 이내에 머물도록 노력해야 합니다.

문자열은 길이 제한 때문에 나누지 않아야 하므로 80자를 넘을 수 있습니다. 긴 식별자가 꼭 필요한 경우, 줄을 나누면 더 읽기 어려워지는 산술식, 줄 끝에 여는 괄호나 대괄호만 남는 것을 피하는 경우에도 80 column 초과를 허용합니다.

Coding Style Addendum
+++++++++++++++++++++

Media development uses ``checkpatch.pl`` on strict mode to verify the code
style, e.g.::

        $ ./scripts/checkpatch.pl --strict --max-line-length=80

In principle, patches should follow the coding style rules, but exceptions
are allowed if there are good reasons. On such case, maintainers and reviewers
may question about the rationale for not addressing the ``checkpatch.pl``.

Please notice that the goal here is to improve code readability. On
a few cases, ``checkpatch.pl`` may actually point to something that would
look worse. So, you should use good sense.

Note that addressing one ``checkpatch.pl`` issue (of any kind) alone may lead
to having longer lines than 80 characters per line. While this is not
strictly prohibited, efforts should be made towards staying within 80
characters per line. This could include using re-factoring code that leads
to less indentation, shorter variable or function names and last but not
least, simply wrapping the lines.

In particular, we accept lines with more than 80 columns:

    - on strings, as they shouldn't be broken due to line length limits;
    - when a function or variable name need to have a big identifier name,
      which keeps hard to honor the 80 columns limit;
    - on arithmetic expressions, when breaking lines makes them harder to
      read;
    - when they avoid a line to end with an open parenthesis or an open
      bracket.

Key cycle date와 review cadence

새 patch는 언제든 보낼 수 있지만 다음 merge window에 들어가려면 `-rc5` 전에 제출하고, 이상적으로는 `-rc6`까지 `linux-media` branch에서 안정화해야 합니다.

Patch가 `https://patchwork.linuxtv.org`에 있으면 결국 처리되므로 다시 제출할 필요가 없습니다. Bug fix를 제외하면 보통 `-rc6`부터 다음 `-rc1` 사이에는 개발 tree에 새 patch를 추가하지 않습니다.

Media subsystem은 traffic이 많아 review에 시간이 걸릴 수 있습니다. 몇 주 동안 feedback이 없으면 ping할 수 있고, 다른 개발자에게 공개적으로 `Reviewed-by`와 특히 `Tested-by:` tag를 추가해 달라고 요청할 수 있습니다.

`Tested-by:`에는 test에 사용한 board와 무엇을 검사했는지 식별하는 상세 설명이 필요합니다.

Key Cycle Dates
---------------

New submissions can be sent at any time, but if they intend to hit the
next merge window they should be sent before -rc5, and ideally stabilized
in the linux-media branch by -rc6.

Review Cadence
--------------

Provided that your patch is at https://patchwork.linuxtv.org, it should
be sooner or later handled, so you don't need to re-submit a patch.

Except for bug fixes, we don't usually add new patches to the development
tree between -rc6 and the next -rc1.

Please notice that the media subsystem is a high traffic one, so it
could take a while for us to be able to review your patches. Feel free
to ping if you don't get a feedback in a couple of weeks or to ask
other developers to publicly add Reviewed-by and, more importantly,
``Tested-by:`` tags.

Please note that we expect a detailed description for ``Tested-by:``,
identifying what boards were used at the test and what it was tested.