Dxr3 Logo

DXR3 & Hollywood Plus Logo
Linux DXR3 and Hollywood+ Driver Project Howto
     
  News
About
FAQ
Howto
Download
Links
Developers
Project Page
   DXR3 / Hollywood Plus HOWTO Table of Contents

Prerequisites

    As with any project there are some prerequisites. Besides the obvious, like needing a computer running a recent version of Linux, you will, for now, need some experience building packages from scratch. You will also have to be comfortable with a text editor. Yeah, you know what that means.

  • Dxr3 or Hollywood Plus

    I hate to have to say it but before you can start watching DVDs and MPEG streams using this driver, you need to have either a Creative Labs DXR3 or a Sigma Designs Hollywood Plus hardware MPEG decoder card. If you have any other decoder card, this driver is of no help to you. So, Sigma Designs' XCard won't work with this driver. But if you have a fast enough computer you can still watch MPEGs and DVDs on your monitor with one of the software viewers available. (Remember, this wouldn't be here if someone didn't ask . . . )

    The card name "dxr3" in this howto refers to all DXR3, Hollywood Plus and compatible cards.

  • Kernel 2.2 or newer

    This driver will only work with Linux kernels version 2.2 and greater. If you are running a 2.0 kernel, well then this is the time to get brave and upgrade! (And if you are running 1.2 or 1.3 on modern hardware then you are either criminally insane or a masochist, but that is a different story). But then there is the question, does a computer old enough to be running a 2.0 kernel actually have enough power to play a DVD - even with a hardware decoder card? Anyway, you'll need the source tree, and you'll need to have run at least "make config" and "make dep" in that tree. Preferably, you install the kernel source for your distribution (package kernel-source), check /usr/src/linux/README for instructions on how to configure the kernel, compile the kernel, install the new kernel, reboot and use uname -a to check that you're running the new kernel. That way you can be sure that the running kernel and the kernel source tree are in sync. Some distributions ship kernel development packages (kernel-devel or the like) that are enough to build modules for the corresponding kernel. If your distribution does that, it is recommended to use that package and build the modules against it, no need to recompile the kernel.

  • I2C Driver

    If you are running a 2.2 kernel, you need to install the I2C driver version 2.4.5 or newer! You can get the I2C driver for 2.2 kernels at the LM Sensors Homepage. If you have a 2.4 kernel, then I2C comes with the kernel and you just need to make sure that it is compiled into the kernel or as a module. If you fail to do this, then your card will emit X-Rays from your TV and cook your DNA! Just kidding. In either case, just make sure that you have this I2C driver installed.

  • rmquasar.vxd (H+) or enc2dev.vxd (dxr3) (as of driver 0.12.0 this is optional and not recommended unless you have serious problems with the supplied microcode)

    You need the appropriate VxD from the Windows driver for your card. If you have a Creative Labs Dxr3, then you will have enc2dev.vxd and if you have a Hollywood Plus, then you'll have rmquasar.vxd. Easy enough. Now, you should be able to find these bad boys in you windows/system directory. If you don't have a windows/system directory because you don't have windows, then you can still get these guys. You just need to obtain the latest version of your card's drivers from the appropriate web site and unzip them. But wait, what the hell is that?!?! They only give us rmquasar.vx_ and enc2dev.vx_! Where is the 'd'?!? They shorted us a 'd'! No, actually, Microsoft, in their infinite corporate wisdom, long ago instituted the policy of compressing their driver files for distribution, which strangely enough are compressed again (as zips, cabs, self extracting exes, etc.) which just wastes cpu cycles. And, if you haven't noticed, compressing a file twice rarely yields any gain in compression. Now, since we are missing a 'd', note: a very special 'd', from our driver file, we need to replace it. Included with the em8300 driver distribution in the scripts directory is a perl program called msexpand.pl which, when run like "msexpand.pl rmquasar.vx_", will after some time make a new copy of the file, this time with the special 'd' replaced. Then you may continue.

  • Compiler and Related Tools

    You will need Perl and a C compiler. If you're building from a Mercurial checkout, you'll need some GNU programs: automake and autoconf. Those two also require GNU m4. Also, bootstrapping a Mercurial checkout requires the development files for GTK+ 2.x (in particular, its m4 macros). If you get errors later about missing header files or libraries, you'll have to install those as well. Chances are that suitable versions are available in your distribution; if not, get them off the Internet.

