From patchwork Tue Dec 8 18:04:30 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 7800881 Return-Path: X-Original-To: patchwork-linux-media@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork1.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.136]) by patchwork1.web.kernel.org (Postfix) with ESMTP id D63D19F1C2 for ; Tue, 8 Dec 2015 18:04:41 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 6B1F120490 for ; Tue, 8 Dec 2015 18:04:40 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 91DFB20453 for ; Tue, 8 Dec 2015 18:04:38 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1751260AbbLHSEh (ORCPT ); Tue, 8 Dec 2015 13:04:37 -0500 Received: from lists.s-osg.org ([54.187.51.154]:46809 "EHLO lists.s-osg.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1750986AbbLHSEg convert rfc822-to-8bit (ORCPT ); Tue, 8 Dec 2015 13:04:36 -0500 Received: from recife.lan (179.186.106.209.dynamic.adsl.gvt.net.br [179.186.106.209]) by lists.s-osg.org (Postfix) with ESMTPSA id AF7A64632A; Tue, 8 Dec 2015 10:04:33 -0800 (PST) Date: Tue, 8 Dec 2015 16:04:30 -0200 From: Mauro Carvalho Chehab To: Laurent Pinchart Cc: Hans Verkuil , Linux Media Mailing List , Jonathan Corbet , linux-doc@vger.kernel.org Subject: Re: [PATCH v8 41/55] [media] DocBook: update descriptions for the media controller entities Message-ID: <20151208160430.20ed8203@recife.lan> In-Reply-To: <2014911.aPaHEit1JK@avalon> References: <00369c40b69f5ce1473d98398e32a7842cf28366.1441540862.git.mchehab@osg.samsung.com> <55F2D37A.2060503@xs4all.nl> <2014911.aPaHEit1JK@avalon> Organization: Samsung X-Mailer: Claws Mail 3.12.0 (GTK+ 2.24.28; x86_64-redhat-linux-gnu) MIME-Version: 1.0 Sender: linux-media-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org X-Spam-Status: No, score=-6.9 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_HI, T_RP_MATCHES_RCVD, UNPARSEABLE_RELAY autolearn=ham version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Em Sun, 06 Dec 2015 03:00:57 +0200 Laurent Pinchart escreveu: > Hello, > > On Friday 11 September 2015 15:13:30 Hans Verkuil wrote: > > On 09/06/2015 02:03 PM, Mauro Carvalho Chehab wrote: > > > Cleanup the media controller entities description: > > > - remove MEDIA_ENT_T_DEVNODE and MEDIA_ENT_T_V4L2_SUBDEV entity > > > types, as they don't mean anything; > > > - add MEDIA_ENT_T_UNKNOWN with a proper description; > > > - remove ALSA and FB entity types. Those should not be used, as > > > the types are deprecated. We'll soon be adidng ALSA, but with > > > a different entity namespace; > > > - improve the description of some entities. > > > > > > Signed-off-by: Mauro Carvalho Chehab > > > > > > diff --git a/Documentation/DocBook/media/v4l/media-ioc-enum-entities.xml > > > b/Documentation/DocBook/media/v4l/media-ioc-enum-entities.xml index > > > 32a783635649..bc101516e372 100644 > > > --- a/Documentation/DocBook/media/v4l/media-ioc-enum-entities.xml > > > +++ b/Documentation/DocBook/media/v4l/media-ioc-enum-entities.xml > > > @@ -179,70 +179,65 @@ > > > > > > > > > > > > - MEDIA_ENT_T_DEVNODE > > > - Unknown device node > > > + MEDIA_ENT_T_UNKNOWN and > > > MEDIA_ENT_T_V4L2_SUBDEV_UNKNOWN + > > > Unknown entity. That generally indicates that > > > + a driver didn't initialize properly the entity, with is a Kernel > > > bug> > > > > > > > I'm wondering: if userspace should never see an unknown entity, wouldn't it > > be better to move these UNKNOWN defines out of the public header to a kernel > > header and drop this from the documentation? > > And shouldn't the bug be caught in kernelspace before it reaches the user ? I don't like the idea of moving this to a Kernel header. Yes, ideally, the user should never saw this, but IMHO, programs should address this somehow, instead of simply crashing if such value is found. Also, keeping this at documentation helps to inform developers that this value is invalid and should never be present on any driver. It should be noticed that getting rid of MEDIA_ENT_T_V4L2_SUBDEV_UNKNOWN is not easy, and should be addressed on a separate patchset. It requires each driver maintainer to check and fix the non-initialized subdevices, and add new definitions at the public header. This will take a while, and such work is independent on the actual MC next gen patch series. So, better to keep it documented there, at least while we're not able to enforce the Kernel do do a BUG_ON() or something similar if a driver doesn't fill the entity type/function. > > > > > > > MEDIA_ENT_T_V4L2_VIDEO > > > - V4L video, radio or vbi device node > > > + V4L video streaming input or output entity > > > > > > - > > > - MEDIA_ENT_T_DEVNODE_FB > > > - Frame buffer device node > > > + MEDIA_ENT_T_V4L2_VBI > > > + V4L VBI streaming input or output entity > > > > > > - > > > - MEDIA_ENT_T_DEVNODE_ALSA > > > - ALSA card > > > + MEDIA_ENT_T_V4L2_SWRADIO > > > + V4L Sofware Digital Radio (SDR) streaming input or output > > > entity > > > > s/Sofware/Software/ > > > > > > > > > > > MEDIA_ENT_T_DVB_DEMOD > > > - DVB frontend devnode > > > + DVB demodulator entity > > > > > > > > > MEDIA_ENT_T_DVB_DEMUX > > > - DVB demux devnode > > > + DVB demux entity. Could be implemented on hardware or in > > > Kernelspace > > s/Could be/Can be/ > > > s/on/in/ > > > > > > > > > > > MEDIA_ENT_T_DVB_TSOUT > > > - DVB DVR devnode > > > + DVB Transport Stream output entity > > > > > > > > > MEDIA_ENT_T_DVB_CA > > > - DVB CAM devnode > > > + DVB Conditional Access module (CAM) entity > > > > > > > > > > MEDIA_ENT_T_DVB_DEMOD_NET_DECAP > > > - DVB network devnode > > > - > > > - > > > - MEDIA_ENT_T_V4L2_SUBDEV > > > - Unknown V4L sub-device > > > + DVB network ULE/MLE desencapsulation entity. Could be > > > implemented on hardware or in Kernelspace > > s/Could be/Can be/ > > > s/on/in/ > > > > Hmm, is desencapsulation correct? Could it be 'de-encapsulation' instead? It > > looks weird. > > > > > > > > > > > > MEDIA_ENT_T_V4L2_SUBDEV_SENSOR > > > - Video sensor > > > + Camera video sensor entity > > s/video sensor/image sensor/ > > > > > > > > > > MEDIA_ENT_T_V4L2_SUBDEV_FLASH > > > - Flash controller > > > + Flash controller entity > > > > > > > > > MEDIA_ENT_T_V4L2_SUBDEV_LENS > > > - Lens controller > > > + Lens controller entity > > > > > > > > > > MEDIA_ENT_T_V4L2_SUBDEV_DECODER > > > - Video decoder, the basic function of the video decoder is > to > > > - accept analogue video from a wide variety of sources such as > > > + Analog video decoder, the basic function of the video > decoder > > > + is to accept analogue video from a wide variety of sources such > as > > > broadcast, DVD players, cameras and video cassette recorders, in > > > - either NTSC, PAL or HD format and still occasionally SECAM, > separate > > > - it into its component parts, luminance and chrominance, and > output > > > + either NTSC, PAL, SECAM or HD format, separating the stream > > > + into its component parts, luminance and chrominance, and output > > > it in some digital video standard, with appropriate embedded > timing > > > signals. > > Does timing signals refer to synchronization signals ? They don't have to be > embedded, do they ? > > > > > > > > > > MEDIA_ENT_T_V4L2_SUBDEV_TUNER > > > - TV and/or radio tuner > > > + Digital TV, analog TV, radio and/or software radio > > > tuner> > > > > > > > > > > Changes done. New patch follows. From 88a5f01638adaf0c5f0fe2dfb34b3a68a2997d8a Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 7 May 2015 22:12:40 -0300 Subject: [media] DocBook: update descriptions for the media controller entities Cc: Linux Media Mailing List , Mauro Carvalho Chehab Cleanup the media controller entities description: - remove MEDIA_ENT_T_DEVNODE and MEDIA_ENT_T_V4L2_SUBDEV entity types, as they don't mean anything; - add MEDIA_ENT_T_UNKNOWN with a proper description; - remove ALSA and FB entity types. Those should not be used, as the types are deprecated. We'll soon be adidng ALSA, but with a different entity namespace; - improve the description of some entities. Change-Id: I0db7672809b567e04a5f367ff6b31315f7b7be8a Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/media-ioc-enum-entities.xml | 49 +++++------- 1 file changed, 22 insertions(+), 27 deletions(-) -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html --- patchwork.orig/Documentation/DocBook/media/v4l/media-ioc-enum-entities.xml +++ patchwork/Documentation/DocBook/media/v4l/media-ioc-enum-entities.xml @@ -179,70 +179,65 @@ - MEDIA_ENT_T_DEVNODE - Unknown device node + MEDIA_ENT_T_UNKNOWN and MEDIA_ENT_T_V4L2_SUBDEV_UNKNOWN + Unknown entity. That generally indicates that + a driver didn't initialize properly the entity, with is a Kernel bug MEDIA_ENT_T_V4L2_VIDEO - V4L video, radio or vbi device node + V4L video streaming input or output entity - - MEDIA_ENT_T_DEVNODE_FB - Frame buffer device node + MEDIA_ENT_T_V4L2_VBI + V4L VBI streaming input or output entity - - MEDIA_ENT_T_DEVNODE_ALSA - ALSA card + MEDIA_ENT_T_V4L2_SWRADIO + V4L Software Digital Radio (SDR) streaming input or output entity MEDIA_ENT_T_DVB_DEMOD - DVB frontend devnode + DVB demodulator entity MEDIA_ENT_T_DVB_DEMUX - DVB demux devnode + DVB demux entity. Can be implemented in hardware or in Kernelspace MEDIA_ENT_T_DVB_TSOUT - DVB DVR devnode + DVB Transport Stream output entity MEDIA_ENT_T_DVB_CA - DVB CAM devnode + DVB Conditional Access module (CAM) entity MEDIA_ENT_T_DVB_DEMOD_NET_DECAP - DVB network devnode - - - MEDIA_ENT_T_V4L2_SUBDEV - Unknown V4L sub-device + DVB network ULE/MLE de-encapsulation entity. Can be implemented in hardware or in Kernelspace MEDIA_ENT_T_V4L2_SUBDEV_SENSOR - Video sensor + Camera image sensor entity MEDIA_ENT_T_V4L2_SUBDEV_FLASH - Flash controller + Flash controller entity MEDIA_ENT_T_V4L2_SUBDEV_LENS - Lens controller + Lens controller entity MEDIA_ENT_T_V4L2_SUBDEV_DECODER - Video decoder, the basic function of the video decoder is to - accept analogue video from a wide variety of sources such as + Analog video decoder, the basic function of the video decoder + is to accept analogue video from a wide variety of sources such as broadcast, DVD players, cameras and video cassette recorders, in - either NTSC, PAL or HD format and still occasionally SECAM, separate - it into its component parts, luminance and chrominance, and output - it in some digital video standard, with appropriate embedded timing + either NTSC, PAL, SECAM or HD format, separating the stream + into its component parts, luminance and chrominance, and output + it in some digital video standard, with appropriate timing signals. MEDIA_ENT_T_V4L2_SUBDEV_TUNER - TV and/or radio tuner + Digital TV, analog TV, radio and/or software radio tuner