From patchwork Thu Aug 27 07:21:45 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: 255995 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=-14.1 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY,SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=ham 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 0E6D9C433E1 for ; Thu, 27 Aug 2020 07:21:59 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id E3A6622BED for ; Thu, 27 Aug 2020 07:21:58 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1598512918; bh=ut0KVfmGm8XdutWFr2zP/KNRnKFt2wtRlb9QfBuJG3s=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=1OIdnjZEvVgtOs1dP/XOoavg6tVhvzz1MuIgvDYoxj67QISM55KBOmUBRAog9pSrZ MBEeANBm00bZTwUW4Xov2rVARpMtaFeh8vbokW6dKXdPbEXX93sj0SmVz6AwYPNF1f M/E6LSW6gQRQXkiwyViLqMI1vJ9+achIGD7IN04A= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1728111AbgH0HV5 (ORCPT ); Thu, 27 Aug 2020 03:21:57 -0400 Received: from mail.kernel.org ([198.145.29.99]:55622 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1728092AbgH0HVw (ORCPT ); Thu, 27 Aug 2020 03:21:52 -0400 Received: from mail.kernel.org (ip5f5ad5a8.dynamic.kabel-deutschland.de [95.90.213.168]) (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 4318722BF3; Thu, 27 Aug 2020 07:21:52 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1598512912; bh=ut0KVfmGm8XdutWFr2zP/KNRnKFt2wtRlb9QfBuJG3s=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=HjqPmH6LDRMj/FloVZt+3N/mJhTks3OpG87osNvMM+dVjfdIkQNdmKxM3dmUuhbmR 4zu67/BCGfhB10AXP/q9jxMECbrZl+vWL6EAkTm1U6ew6nZ1uDo4NAo7O1gQcWl//4 N6VVQHnTtLclJ8BKHPamwFiN9wM12lwG1VQXakyM= Received: from mchehab by mail.kernel.org with local (Exim 4.94) (envelope-from ) id 1kBCEI-002s5E-8X; Thu, 27 Aug 2020 09:21:50 +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 v10 1/4] media: open.rst: better document device node naming Date: Thu, 27 Aug 2020 09:21:45 +0200 Message-Id: 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 Right now, only kAPI documentation describes the device naming. However, such description is needed at the uAPI too. Add it, and describe how to get an unique identifier for a given device. Acked-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- .../userspace-api/media/v4l/open.rst | 43 +++++++++++++++++-- 1 file changed, 40 insertions(+), 3 deletions(-) diff --git a/Documentation/userspace-api/media/v4l/open.rst b/Documentation/userspace-api/media/v4l/open.rst index 38046ef20141..332763053292 100644 --- a/Documentation/userspace-api/media/v4l/open.rst +++ b/Documentation/userspace-api/media/v4l/open.rst @@ -14,12 +14,14 @@ Opening and Closing Devices *************************** -Device Naming -============= +.. _v4l2_device_naming: + +V4L2 Device Node Naming +======================= V4L2 drivers are implemented as kernel modules, loaded manually by the system administrator or automatically when a device is first discovered. -The driver modules plug into the "videodev" kernel module. It provides +The driver modules plug into the ``videodev`` kernel module. It provides helper functions and a common application interface specified in this document. @@ -30,6 +32,41 @@ option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers are allocated in ranges depending on the device node type (video, radio, etc.). +The device nodes supported by the Video4Linux subsystem are: + +======================== ==================================================== +Default device node name Usage +======================== ==================================================== +``/dev/videoX`` Video and metadata for capture/output devices +``/dev/vbiX`` Vertical blank data (i.e. closed captions, teletext) +``/dev/radioX`` Radio tuners and modulators +``/dev/swradioX`` Software Defined Radio tuners and modulators +``/dev/v4l-touchX`` Touch sensors +``/dev/v4l-subdevX`` Video sub-devices (used by sensors and other + components of the hardware peripheral)\ [#]_ +======================== ==================================================== + +Where ``X`` is a non-negative number. + +.. note:: + + 1. The actual device node name is system-dependent, as udev rules may apply. + 2. There is no guarantee that ``X`` will remain the same for the same + device, as the number depends on the device driver's probe order. + If you need an unique name, udev default rules produce + ``/dev/v4l/by-id/`` and ``/dev/v4l/by-path/`` directories containing + links that can be used uniquely to identify a V4L2 device node:: + + $ tree /dev/v4l + /dev/v4l + ├── by-id + │   └── usb-OmniVision._USB_Camera-B4.04.27.1-video-index0 -> ../../video0 + └── by-path + └── pci-0000:00:14.0-usb-0:2:1.0-video-index0 -> ../../video0 + +.. [#] **V4L2 sub-device nodes** (e. g. ``/dev/v4l-subdevX``) use a different + set of system calls, as covered at :ref:`subdev`. + Many drivers support "video_nr", "radio_nr" or "vbi_nr" module options to select specific video/radio/vbi node numbers. This allows the user to request that the device node is named e.g. /dev/video5 instead