Alan Perry's Blog

Friday January 12, 2007

DCAM1394_CMD_PARAM_GET vs. DCAM1394_CMD_REG_READ

The Solaris dcam1394 driver allows access to an IIDC camera's control command registers (which I will abbreviate as IIDC registers) through two different methods.

One method is through the DCAM1394_CMD_PARAM_GET and DCAM1394_CMD_PARAM_SET ioctls (which I will abbreviate as PARAM_GET/SET). Under this method, the ioctls provide an abstraction for the IIDC camera's parameters (as well as some driver parameters). The parameters supported by this abstraction are documented in the dcam1394 man page.

The other method is through the DCAM1394_CMD_REG_READ and DCAM1394_CMD_REG_WRITE ioctls (which I will abbreviate as REG_READ/WRITE). Under this method, each IIDC register is individually accessed by the application. This requires detailed knowledge of the IIDC register set.

How do you use these ioctls?

For PARAM_GET/SET, refer to the blog that I wrote last year on the topic.

For REG_READ/WRITE, the application passes the IIDC register's offset (and, if writing, the value to write) to the driver through the ioctl. This is what code that does this might look like:

/* dcamctl_fd is the file descriptor from opening /dev/dcamctl */
dcam1394_reg_io_t cam_reg;

cam_reg.offs = 0x100; /* inquiry register for video format */

if (ioctl(dcamctl_fd, DCAM1394_CMD_REG_READ, &cam_reg) == -1) {
  perror("reading the video format inquiry register failed");
}

printf("video formats supported:\n");
if (cam_reg.val & 0x01)
  printf("vga uncompressed format\n");
if (cam_reg.val & 0x02)
  printf("svga uncompressed 1 format\n");
if (cam_reg.val & 0x04)
  printf("svga uncompressed 2 format\n");
if (cam_reg.val & 0x40)
  printf("still image format\n");
if (cam_reg.val & 0x80)
  printf("scalable image size format\n");

Why would you want to choose one over the other?

The obvious reason to choose the PARAM_GET/SET ioctls is that their use is documented in one place. The ioctls and the complete set of parameters that one can access through them are described in the dcam1394(7d) man page. Another reason is that, if the application needs to access a large number of parameters, PARAM_GET/SET are much more efficient interfaces.

The reasons not to choose PARAM_GET/SET are also the reasons to choose REG_READ/WRITE instead. For starters, the parameters that are available through PARAM_GET/SET were determined based on the first version of the IIDC spec (1.04). Additional parameters have been added to newer versions of the IIDC spec. Those parameters are not available through PARAM_GET/SET and are available through REG_READ/WRITE. Also, the PARAM_GET/SET interfaces have a lot of overhead when used to access a single parameter. On the other hand, the REG_READ/WRITE interfaces are very simple to use to access a single parameter.

The disadvantage of REG_READ/WRITE is that they require familiarity with the IIDC register set. The IIDC specifications are available from the 1394 Trade Association. Alternately, a simple Google search can be used to find a copy of the specification. Yet another alternative is the device specification from the manufacturer of the camera that you have (such as the manual for the Sony XCD-910 line of cameras).

While the big advantage of REG_READ/WRITE is that they can be used to handle devices that were implemented to newer versions of the IIDC spec (or to handle vendor-specific features), this is not sufficient for controlling all IIDC cameras.

The dcam1394 driver does not read the configuration ROM to determine the base address for the IIDC registers. Instead, it uses the base address that is used by most of the IIDC cameras on the market. Unfortunately, an example of a camera that uses a different base address is the most common, consumer-grade IIDC camera on the market, the Apple iSight (though Apple seems to be phasing it out, hence no link here). Also, the Solaris device discovery mechanism (/etc/driver_aliases) has only been set-up to attach the dcam1394 driver with a camera that claim to be a IIDC 1.04 device. To have Solaris attach the dcam1394 driver to cameras that claim to implement a newer version of the IIDC spec, the driver_aliases file needs to be updated so that there is an entry with spec_id and sw_version_id values that correspond to the version that the camera claims to support. Fortunately, the IIDC specs are backwards compatible.

Note that an application cannot completely depend on one of these sets of interfaces to control an IIDC camera. For example, the DCAM1394_CMD_FRAME_RCV_START and DCAM1394_CMD_FRAME_RCV_STOP ioctls (used to start and stop isochronous data transfers) require synchronization between the internal state of the dcam1394 driver with accessing the IIDC registers, so these accesses are done automatically. Also, some of the parameters that are accessed through PARAM_GET/SET are driver parameters, not IIDC parameters, so have to be accessed through PARAM_GET/SET.

I think that's it.

( Jan 12 2007, 02:12:21 AM PST ) Permalink