videobook.tmpl

嵌入式系统设计与实例开发实验教材二源码 多线程应用程序设计 串行端口程序设计 AD接口实验 CAN总线通信实验 GPS通信实验 Linux内核移植与编译实验 IC卡读写实验 SD驱动使

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN"[]>

<book id="V4LGuide">
 <bookinfo>
  <title>Video4Linux Programming</title>
  
  <authorgroup>
   <author>
    <firstname>Alan</firstname>
    <surname>Cox</surname>
    <affiliation>
     <address>
      <email>[e-mail]</email>
     </address>
    </affiliation>
   </author>
  </authorgroup>

  <copyright>
   <year>2000</year>
   <holder>Alan Cox</holder>
  </copyright>

  <legalnotice>
   <para>
     This documentation is free software; you can redistribute
     it and/or modify it under the terms of the GNU General Public
     License as published by the Free Software Foundation; either
     version 2 of the License, or (at your option) any later
     version.
   </para>
      
   <para>
     This program is distributed in the hope that it will be
     useful, but WITHOUT ANY WARRANTY; without even the implied
     warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
     See the GNU General Public License for more details.
   </para>
      
   <para>
     You should have received a copy of the GNU General Public
     License along with this program; if not, write to the Free
     Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
     MA 02111-1307 USA
   </para>
      
   <para>
     For more details see the file COPYING in the source
     distribution of Linux.
   </para>
  </legalnotice>
 </bookinfo>

<toc></toc>

  <chapter id="intro">
      <title>Introduction</title>
  <para>
        Parts of this document first appeared in Linux Magazine under a
        ninety day exclusivity.
  </para>
  <para>
        Video4Linux is intended to provide a common programming interface
        for the many TV and capture cards now on the market, as well as
        parallel port and USB video cameras. Radio, teletext decoders and
        vertical blanking data interfaces are also provided.
  </para>
  </chapter>
  <chapter id="radio">
        <title>Radio Devices</title>
  <para>
        There are a wide variety of radio interfaces available for PC's, and these
        are generally very simple to program. The biggest problem with supporting
        such devices is normally extracting documentation from the vendor.
  </para>
  <para>
        The radio interface supports a simple set of control ioctls standardised
        across all radio and tv interfaces. It does not support read or write, which
        are used for video streams. The reason radio cards do not allow you to read
        the audio stream into an application is that without exception they provide
        a connection on to a soundcard. Soundcards can be used to read the radio
        data just fine. 
  </para>
  <sect1 id="registerradio">
  <title>Registering Radio Devices</title>
  <para>
        The Video4linux core provides an interface for registering devices. The
        first step in writing our radio card driver is to register it.
  </para>
  <programlisting>


static struct video_device my_radio
{
        "My radio",
        VID_TYPE_TUNER,
        VID_HARDWARE_MYRADIO,
        radio_open.
        radio_close,
        NULL,                /* no read */
        NULL,                 /* no write */
        NULL,                /* no poll */
        radio_ioctl,
        NULL,                /* no special init function */
        NULL                /* no private data */
};


  </programlisting>
  <para>
        This declares our video4linux device driver interface. The VID_TYPE_ value
        defines what kind of an interface we are, and defines basic capabilities.
  </para>
  <para>
        The only defined value relevant for a radio card is VID_TYPE_TUNER which
        indicates that the device can be tuned. Clearly our radio is going to have some
        way to change channel so it is tuneable.
  </para>
  <para>
        The VID_HARDWARE_ types are unique to each device. Numbers are assigned by
        <email>[e-mail]</email> when device drivers are going to be released. Until then you
        can pull a suitably large number out of your hat and use it. 10000 should be
        safe for a very long time even allowing for the huge number of vendors
        making new and different radio cards at the moment.
  </para>
  <para>
        We declare an open and close routine, but we do not need read or write,
        which are used to read and write video data to or from the card itself. As
        we have no read or write there is no poll function.
  </para>
  <para>
        The private initialise function is run when the device is registered. In
        this driver we've already done all the work needed. The final pointer is a
        private data pointer that can be used by the device driver to attach and
        retrieve private data structures. We set this field "priv" to NULL for
        the moment.
  </para>
  <para>
        Having the structure defined is all very well but we now need to register it
        with the kernel. 
  </para>
  <programlisting>


static int io = 0x320;

