Executive Summary: I tried to get a Broadcom CrystalHD chip to work in Linux. I came close to being successful. The chip, kernel driver, and userspace library all work. The example app that would have been the payoff… not so much. I document my process in this post in case others need assistance, or can lend assistance in the final step.

There was some news recently about Broadcom open sourcing code related to a video decoding chip. The brand name here is apparently “CrystalHD” and the chip in question is the BCM-70012. I came into possession of one of these and endeavored to make the open source software surrounding it work in Linux.

The first issue is installing the hardware. It’s a PCI Express mini card which has the same form factor as a PCIe mini wireless networking card. So if your computer can host such a wireless card, it can also hold this thing. Allegedly. First, I tried to place it in the empty PCIe-mini slot in my MSI Wind Nettop. No go. The machine refused to boot up (it would power up but never beep to indicate that it’s really ready to run). Removing the card made the problem go away.

So determined was I to make this chip work that I actually took apart my dear Eee PC 701, ripped out the wireless card and replaced it with the Broadcom card. Deciding it would be too much trouble to attempt to re-attach the keyboard and touchpad ribbons, I realized I could just use USB peripherals.

Resigned to the notion that I just foolishly destroyed my 2 year old Eee PC, I threw the switch anyway and was quite surprised to see it boot up normally. An ‘lspci’ command indicates a new Broadcom multimedia controller hanging off the PCI bus. It’s not pretty but it’s breathing:

So let’s talk software. Broadcom released the driver as open source. To many in the open source community, this is tantamount to, “Okay, done deal! What else needs to be open sourced?” Not so fast. There’s no documentation in the whole package (user-wise, anyway; the libcrystalhd API is thoroughly documented in header comments). So I will describe my experiences with the software.

Download the Linux driver package and unpack it.

Have some kernel source to build against. You don’t actually need a full source tree installed; just the headers will do. To install the appropriate header package on an Ubuntu system, execute:

  apt-get install linux-headers-`uname -r`

When installing a linux-headers package, it’s necessary to specify a kernel version. `uname -r` will determine your Linux kernel version and substitute it into the command line.

If you’re going the route of installing only kernel headers like I did, you will also need to create a symlink from /lib/modules/<version>/build to the new headers tree. This should do the trick:

  ln -s /usr/src/linux-headers-`uname -r` /lib/modules/`uname -r`/build

With that infrastructure in place, change directory into crystalhd/driver/linux. Important step: Run ‘dos2unix *’ in this directory. There are DOS-style line endings running around in here that will foul up the build process. Run ‘autoconf’. Then run ‘./configure’. The whole process looks sort of like this:

$ dos2unix *
$ autoconf 
$ ./configure 
checking for ld... ld
configure: creating ./config.status
config.status: creating ./Makefile

Time to build: ‘make’. This should look something like:

$ make
make -C /lib/modules/2.6.30.5-ep0/build SUBDIRS=/home/melanson/crystalhd/driver/linux modules
make[1]: Entering directory `/usr/src/linux-headers-2.6.30.5-ep0'
  CC [M]  /home/melanson/crystalhd/driver/linux/crystalhd_lnx.o
  CC [M]  /home/melanson/crystalhd/driver/linux/crystalhd_misc.o
  CC [M]  /home/melanson/crystalhd/driver/linux/crystalhd_cmds.o
  CC [M]  /home/melanson/crystalhd/driver/linux/crystalhd_hw.o
  LD [M]  /home/melanson/crystalhd/driver/linux/crystalhd.o
  Building modules, stage 2.
  MODPOST 1 modules
  CC      /home/melanson/crystalhd/driver/linux/crystalhd.mod.o
  LD [M]  /home/melanson/crystalhd/driver/linux/crystalhd.ko
make[1]: Leaving directory `/usr/src/linux-headers-2.6.30.5-ep0'

‘make install’ (as root, of course) to get the module where it needs to go and then ‘modprobe crystalhd’ to activate the driver. After the modprobe command, the last line of my ‘dmesg’ log looks like:

  Broadcom 70012 Decoder 0000:01:00.0: setting latency timer to 64

