VHBA module

About

VHBA module provides a Virtual (SCSI) HBA, which is the link between userspace daemon and linux kernel.

Contrary to what some might expect due to the "userspace" part of the name, userspace CDEmu still needs a kernel module, just like the original CDEmu - the difference is that userspace CDEmu does all the processing (i.e. file reading, fake data generation, etc.) in userspace.

Kernel module takes care of device emulation in the kernel; it registers virtual device with appripriate drivers and creates corresponding device nodes. It also creates a special character device that is used for communication with userspace.

As a virtual device is accessed, requests are generated by kernel, which are in fact SCSI commands. These are passed to userspace daemon via afore-mentioned character device. Once it processes the request, the daemon returns corresponding data and status to kernel, thus completing the request.

The whole process is very similar to accessing a real device, except that requests are passed to userspace daemon instead to hardware.

Early, experimental versions of userspace-cdemu used a module that was called cdemu-module. This release is based on VHBA module, which was written by Chia-I Wu. Contrary to cdemu-module, which implemented all the interfaces (i.e. block device, uniform CD-ROM driver, etc.) manually, VHBA implements virtual SCSI host adapter and lets the kernel's SCSI layer do the rest. This approach is cleaner, faster and more robust.

Requirements

Packaging guidelines

VHBA module provides the control character device via which communication between userspace and kernelspace is done. This requires both read and write permissions on the character device for the user running the CDEmu daemon.

Typically, the read-write permissions on the /dev/vhba_ctl are achieved by using udev's "uaccess" tag, by creating the following udev rule:

KERNEL=="vhba_ctl", SUBSYSTEM=="misc", TAG+="uaccess"

The rule should be stored in a .rule file in either /lib/udev/rules.d or /etc/udev/rules.d directory. For the "uaccess" tag to be applied properly, the rule must be executed before the uaccess rule. Therefore, if the uaccess rule is contained by /lib/udev/rules.d/70-uaccess.rules, the rule above must be stored in a file with number smaller than 70.

The alternative and now obsolete approach is to create a udev rule that explicitly sets the read/write permissions on the control device:

KERNEL=="vhba_ctl", MODE="0660", OWNER="root", GROUP="cdrom"

Putting the above line into .rules file in udev's rules dir (i.e. /etc/udev/rules.d/vhba.rules) will allow the access to control device for daemon run as either root or any member of cdrom group.

Depending on the distribution, use of dkms might also be a good idea.