Compatibility
=============

Please read this carefully: the merging of ivtv and the ivtv
framebuffer driver into the kernel introduced several changes which
impact how you setup the X driver and what MythTV version you can
use.

This X11 driver supports all ivtv versions >= 0.2. If you are using
ivtv >= 1.0.0 and you want to use the PVR350 MPEG decoder with MythTV,
then you need to get the MythTV subversion trunk or the mythtv-vid branch.
The current MythTV release (0.20.2) only supports ivtv versions < 1.0.0.

If you use ivtv 0.10.x and you are using the PVR350 MPEG decoder with
MythTV <= 0.20.2 (i.e., you are not using the MythTV subversion trunk or
the mythtv-vid branch), then you must set the osd_compat=1 option for the
ivtv-fb module. This is the only time you need to do this. See the osd_compat
section at the bottom if you need this, since it impacts the X configuration
file.

There is a bug in the ivtv-1.0.0 driver in kernel 2.6.22 that will make
MythTV from the MythTV subversion trunk or the mythtv-vid branch hit a
locking error occasionally. This is fixed in kernel 2.6.23 and the fix
is also expected to go into kernel 2.6.22.11. Kernels < 2.6.22 are fine.

Note that the name of the ivtv framebuffer kernel module changed:
it is called ivtvfb for ivtv >= 1.0.0 and ivtv-fb for older ivtv versions.
So if you use ivtv < 1.0.0 and you read 'ivtvfb' in the text below, then
replace it with 'ivtv-fb'.

The ivtv framebuffer driver can be obtained from www.ivtvdriver.org. It
is part of the ivtv package. It will be merged with kernel 2.6.24.

The latest MythTV subversion code has overhauled the video out 
handling. By default it will select the 'Bob (2x)' deinterlacer for
Xv output. This is NOT compatible with the Xv overlay support for the
PVR-350. It won't crash, but the resulting image will be extremely poor.
So don't use that.

Xorg 7.x Servers
================

For new 7.x servers run:

	autogen.sh 
        make
        make install

The installation path may well need to be altered using the --prefix
option in autogen.sh.

If you get this error when running autogen.sh or the configure script:

checking for XORG... configure: error: Package requirements (xorg-server
xproto fontsproto ) were not met.

then it is likely that you are missing the xorg-server development
package. For Fedora this package is called 'xorg-x11-server-sdk'.

Debian 4.0 (etch) uses X 7.1.1. You must install the required packages
by using 'apt-get install autoconf automake libtool xserver-xorg-dev
x11proto-core-dev x11proto-fonts-dev'. You can check success by
checking if the files ivtv_drv.la and ivtv_drv.so are available at
/usr/local/lib/xorg/modules/drivers

Xorg 6.x & Xfree86 servers
==========================

cd src
xmkmf {path to Xserver xc directory}
make

Then copy the ivtv_drv.so file into the appropriate location.

Note: this driver used to be called ivtvdev_drv.so but the name was
changed starting with version 1.0.0 to be consistent with existing
X11 video drivers.


X configuration
===============

The next step is to setup the X configuration to enable the X display.
For Xorg the configuration file is /etc/X11/xorg.conf, for Xfree86
the configuration file is /etc/X11/XF86Config.

The default resolution of the framebuffer is 640x400 for NTSC and
640x480 for PAL and SECAM. So the configuration differs between
the two. (For ivtv < 0.10, the resolution is locked to 720x480 for NTSC
and 720x576 for PAL. See the osd_compat section at the bottom for
suitable screen mode entries.)

For NTSC you should add the following to your X config file:

------------------------- cut here -------------------------
Section "Monitor"
    Identifier     "NTSC Monitor"
    HorizSync       10-68
    VertRefresh     25-120

    Mode "640x400"
        DotClock    23.832
        HTimings    640 735 759 800
        VTimings    400 454 456 497
        Flags      "-HSync" "-VSync"
    EndMode
EndSection

Section "Device"
    Identifier     "Hauppauge PVR-350 Framebuffer"
    Driver         "ivtv"
    Option         "fbdev" "/dev/fb0"      # <-- modify if using another device
    BusID          "0:10:0"                # <-- obtain from lspci (see later)
EndSection

Section "Screen"
    Identifier     "TV Screen"
    Device         "Hauppauge PVR-350 Framebuffer"
    Monitor        "NTSC Monitor"
    DefaultDepth    24
    DefaultFbBpp    32
    SubSection     "Display"
        Depth       24
	FbBpp 	    32
        Modes      "640x400"
    EndSubSection
EndSection
------------------------- cut here -------------------------

For PAL/SECAM you should add the following to your X config file:

------------------------- cut here -------------------------
Section "Monitor"
    Identifier     "PAL Monitor"
    HorizSync       10-68
    VertRefresh     25-120

    Mode "640x480"
	DotClock    23.721
	HTimings    640 735 759 800
	VTimings    480 542 544 593
        Flags      "-HSync" "-VSync"
    EndMode
EndSection

Section "Device"
    Identifier     "Hauppauge PVR-350 Framebuffer"
    Driver         "ivtv"
    Option         "fbdev" "/dev/fb0"      # <-- modify if using another device
    BusID          "0:10:0"                # <-- obtain from lspci (see later)
EndSection

Section "Screen"
    Identifier     "TV Screen"
    Device         "Hauppauge PVR-350 Framebuffer"
    Monitor        "PAL Monitor"
    DefaultDepth    24
    DefaultFbBpp    32
    SubSection     "Display"
        Depth       24
	FbBpp 	    32
        Modes      "640x480"
    EndSubSection
EndSection
------------------------- cut here -------------------------

