devfw-ohci

Driver for IEEE-1394 devices on OHCI controllers, primarily cameras

Syntax:

You must be root to run this utility.

Runs on:

x86

Options:

None at present.

Description:

The devfw-ohci driver provides support for IEEE-1394 devices, primarily uncompressed digital cameras (not camcorders).

The driver, when started, finds all connected IEEE-1394 devices and creates device entries for them in the directory /dev/fw0. Created device names are of the form

devicetype-deviceident-serialnumber

with the three parts separated by dashes. No other dashes will appear in the device name.

For known devices (currently only digital cameras), a typical name might be

dc-unibrain-fire-i_1.2-8254

For unrecognized devices, the IEEE numeric device type and device identity are used, and the device is not usable, although it appears in the directory.

Hot-plugging of IEEE-1394 devices is fully supported. The filenames in the /dev/fw0 directory will change as required. The filename of a device is determined by its built-in serial number, not its position on the cable. Hot-plugging may cause an active device to return errors while the bus is resetting, so applications should be prepared to handle transient device errors. Once the bus is back up (this takes a few hundred milliseconds) the device should again be useable. Cameras are automatically reset and restored to their previous state after a bus reset.

This driver will work with multiple isochronous bus master machines on the same bus. This has been tested successfully with Windows 2000. However, some Linux drivers do not play well with others; they assume they are the only master on the bus. Note, though, that multiple computers on the same bus must avoid opening the same devices simultaneously. This is a limitation of the IEEE-1394 bus, which does not have a device allocation mechanism.

Usage:

Digital cameras - functions

read

Digital cameras can be read, but not written. Reading from a digital camera starts continuous frame capture using the current settings. Reading will return bytes from one frame, and the end of the frame is indicated by a return of zero bytes. The next read begins reading with the next frame. Reads will block waiting for the camera when necessary. Thus, to read each frame, just read until zero bytes are returned.

Errors

devctl

Function DCMD_MEDIA_DEVFW_CAMERA_FEATURE_READ

Usage:

int fd; /* file descriptor */
dc1394_feature_info info; /* feature information structure */
...
int stat = devctl(fd,DCMD_MEDIA_DEVFW_CAMERA_FEATURE_READ, &info, sizeof(info);

Reads one standard IEEE-1394 "Camera feature" into a Linux-compatible dc1394_feature_info structure. Typical features are camera gain and exposure time. See below for the full set of feature IDs.. Set feature_id in this structure before the call to devctl. The additional fields will then be filled in.

The "abs" fields are not currently supported.

Feature ID values:

Fields of dc1394_feature_info:

Errors

Function DCMD_MEDIA_DEVFW_CAMERA_FEATURE_WRITE

Usage:

int fd; /* file descriptor */
dc1394_feature_info info; /* feature information structure */
...
int stat = devctl(fd,DCMD_MEDIA_DEVFW_CAMERA_FEATURE_WRITE, &info, sizeof(info));

Writes one standard IEEE-1394 "Camera feature" into a dc1394_feature_info structure. Typical features are camera gain and exposure time. See abovefor the full set. Normal usage is to set feature_id, fill in the structure using DCMD_MEDIA_DEVFW_CAMERA_FEATURE_READ,set value to the desired value for the feature, then use DCMD_MEDIA_DEVFW_CAMERA_FEATURE_WRITE. Currently, the only settable field is value, but other fields may become settable in future, so it's best to get full feature information before setting it.

It's possible to put a camera into an invalid state with this call. If an error is returned, resetting the device with the devctl function DCMD_MEDIA_DEVFW_CAMERA_RESET, or closing and reopening the device, will reset the camera to its default state.

Errors

Function DCMD_MEDIA_DEVFW_CAMERA_VIDEO_MODE_READ

Usage:

int fd; /* file descriptor */
dc1394_video_mode_t mode; /* video mode*/
...
devctl(fd,DCMD_MEDIA_DEVFW_CAMERA_VIDEO_MODE_READ, &mode, sizeof(mode));

Gets the video mode (frame size, color depth, and frame rate) of the camera. videomode and framerate are chosen from the following tables.

Most cameras will support only some of the listed modes. Attempts to set an invalid mode will return EINVAL.

Errors

Function DCMD_MEDIA_DEVFW_CAMERA_VIDEO_MODE_WRITE

Usage:

int fd; /* file descriptor */
dc1394_video_mode_t mode; /* video mode*/
...
int stat = devctl(fd,DCMD_MEDIA_DEVFW_CAMERA_VIDEO_MODE_WRITE, &mdoe, sizeof(info));

Sets the video mode (frame size, color depth, and frame rate) of the camera. The standard table of IEEE-1394 camera formats and modes is used. Only the fields videomode and framerate are settable.

videomode and framerate are chosen from the following tables.

Most cameras will support only some of the listed modes. Attempts to set an invalid mode will return EINVAL.

After setting the video mode, it is useful to read it back, which will retrieve the number of bytes per frame.

Errors

Function DCMD_MEDIA_DEVFW_CAMERA_TIMESTAMP_READ

Usage:

#include <time.h>
int fd; /* file descriptor */
struct timespec frametime; /* time of frame arrival */
...
int stat = devctl(fd,DCMD_MEDIA_DEVFW_CAMERA_TIMESTAMP_READ, &frametime, sizeof(frametime));

This function returns the time, from CLOCK_REALTIME, that the current frame arrived from the camera over the IEEE-1394 bus. It is intended for precise synchronization of camera events, and for the detection of missing frames. The "current frame" is the one currently being read or most recently read.

Errors

Function DCMD_MEDIA_DEVFW_CAMERA_TAKEPICTURE

Usage:

int fd; /* file descriptor */
...
devctl(fd,DCMD_MEDIA_DEVFW_CAMERA_TAKEPICTURE, 0, 0);

Puts the camera into single-frame mode and takes one picture., which can then be read.

Errors

Function DCMD_MEDIA_DEVFW_CAMERA_RESET

Usage:

int fd; /* file descriptor */
...
devctl(fd,DCMD_MEDIA_DEVFW_CAMERA_RESET, 0, 0);

Stops the camera, discards any pending input, and resets the camera to factory defaults. This also puts the camera back in continuous mode.

Errors

Supported chipsets

• OHCI-compatible

IEEE-1394 supported features

Device classes supported

Files:

This driver needs the Mindready Low-Level Adapter support package installed.

liblla.so

Mindready low-level adapter library

Bugs:

The first few frames from some cameras are garbage data.

Testing has been limited to Unibrain cameras.

Only continuous mode (not "takepicture" single frame mode) is currently supported.

Author:

John Nagle / Team Overbot / nagle@overbot.com