Getting the Source

    There are currently two ways to get the source for this driver: by downloading a 'stable' release or by downloading the latest development version. Depending on how old the last release is, it may be best to try out the development version.

  • Download a Release

    If you decide to try one of the 'stable' releases, please note that as of yet none are really quite stable. They are more akin to Mozilla's milestones in that there are still many bugs to be worked out.

  • Source Via Mercurial

    Ok, yeah, you know the development repository is often broken and unstable. Well, yeah, but we still need you guys to check out the latest and greatest from it and report those bugs. So please do. It wont bite, I promise! See the Mercurial section of the download page for instructions how to do a checkout. When done correctly, it should result in an em8300 subdirectory in the directory where the checkout was done. In there you'll find all the goodies you'll need later on.

Compiling the Modules

    Now we must compile the kernel modules and get them configured and loaded.

  • Makefile settings

    Ok, chdir to em8300/modules and open up the Makefile in your favorite editor. Now change KERNEL_LOCATION to wherever your current kernel source tree is, and make sure that you've at least run "make config ; make dep" in there. Now, change -DEM8300_VIDEOMODE_DEFAULT= to EM8300_VIDEOMODE_PAL, EM8300_VIDEOMODE_PAL60, or EM8300_VIDEOMODE_NTSC. If you live in the Americas, choose NTSC. Elsewhere (like Europe), you're probably PAL. If you live in the former Soviet Union then your standard is SECAM, which these cards do not support. You can probably get a PAL TV or use VGA Overlay. Don't worry about these defaults too much because they can be set at run time either by a dvd player with dxr3 support or by the dhc utility.

  • If you have a 2.2 kernel (As of driver 0.11.0 this is no longer needed)

    If you are using a 2.2 kernel, just copy Makefile.2.2 to Makefile and follow the instructions below. Make sure you have the I2C module compiled and installed.

  • Compiling

    Just run "make". This will build the four modules, adv717x.o, bt865.o, em8300.o, and eeprom.o. To install the modules, run "make install".

    If you have any trouble compiling the modules please send a detailed message to the mailing list at dxr3-devel@lists.sourceforge.net. Thanks.

Creating the Device Files

    In Linux, and Unix in general, to communicate with a device you need to have a device file. Well, the Dxr3 and H+ are no different. We currently use four device files, which must be created as root. If you are running devfs or udev, these will be created automatically and will use kernel assigned major/minor numbers, no need to read this section.

  • Creating the /dev/em8300* devices

    To create the four device files, you must be root. As root, run the modules/devices.sh script or these commands:

    # mknod /dev/em8300-0 c 121 0 # mknod /dev/em8300_mv-0 c 121 1 # mknod /dev/em8300_ma-0 c 121 2 # mknod /dev/em8300_sp-0 c 121 3 Note: The device numbers that we are using are currently using are likely to change in the future. Keep that in mind.

    To use more than one card, you need similar device nodes for all cards. Again, udev will do the trick at least since version 0.15.3.

    If you have to create the device nodes manually, just follow the pattern given for one card. Minor number keeps growing, and the number in the device file changes for each card respectively (X in /dev/em8300*-X), everything else remains the same:

    # mknod /dev/em8300-1 c 121 4 # mknod /dev/em8300_mv-1 c 121 5 # mknod /dev/em8300_ma-1 c 121 6 # mknod /dev/em8300_sp-1 c 121 7

    That made the second card, then the third...

    # mknod /dev/em8300-2 c 121 8 # mknod /dev/em8300_mv-2 c 121 9 # mknod /dev/em8300_ma-2 c 121 10 # mknod /dev/em8300_sp-2 c 121 11