We’re not done yet, though. There are 2 provided scripts (bcm_70012_???.sh) which are supposed to load the module and create a device node. The scripts failed to run. Instead, I sorted out the right command for my machine:

mknod -m 666 /dev/crystalhd c 251 0

The major number (251) comes from ‘grep crystalhd /proc/devices’.

Then we move over to the user-land system library (crystalhd/linux_lib/libcrystalhd). A simple ‘make && sudo make install’ should do the trick here.

Then there’s the matter of the example code (crystalhd/examples). Whoever wrote these samples was not in close communication with the people who wrote the rest of the library. It’s reasonable that the code did work at some point. But whoever made this final package reorganized the directory structure and didn’t test this code since there are all kinds of problems when running the simple build script included.

Things went off the rails at this point.

The build script doesn’t build as-is due to incorrect paths. I changed the build script to look like this:

g++ -I ../include/ -I ../linux_lib/libcrystalhd/ -I/usr/include -D__LINUX_USER__ -lcrystalhd -lpthread hellobcm.cpp -o hellobcm

This is to be run from the examples directory. Doing so, however, indicates that hellobcm.cpp has several problems. Upshot: I altered the start of the file to look like this (added 2 headers, subtracted one, added U8 and U32 typedefs which might only work on x86_32):

#include <stdlib .h>
#include <stdio .h>
#include <stdint .h>
#include <string .h>
#include <semaphore .h>
#include "bc_dts_types.h"
#include "bc_dts_defs.h"
#include "libcrystalhd_if.h"
//#include "bc_ldil_if.h"
#include <iostream>
#include <fstream>
#include <sys /shm.h>

typedef unsigned char U8;
typedef unsigned int U32;

#define TRY_CALL_1(func, p1, errmsg) \
[...]

That gets the test program to compile. Running it results in a complaint that firmware can’t be located in a preordained location:

[...]
DtsGetFirmwareFiles:Ctx->FwBinFile is /lib/firmware/bcmFilePlayFw.bin
Failed to Open FW file
[...]

All right, so it wants the firmware files in very specific places (this is actually due to that libcrystalhd user-land library). These firmware files live in crystalhd/firmware/fwbin/70012. Moving the firmware files to /lib/firmware (hey! there are a bunch of firmware files there; I never knew that), makes hellobcm get farther before tossing out a cryptic error. A little investigation reveals that the source is looking for a hardcoded .264 video file (home directory paths implicate a ‘jarod’ and a ‘davilla’, perhaps the same davilla who authored the XBMC blog post).

So I need to feed it a raw .264 video file. All right, Broadcom, let’s see what you’ve got. Chew on the MV1_BRCM_1 H.264 sample (src19td.IBP.264 from here), one of the meanest conformance samples in the ITU suite. Incidentally, it’s from Broadcom (hence, “BRCM”).

Things go… well, confusingly. The program emits a lot of debugging info which largely emanates from the libcrystalhd.so library (that’s also the code which downloads the firmware at initialization). I’m still massaging the code (various other parameters seem to be hardcoded based on the sample) but when it does run successfully, it claims to decode 136/257 frames from the sample. And it does so while occupying the CPU for about a quarter of a second.

For comparison, it takes FFmpeg 16.6 seconds of CPU time to decode this sample using the following command line:

  ffmpeg -benchmark -i src19td.IBP.264 -f yuv4mpegpipe -y /dev/null

It is, of course, inappropriate to make comparisons before I can validate that this example is decoding anything correctly (and it’s a specious comparison anyway). It should be noted that 16.6s amounts to “less than realtime” for a sample that’s 10 seconds long. So that’s the time to beat on my Eee PC 701 equipped with an Intel Celeron M CPU running at 620 MHz… wait, no, ACK! /proc/cpuinfo reports the full 900 MHz! I accidentally overclocked the thing. Or rather, de-underclocked it. Oops. Per my understanding, the only negative implication of that is less battery time.

This same CrystalHD code seems to have been copy and pasted for crystalhd-for-osx. The same example programs live in that tree. I doubt they compile.

Would CrystalHD driver support be useful for FFmpeg? It doesn’t really seem like a good fit. But then, FFmpeg already supports other hardware decoding features such as XvMC and VDPAU.