What to include in a bug report.

What you should include in a bug report depends on what bug you've encountered, but nevertheless I'll take you through the stuff that you can report. There's no such thing as too elaborate when it comes to bug-reports.

We recommend that you send the bug-report either to the sourceforge bug-tracker or to our mailing-list. Both allow attachments.

Before you start:

Make sure you've installed the CDEmu software with debugging symbols intact. For instance on Ubuntu this means you have to make sure the packages libmirage3-dbg, cdemu-daemon-dbg and image-analyzer-dbg are installed. Without these crash dumps are harder to decipher. If you installed the software from tarballs the debugging symbols should already be included.

Compulsory items:

Kernel and distribution versions.
uname -a
lsb_release -a

CDEmu software versions and where you downloaded it from.
cdemu version

If you compiled it yourself, include the gcc and libglib versions.
gcc -v
pkg-config --modversion glib-2.0

Also tell us if the vhba module and the cdemu daemon is operational.
lsmod | grep -i vhba
ps -C cdemu-daemon

Image parser or File filter bugs.

If the bug is related to an image parser or a file filter, in other words, if a CD-image failed to load, there are some info we'd like.

First instruct CDEmu to emit debugging information. To enable this for device #0 do this: cdemu library-debug-mask 0 0x81. Now attempt to load the troublesome CD-image to device #0 and then have a look at the file ~/.cdemu-daemon.log. Include its contents in the bugreport. If you for some reason happen to run the daemon on the system bus, the log file is located at /tmp/cdemu-daemon.log instead.

It's also very useful to have a copy of the image meta-data. It varies between image-formats how this is stored but I'll list some examples.

B6T: We need the B6T file.
C2D: We need the first part of the file. You can get it with the command head --bytes=100K myimage.c2d > mychunk.bin.
CCD: We need the CCD file and the exact size of the IMG and any SUB file(s) in bytes.
CDI: We need the last part of the file. You can get it with the command tail --bytes=100K myimage.nrg > mychunk.bin.
CIF: Nevermind...
CSO: We need the first part of the file. You can get it with the command head --bytes=100K myimage.c2d > mychunk.bin.
CUE: We need the CUE file and the exact size of the BIN file(s) in bytes.
DAA: We need the first part of the file. You can get it with the command head --bytes=100K myimage.c2d > mychunk.bin.
ISO: We need the exact size of the file in bytes.
MDS: We need the MDS file.
MDX: Nevermind...
NRG: We need the last part of the file. You can get it with the command tail --bytes=100K myimage.nrg > mychunk.bin.
TOC: We need the TOC file and the exact size of the BIN file(s) in bytes.

Other bugs in the daemon or in libmirage.

Characterized usually by misbehaviour or that the software plain crashes. Since the amount of debugging information that can be emitted is truly huge, it's usually a good idea to contact us and give us a preliminary bug-report instead of attempting to debug it yourself. We'll be able to tell you exactly what information we need and how to go about aquiring it.

If the problem is misbehaviour, please include a description of the problem in the report. If the bug is related to a crash in the software include the crash message. If the issue is reproducible, please include the steps needed to reproduce the issue.

Bugs that cause CDEmu to crash.

Since crash messages can be a bit cryptic, it's usually a good idea to have a debugger provide some relevant information.

First make sure you have the gdb package installed, then run the commands sudo pkill -KILL cdemu-daemon and gdb /usr/bin/cdemu-daemon, then enter run, leave the program running, and try to provoke a crash by loading a CD-image or whatever you did to have CDEmu crash the last time. Once it crashes it gives you some information about the crash. Now enter info proc, info threads and backtrace to get some more info. Include this information in the report.

If you are having problems getting the daemon to start, you might have a permission issue. Make sure that your user has read and write permissions on /dev/vhba_ctl, normally this means that your user is a member of the group that has permissions on the device.

VHBA bugs.

Include the files /var/log/dmesg and /var/log/kern.log in the bug-report. Also include the output from the lsmod and sudo modinfo vhba commands.

More information.

The README file for the daemon contains a lot of potentially useful information. Chances are if you have a How do I...? type of question the answer can be found there. If you installed CDEmu from packages you can usually find it here: /usr/share/doc/cdemu-daemon/README.gz.