Loading the Kernel Modules

  • ldm and rmm

    In the em8300/modules directory there live two shell scripts related to loading and unloading the kernel modules, ldm and rmm. ldm automates loading of the driver modules, and rmm automates unloading of the modules. In order to pass module parameters to the adv717x.o and em8300.o modules you must edit the ldm script. Commented out underneath the lines to load the adv717x and em8300 modules you can see some examples of the more commonly used module parameters. So, for example, to set the adv717x module option "pixelport_16bit" to 0 and "pixelport_other_pal" to 1 you would have a line like the following:

    insmod adv717x.o pixelport_16bit=0 pixelport_other_pal=1

    Enter other module options similarly. See the following table for a list of module options and explanations of what they do. If you don't want to use ldm and rmm you can just issue the appropriate modprobe/insmod/rmmod commands by themselves and enter the module parameters on the command line or in /etc/modules.conf. Note, with ldm, module options located in /etc/modules.conf will not be read, so if you use ldm make sure to edit the module options in there.

  • Module Parameters

    There are multiple parameters for each of the modules that affect their functionality. The choice of module options will depend upon your particular board. Also, module options for the adv717x driver do not matter for cards with a bt865 chip and vice versa. Further, module options for the adv717x and bt865 modules only matter for TV output and have no effect on overlay. See the Setting the Output Mode section for more information.

