Becoming a Dreambox open source developer

(last update 30 December 2005)

This document is being written by bert hubert who does not work for the Dream company, but I *am* an open source programmer and I want to work on my wonderful dreambox!

Many thanks to Ghost and obi for explaining things to me. They help me practice German too!

Please don't try to do this if you are new to linux or new to compiling - recompiling the firmware of an embedded appliance is not easy, even for experts!

You can break your Dreambox if you make a mistake!. Fixing it may require a return to the dealer, which will be able to tell you broke it! So be careful. I don't guarantee anything.

Some inner details

First, some clarification. There are multiple machines, one called a 'dbox2', one called a 'DreamBox DM7000S'. The former is an older machine from Nokia, Philips and Sagem, the DreamBox is for sale currently. Most of the software you run appears to have been originally written for the dbox2.

The actual program that runs the userinterface is called 'enigma', which is written in C++.

Dreamup Lan for Linux

There is a fancy Windows tool for this, all it does is the following:
  1. Login via telnet
  2. eraseall /dev/mtd/0
  3. cat your.ramfs > /dev/mtd/0
So you can do this too. To login, use root and as password 'dreambox'. These steps take quite some time, up to five minutes in total! Notice the red 0. If you accidentally enter a 4 there, you will destroy your machine. So be careful.

boot sequence

Booting works like this. On /dev/mtd (flash ram) there is a bootloader which expects a cramfs at the beginning of the /dev/mtd. In that filesystem, it looks for /root/platform/kernel/os, which it will boot.

If nothing is there, it will try tftp/bootp, if that doesn't work either, it will see if anything appears on the serial port, and try to boot that. I've been told that tftboot will not touch the flash, though.

If you have messed up the OpenBIOS bootloader, you need special hardware to fix it. This is called 'jtag'.

The bootloader, OpenBIOS, also has options, which you can access over the serial port. To connect, use a nullmodem cable at 115200 bps, N81, and NO hardware flow control. Minicom is a nice way to connect.

When you turn the box on, it prints its name 'DreamBox 7000S', press enter immediately. Here you can configure if it should boot over serial, ethernet of flash.

Partitions on the flash

$ cat /proc/mtd 
dev:    size   erasesize  name
mtd0: 00600000 00020000 "DreamBOX cramfs"
mtd1: 001c0000 00020000 "DreamBOX jffs2"
mtd2: 00040000 00020000 "DreamBOX OpenBIOS"
mtd3: 007c0000 00020000 "DreamBOX (w/o bootloader)"
mtd4: 00800000 00020000 "DreamBOX (w/ bootloader)"
mtd5: 004e0000 00020000 "DreamBOX SquashedFS"
mtd0: the image that gets booted by the bootloader
mtd1: what gets mounted on /var
mtd2: the actual bootloader (may be at the very end of the disk)
mtd3: the entire disk, minus the bootloader
mtd4: the entire disk

Compiling yourself and booting over NFS

WARNING! The instructions below are outdated, follow the instructions here. You will get an error about libmad and libid3tag, to fix, download these from here and here, and put them in cdk/Archive, preferrably before running step 7, if possible. Otherwise wait until you get the error, go to the Archive directory and remove all traces of libmad and libid3tag and put the files you downloaded there. The versions found on sourceforge do NOT work! Outdated instructions below, for historical interest perhaps:

You need two things, a kernel and the userspace programs. Compiling the kernel is somewhat complicated and in many cases, there is no need to do it anyhow.

Building userspace

First check out the cvs repository: 
	mkdir $HOME/tuxbox-cvs
	cd    $HOME/tuxbox-cvs

	cvs -d:pserver:anonymous@cvs.tuxbox.org:/cvs/tuxbox login
	(when prompted for a password, just hit Enter/Return)

	cvs -d:pserver:anonymous@cvs.tuxbox.org:/cvs/tuxbox -z3 co -r rel_1_0_0 .
Now, note that this is targetted at the Nokia DBOX2, which is not (exactly) the Dreambox DM7000S! However, you can fix that easily.

The important directory in here is the 'cdk', cross development kit. In it you will find doc/INSTALL.* (english and german), which you should read, it explains what tools you need.
If you are on Debian unstable, you need to apt-get flex-old and not flex!
Now, for the dreambox, there are a lot of tools you don't need, but which may have problems compiling anyhow. It is suggested to edit this line in cdk/Makefile.am: 

all: core libs root boot apps devel
extra: java fun contrib_apps dvb_apps
It may look slightly different, but what you should do is remove 'java', 'fun' and 'dvb_apps'.

