DXR3 / Hollywood Plus HOWTO Table of Contents
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
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.
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.
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 email@example.com.
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 # 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.
modules/devices.sh script or
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
- 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
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.
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
If you decide to use it, you can skip directly to the
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_
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.
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.
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
$ 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
- 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
In this section we describe some useful programs that have been contributed to the
- 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.
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
- 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.
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
in the source tree, consult it for more information. Note that some parameters are available only for ADV717X based
- 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.
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.
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
||Requires pixelport_16=1, dicom_control=1, dicom_fix=1
- Creative Labs Dxr3 Variants
||ct7235-vbq (9938 rev b) board:ct7260
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 firstname.lastname@example.org
and you can subscribe or unsubscribe at The SourceForge Project Mail
- 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