All Things Microcode

    The em8300 RISC processor needs to be programed before use. This program is called a "microcode" and we will use the one that has already been written for us.

  • Supplied em8300.uc

    Note that version 0.12.0 and later of the driver package comes with a microcode (em8300/drivers/em8300.uc) so just running em8300setup should be enough after it's properly installed, no need to extract your own.

    Additionally, versions 0.15.2 and later have the capability to load the microcode on demand, so even running em8300setup is no longer needed for the purpose of just loading it. You may want to run it for other purposes, though.

    In any case, the microcode file must exist on the Linux system in a place where the kernel modules can find it. One possible location is /lib/firmware/em8300.bin but that can vary between Linux distributions. You can verify that the microcode was found and loaded successfully by searching for "Microcode" in the system log, "dmesg" output, and/or "cat /proc/em8300/*".

    If you use the drivers in packaged form from your distribution, chances are that the microcode is not included in the package. If that is the case, read on.

    A microcode that is known to work well for many users is available separately from http://dxr3.sourceforge.net/download/. If you decide to use it, you can skip directly to the loading section.

  • Uncompressing

    If you have downloaded a copy of the Windows driver (preferably the Windows 98 driver) from Sigma Designs or Creative Labs or copied the driver from the cdrom, then you will have to uncompress the driver files. If you have already installed the Windows driver and have access to your windows/system directory, then you can skip to the next section. First use unzip to uncompress and expand the driver archive. In that archive you will find either rmquasar.vx_ or enc2dev.vx_ depending if you have the Sigma Designs or Creative Labs drivers, respectively. Now we have to uncompress this file. Use the provided perl program "msexpand.pl" located in em8300/scripts to uncompress this file. For example:

    $ unzip HP1_82W1.ZIP $ em8300/scripts/msexpand.pl rmquasar.vx_

  • Extracting

    Now that we have the uncompressed Windows 98 driver vxd, we need to extract the microcode files. To do that use the included perl program microcode_extract.pl located in em8300/scripts. After running this program two or three microcode files will be written to the current directory, the number depending on the driver you have. The different microcode versions seem to be for different revisions of the cards. Currently, the only way to determine which microcode is correct for your card is to try them all and pick the one that works the best. Do not be alarmed if some of them do not work at all.

  • Loading

    At this point you should have the extracted microcode files available. If you're using version 0.15.2 or newer, copy the microcode file to wherever your system's hotplug configuration loads firmware images from (often /lib/firmware), name it em8300.bin, and load the modules; the microcode should be automatically uploaded. If not, or if using version 0.15.1 or earlier, you can use the em8300setup tool to load it. Run em8300setup -h and look at the -f option and where it expects to find the microcode from, copy the microcode there, and try loading it with em8300setup. If things go well, /proc/em8300/* should show that the microcode is loaded. If it says it is not, verify that the /dev/em8300* device files exist. If they do and you have the right permissions (if unsure just chmod a+w /dev/em8300*) it usually means that you have the option "PNP OS Installed" set to "enabled" in your bios. This option exists in virtually all x86 bioses since the pentium. Disable this option, this means the bios will set up all your plug and play device prior to booting the operating system. Windows has a bad habit of randomizing pnp options on booting making it impossible for linux to save any settings as they will have changed after booting into windows. Disabling pnp os will fix this.

    Note: This may cause vga passthrough to stop functioning. We are working on this. The solution at this time is to just plug your monitor straight into the video card or use the "activate_loopback" em8300 module option. You cannot watch MPEG streams on the TV output connector with activate_loopback set, however.

Playing MPEG Streams and DVDs

    This section is all about playing MPEGs and DVDs. If you are using VGA loopback, first see the VGA Overlay section then come right back here. If you are playing on a TV, then make sure you have all your cables connected properly, and that your TV is set to receive the composite signal generated by the card. So, since you are following this document from top to bottom, you should be ready to go.

  • Playing MPEGs via /dev/em8300_mv-* and /dev/em8300_ma-*

    Sending mpeg and pcm streams directly to the card is a great way to test that the thing is working properly without the overhead of working with a full on DVD player. In order to display a MPEG video stream simply send it to "/dev/em8300_mv-0". In order to test the analog audio capability of the card you can use mpg123. For example:

    $ extract_mpeg2 testvideostream.mpeg > /dev/em8300_mv-0 $ mpg123 -a /dev/em8300_ma-0 somegoodtestmusic.mp3 Note, you must send only MPEG video streams to /dev/em8300_mv-*, and only PCM audio to /dev/em8300_ma-*. An MPEG system file, composed of both video and audio, will cause garbage to be displayed on the screen. You must first separate the system into video and audio components, and play each one separately. Also, /dev/em8300-* is a control device, and cannot be use to play mpeg systems.

  • Using Xine to play DVDs

    A dxr3 plugin is included with Xine since Xine 0.5.0. Please see xine-lib/doc/README.dxr3

  • Using MPlayer to play DVDs

    Invoke mplayer with the following options: "-ao oss:/dev/em8300_ma-0 -vo dxr3 -dvd <chapternumber>"

  • Using MPlayer to play DivX/RealVideo etc

    To play any non MPEG1/2 content with mplayer you have to specify an MPEG1 filter, you do this by adding -vop lavc or -vop fame and you are good to go. If you are using gmplayer (GUI enabled MPlayer) you can set the mpeg1 filter to use in Preferences->Video->(dxr3)->Configure Driver.

  • Using OMS to play DVDs

    OMS was the original player for this project but since then development seems to have stopped. Thus, we currently suggest you use Xine. This may change at some future date.

Other Useful Programs

    In this section we describe some useful programs that have been contributed to the project.

  • DHC by Ze'ev Maor

    DHC is a useful program written by Ze've Maor. DHC's source lives in the em8300/dhc directory and it is built by default during the build process if GTK+ 2.x's development files are available. DHC can be used to adjust the brightness, contrast, saturation, aspect ration, TV output standard (PAL, NTSC, and PAL 60), turn on and off the subpicture (subtitles, etc.), and change between analog and spdif audio outputs.

Using VGA Overlay Mode

    VGA Overlay can be used to view hardware MPEG decoded streams on your computer monitor. The main drawback of the Dxr3/H+ design is that using this feature results in added noise and reduced visual quality on the monitor from the video card. So, you may notice that your text that used to appear crisp is now fuzzy with the decoder card inserted. Sorry, there is nothing we can do about this. If it bothers you too much, use a TV instead.

  • Setting it up

    First, you must make sure that the overlay cable is correctly installed. Follow the instructions that came with your card. Second, you may need to enable the "activate_loopback" module option for the em8300 module. See the Module Parameters section above for details. Unload and reload the modules for the change to take effect, if needed. Then you must load the microcode. See the section All Things Microcode for help loading the microcode. Now you should be ready to continue to the next section. Note: Overlay support is considered experimental at this time and will probably not work.

  • dxr3view and autocal

    Again, run "bootstrap" in the em8300 directory, then run configure, make, and make install. First, run autocal. This will make the screen flash for a second. This has to be done every time the microcode is reloaded, which means that you must load Xine or OMS before running autocal. Yeah, I know its silly. Should be fixed in the future. Then you have to run dxr3view. This will bring up a rectangular window with the overlay window on top. It should look akin to the windows overlay. Now, you should be able to press play in Xine or OMS and watch your MPEG. The control window in dxr3view can be used to fine tune the size, shape, and appearance of the overlay to a certain extent. Also, if you press 't' while the mouse is over the dxr3view window, a menu with several options, including fullscreen, will appear.

Setting the Output Mode

    Available output modes of dxr3 cards cover all needs. Readily available are composite, S-video and component, that is, YUV. For RGB output a hardware modification must be done. Output mode is selected by controlling the card's video encoder chip with module options. Video encoder chip is either BT865, ADV7170 or ADV7175. BT865 is controlled by module bt865.ko and the ADV chips by module adv717x.ko. The encoder chip isn't any MPEG encoder, no way. Instead it gets the raw, digital video signal from the EM8300 MPEG2 decoder and encodes it into analog output signal, adds the necessary sync signals, color burst that PAL needs and so on. The chip has four DAC outputs of which three are connected to the mini-DIN output connector. The fourth is needed for RGB output. Additionally, with a modified card and special cable you can get two composite outputs plus S-video simultaneously. In a multiroom system you could use one output for one room, the other for another room and S-video for video projector without any video distribution anmplifier. All outputs are perfect 75-ohm outputs, no impedance problems. Audio output can be divided into two or three with a simple divider cable.

    This section describes only a subset of available output modes; the canonical and most up to date document about it is modules/README-modoptions in the source tree, consult it for more information. Note that some parameters are available only for ADV717X based cards.

  • Setting up composite

    The default output mode of dxr3 is composite with S-video, so, using this mode won't require any options.

    However, if you need to set this mode for your card, for example in a multiple-dxr3 system, the option is

    modprobe adv717x output_mode=comp+svideo modprobe bt865 output_mode=comp+svideo The composite+svideo cable that comes with the card will do.

  • Setting up S-video

    The default output mode of dxr3 is composite with S-video, so using this mode won't require any options either. However, it has been reported that in some setups, using plain S-video results in significantly better picture quality than with composite with S-video. In case you're not regularly switching cables between composite-only and S-video-only devices but use S-video most of the time, it is recommended to set S-video only output using the svideo output mode instead of comp+svideo.

    If you need yo set this mode for your card, for example in a multiple-dxr3 system, the option is

    modprobe adv717x output_mode=comp+svideo modprobe bt865 output_mode=comp+svideo or for plain S-video if you have a ADV717X based card modprobe adv717x output_mode=svideo The composite+svideo cable that comes with the card will do, or you can stick the S-video cable straight into dxr3's output connector. Actually, the comp+svideo mode is 2comp+svideo, so, with a modified card and special cable you get two composite outputs plus S-video.

  • Setting up YUV

    There are video projectors that don't have RGB input for NTSC/PAL frequencies, that is, no SCART connector. Instead, they have component video connectors. For practical purposes, component video and RGB give the best picture quality, better than S-video or composite. YUV output is available only with ADV717X based cards.

    modprobe adv717x output_mode=yuv You will need a special cable for YUV output. The component video cable for the REALmagic Xcard™ (part # 22-000213-01 in the REALmagic online shop) has been reported to work. As usual, no guarantees, your mileage may vary.

  • Setting up RGB

    Using RGB output requires a hardware modification for the card, because only three output signals from the video encoder chip are connected to the mini-DIN output connector. Bad design, veery baad design, naughty manufacturers. RGB output actually needs the R, G and B lines plus a fourth line for synchronization signal, that is, composite video. Those signals are found in any RGB-accepting SCART connector. There is another way of synchronizing the RGB picture, adding the sync signals to only Green line yielding to sync-on-green, or adding the sync signals to all R, G and B. However, displays accepting these kind of sync signals are rare, next to not existing, I'd say. The SCART standard requires the discrete sync signal, so, we'll have to do that way and add the missing connection to the dxr3.

    But, module options first. For SCART connector:

    modprobe adv717x output_mode=rgb modprobe bt865 output_mode=rgb For sync on green, that is, sync on all R, G and B (available with ADV717X based cards only): modprobe adv717x output_mode=rgbs You will need a special cable and to modify your card to use RGB output.

Using Multiple Cards

    Yes, it's possible to use more than one dxr3 card in one computer. The multicard functionality has been built into the driver for some time ago, but there were some bugs that have been corrected as of version 0.15.3 and later.

  • Output Modes

    If you have, say, two dxr3 cards is your computer and you want to have the best RGB picture for yourself but composite for livingroom because composite goes nicely in one coaxial cable instead of four, set the cards accordingly, composite being actually composite and S-video:

    modprobe adv717x output_mode=rgb,comp+svideo modprobe bt865 output_mode=rgb,comp+svideo So you just give the options separated by commas. The same goes for three cards, of which #1 would be RGB, #0 and #2 composite+svideo: modprobe adv717x output_mode=comp+svideo,rgb,comp+svideo modprobe bt865 output_mode=comp+svideo,rgb,comp+svideo and so on.

Identifying your Card

    Sometimes it is helpful to know some details about your particular board, especially if you need help getting the driver to work. You can use the following table to help figure out what card you have and if there are any special notes about it.

  • Sigma Designs Hollywood Plus Variants

    Board ID EM8300 Version Video Chip Notes
    ??? Rev 2 ADV7170 Requires pixelport_16=0
    ??? Rev 2 ADV7175 Requires pixelport_16=1, dicom_control=1, dicom_fix=1

  • Creative Labs Dxr3 Variants

    Board ID EM8300 Version Video Chip Notes
    ct7235-vbq (9938 rev b) board:ct7260 Rev 2 Conexant bt865akrf  

Getting Help

    Eventually, every one of us needs a little help, especially with this hardware ;). There are currently three ways to get help: IRC, the mailing list, and the Sourceforge Fora. Note, the best way to get help is the Mailing list, and the least favorable is the SourceForge Fora. This may change in the future, but currently not many developers visit the SourceForge Fora.

  • Mailing List - Preferred Method

    By far the best way to get help is to send a message to the mailing list. This is because all the developers are subscribed and read their email throughout the day. The list is dxr3-devel@lists.sourceforge.net and you can subscribe or unsubscribe at The SourceForge Project Mail Page.

  • IRC Channel

    We have an IRC channel! Its #dxr3 on irc.openprojects.net. Come join us and ask questions about the driver or just chat with the developers and other users.

  • Sourceforge Fora

    As nice as they are, we don't use them. But you really can't tell that by the number of people who have posted to them. Do us all a favor, and just stay away from them for now. Perhaps one day we may be popular enough to need them, but right now, just say "no".

   
SourceForge Logo    
 
dxr3-devel mailing list
Last modified: Sun Oct 26 18:56:53 EET 2008