Now configure your tree: 

		mkdir $HOME/dbox2	
		cd    $HOME/tuxbox-cvs/cdk
		./autogen.sh
		./configure --prefix=$HOME/dbox2 --with-cvsdir=$HOME/tuxbox-cvs --enable-maintainer-mode
What this says is that your build tree will live in ~/dbox2, where you will find lots of tools, about which more later.

There are drivers meant for the Nokia DBOX2 which don't compile for the Dreambox, which you should disable. This works like this.

Each subsystem compiled for the dreambox leaves behind a .file to indicate that it was built succesfully. To indicate that system is already built or should not be built, simply touch that file. Currently, you must touch .lirc, which is an ir driver not used by the Dreambox.

Now start the compilation: 

	make all extra
The first time this will take many hours as it has to make everything for a dreambox, like the C library, C compiler, C++ compiler, libraries to draw fonts etc.
All these files end up in ~/dbox2/, which has two interesting directories, cdk and cdkroot. The former contains tools for you to run on Dreambox binaries, the second is the new root filesystem for your Dreambox!

During compiling you may find that some programs have released newer versions, in which case you need to update cdk/rules-archive. Afterwards, you may have to rerun ./autogen.sh, I'm unsure about that.

Ok, if compiling is done, you need to make some changes because you are not booting a DBOX2 but a dreambox. Edit the file ~/dbox2/etc/init.d/rc.S and remove all 'insmod' lines - they are not for you. However, add the following three lines, in this order: 

insmod fb  
insmod dream  
insmod avs
These are special modules which you need to copy off your Dreambox. They are in /lib/modules/2.4.20 and you should copy them to ~/dbox2/cdkroot/lib/modules/2.4.20 too. Make sure they are owned by root!

Make the kernel boot with root on NFS

(This section is still up to date, except for the bit about the password)

The easiest way to do this is to install a DHCP server on your development machine. When the Dreambox boots, you can talk to it over the serial port, as described above.
Some time after turning the machine on, it will give you a bootprompt, which you can replace. Only backspace works, no arrows. The cursor keys may appear to work, but they don't.
The line to boot over NFS in the simplest case is: 

console=ttyS0,115200 root=/dev/nfs rw ip=bootp
In your dhcpd.conf, add the following: 
host drbox2
{
 	fixed-address 10.0.0.97;
	hardware ethernet xx:xx:xx:xx:xx:xx ;
	allow bootp;
	option root-path "/home/ahu/dbox2/cdkroot";
}
You can read the ethernet MAC address from the back of your dreambox, or use ARP. Also update the root-path and the fixed-address to values of your liking. Don't forget to tell the dhcpserver you changed the configuration.

You should allow that address to mount the cdkroot path read/write, add the no_root_squash flag.

If your NFS server is not on the same machine as the dhcp server, add the following to the bootline above: 

nfsroot=10.0.1.8:/home/ahu/dbox2/cdkroot
Alternatively, obi reports that you can add: 
next-server your.development.machine;
to the dhcp stanza above, and not change the bootline.

Ok, after booting, it should start your new enigma automatically. If not, run /bin/enigma yourself.

The root password of this install is 'dbox2' and not 'dreambox'!.

Compiling the kernel

The kernel consists of a more or less regular ppc Linux kernel plus some patches. Furthermore, there are three closed source modules which you need to load. This is fine with the GPL, so please don't argue about it.

To get the 2.4.20 kernel source for PPC32, get BitKeeper and execute this command: 

bk clone -rv2.4.20_linuxppc_2_4_devel bk://source.mvista.com/linuxppc_2_4_devel
BitKeeper is a nice tool which is free (as in beer) for open source use. Afterwards, get this patch.

Now get the .config here, and copy it to your kernel directory. To compile, enter 'make oldconfig dep zImage', the new kernel will be in arch/ppc/boot/images/zImage.treeboot

If you have managed to compile a kernel with the compiler in ~/dbox2/cdk/, and find modules for your kernel (which need the same version of gcc as you used!), an easy way to boot is over tftpboot. The modules for 2.4.20 are on the official images that come with the DreamBox.

To do so, enter the menu of OpenBIOS by pressing enter after it prints the first line over the serial port, and choose 'setup boot devices'. Turn on booting over ethernet. Make sure your dhcp entry specifies a kernel, and that you run tftp on the dhcp server.

To specify a kernel, add the following to your dhcpd.conf: 

filename "/boot/zImage.treeboot";
Many tfptservers restrict access to files to a certain directory, often /boot or something in /var, make sure to check that.