From mboxrd@z Thu Jan 1 00:00:00 1970 Return-path: Received: from mxweblb06fl.versatel.de ([89.246.255.250]:39604 "EHLO mxweblb06fl.versatel.de" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1757581Ab0DGTJi (ORCPT ); Wed, 7 Apr 2010 15:09:38 -0400 Received: from ens28fl.versatel.de (ens28fl.versatel.de [82.140.32.10]) by mxweblb06fl.versatel.de (8.13.1/8.13.1) with ESMTP id o37IoXDJ028570 for ; Wed, 7 Apr 2010 20:50:34 +0200 Received: from cinnamon-sage.de (i577A40AB.versanet.de [87.122.64.171]) (authenticated bits=0) by ens28fl.versatel.de (8.12.11.20060308/8.12.11) with SMTP id o37IoYcj010975 for ; Wed, 7 Apr 2010 20:50:34 +0200 Received: from 192.168.23.2:50297 by cinnamon-sage.de for ,, ; 07.04.2010 20:50:33 Message-ID: <4BBCD3F9.1070207@cinnamon-sage.de> Date: Wed, 07 Apr 2010 20:50:33 +0200 From: Lars Hanisch MIME-Version: 1.0 To: Mike Isely CC: Hans Verkuil , linux-media@vger.kernel.org Subject: Re: RFC: exposing controls in sysfs References: <201004052347.10845.hverkuil@xs4all.nl> In-Reply-To: Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit Sender: linux-media-owner@vger.kernel.org List-ID: Am 06.04.2010 16:33, schrieb Mike Isely: > > Comments below... > > On Mon, 5 Apr 2010, Hans Verkuil wrote: > >> Hi all, >> >> The new control framework makes it very easy to expose controls in sysfs. >> The way it is implemented now in the framework is that each device node >> will get a 'controls' subdirectory in sysfs. Below which are all the controls >> associated with that device node. >> >> So different device nodes can have different controls if so desired. >> >> The name of each sysfs file is derived from the control name, basically making >> it lowercase, replacing ' ', '-' and '_' with '_' and skipping any other non- >> alphanumerical characters. Seems to work well. >> >> For numerical controls you can write numbers in decimal, octal or hexadecimal. >> >> When you write to a button control it will ignore what you wrote, but still >> execute the action. >> >> It looks like this for ivtv: >> >> $ ls /sys/class/video4linux/video1 >> controls dev device index name power subsystem uevent >> >> $ ls /sys/class/video4linux/video1/controls >> audio_crc chroma_gain spatial_chroma_filter_type video_bitrate_mode >> audio_emphasis contrast spatial_filter video_encoding >> audio_encoding hue spatial_filter_mode video_gop_closure >> audio_layer_ii_bitrate insert_navigation_packets spatial_luma_filter_type video_gop_size >> audio_mute median_chroma_filter_maximum stream_type video_mute >> audio_sampling_frequency median_chroma_filter_minimum stream_vbi_format video_mute_yuv >> audio_stereo_mode median_filter_type temporal_filter video_peak_bitrate >> audio_stereo_mode_extension median_luma_filter_maximum temporal_filter_mode video_temporal_decimation >> balance median_luma_filter_minimum video_aspect volume >> brightness mute video_b_frames >> chroma_agc saturation video_bitrate >> >> >> The question is, is this sufficient? >> >> One of the few drivers that exposes controls in sysfs is pvrusb2. As far as >> I can tell from the source it will create subdirectories under the device >> node for each control. Those subdirs have the name ctl_ (e.g. >> ctl_volume), and below that are files exposing all the attributes of that >> control: name, type, min_val, max_val, def_val, cur_val, custom_val, enum_val >> and bit_val. Most are clear, but some are a bit more obscure. enum_val is >> basically a QUERYMENU and returns all menu options. bit_val seems to be used >> for some non-control values like the TV standard that pvrusb2 also exposes >> and where bit_val is a bit mask of all the valid bits that can be used. >> >> Mike, if you have any additional information, just let us know. My pvrusb2 >> is in another country at the moment so I can't do any testing. > > Hans: > > What you see in the pvrusb2 driver is the result of an idea I had back > in 2005. The pvrusb2 driver has an internal "control" API; my original > idea back then was to then reimplement other interfaces on top of that > API, in a manner that is as orthogonal as possible. The reality today > is still pretty close to that concept (except for DVB unfortunately > since that framework's architecture effectively has to take over the RF > tuner...); the V4L2 implementation in the driver certainly works this > way. The sysfs interface you see here is the result of implementing the > same API through sysfs. Right now with the pvrusb2 driver the only > thing not exported through sysfs is the actual streaming of video > itself. > > The entire sysfs implementation in the driver can be found in > pvrusb2-sysfs.c. Notice that the file is generic; there is not anything > in it that is specific to any particular control. Rather, > pvrusb2-sysfs.c is able to iterate through the driver's controls, > picking up the control's name, its type, and accessors. Based on what > it finds, this module then synthesizes the interface that you see in > /class/pvrusb2/* - it's actually possible to add new controls to the > driver without changing anything in pvrusb2-sysfs.c. > > >> >> Personally I think that it is overkill to basically expose the whole >> QUERYCTRL information to sysfs. I see it as an easy and quick way to read and >> modify controls via a command line. > > Over time, I have ended up using pretty much every control in that > interface. Obviously not every control always gets touched, but I have > found it extremely valuable to have such direct access to every "knob" > in the driver this way. > > Also, the original concept was that the interface was to be orthogonal; > in theory any kind of control action in one interface should be just as > valid in another. > > >> >> Mike, do you know of anyone actively using that additional information? > > Yes. > > The VDR project at one time implemented a plugin to directly interface > to the pvrusb2 driver in this manner. I do not know if it is still > being used since I don't maintain that plugin. Just FYI: The PVR USB2 device is now handled by the pvrinput-plugin, which uses only ioctls. The "old" pvrusb2-plugin is obsolete. http://projects.vdr-developer.org/projects/show/plg-pvrinput Regards, Lars. > > I have over the years seen feedback from many users who just love using > the sysfs interface - by using sysfs for access to all the knobs& > switches while just using "cat /dev/video0" (or whatever) to grab the > video stream, it's possible to nearly completely operate the device > without writing a single line of C code. I have read of some people who > have hacked up shell scripts for special purposes using this driver. > > When I say "nearly completely" above, the big asterisk there is DVB. > The analog side is completely operable via sysfs. However because of > the way DVB works it is currently not possible to export the digital > side of the driver through anything except DVB itself (a situation that > I find to be "wrong" but probably will be very difficult to solve > technically due to DVB's architecture and will likely be impossible > anyway because the kinds of pvrusb2 driver changes that I think would be > required probably won't be accepted by others anyway so I haven't been > very motivated to attack the problem). > > >> >> And which non-control values do you at the moment expose in pvrusb2 through >> sysfs? Can you perhaps give an ls -R of all the files you create in sysfs >> for pvrusb2? > > *ALL* of them are exposed. The exact set is synthesized at run-time by > pvrusb2-sysfs.c via introspection of the control API defined in > pvrusb2-hdw.h. In the in-V4L version of the pvrusb2 driver this set of > controls is likely a constant, but it has certainly changed over time as > V4L and the pvrusb2 driver have evolved. In the standalone pvrusb2 > driver, the control set can actually vary due to ifdef's in > pvrusb2-hdw.c, which are affected by the kernel version and v4l-dvb > snapshot against which the driver is compiled. > > >> >> I am wondering whether some of those should get a place in the >> framework as well. While I don't think e.g. cropping parameters are >> useful, things like the current input or tuner frequency can be handy. >> However, for those to be useful they would have to be wired up >> internally through the framework. For example, VIDIOC_S_FREQUENCY >> would have to be hooked up internally to a control. That would ensure >> that however you access it (ioctl or sysfs) it will both end up in the >> same s_ctrl function. > > I think you're missing a critical point here. > > There isn't any logic in the module within the pvrusb2 driver which > "decides" which controls to expose. The driver itself has an internal > API used by everything else, and all that pvrusb2-sysfs.c does is > enumerate that to expose all of the controls. It would actually be > extra work in the pvrusb2 driver to impose a policy on which controls > are visible. The cropping parameters are an example of this. Another > pvrusb2 driver user wanted to get cropping to work (which unfortunately > *still* requires v4l-dvb changes that are not implemented). Part of his > implementation involved adding a few extra knobs within the driver to > control the cropping behavior. Once he did that, the knobs > automatically became available via sysfs. > > >> >> It will be nice to hear from you what your experience is. > > Here's my experience: > > I originally did the sysfs interface back in 2005 as a proof of concept. > I wanted to prove that the internal API within the driver was > functionally complete and relatively easy to use. I had recently > finished reading the LDDv3 and learned of the sysfs class interface. > It occurred to me back then that it would be easy to define a sysfs > class interface for the pvrusb2 driver in terms of that API. So I did, > and it was literally a 2 day hack. It's worked fabulously well ever > since. In terms of popularity, I find that the user community loves it, > while the developer community seems to tolerate it. > > I routinely use the sysfs interface for my own testing. It's just > simply trivial to tweak things in the driver at the shell level using > that interface. I remember once using all the mpeg knobs to experiment > with all the ways that filtering could be controlled, for example. A > common use-case for me during testing is to use mplayer as a dumb > streaming app while tweaking the driver via sysfs. > > I've had feedback from many users over the years who, upon discovering > this interface, just latch onto it. On more than one occassion I've had > feedback to the effect of "I don't care about any V4L app; I just want > to stream video and the sysfs interface makes this trivial to control". > Probably the fact that only just a small handful of V4L apps (xawtv, > mythtv and recently now mplayer?) even handle mpeg video has amplified > this behavior: Many users have found it simpler to forget about V4L apps > and just instead "cat /dev/video0" along with some shell hacking. > > And long ago I know the VDR application gained a plugin script which > itself used the sysfs interface to control the driver. > > One aspect of that sysfs interface that I think has had a lot of value > over time is that it is (within limits) self-describing. For each > control you get not only the ability to get (and usually set) its value, > but you can inspect its limits, learn what the default value is, > retrieve a description (though being english only that has limited > utility), and discover its type. The sysfs interface in the driver > tries to use symbolic values where possible, including when setting / > clearing bits in a bit mask. The fact that such information is there > helps when writing, say, a generic dialog-based wrapper to provide a TUI > (Text User Interface) over the interface without having to encode too > much specific information in the wrapper itself. Thus if new controls > get added (or changed) later then such things just automatically adapt. > Of course this isn't a perfect thing, but it helps. > >> >> Comments? Ideas? Once we commit to something it is there for a long time to >> come since sysfs is after all a public API (although it seems to be more >> changable than ioctls). > > I have found it useful over a long period of time. > > I also suggest that if such an interface is defined in the general case > that it should include some introspection capabilities, which will make > it easier (or even possible) to evolve the interface over time while > minimizing backwards compatibility issues. > > If such a generic interface were made available, I could see an argument > to remove the sysfs interface from the pvrusb2 driver. HOWEVER there is > a community using it, and also unless the generic interface were a > complete replacement, the pvrusb2 piece will probably have to stay. > (Note: the sysfs interface in the pvrusb2 driver is already a CONFIG_XX > parameter so it's easy to deselect it when building the driver.) > > -Mike > >