In the "Device" section you will have to modify the Option field to select
the correct framebuffer device (usually /dev/fb0 or /dev/fb1). You also have
to obtain the correct BusID of the framebuffer device. To do that run:

lspci | grep iTVC15

You should get a line like this:

06:02.0 Multimedia video controller: Internext Compression Inc iTVC15 MPEG-2 Encoder (rev 01)

The numbers at the beginning form the BusID: 06:02.0 becomes "6:2:0" in the
X config file. Note that lspci reports the numbers as hexadecimal where the
BusID option expects them as decimal. So if lspci reports "01:0e.0", then
BusID should be "1:14:0".

The final step is to add the TV Screen to you server layout:

Section "ServerLayout"
    ...
    Screen 0 "Screen 1"                      # << (your computer monitor)

    # (add the following line)
    Screen 1 "TV Screen" RightOf "Screen 1"  # << (TV screen)
    ...
EndSection

If you want to use the TV Screen as the main display, then you can just use:

    Screen 0 "TV Screen"
  
After restarting X you should see the X screen on your TV.


Custom resolutions
==================

Note: Custom resolutions are only possible if the osd_compat module option was
not specified with the ivtv-fb module. Setting that option locks down the
resolution to a fixed value.

If you want to use a custom resolution then you should first load the
ivtvfb module with the resolutions you want. To do that change your
modprobe configuration file by adding a line to /etc/modprobe.conf or
(for Debian 4.0) by creating a file /etc/modprobe.d/ivtvfb:

options ivtvfb osd_xres=720 osd_yres=576

(Run 'modinfo ivtvfb' to see all module options.)

Now load ivtvfb ('modprobe ivtvfb') and the new height and width will be used.

Note that you should make sure that either X isn't started at all, or that
X isn't using the PVR-350 framebuffer. You can get problems if the
X configuration and the framebuffer have a mismatch regarding the resolution
or timings.

Next run 'fbset -x /dev/fbX' (replace /dev/fbX with the correct framebuffer
device). That gives you a new Mode description, e.g.:

Mode "720x576"
    # D: 23.720 MHz, H: 29.650 kHz, V: 50.001 Hz
    DotClock 23.721
    HTimings 720 775 799 800
    VTimings 576 590 592 593
    Flags    "-HSync" "-VSync"
EndMode

Replace the "Mode" subsection in the "Monitor" section and update the
Modes resolution in the "Screen" section.

Start X and the new resolution should be used.

You can also have multiple "Mode" subsections in "Monitor" and use xrandr to
switch dynamically.


How to prevent the console from using the framebuffer
=====================================================

By default when you load ivtvfb the framebuffer is used for the console
output. Unfortunately, this is usually very annoying since this makes it
hard to unload ivtvfb.

You can prevent this by adding a magic incantation to the kernel options
in your grub or lilo configuration.

If your monitor console is using the framebuffer of you graphics cards,
then you should use kernel option 'fbcon=vc:0-0'. This ensures that only
the first framebuffer device (that of your graphics card) is used.

If you don't use a framebuffer at all for your console, then use the option
'fbcon=vc:64-63', this will prevent any framebuffer device from being used
for the console.

However, in kernel 2.6.23 the 'vc:64-63' trick no longer works. Instead
enable the VT_HW_CONSOLE_BINDING configuration option when compiling
the kernel: 'Device Drivers', 'Character devices', 'Support for binding and
unbinding console drivers'. You can now unload ivtvfb by running
'rmmod -f ivtvfb' and the standard console will automatically be reattached.

There may be more elegant methods of doing this, please let me know if
you find one.


Xv interlace controls
=====================

To enable the Xv interlace controls, the following line should be added to the
ivtv Device section in the X11 configuration file:

 Option "xv_interlace" "true"

When X is started with the above option, the following line should appear in
the log file:

 IVTV(x): Xv interlace controls enabled

With Xv interlace controls enabled, the following attributes are available :-

 XV_FIELD_TOPFIRST
  0 = Bottom field first
  1 = Top field first (default)

 XV_INTERLACED
  0 = Progressive
  1 = Interlaced
  2 = Driver select (default)

 XV_FIELD_OVERRIDE (Overrides XV_FIELD_TOPFIRST)
  -1 = No action (default)
  0 = Force bottom field first
  1 = Force top field first
  2 = Invert field order set by XV_FIELD_TOPFIRST

XV_FIELD_OVERRIDE is really a kludge that allows the field order to be forced
when the application that's playing the video gets the field order wrong.
Unless there is a problem with playback, it should be left at -1.

NOTE: Interlace controls are only supported from ivtv 0.10.0 onwards. Version
0.10.6 or versions >= 1.1.0 are recommended.


ivtv-fb osd_compat option
=========================

If you are using ivtv 0.10.x and MythTV <= 0.20.2, then you have to set
the osd_compat=1 option for the ivtv-fb module. This selects the framebuffer
mode that MythTV expects (these MythTV versions hardcoded the framebuffer
resolution and depth. If these would not match, then you would get a crash).

In practice this means that the X configuration changes. Instead of having
a section Mode "640x480" (PAL) or Mode "640x400" (NTSC) you now have to
specify this:

NTSC:

Mode "720x480"
    DotClock 23.832
    HTimings 720 775 799 800
    VTimings 480 494 496 497
    Flags    "-HSync" "-VSync"
EndMode

PAL:

Mode "720x576"
    DotClock 23.721
    HTimings 720 775 799 800
    VTimings 576 590 592 593
    Flags    "-HSync" "-VSync"
EndMode

And the Modes line in your Screen section also changes from "640x400" or
"640x480" to "720x480" or "720x576" respectively.