int __init myradio_init(struct video_init *v)
{
        if(check_region(io, MY_IO_SIZE))
        {
                printk(KERN_ERR 
                    "myradio: port 0x%03X is in use.\n", io);
                return -EBUSY;
        }

        if(video_device_register(&amp;my_radio, VFL_TYPE_RADIO)==-1)
                return -EINVAL;
        request_region(io, MY_IO_SIZE, "myradio");
        return 0;
}

  </programlisting>
  <para>
        The first stage of the initialisation, as is normally the case, is to check 
        that the I/O space we are about to fiddle with doesn't belong to some other 
        driver. If it is we leave well alone. If the user gives the address of the 
        wrong device then we will spot this. These policies will generally avoid 
        crashing the machine.
  </para>
  <para>
        Now we ask the Video4Linux layer to register the device for us. We hand it
        our carefully designed video_device structure and also tell it which group
        of devices we want it registered with. In this case VFL_TYPE_RADIO.
  </para>
  <para>
        The types available are
  </para>
   <table frame=all><title>Device Types</title>
   <tgroup cols=3 align=left>
   <tbody>
   <row>
        <entry>VFL_TYPE_RADIO</><entry>/dev/radio{n}</><entry>

        Radio devices are assigned in this block. As with all of these
        selections the actual number assignment is done by the video layer
        accordijng to what is free.</entry>
	</row><row>
        <entry>VFL_TYPE_GRABBER</><entry>/dev/video{n}</><entry>
        Video capture devices and also -- counter-intuitively for the name --
        hardware video playback devices such as MPEG2 cards.</entry>
	</row><row>
        <entry>VFL_TYPE_VBI</><entry>/dev/vbi{n}</><entry>
        The VBI devices capture the hidden lines on a television picture
        that carry further information like closed caption data, teletext
        (primarily in Europe) and now Intercast and the ATVEC internet
        television encodings.</entry>
	</row><row>
        <entry>VFL_TYPE_VTX</><entry>/dev/vtx[n}</><entry>
        VTX is 'Videotext' also known as 'Teletext'. This is a system for
        sending numbered, 40x25, mostly textual page images over the hidden
        lines. Unlike the /dev/vbi interfaces, this is for 'smart' decoder 
        chips. (The use of the word smart here has to be taken in context,
        the smartest teletext chips are fairly dumb pieces of technology).
	</entry>
    </row>
    </tbody>
    </tgroup>
    </table>
  <para>
        We are most definitely a radio.
  </para>
  <para>
        Finally we allocate our I/O space so that nobody treads on us and return 0
        to signify general happiness with the state of the universe.
  </para>
  </sect1>
  <sect1 id="openradio">
  <title>Opening And Closing The Radio</title>

  <para>
        The functions we declared in our video_device are mostly very simple.
        Firstly we can drop in what is basically standard code for open and close. 
  </para>
  <programlisting>


static int users = 0;

static int radio_open(stuct video_device *dev, int flags)
{
        if(users)
                return -EBUSY;
        users++;
        MOD_INC_USE_COUNT;
        return 0;
}

  </programlisting>
  <para>
        At open time we need to do nothing but check if someone else is also using
        the radio card. If nobody is using it we make a note that we are using it,
        then we ensure that nobody unloads our driver on us.
  </para>
  <programlisting>


static int radio_close(struct video_device *dev)
{
        users--;
        MOD_DEC_USE_COUNT;
}

  </programlisting>
  <para>
        At close time we simply need to reduce the user count and allow the module
        to become unloadable.
  </para>
  <para>
        If you are sharp you will have noticed neither the open nor the close
        routines attempt to reset or change the radio settings. This is intentional.
        It allows an application to set up the radio and exit. It avoids a user
        having to leave an application running all the time just to listen to the
        radio. 
  </para>
  </sect1>
  <sect1 id="ioctlradio">
  <title>The Ioctl Interface</title>
  <para>
        This leaves the ioctl routine, without which the driver will not be
        terribly useful to anyone.
  </para>
  <programlisting>


static int radio_ioctl(struct video_device *dev, unsigned int cmd, void *arg)
{
        switch(cmd)
        {
                case VIDIOCGCAP:
                {
                        struct video_capability v;
                        v.type = VID_TYPE_TUNER;
                        v.channels = 1;
                        v.audios = 1;
                        v.maxwidth = 0;
                        v.minwidth = 0;
                        v.maxheight = 0;
                        v.minheight = 0;
                        strcpy(v.name, "My Radio");
                        if(copy_to_user(arg, &amp;v, sizeof(v)))
                                return -EFAULT;
                        return 0;
                }

  </programlisting>
  <para>
        VIDIOCGCAP is the first ioctl all video4linux devices must support. It
        allows the applications to find out what sort of a card they have found and
        to figure out what they want to do about it. The fields in the structure are
  </para>
   <table frame=all><title>struct video_capability fields</title>
   <tgroup cols=2 align=left>
   <tbody>
   <row>
        <entry>name</><entry>The device text name. This is intended for the user.</>
	</row><row>
        <entry>channels</><entry>The number of different channels you can tune on
                        this card. It could even by zero for a card that has
                        no tuning capability. For our simple FM radio it is 1. 
                        An AM/FM radio would report 2.</entry>
	</row><row>
        <entry>audios</><entry>The number of audio inputs on this device. For our
                        radio there is only one audio input.</entry>
	</row><row>
        <entry>minwidth,minheight</><entry>The smallest size the card is capable of capturing
		        images in. We set these to zero. Radios do not
                        capture pictures</entry>
	</row><row>
        <entry>maxwidth,maxheight</><entry>The largest image size the card is capable of
                                      capturing. For our radio we report 0.
				</entry>
	</row><row>
        <entry>type</><entry>This reports the capabilities of the device, and
                        matches the field we filled in in the struct
                        video_device when registering.</entry>
    </row>
    </tbody>
    </tgroup>
    </table>
  <para>
        Having filled in the fields, we use copy_to_user to copy the structure into
        the users buffer. If the copy fails we return an EFAULT to the application
        so that it knows it tried to feed us garbage.