From patchwork Fri Aug 28 09:16:50 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 255979 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=-19.1 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, INCLUDES_PATCH, MAILING_LIST_MULTI, MENTIONS_GIT_HOSTING, SIGNED_OFF_BY, SPF_HELO_NONE, SPF_PASS, URIBL_BLOCKED, USER_AGENT_GIT 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 A0728C433E2 for ; Fri, 28 Aug 2020 09:17:33 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 7B1D420C56 for ; Fri, 28 Aug 2020 09:17:33 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1598606253; bh=qf3s74BFMfzPaXEhkWfFmaoIcsmrt/xu5Ve7JjjrqSI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=1UXaTzQW1ywc7A6XDafYJ5+E6XuMqt95lFJgY9RixG7YwFZjJ5T3abJApTY69nFV4 FZABzy/gDC9veVRIvXF/hiG5afFs+mOkUtZKzv0nk5E4Hj0l/f63IV1cscau7fBYd/ n9iggmyXa0GflO+4+cV+/o91tUTQiXDwbxTxAkws= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1728912AbgH1JRK (ORCPT ); Fri, 28 Aug 2020 05:17:10 -0400 Received: from mail.kernel.org ([198.145.29.99]:48546 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1728548AbgH1JQy (ORCPT ); Fri, 28 Aug 2020 05:16:54 -0400 Received: from mail.kernel.org (unknown [95.90.213.181]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id 3D68520C56; Fri, 28 Aug 2020 09:16:53 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1598606213; bh=qf3s74BFMfzPaXEhkWfFmaoIcsmrt/xu5Ve7JjjrqSI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=o/uh8mxaO6aCUHIiw2fwZiZV736BMezCvVZ65ayjQd+uNMxyLAfU1Wnnke7NimkcA JQwQYJ0gDv34xBMFZlJvL3TtZzLXKFS3l0DYmV2BPolWYsMIfobj6knnDaF602uTJS eMwJpIuapVR7lg5zsX0f3IVpajA3zGxemaSiEKvM= Received: from mchehab by mail.kernel.org with local (Exim 4.94) (envelope-from ) id 1kBaV9-0047AH-Ap; Fri, 28 Aug 2020 11:16:51 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , Hans Verkuil , Sakari Ailus , linux-media@vger.kernel.org Subject: [PATCH v11 4/4] media: open.rst: document mc-centric and video-node-centric Date: Fri, 28 Aug 2020 11:16:50 +0200 Message-Id: <99929cf3d951ff9dbe0e70e9380dfb2c13408869.1598606093.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.26.2 In-Reply-To: References: MIME-Version: 1.0 Sender: linux-media-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org 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 | 59 +++++++++++++++++-- 1 file changed, 53 insertions(+), 6 deletions(-) diff --git a/Documentation/userspace-api/media/v4l/open.rst b/Documentation/userspace-api/media/v4l/open.rst index 4928f636c576..d20f98969294 100644 --- a/Documentation/userspace-api/media/v4l/open.rst +++ b/Documentation/userspace-api/media/v4l/open.rst @@ -13,6 +13,53 @@ Opening and Closing Devices *************************** +.. _v4l2_hardware_control: + +Controlling a hardware peripheral via V4L2 +========================================== + +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 drivers to identify the V4L2 +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 +156,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 +166,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