NAME
utoppy —
USB driver for the Topfield
TF5000PVR range of digital video recorders
SYNOPSIS
utoppy* at uhub? port ?
#include <dev/usb/utoppy.h>
DESCRIPTION
The
utoppy driver provides support for the Topfield TF5000PVR
range of DVB recorders (nicknamed ‘
Toppy
’)
which are popular in Europe and Australia. These recorders have a USB device
interface which can be used to transfer recordings to and from the unit's hard
disk. The USB interface can also be used to upload binary images for execution
on the Toppy's MIPS cpu.
The Toppy's USB protocol has not been officially documented by Topfield, but the
basic features have been reverse engineered by others in order to write
replacements for the official ‘
Altair
’
download/upload program from Topfield.
Existing replacements for Altair suffer from the fact that they are ultimately
built on top of
ugen(4). This has
a number of detrimental side-effects:
- Performance suffers since all Toppy command packets have
to cross the user-kernel interface.
- The userland programs are full of clutter to deal with
interpreting the command/status packets, not to mention byte-swapping and
host endian issues.
- Signals can interrupt a data transfer at a critical point,
leaving the Toppy in an undefined state. For example, interrupting a
download with ‘
Turbo
’ mode enabled
will leave the Toppy completely unresponsive to the remote control, and
prevent timer-based recordings from starting.
The
utoppy driver provides a clean and stable interface to the
Toppy protocol, and ensures that an interrupt caused by a signal does not
leave the Toppy in an undefined state.
UTOPPY INTERFACE
Use the following header file to get access to the utoppy specific structures
and defines.
#include <dev/usb/utoppy.h>
The
utoppy driver can be accessed through the
/dev/utoppyN character device. The primary means of
controlling the driver is by issuing a series of
ioctl(2) system calls followed by
read(2) or
write(2) system calls as
appropriate.
The following
ioctl(2) commands are
supported by the
utoppy driver:
-
-
UTOPPYIOTURBO
int *mode
- This command can be used to enable or disable
‘
Turbo
’ mode for subsequent
UTOPPYIOREADFILE
or
UTOPPYIOWRITEFILE
commands (see below). If
num is non-zero, Turbo mode will be enabled.
Otherwise Turbo mode will be disabled. In non-Turbo mode, the Toppy's USB
interface is capable of sustaining around 5.6 Mbit/s during a file
transfer. With Turbo mode enabled, it can sustain just over 16 Mbit/s. Of
course, these figures are valid only if the Toppy is connected via a USB
2.0 interface. Performance using an older USB 1 interface will be
significantly lower.
-
-
UTOPPYIOCANCEL
void
- This command can be used to abort an in-progress
UTOPPYIOREADDIR
,
UTOPPYIOREADFILE
, or
UTOPPYIOWRITEFILE
command.
-
-
UTOPPYIOREBOOT
void
- This command will cause the Toppy to reboot cleanly.
-
-
UTOPPYIOSTATS
struct utoppy_stats *stats
- This command retrieves statistics for the Toppy's hard
disk.
struct utoppy_stats {
uint64_t us_hdd_size; /* Size of the disk, in bytes */
uint64_t us_hdd_free; /* Free space, in bytes */
};
-
-
- UTOPPYIORENAME
struct utoppy_rename *rename
- This command is used to rename a file or directory on the
Toppy's hard disk. The full pathname to each file must be provided.
struct utoppy_rename {
char *ur_old_path; /* Path to existing file */
char *ur_new_path; /* Path to new file */
};
-
-
- UTOPPYIOMKDIR
char *path
- This command creates the directory specified by
path.
-
-
- UTOPPYIODELETE
char *path
- This command deletes the file or directory specified by
path.
-
-
- UTOPPYIOREADDIR
char *path
- This command initiates a read of the contents of the
directory specified by path. After issuing this
command, the directory contents must be read using consecutive
read(2) system calls. Each
read(2) will transfer one or
more directory entries into the user-supplied buffer. The buffer must be
large enough to receive at least one directory entry. When
read(2) returns zero, all
directory entries have been read.
A directory entry is described using the following data structure:
struct utoppy_dirent {
char ud_path[UTOPPY_MAX_FILENAME_LEN + 1];
enum {
UTOPPY_DIRENT_UNKNOWN,
UTOPPY_DIRENT_DIRECTORY,
UTOPPY_DIRENT_FILE
} ud_type;
off_t ud_size;
time_t ud_mtime;
uint32_t ud_attributes;
};
The ud_path field contains the name of the directory
entry.
The ud_type field specifies whether the entry
corresponds to a file or a sub-directory.
The ud_size field is valid for files only, and
specifies the file's size in bytes.
The ud_mtime field describes the file or directory's
modification time, specified as seconds from the Unix epoch. The timestamp
is relative to the current timezone, so
localtime(3) can be used
to convert it into human readable form. Note that the Toppy sets directory
timestamps to a predefined value so they are not particularly useful.
The ud_attributes field is not used at this time.
-
-
- UTOPPYIOREADFILE
struct utoppy_readfile *
- This command is used to initiate reading a file from the
Toppy's hard disk. The full pathname, together with the file offset at
which to start reading, is specified using the following data structure:
struct utoppy_readfile {
char *ur_path;
off_t ur_offset;
};
After issuing this command, the file must be read using consecutive
read(2) system calls. When
read(2) returns zero, the
entire file has been read.
-
-
- UTOPPYIOWRITEFILE
struct utoppy_writefile *
- This command is used to initiate writing to a file on the
Toppy's hard disk. The file to be written is described using the following
data structure:
struct utoppy_writefile {
char *uw_path;
off_t uw_offset;
off_t uw_size;
time_t uw_mtime;
};
The uw_path field specifies the full pathname of the
file to be written.
The uw_offset field specifies the file offset at which
to start writing, assuming the file already exists. Otherwise,
uw_offset must be zero.
The protocol requires that the Toppy must be informed of a file's size in
advance of the file being written. This is accomplished using the
uw_size field. It may be possible to work around
this limitation in a future version of the driver.
The uw_mtime field specifies the file's timestamp
expressed as seconds from the Unix epoch in the local timezone.
Due to limitations with the protocol, a
utoppy device can be
opened by only one application at a time. Also, only a single
UTOPPYIOREADDIR
,
UTOPPYIOREADFILE
, or
UTOPPYIOWRITEFILE
command can be in progress at any
given time.
FILES
- /dev/utoppy0
- device node
SEE ALSO
utoppya(1),
usb(4)
HISTORY
The
utoppy driver appeared in
NetBSD
4.0.
AUTHORS
Steve C. Woodford
<
scw@netbsd.org>