From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-16.3 required=3.0 tests=BAYES_00, HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_PATCH,MAILING_LIST_MULTI, MENTIONS_GIT_HOSTING,SIGNED_OFF_BY,SPF_HELO_NONE,SPF_PASS,USER_AGENT_SANE_1 autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id D70BBC433E1 for ; Thu, 27 Aug 2020 12:44:32 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id BF46622B40 for ; Thu, 27 Aug 2020 12:44:32 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1728512AbgH0Mny (ORCPT ); Thu, 27 Aug 2020 08:43:54 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:38324 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1728977AbgH0MXs (ORCPT ); Thu, 27 Aug 2020 08:23:48 -0400 Received: from hillosipuli.retiisi.org.uk (hillosipuli.retiisi.org.uk [IPv6:2a01:4f9:c010:4572::81:2]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 937E7C061235; Thu, 27 Aug 2020 05:23:47 -0700 (PDT) Received: from valkosipuli.localdomain (valkosipuli.retiisi.org.uk [IPv6:2a01:4f9:c010:4572::80:2]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange ECDHE (P-256) server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by hillosipuli.retiisi.org.uk (Postfix) with ESMTPS id 0CE80634C87; Thu, 27 Aug 2020 15:23:37 +0300 (EEST) Received: from sailus by valkosipuli.localdomain with local (Exim 4.92) (envelope-from ) id 1kBGwL-0000XK-Cs; Thu, 27 Aug 2020 15:23:37 +0300 Date: Thu, 27 Aug 2020 15:23:37 +0300 From: Sakari Ailus To: Mauro Carvalho Chehab Cc: Linux Doc Mailing List , linux-kernel@vger.kernel.org, Jonathan Corbet , Hans Verkuil , Sakari Ailus , linux-media@vger.kernel.org Subject: Re: [PATCH v10 4/4] media: open.rst: document mc-centric and video-node-centric Message-ID: <20200827122337.GD851@valkosipuli.retiisi.org.uk> References: MIME-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: User-Agent: Mutt/1.10.1 (2018-07-13) Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Hi Mauro, On Thu, Aug 27, 2020 at 09:21:48AM +0200, Mauro Carvalho Chehab wrote: > When we added support for omap3, back in 2010, we added a new > type of V4L2 devices that aren't fully controlled via the V4L2 > device node. > > Yet, we have never clearly documented in the V4L2 specification > the differences between the two types. > > Let's document them based on the the current implementation. > > Signed-off-by: Mauro Carvalho Chehab > --- > .../userspace-api/media/v4l/open.rst | 58 +++++++++++++++++-- > 1 file changed, 52 insertions(+), 6 deletions(-) > > diff --git a/Documentation/userspace-api/media/v4l/open.rst b/Documentation/userspace-api/media/v4l/open.rst > index b9367e02b884..e9cfbe954918 100644 > --- a/Documentation/userspace-api/media/v4l/open.rst > +++ b/Documentation/userspace-api/media/v4l/open.rst > @@ -13,6 +13,52 @@ > Opening and Closing Devices > *************************** > > +.. _v4l2_hardware_control: > + > +Controlling a hardware peripheral via V4L2 > +========================================== > + > +A V4L2 hardware peripheral is usually complex: support for it is > +implemented via a bridge driver and often by several additional drivers. How about this, instead: Hardware that is supported using the V4L2 uAPI often consists of multiple devices or peripherals, each of which have their own driver. > +The bridge driver exposes one or more V4L2 device nodes > +(see :ref:`v4l2_device_naming`). > + > +There are other drivers providing support for other components of > +the hardware, which may also expose device nodes, called V4L2 sub-devices. > + > +When such V4L2 sub-devices are exposed, they allow controlling those > +other hardware components - usually connected via a serial bus (like > +I²C, SMBus or SPI). Depending on the bridge driver, those sub-devices > +can be controlled indirectly via the bridge driver or explicitly via > +the :ref:`Media Controller ` and via the > +:ref:`V4L2 sub-devices `. > + > +The devices that require the use of the > +:ref:`Media Controller ` are called **MC-centric** > +devices. The devices that are fully controlled via V4L2 device nodes > +are called **video-node-centric**. > + > +Userspace can check if a V4L2 hardware peripheral is MC-centric by > +calling :ref:`VIDIOC_QUERYCAP` and checking the > +:ref:`device_caps field `. > + > +If the device returns ``V4L2_CAP_IO_MC`` flag at ``device_caps``, > +then it is MC-centric, otherwise, it is video-node-centric. > + > +It is required for MC-centric hardware to identify the V4L2 s/hardware/drivers/ > +sub-devices and to configure the pipelines via the > +:ref:`media controller API ` before using the peripheral. > +Also, the sub-devices' configuration shall be controlled via the > +:ref:`sub-device API `. > + > +.. note:: > + > + A video-node-centric may still provide media-controller and > + sub-device interfaces as well. > + > + However, in that case the media-controller and the sub-device > + interfaces are read-only and just provide information about the > + device. The actual configuration is done via the video nodes. > > .. _v4l2_device_naming: > > @@ -109,7 +155,7 @@ Related Devices > Devices can support several functions. For example video capturing, VBI > capturing and radio support. > > -The V4L2 API creates different nodes for each of these functions. > +The V4L2 API creates different V4L2 device nodes for each of these functions. > > The V4L2 API was designed with the idea that one device node could > support all functions. However, in practice this never worked: this > @@ -119,17 +165,17 @@ switching a device node between different functions only works when > using the streaming I/O API, not with the > :ref:`read() `/\ :ref:`write() ` API. > > -Today each device node supports just one function. > +Today each V4L2 device node supports just one function. > > Besides video input or output the hardware may also support audio > sampling or playback. If so, these functions are implemented as ALSA PCM > devices with optional ALSA audio mixer devices. > > One problem with all these devices is that the V4L2 API makes no > -provisions to find these related devices. Some really complex devices > -use the Media Controller (see :ref:`media_controller`) which can be > -used for this purpose. But most drivers do not use it, and while some > -code exists that uses sysfs to discover related devices (see > +provisions to find these related V4L2 device nodes. Some really complex > +hardware use the Media Controller (see :ref:`media_controller`) which can > +be used for this purpose. But several drivers do not use it, and while some > +code exists that uses sysfs to discover related V4L2 device nodes (see > libmedia_dev in the > `v4l-utils `__ git > repository), there is no library yet that can provide a single API > -- Sakari Ailus